Multi-tool Export
PythonSCAD ships a small helper, MultiToolExporter, for the common
multi-tool / multi-color workflow where a single model is split into several
parts (typically one per filament color or print head) and each part is
exported either to its own file or into one multi-object 3MF file.
The class lives in the pythonscad package (a strict superset of openscad),
so it is available under either of these imports:
MultiToolExporter
MultiToolExporter is a list subclass whose items are
(name, object) 2-tuples or optional (name, object, export) 3-tuples.
The name is a label used to build the output filename and must be a
non-empty string. The optional export flag defaults to True; set it to
False for cutters that participate in cumulative subtraction but are
omitted from parts(), show(), and all export paths. Output paths must be
unique among exportable items; hidden duplicate names are allowed.
Item order matches dict.items() and the multi-object form of
export, so a MultiToolExporter and a dict of
parts are interchangeable (MultiToolExporter(items=parts.items())
and dict(exporter.parts())).
Filename layout: for each item, per-file export() writes to:
so a typical use is export(prefix="out/model-", suffix=".stl"). Prefer
passing prefix / suffix / mkdir to export(); constructor prefix /
suffix / mkdir remain supported but emit DeprecationWarning when
explicitly passed (including "" / False).
Cumulative-difference semantics: for each index i, the geometry
exported is
i.e. each entry's volume minus every later entry's volume, including
later entries with export=False. Cutters therefore affect only earlier
list entries; ordering semantics are unchanged. This guarantees that
overlapping regions are claimed by exactly one exported part:
later entries "win" over earlier ones, so each part only keeps the
volume not claimed by any subsequent item. The last list entry is exported
as-is (no degenerate one-child difference node) when it is exportable and
therefore claims everything that overlaps with it.
Constructor:
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
prefix |
str or None |
None |
Default prepended to every per-file output filename. Prefer export(prefix=...). Passing a value (including "") is deprecated. |
suffix |
str or None |
None |
Default appended to every per-file output filename (typically the extension). Prefer export(suffix=...). Passing a value (including "") is deprecated. |
mkdir |
bool or None |
None |
Default whether to create each output file's directory with os.makedirs(..., exist_ok=True). Prefer export(mkdir=...). Passing a value (including False) is deprecated. See note below. |
items |
iterable of (name, object) or (name, object, export) |
() |
Optional initial items, validated as if appended. export must be bool (0/1 rejected). |
When mkdir=True, filenames without a directory component (e.g.
"flag-" rather than "out/flag-") are exported as-is - no directory
is created and no error is raised.
Methods:
| Method | Description |
|---|---|
append(item) |
Append a single (name, object) or (name, object, export) tuple. Validates the shape. |
extend(items) |
Append each item tuple from an iterable. |
insert(i, item) |
Insert a single item tuple at position i. |
parts() |
Return computed (name, geometry) pairs for exportable items only. Useful for lower-level dict(exporter.parts()) 3MF export. |
export(prefix=..., suffix=..., mkdir=...) |
Write each exportable part to its own file. Path layout args override instance defaults for this call. Raises ValueError if any two exportable items would write to the same output path. |
export(single_file="out/model.3mf") |
Write exportable parts into one 3MF file. No-ops when all hidden. Raises ValueError for non-.3mf paths or duplicate exportable names. |
show(render=False) |
Render each exportable part into the preview viewport (same cumulative-difference semantics as export). With render=True, each part is evaluated to a mesh first — see Preview artifacts. |
Validation:
- Every inserted item must be a 2-tuple of
(str, object)or a 3-tuple of(str, object, bool). Anything else raisesTypeError. - The
namemust be a non-empty string. Empty names raiseValueError. - The optional third element must be an actual
bool(0/1and other truthy values are rejected). - At per-file
export()time, the full output filename (f"{prefix}{name}{suffix}") of every exportable item is normalised withos.path.normcase(os.path.normpath(filename))(plus an extra.casefold()on macOS) and any collision raisesValueErrorrather than letting later parts silently overwrite earlier ones. This rejects raw duplicate names everywhere, plus path aliases like"a/../b"vs"b", plus case-only collisions like"a.stl"vs"A.stl"on Windows and macOS (whose default filesystems are case-insensitive). Linux treats such case-only pairs as distinct files and is left alone. Hidden (export=False) duplicate names are allowed.
Examples:
A two-color flag with a hidden slot cutter after both printable parts (the slot subtracts from both colors but is not exported):
from pythonscad import *
background = cube([200, 100, 1]).color("blue")
slot = cube([40, 40, 2]).translate([80, 30, -0.5])
star = cylinder(r=20, h=2, fn=5).translate([100, 50, -0.5]).color("red")
exporter = MultiToolExporter()
exporter.append(("blue", background)) # blue minus slot and star
exporter.append(("red", star)) # red minus slot
exporter.append(("slot", slot, False)) # cuts both; no file
exporter.export(prefix="out/flag-", suffix=".stl", mkdir=True)
# -> writes out/flag-blue.stl and out/flag-red.stl only
A two-color flag (red star cut out of a blue background):
from pythonscad import *
background = cube([200, 100, 1]).color("blue")
star = cylinder(r=20, h=2, fn=5).translate([100, 50, -0.5]).color("red")
exporter = MultiToolExporter()
exporter.append(("blue", background)) # blue: rectangle minus the star area
exporter.append(("red", star)) # red: the star itself (later wins)
exporter.export(prefix="out/flag-", suffix=".stl", mkdir=True)
# -> writes out/flag-blue.stl and out/flag-red.stl
Seeding from the constructor:
Previewing the same split inside the GUI without writing files:
Preview artifacts
Every part except the last is a difference of its object minus all later
objects. When the parts have the same height (for example several colors
extruded to the same H), the cutters share the part's top and bottom
planes. F5 (OpenCSG) previews such a difference with the classic
coplanar-face artifacts: holes look see-through (lettering cut into a rim
loses its top) and the caps flicker. Offsetting parts does not help, because
the coplanar faces are inside each part's own difference.
Pass render=True to evaluate each part to a mesh before showing it:
The preview then shows exactly the flush solids that export() writes, at
the cost of one geometry evaluation per part. parts() and export() are
unaffected.
Single-file 3MF export
Pass single_file to write one 3MF file containing every computed part as a
named object. This is useful for slicers such as PrusaSlicer, where each 3MF
object can be assigned to a different tool or filament color. Prefix and
suffix are unused on this path:
from pythonscad import *
background = cube([200, 100, 1]).color("blue")
star = cylinder(r=20, h=2, fn=5).translate([100, 50, -0.5]).color("red")
exporter = MultiToolExporter()
exporter.append(("blue", background))
exporter.append(("red", star))
# Cumulative-difference split, then one 3MF with two named objects.
exporter.export(single_file="flag.3mf")
For single-file export, exportable item names become 3MF object names and must
be unique among exportable items. Hidden cutters are omitted. If every item
is hidden, single-file export is a no-op.
single_file currently supports only .3mf; use plain export(prefix=..., suffix=...)
when you want one output file per part.
The lower-level export(dict(exporter.parts()), "flag.3mf") form is still
available if you want to build the part dictionary yourself. See
Multi-object 3MF export for the full
dict-export contract.