Automatic Slicing: user guide (beta)

Before you start: a Full License, and Bambu Studio or OrcaSlicer installed on the computer.

1. Prepare the print profile. In Bambu Studio or OrcaSlicer, set the printer, the filament and all the print settings of your jobs, for example on a simple cube, then save the project as a .3mf file. These settings are applied to every piece.

2. Prepare the split file. In Split3r, on any model, set the split the way you want it done: the same printer as in the .3mf, the piece size, the type of joint, Optimize or not. Save the project with File, Save As: the .s3r file you get is your reference file.

3. Create the job folder. A folder where you put that .s3r file, and only one. The .3mf profile can sit there too.

4. Set up Automatic Slicing. Menu Project, Automatic Slicing Configuration...: give the job folder; in the Slicing tab, tick "Slice the pieces after the split" and choose the .3mf profile; in the Pricing tab, your rates if you want the priced quote.

5. Drop your models (STL, PLY or 3MF) in the job folder, next to the .s3r.

6. Start. Menu Project, "Automatic Slicing: Process Job Folder Now". Or tick "Automatic Slicing: Watch Job Folder" so that every new model is processed on its own. Or start Split3r with --batch from another program.

Result: every model gets its own sub-folder (its Workzone), with the split pieces, the pieces laid in their print position, the G-codes, the pictures, the PDF quote and the data file. The chapters below give the details.

About ready.txt: with models dropped in the job folder as above, you have nothing to create: Split3r writes this file itself in each Workzone it prepares. You only need it when you build the Workzone sub-folders yourself (chapter 3): put a ready.txt file, empty or not, in the sub-folder, last. It tells Split3r that the Workzone is complete and can be processed.

This guide describes the Automatic Slicing mode of Split3r (first called Quotation mode): a batch mode that splits models from a job folder, lays every piece in its print position, optionally slices them with your own slicer, and writes machine-readable results (JSON), pictures and PDF reports. It is now a standard function of Split3r: the three menu entries are always there, the -q flag is no longer needed (it is still accepted and changes nothing). It requires a Full License (Basic + Add-ons): without it the entries are greyed out and --batch ends with exit code 3. The --batch flag and the file names (quotation_result.json...) have not changed.

Split3r 1.5.0 RC2 is available on the Downloads page.

• 1. Starting Split3r in batch mode
• 2. Configuration
• 3. Job folder and Workzones
• 4. Automatic Workzones (models dropped at the root)
• 5. Piece sizes and cut planes
• 6. Print positions
• 7. Slicing
• 8. Files written per Workzone
• 9. quotation_result.json
• 10. What stops a Workzone, and what does not
• 11. Usable plate size (custom printer)
• 12. Logs
• 13. Current limits of this beta

From the window: menu Project, the three "Automatic Slicing" entries. From the command line, with --batch (the window stays visible):

macOS:

/Applications/Split3r.app/Contents/MacOS/Split3r --batch /path/to/JobFolder
/Applications/Split3r.app/Contents/MacOS/Split3r --batch /path/to/JobFolder/Workzone/project.s3r

Linux (AppImage, the file is named Split3r-<version>-x86_64.AppImage):

./Split3r-1.5.0-x86_64.AppImage --batch /path/to/JobFolder

Windows (the installer puts Split3r in C:\Program Files\Split3r_<version>):

"C:\Program Files\Split3r_<version>\Split3r.exe" --batch D:\Jobs

Exit code of --batch: 0 every Workzone succeeded, 1 at least one failed, 2 nothing was processed (folder not found, no ready Workzone), 3 the licence does not include this function (a Full License is required). Any other value means Split3r itself crashed.

Run one batch at a time. A licence allows one active computer, and two runs on the same job folder would pick up the same Workzones.

Licence: each run needs the licence server. In this build, if the server cannot be reached at start-up, a licence window opens and waits for a click, which blocks an unattended run. During a long run the licence is checked again when the last check is more than 15 minutes old.

Menu Project, "Automatic Slicing Configuration...". The settings are saved in quotation.json next to the other Split3r settings:

These settings are used only to fill the pricing block and the PDF.

A job folder contains one sub-folder per Workzone. A Workzone contains:

• exactly one .s3r project file,
• the model it names (stl_path), STL, PLY or 3MF,
• the ready file (ready.txt by default), written last.

A Workzone that already contains quotation_result.json is considered done and is skipped. Delete that file to process it again. Folders whose name starts with . or _ are ignored.

Minimal .s3r (JSON):

{
  "stl_path": "column.stl",
  "x_size": 310, "y_size": 290, "z_size": 340,
  "printer_brand": "Bambu Lab", "printer_model": "H2S usable", "printer_size": [310, 290, 340],
  "tenon_mode": "lap_joint",
  "lap_joint": {"d1": 1.0, "width": 2.0, "height": 2.0, "clearance": 0.15},
  "tenon_template": {"template": "pyramide", "pyr_base": 10.0},
  "optimize": {"enabled": true, "centered": false, "swap": false},
  "equal_pieces": true,
  "split3r_version": "1.5.0",
  "client": {"quote_id": "Q-2026-0912", "file_id": 4711, "scale": 1.0}
}

Do not write planes or printer_index: Split3r recomputes the cut planes from the sizes. The model must already be at the final scale (no scale key is read).

You can also drop model files (STL, PLY, 3MF) directly in the job folder, next to exactly one reference .s3r. At the next pass (watch, "Process Job Folder Now" or --batch), each model gets its own Workzone: a sub-folder named after the file (suffix _2, _3 if the name is taken), the model moved into it, a copy of the reference .s3r with stl_path set to the file and the cut planes removed, and the ready file. Then the Workzone is processed like any other.

Rules:

• one .s3r at the root; none or several: nothing is prepared and the log says why;
• the slicer profile 3MF configured in the settings is never taken as a model, even if it sits in the job folder;
• a model is taken only when its size and date have not changed between two passes (a file still being copied waits for the next pass);
• other files at the root are ignored.

x_size, y_size and z_size are the largest size of a finished piece, whatever protrudes from its cut face included. Split3r does the arithmetic:

1. In batch mode, a size above "printer size minus bed margin" (margin on each side in X and Y, once in height) is reduced to that value before the split. settings.cut_size_capped then gives the values before and after; settings.cut_size_mm always holds the sizes really used.
2. The distance between two cut planes is that size minus what protrudes: the lip height in lap joint mode, the male tenon height (half its base) in male/female mode, nothing otherwise. settings.protrusion_mm and settings.cut_step_max_mm give the values.

Example: printer 310 x 290 x 340, bed margin 5, lap joint lip 2: finished piece at most 300 x 280 x 335, cut planes at most 298 x 278 x 333 apart.

equal_pieces: without it, pieces are cut at the full distance from one end and the remainder goes into the last piece (a 1000 mm model at 333 mm gives 333 / 333 / 333 and a 1 mm sliver). With it, Split3r keeps the smallest number of pieces that respects the sizes and gives them all the same size (4 pieces of 250 mm). It applies to the regular grid, to the Optimize slices and to the boxes inside each slice.

Every piece is written a second time, already turned into its print position, in the print/ folder of the Workzone (same format as the piece, colours kept for PLY). The rotation is a quarter turn (exact, no rounding); the copy is not translated.

Rule, in order:

1. a cut face that carries a lip or male tenons is never put on the bed (male_faces of the piece; protrudes_mm of each cut face);
2. the largest remaining cut face goes down (rule: "largest cut face");
3. a piece that is too tall on that face (tall ratio) is laid down only if a side that really makes it lower offers a truly flat area larger than the cut face; otherwise it stays standing;
4. the next candidates are the other cut faces ("other cut face"), then the side with the largest truly flat area ("largest flat face"; "lying flat" when no side is flat), then the original position ("as is");
5. each candidate is checked against the fit limit; the first pose that fits wins; if none fits, the first one is kept, print.fits is false and pieces_not_fitting lists the piece.

Fit limit (fit_limit_mm in the JSON): the finished piece sizes of section 5, that is the .s3r sizes capped at the printer size minus the bed margin. The comparison allows 0.01 mm.

Pieces made of several separate bodies (rare, happens when the model has detached parts): each body is laid by the same rules (or on its largest flat face if it has no cut face). print/<piece> shows the bodies side by side, print/bodies/ holds one file per body. Tiny fragments (under 1 mm3 or thinner than 0.5 mm) are not separated; they stay attached to the largest body.

The tenon file written by the split stands on its tip. Its print copy in print/ is laid on its largest face, and that copy is the one sliced.

When slicing is enabled, every piece (from its print copy) and the tenon are sent to the slicer, one at a time. Split3r builds a project 3MF per piece from your profile (all settings copied as they are) and runs the slicer command line with --allow-newer-file.

• A single piece, a single tenon and tenon plates are placed by Split3r at the plate centre (turned a quarter turn on the plate when that is the only way it fits) and the slicer does not move them. The slicer's automatic arrangement reserves room for a wipe tower even with a single filament and leaves large pieces off the plate (return code -50).
• A piece made of several bodies is arranged by the slicer, which adds plates when needed. Split3r then checks that every body was sliced; a body left out is sliced on its own and added to the piece (slicing.missing_bodies, slicing.bodies_sliced_alone).
• A piece exactly as tall as the printer is refused (Bambu Studio, return code -104, "G-code outside of the printable area": the z-hop on the last layer goes above the maximum). The bed margin in height avoids it.
• A slicer that has written a successful result but does not close is stopped 15 seconds later and its result is used (slicing.slicer_stopped).

Outputs go to gcode/ in the Workzone: <piece>.gcode.3mf (openable in the slicer), <piece>.gcode, and <piece>.slice.json when the slicer writes one. When the slicer needed several plates for one piece, the files are <piece>_plate_1.gcode, <piece>_plate_2.gcode... A body sliced on its own gives <piece>_body_<n>.gcode. Tenon plates are tenons_plate_1.gcode...

Bambu Studio's command line applies its own "safe" accelerations, so a time can differ slightly from the same plate sliced in the window.

A slicer refusal is recorded per piece with a plain reason (for example "no object fully inside the plate", "3MF file version not accepted by this slicer", "slicing failed"). A crash or an empty result is retried once.

Per job folder: quotation_batch.json (one line per Workzone with status, reason, piece and join counts, print time, filament, price) and quotation_batch.pdf. Both are updated after each Workzone.

Names in the JSON are the names on disk.

Stops it (status failure, with the reason): no .s3r or several, model file missing, model that cannot be loaded, PreSplit that produces no cut box, split that writes no piece, time limit reached. The next Workzone is processed anyway.

Does not stop it: a piece that does not fit (noted), measurement errors (noted in analysis_errors), a slicer refusal (noted per piece, slicing becomes partial, price marked not complete), a missing slicer profile (slicing skipped), a split that places no tenon (tenon is null).

To split against the usable area of your printers instead of the catalogue size, declare a custom printer in custom_printer_filament.json, in the settings folder of section 2:

[
  {"id": "h2s-usable", "name": "Bambu Lab", "model": "H2S usable", "x": 310, "y": 290, "z": 340}
]

{"printers": [...]} is accepted too, id is optional. Use a model name that does not exist in the catalogue, then put that name and model in printer_brand and printer_model of the .s3r. This file is never overwritten by an update. Remember that the bed margin of section 2 is taken off this size as well.

Add -d to the command line to get a full log file:

Every line of this mode starts with Quotation:. Slicer refusals include the last lines printed by the slicer. Without -d, no log file is written.

• One Workzone at a time, one batch at a time; Split3r is busy during a batch.
• Tenons: a tenon is placed only where it is at least the tenon margin (10 mm by default) away from every edge of the cut face and where its footprint fits entirely. On thin walls no tenon can be placed: no sockets, no male pegs, and male/female then gives the same pieces as female/female. The reason is given for the Workzone (tenon_note), not per joint.
• Lap joint pieces have no open edges but contain edges shared by more than two triangles, which slicers report and repair. Female/female pieces do not.
• Pieces that come out of the split with several separate bodies are handled (sections 6 and 7). What is not handled yet is a model made of several bodies that touch or overlap before the split: Split3r cuts it as one, and the cut is less reliable where the bodies meet.
• The print/ copies assume FDM printing (face down). For resin they can be ignored; the pieces in splits_<model>/ are unchanged.
• Only Bambu Studio and OrcaSlicer (and their derivatives) are driven.
• Licence server out of reach: a window opens and waits (section 1).