Skip to content

Command line

Split a mesh without opening the app: for batch jobs, scripts, or a quick split you already know the settings for. It runs the same splitting code as the browser app and the OrcaSlicer plugin, so the same settings give the same parts.

Setup

Pick one. All three run the same code and give the same parts.

Download (nothing to install). Get the file for your computer from the latest release and run it from a terminal:

Computer File
Windows mesh-splitter-windows-x64.exe
Mac (Apple silicon) mesh-splitter-macos-arm64
Mac (Intel) mesh-splitter-macos-x64
Linux mesh-splitter-linux-x64, mesh-splitter-linux-arm64
mesh-splitter-windows-x64.exe figure.stl --auto 6 -o figure.3mf

The files aren't code-signed. On Windows, if SmartScreen stops it, click More info, then Run anyway. On a Mac or Linux, make it runnable first: chmod +x mesh-splitter-macos-arm64, and on a Mac also xattr -d com.apple.quarantine mesh-splitter-macos-arm64.

npx (needs Node.js 20+). No clone needed:

npx github:d-carrigg/mesh-splitter figure.stl --auto 6 -o figure.3mf

From the repo folder (needs uv and Node.js 20+).

uv run mesh-splitter split --help

The first run installs two small npm packages (npm ci). You can also run it with Node directly: npm ci, then node cli/split.mjs ....

The examples below use uv run mesh-splitter split. With a downloaded file or npx, put that in its place, for example mesh-splitter-windows-x64.exe figure.stl --auto 6. --version prints the version.

Examples

# Auto split, count picked from the creases; writes figure_parts.3mf next to the mesh
uv run mesh-splitter split figure.stl

# Exactly 6 parts, plus one STL per part
uv run mesh-splitter split figure.stl --auto 6 -o figure.3mf --stl parts/

# One part per shell, as a painted 3MF
uv run mesh-splitter split kit.3mf --shells --painted kit_painted.3mf

# Parts grown from seed points
uv run mesh-splitter split figure.stl --seeds seeds.json -o figure.3mf

# Finish a split in the app, then re-export it from a script
uv run mesh-splitter split figure.stl --session figure.split.json --stl parts/

It prints each part with its filament slot and face count, then the files it wrote ("Replaced" for a file that was already there). Cutting along the part boundaries adds faces, so the part list also gives the face count after the split.

Auto and shells splits number parts from slot 2 (slot 1 is Unassigned). If two parts end up on the same slot, for example more than 15 parts, it prints a warning. After --merge on an auto or shells split, the slots are renumbered with no gaps.

Methods

Pick one. Without one, it auto splits.

Option What it does
--auto [N] Auto split into N parts (2 to 32). Without N, it picks the count from the model's creases, like the app does when it opens a model.
--shells Split by shells: one part per separate piece.
--seeds FILE Grow parts from seed points, like seeds in the app. See Seeds file.
--session FILE Apply a .split.json saved from the app (Save session). It must be for the same mesh.

After the method, --merge "NAME=A,B" joins parts A and B (by name, such as Part 3) into one part called NAME, like Ctrl+click merge in the app. Give it one part to just rename it (--merge "Head=Part 3"). Repeat it for more groups:

uv run mesh-splitter split figure.stl --merge "Body=Part 1,Part 4" --merge "Head=Part 2" -o figure.3mf

Moves, rotations, scaling and replacements from a session are not applied: those parts are written in their original position and shape, and it prints a note naming them.

Outputs

With no output option, it writes <name>_parts.3mf next to the mesh. Use any mix of these:

Option Writes
-o, --out FILE Multi-part 3MF: one object, one part per split part with its name and filament slot. The same file as Multi-part 3MF to Downloads in the plugin. Import it with Ctrl+I.
--painted FILE Painted 3MF: one mesh, each face painted with its part's filament slot.
--stl DIR One closed STL per part, with the cut openings capped.
--merged FILE All parts in one STL. Each part is closed, so the cut caps stay inside where parts touch.
--save-session FILE A .split.json you can load in the app (Load session) to keep editing.
--report FILE JSON summary: the mesh's bounds, and each part's name, filament slot, face count, bounds and center.

See Exporting for how each format loads in the slicer.

Settings

Option App control Default
--crease DEG Crease slider: concave creases sharper than this separate parts. Lower is more sensitive. 2
--denoise N Denoise slider: smoothing passes on the concavity map. Higher ignores small dents. 4
--filaments N Your printer has N filament slots (1 to 16, such as 4 for one AMS). Parts are numbered 1 to N, reusing slots when there are more parts than slots. Replaces slots from a seeds file or session.
-q, --quiet Print only errors.

Seeds file

A JSON list of parts. Each part has seed points (x, y, z in the mesh's units, usually mm), face indices, or both. Each point picks the nearest face. name and filament (1 to 16) are optional; a part without a filament gets the next free slot.

[
  { "name": "Head", "filament": 2, "points": [[0, 0, 40]] },
  { "name": "Body", "filament": 3, "points": [[0, 0, 10], [0, 5, 0]] },
  { "name": "Base", "faces": [120] }
]

Faces no seed can reach, such as a separate shell with no seed on it, stay in the Unassigned part on filament 1.