Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,7 @@ assembly mode (the assembly must honour `-D cut=true` and colour each part outsi
| Command | What |
|---|---|
| `3d export <file.scad>` | STL/[3MF](GLOSSARY.md#3mf) with manifold/self-intersect validation. **Nonzero exit on bad geometry.** |
| `3d convert <IN...> <OUT>` | Convert between formats (`.scad .stl .3mf .usdz .obj` → `.stl .3mf .usdz .png`); a colored `.scad` becomes a true multicolour Orca project 3MF — one object per `color()` with its own extruder ([docs](docs/commands/convert.md)). |
| `3d validate <file.scad>` | Fast syntax check (no render). |
| `3d params <file.scad> [--json]` | Extract Customizer-style parameters. |
| `3d om <file.scad> <selector>` | Query `.scad` object-model annotations as JSON. |
Expand Down
2 changes: 2 additions & 0 deletions docs/architecture/lib-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,8 @@ Every current root Python module is listed here so future additions are intentio
- `collision_check.py` — geometry / collision check implementation.
- `collision_viz.py` — geometry / collision visualization implementation.
- `config.py` — project and CLI configuration helpers.
- `convert_mesh.py` — the colour-aware conversion worker behind `3d convert` (run via `cli.pyrun`): reads any convert input through `dimension_model` (+ a pxr/usd-core reader for USDZ), splits the faces into colour groups and writes an Orca project 3MF (one object per colour, per-object extruder), a merged binary STL or a multicolour USDZ.
- `convert_plan.py` — the pure-stdlib route/collision policy of `3d convert`: format inference (extensionless outputs filled from the conversion), route legality, the auto-suffix / refuse-with-a-free-name-command contract and the staging+commit that re-checks existence at write time.
- `debug_overlay.py` — pure planning and advisory helpers for render/reference debug overlays.
- `errors.py` — structured CLI error model.
- `events.py` — append-only CLI/model workflow event store.
Expand Down
1 change: 1 addition & 0 deletions docs/commands/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ explain why the command exists, what its inputs mean, and how it fits into the l
| Command | Doc | Role |
|---|---|---|
| `export` | [export.md](export.md) | Format-aware [STL](GLOSSARY.md#stl)/[3MF](GLOSSARY.md#3mf)/USDZ export, format planning, and [manifold](GLOSSARY.md#manifold) validation when the mesh stack is available. |
| `convert` | [convert.md](convert.md) | Convert between formats (multicolour scad→Orca project [3MF](GLOSSARY.md#3mf) with per-object extruders, stl/usdz/png, retarget alias). |
| `generate` | [generate.md](generate.md) | Text description + named dimensions -> verified parametric `.scad` via an AI backend (generate/validate/render/check/fix loop). |
| `fit-niche` | [fit-niche.md](fit-niche.md) | Generate a parametric insert/plug that mates into a described cavity with FDM clearances. |
| `assembly` | [assembly.md](assembly.md) | Whole-assembly checks over declared mates: blocking intersections, per-mate fit clearance, insertion/removal sweeps on any axis, assembly order, finger/tool ergonomics, explode, BOM, 3MF positioning (`check`, `sweep`, `order`, `ergonomics`, `explode`, `bom`, `position`, `show`). |
Expand Down
83 changes: 83 additions & 0 deletions docs/commands/convert.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# `3d convert` — one command for every model-format conversion

Converts one or more model files into a result file; the output format comes from the
result's extension. The flagship route is **multicolour scad → Orca project 3MF**: every
`color()` group of the OpenSCAD source becomes its own object with per-object `extruder`
metadata and its authored colour, so an AMS / multi-filament slicer prints the model in
colours instead of one uniform blob.
Issue: [#741](https://github.com/alex-mextner/3d-cli/issues/741) (multicolour projects
in general: [#89](https://github.com/alex-mextner/3d-cli/issues/89)).

## Usage

```
3d convert <IN...> <OUT> [options]
```

One or more inputs, the **LAST argument is the result**. Inputs: `.scad .stl .3mf .usdz .obj`.

| Option | Default | What |
|---|---|---|
| `--force` | off | Overwrite an existing OUT. Without it an existing target is refused (exit 2) with the ready-to-run command that uses a free name. |
| `-D k=v` | — | OpenSCAD define for `.scad` inputs (repeatable). |
| `--color r,g,b` | `0.78,0.74,0.66` | Diffuse colour `0..1` for a single-colour `.usdz` output; authored colours are kept. |
| `--bed MM` | `270` | Square bed size for the `.3mf` project layout (same default as [`3d arrange`](arrange.md)). |
| `--to PRINTER` | — | `3mf→3mf` only: retarget the project to that machine preset. Delegates to [`3d retarget`](retarget.md); its `--set`, `--preset`, `--keep`, `--margin`, `--process`, `--filament`, `--preset-dir`, `--include-non-printable` and `-v` options pass through. |

```bash
3d convert mole.scad mole.3mf # multicolour Orca project (one object per colour)
3d convert mole.scad mole.usdz # AR Quick Look package, one coloured mesh per colour
3d convert part.stl copy.stl # lossless same-format copy
3d convert model.scad out.stl -D 'depth=40' # parametric export
3d convert a.stl b.stl merged.3mf # merge several inputs into one project
3d convert model.scad shot.png # render as png
3d convert spoon.3mf spoon-u1.3mf --to u1 # retarget alias (`3d retarget` under the hood)
3d convert spoon.3mf spoon-u1 --to u1 # same, extension filled from the input
```
## Output formats

| Extension | What you get |
|---|---|
| `.stl` | Binary mesh. A single `.scad` goes straight through OpenSCAD (the [`3d export`](export.md) route); a project `.3mf` uses its placed world coordinates (`slicing/retarget_3mf.export_stl`); anything else (or several inputs) is merged through the colour-aware mesh worker, inputs laid out side by side. |
| `.3mf` | A true Orca/Bambu **project** 3MF (plates, object names, per-object metadata) built by `lib/orca_project_3mf.py`. From `.scad`/`.stl`/`.usdz`/`.obj` inputs every colour group becomes its own object with per-object `extruder` metadata (1-based, first-appearance colour order; uncoloured geometry prints on extruder 1). From a `.3mf` without retarget options the project is repackaged unchanged (a rename). |
| `.usdz` | AR Quick Look package; one coloured mesh per colour group (`lib/usdz.py`). |
| `.png` | A render of the model (exactly one input; `.scad`/`.stl` render directly, other inputs are staged through an STL). |
| *(none)* | Filled from the conversion: a single `.stl`/`.3mf` input keeps its own format, anything else becomes `.3mf`. |

Not writable: `.scad` (use [`3d import`](import.md) for a wrapper) and the planned export
formats (`obj`, `ply`, `glb`, …) — refused with the accepted list.

## Multicolour scad → 3MF

`lib/convert_mesh.py` renders the scad through OpenSCAD's 3MF export, which keeps every
`color()` as a per-triangle base material, reads that back colour-grouped
(`lib/dimension_model.py`), and emits one project object per colour:

- each object carries `<metadata key="extruder" value="N"/>` (Orca's per-object
filament slot) plus its authored colour as the 3MF base material;
- the colour groups keep their authored relative positions — the overlap between
adjacent colour groups is exactly what fuses the colours in the print;
- the assembly is laid flat (min z = 0) and centred on the bed; several inputs are
placed side by side with a 12 mm gap;
- equal colours share one extruder slot, across inputs too.

Open the result in an Orca-family slicer, map the extruder slots to your filaments
(AMS slots or the filament list) and slice.

## Collision behaviour

- An output that would overwrite **one of its own inputs** never fails: the same
extension is legal, the output silently becomes the next free suffix
(`3d convert a.stl a.stl` writes `a-2.stl`).
- Any **other existing target** is refused (exit 2) with the exact ready-to-run command
using a free name, plus the `--force` variant. `--force` overwrites.
- The file may appear later: every route writes a staging file beside the target first
and commits it only after re-checking that the target still does not exist, so a
failed or refused conversion never leaves a half-written output (and never clobbers a
file that appeared mid-run).

## Exit codes

- `0` — converted
- `1` — the conversion itself failed (OpenSCAD error, unreadable geometry, retarget did not fit)
- `2` — bad usage, unreadable input format, or a refused overwrite
Loading
Loading