OpenSCAD用戶手冊/在命令行環境下使用OpenSCAD

維基教科書,自由的教學讀本

命令行語法[編輯]

OpenSCAD的使用不僅限於GUI環境,它也能以命令行參數的形式進行工作。其可用命令有:

OpenSCAD 2019.05版支持以下選項:

 Usage: openscad [options] file.scad
 支持的选项options:
   -o [ --o ] arg               输出指定的文件而非运行GUI,可指定的文件拓展类型有:
                                stl,off, amf, 3mf, csg, dxf, svg, png, echo, ast,
                                term, nef3, nefdbg
                                
   -D [ --D ] arg               var=val -pre-define variables
   -p [ --p ] arg               customizer parameter file
   -P [ --P ] arg               customizer parameter set
   -h [ --help ]                print this help message and exit
   -v [ --version ]             print the version
   --info                       print information about the build process
                                
   --camera arg                 camera parameters when exporting png: 
                                =translate_x,y,z,rot_x,y,z,dist or 
                                =eye_x,y,z,center_x,y,z
   --autocenter                 adjust camera to look at object's center
   --viewall                    adjust camera to fit object
   --imgsize arg                =width,height of exported png
   --render arg                 for full geometry evaluation when exporting png
   --preview arg                [=throwntogether] -for ThrownTogether preview 
                                png
   --view arg                   =view options: axes | crosshairs | edges | 
                                scales | wireframe
   --projection arg             =(o)rtho or (p)erspective when exporting png
   --csglimit arg               =n -stop rendering at n CSG elements when 
                                exporting png
   --colorscheme arg            =colorscheme: *Cornfield | Metallic | Sunset | 
                                Starnight | BeforeDawn | Nature | DeepOcean | 
                                Solarized | Tomorrow | Tomorrow 2 | Tomorrow 
                                Night | Monotone
                                
   -d [ --d ] arg               deps_file -generate a dependency file for make
   -m [ --m ] arg               make_cmd -runs make_cmd file if file is missing
   -q [ --quiet ]               quiet mode (don't print anything *except* 
                                errors)
   --hardwarnings               Stop on the first warning
   --check-parameters arg       =true/false, configure the parameter check for 
                                user modules and functions
   --check-parameter-ranges arg =true/false, configure the parameter range check
                                for builtin modules
   --debug arg                  special debug info
   -s [ --s ] arg               stl_file deprecated, use -o
   -x [ --x ] arg               dxf_file deprecated, use -o

OpenSCAD 2015.03-1版支持以下選項:

openscad     [ -o output_file [ -d deps_file ] ]\
             [ -m make_command ] [ -D var=val [..] ] \
             [ --help ] print this help message and exit \
             [ --version ] [ --info ] \
             [ --camera=translatex,y,z,rotx,y,z,dist | \
               --camera=eyex,y,z,centerx,y,z ] \
             [ --autocenter ] \
             [ --viewall ] \
             [ --imgsize=width,height ] [ --projection=(o)rtho|(p)ersp] \
             [ --render | --preview[=throwntogether] ] \
             [ --colorscheme=[Cornfield|Sunset|Metallic|Starnight|BeforeDawn|Nature|DeepOcean] ] \
             [ --csglimit=num ]\
             filename

OpenSCAD 2014.03+版支持以下選項:

openscad     [ -o output_file [ -d deps_file ] ]\
             [ -m make_command ] [ -D var=val [..] ] \
             [ --version ] [ --info ] \
             [ --camera=translatex,y,z,rotx,y,z,dist | \
               --camera=eyex,y,z,centerx,y,z ] \
             [ --imgsize=width,height ] [ --projection=(o)rtho|(p)ersp] \
             [ --render | --preview[=throwntogether] ] \
             [ --csglimit=num ] \
             filename

Openscad 2013.05版支持以下選項:

openscad     [ -o output_file [ -d deps_file ] ]\
             [ -m make_command ] [ -D var=val [..] ] [ --render ] \
             [ --camera=translatex,y,z,rotx,y,z,dist | \
               --camera=eyex,y,z,centerx,y,z ] \
             [ --imgsize=width,height ] [ --projection=(o)rtho|(p)ersp] \
             filename

更早的發行版僅支持以下選項:

openscad [ -o output_file [ -d deps_file ] ] \
         [ -m make_command ] [ -D var=val [..] ] filename

OpenSCAD 2011.09.30版中可用的選項有(現已廢止):

openscad [ { -s stl_file | -o off_file | -x dxf_file } [ -d deps_file ] ]\
         [ -m make_command ] [ -D var=val [..] ] filename

導出選項[編輯]

When called with the -o option, OpenSCAD will not start the GUI, but execute the given file and export the to the output_file in a format depending on the extension (.stl / .off / .dxf, .csg).

Some versions use -s/-d/-o to determine the output file format instead; check with "openscad --help".

If the option -d is given in addition to an export command, all files accessed while building the mesh are written in the argument of -d in the syntax of a Makefile.

For at least 2015.03-2+, specifying the extension .echo causes openscad to produce a text file containing error messages and the output of all echo() calls in filename as they would appear in the console window visible in the GUI. Multiple output files are not supported, so using this option you cannot also obtain the model that would have normally been generated.

Camera and image output[編輯]

For 2013.05+, the option to output a .png image was added. There are two types of cameras available for the generation of images.

The first camera type is a 'gimbal' camera that uses Euler angles, translation, and a camera distance, like OpenSCAD's GUI viewport display at the bottom of the OpenSCAD window.

The second camera type is a 'vector' camera, with an 'eye' camera location vector and a 'lookat' center vector.

--imgsize x,y chooses the .png dimensions and --projection chooses orthogonal or perspective, as in the GUI.

By default, cmdline .png output uses Preview mode (f5) with OpenCSG. For some situations it will be desirable instead to use the full render, with CGAL. This is done by adding '--render' as an option.

Constants[編輯]

In order to pre-define variables, use the -D option. It can be given repeatedly. Each occurrence of -D must be followed by an assignment. Unlike normal OpenSCAD assignments, these assignments don't define variables, but constants, which can not be changed inside the program, and can thus be used to overwrite values defined in the program at export time.

If you want to assign the -D variable to another variable, the -D variable MUST be initialised in the main .scad program

param1=17;       // must be initalized
val=param1;      // param1 passed via -D on cmd-line
echo(val,param1); // outputs 17,17

without the first line, val would be undefined.

The right hand sides can be arbitrary OpenSCAD expressions, including mathematical operations and strings. Be aware that strings have to be enclosed in quotes, which have to be escaped from the shell. To render a model that takes a quality parameter with the value "production", one has to run

openscad -o my_model_production.stl -D 'quality="production"' my_model.scad

When executing OpenSCAD from another process in Unix, the single-quotes shouldn't be used e.g. from within a Java application:

   pb = new ProcessBuilder("/usr/bin/openscad",
     "-o", "my_model_production.stl",
     "-D", "quality=\"production\"",
     "my_model.scad");

On Windows you may need to escape the inner quotes instead:

openscad -o my_model_production.stl -D "quality=\"production\"" my_model.scad

Command to build required files[編輯]

In a complex build process, some files required by an OpenSCAD file might be currently missing, but can be generated, for example if they are defined in a Makefile. If OpenSCAD is given the option -m make, it will start make file the first time it tries to access a missing file.

處理一個文件夾中所有的.scad文件[編輯]

Example to convert all the .scad in a folder into .stl:

In a folder with .scad files, make a .bat file with text:

   FOR %%f in (*.scad)  DO openscad -o "%%~nf.stl" "%%f" 

If it closes without processing, check to set the PATH by adding openscad directory to:

     Start - Settings - Control Panel - System - Advanced tab - Environment Variables - System Variables, select Path, then click Edit.

Add the openscad directory to the list


Makefile示例[編輯]

The -d and -m options only make sense together. (-m without -d would not consider modified dependencies when building exports, -d without -m would require the files to be already built for the first run that generates the dependencies.)

Here is an example of a basic Makefile that creates an .stl file from an .scad file of the same name:

# explicit wildcard expansion suppresses errors when no files are found
include $(wildcard *.deps)

%.stl: %.scad
	openscad -m make -o $@ -d $@.deps $<

When make my_example.stl is run for the first time, it finds no .deps files, and will just depend on my_example.scad; since my_example.stl is not yet preset, it will be created unconditionally. If OpenSCAD finds missing files, it will call make to build them, and it will list all used files in my_example.stl.deps.

When make my_example.stl is called subsequently, it will find and include my_example.stl.deps and check if any of the files listed there, including my_example.scad, changed since my_example.stl was built, based on their time stamps. Only if that is the case, it will build my_example.stl again.

Automatic targets[編輯]

When building similar .stl files from a single .scad file, there is a way to automate that too:

# match "module foobar() { // `make` me"
TARGETS=$(shell sed '/^module [a-z0-9_-]*().*make..\?me.*$$/!d;s/module //;s/().*/.stl/' base.scad)

all: ${TARGETS}

# auto-generated .scad files with .deps make make re-build always. keeping the
# scad files solves this problem. (explanations are welcome.)
.SECONDARY: $(shell echo "${TARGETS}" | sed 's/\.stl/.scad/g')

# explicit wildcard expansion suppresses errors when no files are found
include $(wildcard *.deps)

%.scad:
	echo -ne 'use <base.scad>\n$*();' > $@

%.stl: %.scad
	openscad -m make -o $@ -d $@.deps $<

All objects that are supposed to be exported automatically have to be defined in base.scad in an own module with their future file name (without the ".stl"), and have a comment like "// make me" in the line of the module definition. The "TARGETS=" line picks these out of the base file and creates the file names. These will be built when make all (or make, for short) is called.

As the convention from the last example is to create the .stl files from .scad files of the same base name, for each of these files, an .scad file has to be generated. This is done in the "%.scad:" paragraph; my_example.scad will be a very simple OpenSCAD file:

use <base.scad>
my_example();

The ".SECONDARY" line is there to keep make from deleting the generated .scad files. If it deleted it, it would not be able to automatically determine which files need no rebuild any more; please post ideas about what exactly goes wrong there (or how to fix it better) on the talk page!

Windows版備註[編輯]

On Windows, openscad.com should be called from the command line as a wrapper for openscad.exe. This is because Openscad uses the 'devenv' solution to the Command-Line/GUI output issue. Typing 'openscad' at the cmd.exe prompt will, by default, call the .com program wrapper.

MacOS版備註[編輯]

On MacOS the binary is normally hidden inside the App folder. If OpenSCAD is installed in the global Applications folder, it can be called from command line like in the following example that just shows the OpenSCAD version:

macbook:/$ /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD -v
OpenSCAD version 2013.06

Alternatively, you may create a symbolic link to the binary to make calls from the command line easier:

 macbook:/$ sudo ln -sf /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD /usr/local/bin/openscad

Now you can call openscad directly without having to type in the full path.

 macbook:/$ openscad -v
 OpenSCAD version 2015.03-3

On some versions of MacOS, you might get the following error when attempting to run openscad via that link:

 This application failed to start because it could not find or load the Qt platform plugin "cocoa".
 Reinstalling the application may fix this problem.
 Abort trap: 6

You can fix this by creating a wrapper script to invoke the executable directly:

 sudo rm -f /usr/local/bin/openscad
 echo '#!/bin/sh' > test
 echo '/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD $*' >> test
 chmod +x test ; sudo mv test /usr/local/bin/openscad