|
| 1 | +# 3MF Coloring Handoff (Unresolved) |
| 2 | + |
| 3 | +## Goal |
| 4 | +Export `.3mf` so: |
| 5 | +- base/top layer is white (or base color), |
| 6 | +- only icon/text regions are black, |
| 7 | +- geometry stays correctly stacked in Z (icons/text not dropped to layer 0). |
| 8 | + |
| 9 | +## Current user-reported failures |
| 10 | +Observed across attempts: |
| 11 | +1. Whole top face imports black instead of only icon/text. |
| 12 | +2. In some variants, icon/text part appears on layer 0. |
| 13 | + |
| 14 | +## Current implementation (where to look) |
| 15 | + |
| 16 | +### SVG and mask generation |
| 17 | +- `assets/js/app.js:1064` `generateSVGString(tagData, forceBlack = false)` |
| 18 | +- `.3mf` path uses `generateSVGString(tagData, true)` (black on white mask) |
| 19 | +- Rasterization: `assets/js/app.js:1412` `svgToImageData(...)` |
| 20 | +- Mask extraction (luma+alpha threshold): `assets/js/app.js:1991` `extractContourGroupsFromImageData(...)` |
| 21 | + |
| 22 | +### 3MF geometry build |
| 23 | +- Constants: |
| 24 | + - `assets/js/app.js:1375` `CONTENT_LAYER_HEIGHT_MM = 0.2` |
| 25 | + - `assets/js/app.js:1378` `CONTENT_BASE_Z_MM = 0.8` |
| 26 | + - `assets/js/app.js:1381` `CONTENT_3MF_CONTOUR_CUT_WIDTH_MM = 0.02` |
| 27 | + - `assets/js/app.js:1382` `CONTENT_3MF_BASE_LAYER_HEIGHT_MM = 0.2` |
| 28 | + - `assets/js/app.js:1383` `CONTENT_3MF_ICON_EXTRA_HEIGHT_MM = 0.2` |
| 29 | +- Contour helpers: |
| 30 | + - `assets/js/app.js:2047` `normalizeContentGroups(...)` |
| 31 | + - `assets/js/app.js:2068` `buildTopLayerWithContourCut(...)` |
| 32 | +- Mesh builder: |
| 33 | + - `assets/js/app.js:2447` `buildTag3MFMeshData(...)` |
| 34 | + - Base top partition is extruded `0.8 -> 1.0` |
| 35 | + - Content (icons/text) is extruded `1.0 -> 1.2` |
| 36 | + |
| 37 | +### 3MF writer |
| 38 | +- `assets/js/app.js:2584` `build3MFObjectXml(...)` |
| 39 | + - object-level `pid/pindex` |
| 40 | + - triangle-level `pid/p1/p2/p3` |
| 41 | +- `assets/js/app.js:2605` `build3MFModelXml(...)` |
| 42 | + - `<basematerials id="10">` with white+black |
| 43 | + - object `1 = Base`, object `2 = Content`, object `3 = assembly` |
| 44 | + - build currently contains `<item objectid="3" />` |
| 45 | +- `assets/js/app.js:2624` `write3MF(...)` |
| 46 | + |
| 47 | +### Server MIME |
| 48 | +- `server.py:29` supports `.3mf` as `model/3mf`. |
| 49 | + |
| 50 | +## What was tried so far (chronological) |
| 51 | + |
| 52 | +1. **Initial 3MF export from STL mesh path** |
| 53 | + - Used `buildTagMeshData(...)` with forced `pocketMode: solid`. |
| 54 | + - Result: color/material separation unreliable. |
| 55 | + |
| 56 | +2. **Split 3MF mesh pipeline** |
| 57 | + - Added dedicated `buildTag3MFMeshData(...)`. |
| 58 | + - Base keeps full top-layer geometry excluding black regions; content has black regions. |
| 59 | + |
| 60 | +3. **Contour extraction robustness** |
| 61 | + - Added adaptive contour grouping by matching expected filled area. |
| 62 | + - Changed mask fill test from red-channel-only to luma+alpha. |
| 63 | + |
| 64 | +4. **Contour cut approach** |
| 65 | + - Implemented `0.02mm` contour cut around black regions for base top layer. |
| 66 | + - Goal: avoid coplanar ambiguity and force clean separation. |
| 67 | + |
| 68 | +5. **Material encoding hardening** |
| 69 | + - Added explicit base and content materials in `basematerials`. |
| 70 | + - Added per-object and per-triangle material tags. |
| 71 | + - Switched display colors to 6-digit hex (`#FFFFFF`, `#000000`). |
| 72 | + |
| 73 | +6. **Build structure variants** |
| 74 | + - Tried dual build items (`objectid=1` + `objectid=2`) for importer compatibility. |
| 75 | + - User reported icon/text dropping to layer 0 in that variant. |
| 76 | + - Reverted to assembly build item (`objectid=3`) to preserve Z placement. |
| 77 | + |
| 78 | +7. **Height separation** |
| 79 | + - Made content one extra layer above top base layer (`1.0 -> 1.2` vs base top `0.8 -> 1.0`). |
| 80 | + - Geometry became correct, but coloring remained wrong in user workflow. |
| 81 | + |
| 82 | +## Why this is likely still failing |
| 83 | +Slicer/importer behavior differs a lot for: |
| 84 | +- assembly object material inheritance, |
| 85 | +- component-level vs object-level material precedence, |
| 86 | +- per-triangle material parsing on component objects. |
| 87 | + |
| 88 | +The current file is valid enough to load, but importer may flatten color assignment across top faces. |
| 89 | + |
| 90 | +## Repro steps used |
| 91 | +1. Open app, create tag with at least one icon/text. |
| 92 | +2. Export `.3mf` from main download flow. |
| 93 | +3. Import into slicer. |
| 94 | +4. Verify: |
| 95 | + - Z levels (content above base), |
| 96 | + - only icon/text faces get black filament. |
| 97 | + |
| 98 | +## Suggested next experiments (priority order) |
| 99 | + |
| 100 | +1. **Inspect generated `3D/3dmodel.model` from an exported file** |
| 101 | + - Confirm actual triangle counts in object 1 vs 2. |
| 102 | + - Confirm content object has non-zero Z (>= `1.0`). |
| 103 | + - Confirm `pid/pindex` and triangle `pid/p1/p2/p3` values. |
| 104 | + |
| 105 | +2. **Set material on component entries (not just child objects)** |
| 106 | + - Keep assembly object `3`. |
| 107 | + - Add `pid/pindex` directly on `<component objectid="1"...>` and `<component objectid="2"...>`. |
| 108 | + - Some slicers prefer component-level property assignment for assemblies. |
| 109 | + |
| 110 | +3. **Single-object, per-triangle material export** |
| 111 | + - Merge base+content triangles into one object. |
| 112 | + - Assign white/black per triangle using same `pid`. |
| 113 | + - Avoids assembly/component interpretation differences. |
| 114 | + |
| 115 | +4. **Offer slicer-specific export mode** |
| 116 | + - Add selectable 3MF mode: |
| 117 | + - `Assembly (current)` |
| 118 | + - `Dual Build Items` |
| 119 | + - `Single Object + Triangle Materials` |
| 120 | + - Keep geometry generation identical; vary only XML structure. |
| 121 | + |
| 122 | +5. **Add optional tiny XY shrink on content (e.g. 0.01mm)** |
| 123 | + - Reduces face-overlap ambiguity in importers that fuse touching shells. |
| 124 | + |
| 125 | +## Data another AI should collect next |
| 126 | +- One problematic exported `.3mf` file from user. |
| 127 | +- User slicer + version (e.g. Bambu Studio x.y.z, OrcaSlicer x.y.z, PrusaSlicer x.y.z). |
| 128 | +- Screenshot of object/material tree after import. |
| 129 | +- Whether “split to parts/objects” import options are enabled. |
| 130 | + |
| 131 | +## Important note |
| 132 | +Geometry logic is now close to desired behavior. Remaining issue appears to be **3MF importer/material interpretation**, not contour generation alone. |
0 commit comments