Skip to content

Commit cb7ddad

Browse files
author
William
committed
docs: refactor project structure and update documentation
- Refactored the project by separating concerns: moved CSS to `assets/css/app.css` and JavaScript logic to `assets/js/app.js`. - Cleaned up `index.html` to contain only the core markup. - Updated `README.md` with information about the new app structure and supported export formats (SVG, STL, and 3MF). - Added details regarding 3MF multi-color object support for slicers.
1 parent 4d429f3 commit cb7ddad

31 files changed

Lines changed: 30595 additions & 4304 deletions

‎3MF_COLORING_HANDOFF.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
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.

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
# InfinityGrid Sticker Designer
22

3+
## App structure
4+
- `index.html` now keeps the markup only.
5+
- `assets/css/app.css` contains UI styles.
6+
- `assets/js/app.js` contains app logic and exporters.
7+
8+
## Export formats
9+
- From the editor footer, choose format in the dropdown and click the download icon.
10+
- Supported:
11+
- `SVG`
12+
- `STL`
13+
- `3MF` (separate Base and Content objects for easier multi-color assignment in slicers)
14+
315
## Can GitHub host this Docker image?
416
- **Yes** for image storage: use **GitHub Container Registry (GHCR)**.
517
- **No** for always-on container hosting from your repo alone. You still run containers on your laptop (or another server).

‎__pycache__/server.cpython-313.pyc‎

11.1 KB
Binary file not shown.

0 commit comments

Comments
 (0)