OpenSCAD 用户手册/在命令行环境中使用 OpenSCAD
OpenSCAD 不仅可以用作 GUI，还可以处理命令行参数。
OpenSCAD 2021.01 具有以下选项
Usage: openscad [options] file.scad
Allowed options:
--export-format arg overrides format of exported scad file when
using option '-o', arg can be any of its
supported file extensions. For ascii stl
export, specify 'asciistl', and for binary stl
export, specify 'binstl'. Ascii export is the
current stl default, but binary stl is planned
as the future default so asciistl should be
explicitly specified in scripts when needed.
-o [ --o ] arg output specified file instead of running the
GUI, the file extension specifies the type: stl,
off, wrl, amf, 3mf, csg, dxf, svg, pdf, png,
echo, ast, term, nef3, nefdbg (May be used
multiple time for different exports). Use '-'
for stdout
-D [ --D ] arg var=val -pre-define variables
-p [ --p ] arg customizer parameter file
-P [ --P ] arg customizer parameter set
--enable arg enable experimental features (specify 'all' for
enabling all available features): roof |
input-driver-dbus | lazy-union |
vertex-object-renderers |
vertex-object-renderers-indexing |
vertex-object-renderers-direct |
vertex-object-renderers-prealloc | textmetrics
-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
--animate arg export N animated frames
--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
--summary arg enable additional render summary and statistics:
all | cache | time | camera | geometry |
bounding-box | area
--summary-file arg output summary information in JSON format to the
given file, using '-' outputs to stdout
--colorscheme arg =colorscheme: *Cornfield | Metallic | Sunset |
Starnight | BeforeDawn | Nature | DeepOcean |
Solarized | Tomorrow | 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 - specify 'all' or a set of
source file names
-s [ --s ] arg stl_file deprecated, use -o
-x [ --x ] arg dxf_file deprecated, use -o
OpenSCAD 2019.05 具有以下选项
Usage: openscad [options] file.scad
Allowed options:
-o [ --o ] arg output specified file instead of running the
GUI, the file extension specifies the type: 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
当使用 -o 选项调用时，OpenSCAD 不会启动 GUI，而是执行给定的文件并根据扩展名（.stl / .off / .dxf，.csg）将其导出到 output_file。
一些版本使用 -s/-d/-o 来确定输出文件格式；请使用“openscad --help”进行检查。
如果除了导出命令之外还给出了选项 -d，则在构建网格时访问的所有文件都将以 Makefile 语法写入 -d 的参数中。
对于至少 2015.03-2+，指定扩展名 .echo 会使 openscad 生成一个文本文件，其中包含错误消息以及 filename 中所有 echo() 调用的输出，就像它们在 GUI 中可见的控制台窗口中出现一样。不支持多个输出文件，因此使用此选项，您也不能获取本来应该生成的模型。
对于 2013.05+，添加了输出 .png 图像的选项。有两种类型的相机可用于生成图像。
第一种相机类型是“万向节”相机，它使用欧拉角、平移和相机距离，就像 OpenSCAD 窗口底部的 OpenSCAD GUI 视窗显示一样。
第二种相机类型是“矢量”相机，具有“眼睛”相机位置矢量和“看向”中心矢量。
--imgsize x,y 选择 .png 尺寸，--projection 选择正交或透视，就像在 GUI 中一样。
默认情况下，cmdline .png 输出使用带有 OpenCSG 的预览模式（f5）。在某些情况下，可能需要输出完整的渲染，使用 CGAL。这可以通过添加“--render”作为选项来完成。
为了预定义变量，请使用 -D 选项。它可以重复给出。每次出现 -D 后面必须跟一个赋值。与正常的 OpenSCAD 赋值不同，这些赋值不会定义变量，而是定义常量，这些常量不能在程序内部更改，因此可以用来覆盖程序在导出时定义的值。
如果要将 -D 变量分配给另一个变量，则 -D 变量必须在主 .scad 程序中初始化
param1=17; // must be initialized val=param1; // param1 passed via -D on cmd-line echo(val,param1); // outputs 17,17
如果没有第一行，val 将未定义。
右侧可以是任意的 OpenSCAD 表达式，包括数学运算和字符串。
请注意，您的 shell（bash、cmd 等）会在将参数传递给 openscad 之前解析这些参数，因此您需要适当地引用或转义包含空格或引号等特殊字符的参数。例如，要将字符串 production 分配给 quality 参数，您必须确保 shell 不会剥离 openscad 所期望的 " 字符。在 bash 中，您可以这样写
openscad -o my_model_production.stl -D 'quality="production"' my_model.scad
或者从 Windows 提示符中
openscad.com -o my_model_production.stl -D "quality=""production""" my_model.scad
或者您可能需要转义内部引号而不是外部引号
openscad -o my_model_production.stl -D "quality=\"production\"" my_model.scad
请注意，当从不使用 shell 的另一个进程执行 OpenSCAD 时，这种双重转义是不必要的，因为每个参数都是单独传递的。例如，一个 Java 应用程序可能会像这样启动一个进程
pb = new ProcessBuilder("/usr/bin/openscad",
"-o", "my_model_production.stl",
"-D", "quality=\"production\"",
"my_model.scad");
在复杂的构建过程中，如果在 Makefile 中定义了一些 OpenSCAD 文件所需的缺失文件，则可以生成这些文件。如果 OpenSCAD 给出了选项 -m make，它会在第一次尝试访问缺失的 file 时启动 make file。
将文件夹中的所有 .scad 转换为 .stl 的示例
在包含 .scad 文件的文件夹中，创建一个包含以下文本的 .bat 文件
FOR %%f in (*.scad) DO openscad -o "%%~nf.stl" "%%f"
如果它在未处理的情况下关闭，请检查通过将 openscad 目录添加到以下位置来设置 PATH
Start - Settings - Control Panel - System - Advanced tab - Environment Variables - System Variables, select Path, then click Edit.
将 openscad 目录添加到列表中
-d 和 -m 选项只有在组合使用时才有意义。（-m 而不使用 -d 将不会在构建导出时考虑修改的依赖项，-d 而不使用 -m 将要求文件在生成依赖项的第一次运行之前就已经构建好了。）
以下是一个基本 Makefile 的示例，它从同名 .scad 文件创建一个 .stl 文件
# explicit wildcard expansion suppresses errors when no files are found include $(wildcard *.deps) %.stl: %.scad openscad -m make -o $@ -d [email protected] $<
当第一次运行 make my_example.stl 时，它找不到任何 .deps 文件，并且必须依赖于 my_example.scad。由于 my_example.stl 尚未预置，因此它将无条件地创建。如果 OpenSCAD 发现缺失文件，它会调用 make 来构建它们，并将所有用到的文件列在 my_example.stl.deps 中。
当随后调用 make my_example.stl 时，它会找到并包含 my_example.stl.deps，并检查其中列出的所有文件（包括 my_example.scad）自 my_example.stl 构建以来是否发生了更改，这取决于它们的时间戳。只有在这种情况下，它才会再次构建 my_example.stl。
当从单个 .scad 文件构建类似的 .stl 文件时，也有一种方法可以实现自动化
# 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 [email protected] $<
所有应该自动导出的对象都必须在 base.scad 中使用它们未来的文件名（不带“.stl”）定义在一个单独的模块中，并且在模块定义行中有一个注释，例如“// make me”。“TARGETS=”行从基本文件选出这些文件名，并创建文件名。在调用 make all（或 make，简而言之）时构建这些文件。
由于上一个示例的约定是从同名的 .scad 文件创建 .stl 文件，因此必须为每个这些文件生成一个 .scad 文件。这在“%.scad:”段落中完成；my_example.scad 是一个简单的 OpenSCAD 文件
use <base.scad> my_example();
“.SECONDARY”行是为了防止 make 删除生成的 .scad 文件。它的存在有助于确定哪些文件不再需要重建；请在讨论页面上发布有关究竟是什么出错（或者如何更好地修复它）的想法！
在 Windows 上，openscad.com 应该从命令行调用，作为 openscad.exe 的包装器。这是因为 Openscad 使用“devenv”解决方案来解决命令行/GUI 输出问题。在 cmd.exe 提示符下键入“openscad”会默认调用 .com 程序包装器。
在 MacOS 上，二进制文件通常隐藏在 App 文件夹中。如果 OpenSCAD 安装在全局应用程序文件夹中，它可以像以下示例一样从命令行调用，该示例只显示 OpenSCAD 版本
macbook:/$ /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD -v OpenSCAD version 2013.06
或者，您可以创建一个指向二进制文件的符号链接，以便更容易地从命令行调用
macbook:/$ sudo ln -sf /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD /usr/local/bin/openscad
现在您可以直接调用 openscad，而无需输入完整的路径。
macbook:/$ openscad -v OpenSCAD version 2015.03-3
在某些版本的 MacOS 上，尝试通过该链接运行 openscad 时，您可能会收到以下错误
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
您可以通过创建一个包装脚本直接调用可执行文件来解决此问题
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