bambu-printer-mcp 1.1.87 → 1.1.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,630 @@
1
+ """Scan touch-up helpers for mesh-mode build(): a captured scan's own maps, never Blender.
2
+
3
+ scan_touchup(load_scan(...), colour="colour", normal="normal") takes load_scan's textured mesh (its UVs kept) and
4
+ the declared colour and normal map inputs, and returns a ScanTouchup. Its steps are recorded and run in a fixed
5
+ order by .mesh(): clean (loose pieces, spikes, holes) -> refine (smaller triangles, the body's size kept) -> relief
6
+ (the normal map's measured detail) -> texture relief (opt-in: a textile's stitch pattern from the colour texture)
7
+ -> flatten -> beads and cords (manifold3d union) -> seat.
8
+ .regions() lists the colour regions by id (printed to build.log, with regions.png in the run folder) so the other
9
+ steps can name them. Relief is the measured detail by default; colour says where a feature is, and makes relief
10
+ only through texture_relief(), for a textile the photos show in relief.
11
+ """
12
+ import hashlib
13
+ import json
14
+ from pathlib import Path
15
+
16
+ import numpy as np
17
+ from scipy import sparse
18
+ from scipy.sparse.csgraph import connected_components, dijkstra
19
+
20
+ MAX_TRIANGLES = 240_000 # the engine's inspect step reads at most 250,000
21
+
22
+
23
+ # --- mesh basics (positions welded; UVs kept per face corner) -----------------------------------------------------
24
+
25
+ def _face_normals(V, F, unit=True):
26
+ n = np.cross(V[F[:, 1]] - V[F[:, 0]], V[F[:, 2]] - V[F[:, 0]])
27
+ return n / (np.linalg.norm(n, axis=1, keepdims=True) + 1e-20) if unit else n
28
+
29
+
30
+ def _vertex_normals(V, F):
31
+ fn = _face_normals(V, F, unit=False)
32
+ vn = np.zeros_like(V)
33
+ for k in range(3):
34
+ np.add.at(vn, F[:, k], fn)
35
+ return vn / (np.linalg.norm(vn, axis=1, keepdims=True) + 1e-20)
36
+
37
+
38
+ def _edges(F):
39
+ return np.unique(np.sort(np.concatenate([F[:, [0, 1]], F[:, [1, 2]], F[:, [2, 0]]]), axis=1), axis=0)
40
+
41
+
42
+ def _adjacency(V, F):
43
+ e = _edges(F)
44
+ n = len(V)
45
+ return sparse.coo_matrix((np.ones(2 * len(e)), (np.r_[e[:, 0], e[:, 1]], np.r_[e[:, 1], e[:, 0]])),
46
+ shape=(n, n)).tocsr()
47
+
48
+
49
+ def _vertex_areas(V, F):
50
+ fa = np.linalg.norm(_face_normals(V, F, unit=False), axis=1) / 6
51
+ va = np.zeros(len(V))
52
+ for k in range(3):
53
+ np.add.at(va, F[:, k], fa)
54
+ return va
55
+
56
+
57
+ def _components(mask, A):
58
+ idx = np.flatnonzero(mask)
59
+ label = np.full(len(mask), -1, dtype=np.int64)
60
+ if not len(idx):
61
+ return label, 0
62
+ n, lab = connected_components(A[idx][:, idx], directed=False)
63
+ label[idx] = lab
64
+ return label, n
65
+
66
+
67
+ def _distance(A, V, seeds, limit):
68
+ """Distance over the mesh's edges from a vertex set, up to limit mm (inf beyond)."""
69
+ coo = A.tocoo()
70
+ n = len(V)
71
+ seeds = np.flatnonzero(seeds)
72
+ if not len(seeds):
73
+ return np.full(n, np.inf)
74
+ w = np.linalg.norm(V[coo.row] - V[coo.col], axis=1)
75
+ G = sparse.csr_matrix((np.r_[w, np.full(len(seeds), 1e-12)], (np.r_[coo.row, np.full(len(seeds), n)],
76
+ np.r_[coo.col, seeds])), shape=(n + 1, n + 1))
77
+ return dijkstra(G, directed=True, indices=n, limit=limit)[:n]
78
+
79
+
80
+ def _sample(image, uv):
81
+ h, w = image.shape[:2]
82
+ x = np.clip(uv[:, 0], 0, 1) * (w - 1)
83
+ y = np.clip(1 - uv[:, 1], 0, 1) * (h - 1)
84
+ x0, y0 = np.floor(x).astype(np.int64), np.floor(y).astype(np.int64)
85
+ x1, y1 = np.minimum(x0 + 1, w - 1), np.minimum(y0 + 1, h - 1)
86
+ fx, fy = x - x0, y - y0
87
+ if image.ndim == 3:
88
+ fx, fy = fx[:, None], fy[:, None]
89
+ return (image[y0, x0] * (1 - fx) * (1 - fy) + image[y0, x1] * fx * (1 - fy)
90
+ + image[y1, x0] * (1 - fx) * fy + image[y1, x1] * fx * fy)
91
+
92
+
93
+ def _per_vertex(values, F, FT, n):
94
+ total = np.zeros((n,) + values.shape[1:])
95
+ count = np.zeros(n)
96
+ for k in range(3):
97
+ np.add.at(total, F[:, k], values[FT[:, k]])
98
+ np.add.at(count, F[:, k], 1)
99
+ count = np.maximum(count, 1)
100
+ return total / (count[:, None] if total.ndim == 2 else count)
101
+
102
+
103
+ # --- clean and refine --------------------------------------------------------------------------------------------
104
+
105
+ def _drop_floaters(V, F, FT, keep_fraction=0.02):
106
+ n, label = connected_components(_adjacency(V, F), directed=False)
107
+ if n <= 1:
108
+ return V, F, FT, 0
109
+ fl = label[F[:, 0]]
110
+ area = np.bincount(fl, np.linalg.norm(_face_normals(V, F, unit=False), axis=1), n)
111
+ keep = area >= keep_fraction * area.max()
112
+ used = np.unique(F[keep[fl]])
113
+ remap = np.full(len(V), -1)
114
+ remap[used] = np.arange(len(used))
115
+ return V[used], remap[F[keep[fl]]], None if FT is None else FT[keep[fl]], int((~keep & (area > 0)).sum())
116
+
117
+
118
+ def _remove_spikes(V, F, rounds=4):
119
+ """A vertex standing out of its neighbours' centre by more than 1.5 times their own spread around it (a cone
120
+ sharper than about 34 degrees) is a needle or a fused fin tip: it goes to that centre, repeatedly, so a spike
121
+ recedes from its tip. Bumps and the object's own features rise over several edge lengths and stay."""
122
+ A = _adjacency(V, F)
123
+ deg = np.maximum(np.asarray(A.sum(axis=1)).ravel(), 1)
124
+ moved = np.zeros(len(V), dtype=bool)
125
+ V = V.copy()
126
+ for _ in range(rounds):
127
+ mean = (A @ V) / deg[:, None]
128
+ spread = np.sqrt(np.maximum((A @ (V ** 2).sum(1)) / deg - (mean ** 2).sum(1), 0))
129
+ height = np.abs(np.einsum("ij,ij->i", V - mean, _vertex_normals(V, F)))
130
+ spike = height > 1.5 * spread
131
+ if not spike.any():
132
+ break
133
+ V[spike] = mean[spike]
134
+ moved |= spike
135
+ return V, int(moved.sum())
136
+
137
+
138
+ def _fill_holes(V, F, FT, max_rim=2000):
139
+ directed = np.concatenate([F[:, [0, 1]], F[:, [1, 2]], F[:, [2, 0]]])
140
+ _, inv, cnt = np.unique(np.sort(directed, axis=1), axis=0, return_inverse=True, return_counts=True)
141
+ rim = directed[cnt[inv.reshape(-1)] == 1]
142
+ if not len(rim):
143
+ return V, F, FT, 0
144
+ nxt = {int(a): int(b) for a, b in rim}
145
+ seen, loops = set(), []
146
+ for start in list(nxt):
147
+ loop, v = [], start
148
+ while v not in seen and v in nxt:
149
+ seen.add(v)
150
+ loop.append(v)
151
+ v = nxt[v]
152
+ if v == start and 3 <= len(loop) <= max_rim:
153
+ loops.append(loop)
154
+ corner = {}
155
+ if FT is not None:
156
+ for k in range(3):
157
+ for vi, ti in zip(F[:, k], FT[:, k]):
158
+ corner.setdefault(int(vi), int(ti))
159
+ Vs, Fs, FTs = [V], [F], [FT]
160
+ n = len(V)
161
+ for loop in loops:
162
+ Vs.append(V[loop].mean(axis=0)[None])
163
+ tris = np.array([[loop[(i + 1) % len(loop)], loop[i], n] for i in range(len(loop))])
164
+ Fs.append(tris)
165
+ if FT is not None:
166
+ FTs.append(np.array([[corner[int(a)], corner[int(b)], corner[int(a)]] for a, b, _ in tris]))
167
+ n += 1
168
+ return np.concatenate(Vs), np.concatenate(Fs), None if FT is None else np.concatenate(FTs), len(loops)
169
+
170
+
171
+ def _subdivide(V, F, UV, FT):
172
+ """1-to-4 split. New edge points sit on the curved surface the vertex normals describe (Phong tessellation), so
173
+ original vertices never move and the body is not shrunk; UVs split per corner, so seams stay seams."""
174
+ N = _vertex_normals(V, F)
175
+ nv, nf = len(V), len(F)
176
+ uniq, inv = np.unique(np.sort(np.concatenate([F[:, [0, 1]], F[:, [1, 2]], F[:, [2, 0]]]), axis=1), axis=0,
177
+ return_inverse=True)
178
+ inv = inv.reshape(-1)
179
+ a, b = uniq[:, 0], uniq[:, 1]
180
+ mid = 0.5 * (V[a] + V[b])
181
+ proj = lambda q, p, n: q - np.einsum("ij,ij->i", q - p, n)[:, None] * n # noqa: E731
182
+ mid = 0.25 * mid + 0.75 * 0.5 * (proj(mid, V[a], N[a]) + proj(mid, V[b], N[b]))
183
+ m01, m12, m20 = nv + inv[:nf], nv + inv[nf:2 * nf], nv + inv[2 * nf:]
184
+ F2 = np.concatenate([np.c_[F[:, 0], m01, m20], np.c_[m01, F[:, 1], m12], np.c_[m20, m12, F[:, 2]],
185
+ np.c_[m01, m12, m20]])
186
+ V2 = np.concatenate([V, mid])
187
+ if FT is None:
188
+ return V2, F2, None, None
189
+ nt = len(UV)
190
+ ut, it = np.unique(np.sort(np.concatenate([FT[:, [0, 1]], FT[:, [1, 2]], FT[:, [2, 0]]]), axis=1), axis=0,
191
+ return_inverse=True)
192
+ it = it.reshape(-1)
193
+ t01, t12, t20 = nt + it[:nf], nt + it[nf:2 * nf], nt + it[2 * nf:]
194
+ FT2 = np.concatenate([np.c_[FT[:, 0], t01, t20], np.c_[t01, FT[:, 1], t12], np.c_[t20, t12, FT[:, 2]],
195
+ np.c_[t01, t12, t20]])
196
+ return V2, F2, np.concatenate([UV, 0.5 * (UV[ut[:, 0]] + UV[ut[:, 1]])]), FT2
197
+
198
+
199
+ # --- the normal map's measured relief ----------------------------------------------------------------------------
200
+
201
+ def _uv_islands(UV, FT, w, h):
202
+ """The UV island (1-based) of each triangle: triangles joined through shared texture positions. Positions are
203
+ welded at 1/1000 texel, so an exporter that repeats a vt per corner still yields whole islands; separate islands
204
+ never share a position."""
205
+ from scipy.sparse import coo_matrix
206
+ from scipy.sparse.csgraph import connected_components
207
+ key = np.round(UV * [w, h] * 1000).astype(np.int64)
208
+ _, weld = np.unique(key, axis=0, return_inverse=True)
209
+ t = weld.reshape(-1)[FT]
210
+ n = int(t.max()) + 1
211
+ edges = np.concatenate([t[:, [0, 1]], t[:, [1, 2]]])
212
+ _, comp = connected_components(coo_matrix((np.ones(len(edges)), (edges[:, 0], edges[:, 1])), shape=(n, n)),
213
+ directed=False)
214
+ return comp[t[:, 0]] + 1
215
+
216
+
217
+ def _texture_space(UV, FT, V, F, w, h, islands=False):
218
+ """The texels the mesh's UV triangles cover, and millimetres per texel (median over triangles). With islands,
219
+ the coverage is each texel's UV island id (0 outside every island) instead of a mask."""
220
+ from PIL import Image, ImageDraw
221
+ px = UV[FT] * [w, h]
222
+ ids = _uv_islands(UV, FT, w, h) if islands else np.ones(len(FT), dtype=np.int64)
223
+ cover = Image.new("I", (w, h), 0)
224
+ draw = ImageDraw.Draw(cover)
225
+ for tri, k in zip(px, ids):
226
+ draw.polygon([(x, h - y) for x, y in tri], fill=int(k))
227
+ cover = np.asarray(cover).astype(np.int32)
228
+ e1, e2 = px[:, 1] - px[:, 0], px[:, 2] - px[:, 0]
229
+ tex_area = np.abs(e1[:, 0] * e2[:, 1] - e1[:, 1] * e2[:, 0]) / 2
230
+ area3 = np.linalg.norm(_face_normals(V, F, unit=False), axis=1) / 2
231
+ ok = tex_area > 1e-6
232
+ return (cover if islands else cover > 0), float(np.median(np.sqrt(area3[ok] / tex_area[ok])))
233
+
234
+
235
+ def _height_map(normal_rgb, UV, FT, V, F, longest_mm, finest_mm):
236
+ """Integrates the tangent-space normal map (OpenGL: +X along U, +Y along V, as Object Capture writes it) with a
237
+ screened Poisson solve: the height (mm) of the scan's fine detail over its coarse surface, per texel. Each UV
238
+ island is solved, smoothed and faded on its own, so relief never crosses the atlas gap to a neighbouring island
239
+ (Codex review, 2026-11-11)."""
240
+ from scipy.ndimage import binary_erosion, find_objects, gaussian_filter
241
+ h, w = normal_rgb.shape[:2]
242
+ islands, mm = _texture_space(UV, FT, V, F, w, h, islands=True)
243
+ n = normal_rgb * 2 - 1
244
+ nz = np.maximum(n[..., 2], 0.2)
245
+ g_col = (-n[..., 0] / nz).astype(np.float32)
246
+ g_row = (n[..., 1] / nz).astype(np.float32) # image rows run down: -V
247
+ k0 = np.float32(2 * np.pi * mm / longest_mm)
248
+ pad = int(np.ceil(6 / k0)) # the screened solve decays over 1 / k0 texels
249
+ smooth, fade = max(finest_mm / mm / 2, 0.5), max(1.0, 0.3 / mm)
250
+ erode = max(2, int(round(0.4 / mm))) # seams were integrated apart
251
+ height = np.zeros((h, w), dtype=np.float32)
252
+ for k, box in enumerate(find_objects(islands), start=1):
253
+ if box is None:
254
+ continue
255
+ rows = slice(max(box[0].start - pad, 0), min(box[0].stop + pad, h))
256
+ cols = slice(max(box[1].start - pad, 0), min(box[1].stop + pad, w))
257
+ m = islands[rows, cols] == k
258
+ hc, wc = m.shape
259
+ kx = (2 * np.pi * np.fft.rfftfreq(wc)).astype(np.float32)[None, :]
260
+ ky = (2 * np.pi * np.fft.fftfreq(hc)).astype(np.float32)[:, None]
261
+ spectrum = -(1j * kx * np.fft.rfft2(np.where(m, g_col[rows, cols], 0)) +
262
+ 1j * ky * np.fft.rfft2(np.where(m, g_row[rows, cols], 0))) / (kx ** 2 + ky ** 2 + k0 ** 2)
263
+ part = np.fft.irfft2(spectrum, s=(hc, wc)).astype(np.float32) * np.float32(mm)
264
+ mf_ = m.astype(np.float32)
265
+ part = gaussian_filter(part * mf_, smooth) / np.maximum(gaussian_filter(mf_, smooth), 1e-3)
266
+ inner = gaussian_filter(binary_erosion(m, iterations=erode).astype(np.float32), fade)
267
+ height[rows, cols] += part * inner * mf_
268
+ return height, mm
269
+
270
+
271
+ def _texture_band(rgb, UV, FT, V, F, finest_mm, longest_mm):
272
+ """The colour texture's luminance between finest_mm and longest_mm (a textile's stitch or weave scale), per
273
+ texel. Each UV island is filtered on its own, normalised by its own coverage, so neither a seam's padding nor a
274
+ neighbouring island packed within the blur radius bleeds in (Codex review, 2026-11-11); the scan's baked shading
275
+ is longer than longest_mm and drops out."""
276
+ from scipy.ndimage import find_objects, gaussian_filter
277
+ h, w = rgb.shape[:2]
278
+ islands, mm = _texture_space(UV, FT, V, F, w, h, islands=True)
279
+ lum = rgb[..., :3] @ np.array([0.2126, 0.7152, 0.0722], dtype=np.float32)
280
+ fine, coarse = max(finest_mm / 2 / mm, 0.5), max(longest_mm / 2 / mm, 0.5)
281
+ pad = int(np.ceil(4 * coarse))
282
+ band = np.zeros((h, w), dtype=np.float32)
283
+ for k, box in enumerate(find_objects(islands), start=1):
284
+ if box is None:
285
+ continue
286
+ rows = slice(max(box[0].start - pad, 0), min(box[0].stop + pad, h))
287
+ cols = slice(max(box[1].start - pad, 0), min(box[1].stop + pad, w))
288
+ m = (islands[rows, cols] == k).astype(np.float32)
289
+ lm = lum[rows, cols] * m
290
+
291
+ def blur(sigma):
292
+ return gaussian_filter(lm, sigma) / np.maximum(gaussian_filter(m, sigma), 1e-3)
293
+ band[rows, cols] += (blur(fine) - blur(coarse)) * m
294
+ return band
295
+
296
+
297
+ # --- colour regions ----------------------------------------------------------------------------------------------
298
+
299
+ def _lab(rgb):
300
+ c = np.where(rgb > 0.04045, ((rgb + 0.055) / 1.055) ** 2.4, rgb / 12.92)
301
+ xyz = c @ np.array([[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]]).T
302
+ f = np.cbrt(np.maximum(xyz / [0.9505, 1.0, 1.089], 0.008856))
303
+ return np.stack([116 * f[:, 1] - 16, 500 * (f[:, 0] - f[:, 1]), 200 * (f[:, 1] - f[:, 2])], axis=1)
304
+
305
+
306
+ def _regions(V, F, colours, clusters, min_area, max_regions=40):
307
+ from scipy.cluster.vq import kmeans2
308
+ lab = _lab(colours) * [0.5, 1.0, 1.0] # shading moves lightness more than hue
309
+ rng = np.random.default_rng(7)
310
+ centres, _ = kmeans2(lab[rng.choice(len(lab), min(len(lab), 40000), replace=False)], clusters, seed=rng,
311
+ minit="++", iter=30)
312
+ cluster = np.argmin(((lab[:, None] - centres[None]) ** 2).sum(-1), axis=1)
313
+ A = _adjacency(V, F)
314
+ va = _vertex_areas(V, F)
315
+ piece = np.full(len(V), -1)
316
+ count = 0
317
+ for c in range(clusters):
318
+ label, n = _components(cluster == c, A)
319
+ piece[label >= 0] = label[label >= 0] + count
320
+ count += n
321
+ area = np.bincount(piece, va, count)
322
+ body = int(np.argmax(area))
323
+ kept = sorted((p for p in range(count) if p != body and area[p] >= min_area), key=lambda p: -area[p])[:max_regions]
324
+ ids = {body: 0, **{p: i + 1 for i, p in enumerate(kept)}}
325
+ label = np.array([ids.get(p, -1) for p in range(count)])[piece]
326
+ e = _edges(F)
327
+ cross = label[e[:, 0]] != label[e[:, 1]]
328
+ pairs = np.concatenate([label[e[cross]], label[e[cross]][:, ::-1]])
329
+ vn = _vertex_normals(V, F)
330
+ out = []
331
+ for rid in range(len(ids)):
332
+ sel = label == rid
333
+ w = va[sel]
334
+ centre = (V[sel] * w[:, None]).sum(0) / w.sum()
335
+ normal = (vn[sel] * w[:, None]).sum(0)
336
+ normal /= np.linalg.norm(normal) + 1e-20
337
+ rel = V[sel] - centre
338
+ span = rel @ np.linalg.svd(rel * np.sqrt(w)[:, None], full_matrices=False)[2].T
339
+ around = np.unique(pairs[pairs[:, 0] == rid][:, 1])
340
+ out.append({"id": rid, "colour": "#%02x%02x%02x" % tuple(int(round(v * 255)) for v in colours[sel].mean(0)),
341
+ "area_mm2": round(float(w.sum()), 1), "centre_mm": [round(float(v), 2) for v in centre],
342
+ "normal": [round(float(v), 3) for v in normal], "length_mm": round(float(np.ptp(span[:, 0])), 2),
343
+ "width_mm": round(float(np.ptp(span[:, 1])), 2),
344
+ "flatness_rms_mm": round(float(np.sqrt(np.average(span[:, 2] ** 2, weights=w))), 3),
345
+ "inside": int(around[0]) if rid and len(around) == 1 and around[0] >= 0 else None})
346
+ return label, out
347
+
348
+
349
+ def _picture(V, F, label, regions, path):
350
+ """The scan from four sides, each region in its own colour with its id written on it."""
351
+ from PIL import Image, ImageDraw
352
+ palette = np.array([[0.75, 0.75, 0.72]] + [np.random.default_rng(i).uniform(0.15, 0.95, 3) for i in range(1, len(regions) + 1)])
353
+ fl = np.where((label[F] == label[F][:, :1]).all(1), label[F[:, 0]], -1)
354
+ colours = np.where(fl[:, None] >= 0, palette[np.clip(fl, 0, None)], 0.5)
355
+ lo, hi = V.min(0), V.max(0)
356
+ centre, radius = (lo + hi) / 2, float(np.linalg.norm(hi - lo) / 2)
357
+ tiles = []
358
+ for name, az, el in (("front", -90, 25), ("right", 0, 25), ("back", 90, 25), ("top", -90, 89)):
359
+ a, b = np.radians([az, el])
360
+ toward = np.array([np.cos(b) * np.cos(a), np.cos(b) * np.sin(a), np.sin(b)])
361
+ fwd = -toward
362
+ right = np.cross(fwd, [0, 0, 1] if abs(toward[2]) < 0.999 else [0, 1, 0])
363
+ right /= np.linalg.norm(right)
364
+ up = np.cross(right, fwd)
365
+ eye = centre + toward * radius * 5
366
+ size, focal = 900, 4.6
367
+ rel = V[F] - eye
368
+ n = _face_normals(V, F)
369
+ vis = np.einsum("ij,ij->i", n, rel.mean(1)) < 0
370
+ z = rel[vis] @ fwd
371
+ x = (rel[vis] @ right) / z * focal * size / 2 + size / 2
372
+ y = -(rel[vis] @ up) / z * focal * size / 2 + size / 2
373
+ shade = 0.55 + 0.45 * np.clip(n[vis] @ (-fwd * 0.8 + up * 0.6), 0, 1)
374
+ rgb = (np.clip(colours[vis] * shade[:, None], 0, 1) * 255).astype(np.uint8)
375
+ im = Image.new("RGB", (size, size), (167, 167, 168))
376
+ d = ImageDraw.Draw(im)
377
+ for i in np.argsort(-z.mean(1)):
378
+ d.polygon([(x[i, 0], y[i, 0]), (x[i, 1], y[i, 1]), (x[i, 2], y[i, 2])], fill=tuple(rgb[i]))
379
+ for r in regions[1:]:
380
+ c = np.asarray(r["centre_mm"]) - eye
381
+ if np.dot(r["normal"], toward) > 0.1:
382
+ zc = c @ fwd
383
+ d.text(((c @ right) / zc * focal * size / 2 + size / 2, -(c @ up) / zc * focal * size / 2 + size / 2),
384
+ str(r["id"]), fill=(0, 0, 0), stroke_width=2, stroke_fill=(255, 255, 255))
385
+ d.text((8, 8), name, fill=(0, 0, 0))
386
+ tiles.append(im)
387
+ sheet = Image.new("RGB", (1800, 1800))
388
+ for i, t in enumerate(tiles):
389
+ sheet.paste(t, ((i % 2) * 900, (i // 2) * 900))
390
+ sheet.save(path)
391
+
392
+
393
+ # --- the touch-up ------------------------------------------------------------------------------------------------
394
+
395
+ class ScanTouchup:
396
+ def __init__(self, scan, colour=None, normal=None, edge_mm=0.4, clusters=6, min_region_mm2=3.0, clean=True):
397
+ """scan: load_scan's trimesh (millimetres, Z up, its UVs kept). colour, normal: the declared files' paths."""
398
+ import trimesh # noqa: F401 (load_scan's type)
399
+ V = np.asarray(scan.vertices, dtype=np.float64)
400
+ F = np.asarray(scan.faces, dtype=np.int64)
401
+ uv = getattr(scan.visual, "uv", None)
402
+ UV = np.asarray(uv, dtype=np.float64) if uv is not None and len(uv) == len(V) else None
403
+ FT = F.copy() if UV is not None else None
404
+ # Weld positions split at UV seams; every face corner keeps its UV.
405
+ key = np.round(V * 1e6).astype(np.int64)
406
+ _, first, inverse = np.unique(key, axis=0, return_index=True, return_inverse=True)
407
+ V, F = V[first], inverse.reshape(-1)[F]
408
+ good = np.linalg.norm(_face_normals(V, F, unit=False), axis=1) > 1e-12
409
+ F = F[good]
410
+ FT = FT[good] if FT is not None else None
411
+ self.changes, self.stats = [], {"input_triangles": int(len(F))}
412
+ if clean:
413
+ V, F, FT, pieces = _drop_floaters(V, F, FT)
414
+ V, spikes = _remove_spikes(V, F)
415
+ V, F, FT, holes = _fill_holes(V, F, FT)
416
+ self.stats.update(loose_pieces_removed=pieces, spike_points_moved=spikes, holes_closed=holes)
417
+ for n, text in ((pieces, "loose piece(s) removed"), (spikes, "spike point(s) pulled back into the surface"),
418
+ (holes, "hole(s) closed")):
419
+ if n:
420
+ self.changes.append(("changed", f"{n} {text}"))
421
+ e = _edges(F)
422
+ edge = float(np.linalg.norm(V[e[:, 0]] - V[e[:, 1]], axis=1).mean())
423
+ levels = 0
424
+ while edge > edge_mm * 1.25 and len(F) * 4 <= MAX_TRIANGLES:
425
+ V, F, UV, FT = _subdivide(V, F, UV, FT)
426
+ edge /= 2
427
+ levels += 1
428
+ self.stats.update(refine_levels=levels, mean_edge_mm=round(edge, 3), triangles=int(len(F)))
429
+ self.V, self.F, self.UV, self.FT = V, F, UV, FT
430
+ self.colour_path, self.normal_path = colour, normal
431
+ self._clusters, self._min_area = clusters, min_region_mm2
432
+ self._label = self._regions = None
433
+ self._flat, self._parts, self._seat, self._texture = [], [], None, None
434
+
435
+ def _image(self, path, mode):
436
+ from PIL import Image
437
+ return np.asarray(Image.open(path).convert(mode), dtype=np.float32) / 255
438
+
439
+ def regions(self, picture="regions.png"):
440
+ """The colour regions, largest first; 0 is the body. Printed to build.log; picture saved in the run folder."""
441
+ if self._regions is None:
442
+ if self.colour_path is None or self.UV is None:
443
+ raise ValueError("regions need the scan's UVs and its colour map as a declared input")
444
+ colours = np.clip(_per_vertex(_sample(self._image(self.colour_path, "RGB"), self.UV), self.F, self.FT,
445
+ len(self.V)), 0, 1)
446
+ self._label, self._regions = _regions(self.V, self.F, colours, self._clusters, self._min_area)
447
+ signature = hashlib.sha256(self._label.astype(np.int32).tobytes()).hexdigest()[:12]
448
+ print(json.dumps({"scan_regions": self._regions, "signature": signature}))
449
+ if picture:
450
+ _picture(self.V, self.F, self._label, self._regions, Path(picture))
451
+ return self._regions
452
+
453
+ def _mask(self, ids):
454
+ self.regions(picture=None) if self._regions is None else None
455
+ ids = [ids] if isinstance(ids, (int, np.integer)) else list(ids)
456
+ for i in ids:
457
+ if not 0 < i < len(self._regions):
458
+ raise ValueError(f"no region {i} (1..{len(self._regions) - 1}; 0 is the body)")
459
+ return np.isin(self._label, ids)
460
+
461
+ def flatten(self, ids, shape="plane", feather_mm=1.5, max_move_mm=1.0, name="Region"):
462
+ """Moves regions the photos show flat (a card, a label) onto one fitted surface: "plane", or "curved" (a
463
+ quadric) for a bent card. Patches inside them (printed ink) come along; the move fades out over feather_mm
464
+ inside their rim and never exceeds max_move_mm."""
465
+ mask = self._mask(ids)
466
+ A = _adjacency(self.V, self.F)
467
+ outside, n = _components(~mask, A)
468
+ if n > 1:
469
+ mask |= (outside >= 0) & (outside != np.argmax(np.bincount(outside[outside >= 0])))
470
+ self._flat.append((mask, shape, feather_mm, max_move_mm, name))
471
+ return self
472
+
473
+ def bead(self, region, diameter_mm=None, proud_mm=None, name="Bead"):
474
+ """A sphere seated on a round region (an eye, a button): by default the region's own size, standing out
475
+ 35% of its diameter."""
476
+ self._parts.append(("bead", self._mask(region), diameter_mm, proud_mm, name))
477
+ return self
478
+
479
+ def cord(self, region, diameter_mm=None, proud_mm=None, name="Cord"):
480
+ """A round cord laid along a thread-like region (a stitched mustache, a seam), following its own curve."""
481
+ self._parts.append(("cord", self._mask(region), diameter_mm, proud_mm, name))
482
+ return self
483
+
484
+ def texture_relief(self, height_mm, regions=None, finest_mm=0.4, longest_mm=3.0, name="Textile"):
485
+ """Raises a textile's stitch or weave pattern from the colour texture: for fabric, knit or crochet the photos
486
+ show in relief that the scan did not capture (its normal map holds almost none). Off unless called; never
487
+ for hard objects, printed graphics or labels. The luminance between finest_mm and longest_mm is normalised
488
+ over the textile and scaled so its peaks stand about height_mm / 2 out and in (lit loops up, shadowed gaps
489
+ down). It goes on `regions` (default: every region not flattened, beaded or corded), fading out over 1 mm
490
+ from those and from the seat band. Listed as assumed."""
491
+ if not 0 < float(height_mm) <= 2:
492
+ raise ValueError("texture_relief height_mm must be above 0 and at most 2")
493
+ if not 0 < finest_mm < longest_mm:
494
+ raise ValueError("texture_relief needs 0 < finest_mm < longest_mm")
495
+ if self.colour_path is None or self.UV is None:
496
+ raise ValueError("texture_relief needs the scan's UVs and its colour map as a declared input")
497
+ self._texture = (float(height_mm), None if regions is None else self._mask(regions), float(finest_mm),
498
+ float(longest_mm), name)
499
+ return self
500
+
501
+ def seat(self, height_mm):
502
+ """Cuts a flat base height_mm above the lowest point and sets it on z = 0."""
503
+ self._seat = float(height_mm)
504
+ return self
505
+
506
+ def mesh(self, relief_gain=1.0, relief_longest_mm=8.0, relief_finest_mm=0.3):
507
+ """Runs the recorded steps and returns the closed trimesh. relief_gain 1 adds the normal map's detail at the
508
+ height it measured; 0 adds none. Prints the changes to build.log."""
509
+ import manifold3d as mf
510
+ import trimesh
511
+ V, F = self.V.copy(), self.F
512
+ A = _adjacency(V, F)
513
+ keep_clear = np.zeros(len(V), dtype=bool)
514
+ for mask, *_ in self._flat:
515
+ keep_clear |= mask
516
+ for _, mask, *_ in self._parts:
517
+ keep_clear |= mask
518
+ if relief_gain and self.normal_path and self.UV is not None:
519
+ height, mm = _height_map(self._image(self.normal_path, "RGB"), self.UV, self.FT, V, F,
520
+ relief_longest_mm, relief_finest_mm)
521
+ h = _per_vertex(_sample(height, self.UV), F, self.FT, len(V))
522
+ del height
523
+ fade = np.clip(_distance(A, V, keep_clear, 1.0), 0, 1) if keep_clear.any() else np.ones(len(V))
524
+ if self._seat is not None:
525
+ fade *= np.clip(V[:, 2] - V[:, 2].min() - self._seat, 0, 1)
526
+ V = V + (relief_gain * h * fade)[:, None] * _vertex_normals(V, F)
527
+ rms = float(np.sqrt(np.mean(h ** 2)))
528
+ self.stats["relief_measured_rms_mm"] = round(rms, 4)
529
+ self.changes.append(("changed" if relief_gain == 1 else "assumed",
530
+ f"surface detail from the scan's normal map, {rms * relief_gain:.2f} mm rms"
531
+ + ("" if relief_gain == 1 else f" ({relief_gain:g}x what it measured)")))
532
+ if self._texture is not None:
533
+ height_mm, include, finest, longest, name = self._texture
534
+ band = _texture_band(self._image(self.colour_path, "RGB"), self.UV, self.FT, V, F, finest, longest)
535
+ b = _per_vertex(_sample(band, self.UV), F, self.FT, len(V))
536
+ del band
537
+ allowed = ~keep_clear if include is None else include & ~keep_clear
538
+ fade = np.clip(_distance(A, V, ~allowed, 1.0), 0, 1) if (~allowed).any() else np.ones(len(V))
539
+ if self._seat is not None:
540
+ fade *= np.clip(V[:, 2] - V[:, 2].min() - self._seat, 0, 1)
541
+ scale = float(np.percentile(np.abs(b[allowed]), 90)) if allowed.any() else 0.0
542
+ if scale > 0:
543
+ h = 0.5 * height_mm * np.clip(b / scale, -1, 1)
544
+ V = V + (h * fade)[:, None] * _vertex_normals(V, F)
545
+ self.stats["texture_relief_rms_mm"] = round(float(np.sqrt(np.mean((h * fade)[allowed] ** 2))), 3)
546
+ self.changes.append(("assumed", f"{name}: stitch pattern raised from the colour texture, "
547
+ f"{height_mm:g} mm peak to peak, on the textile only"))
548
+ vn = _vertex_normals(V, F)
549
+ for mask, shape, feather, cap, name in self._flat:
550
+ pts = V[mask]
551
+ centre = pts.mean(0)
552
+ axes = np.linalg.svd(pts - centre, full_matrices=False)[2]
553
+ n = axes[2] * (1 if axes[2] @ vn[mask].mean(0) >= 0 else -1)
554
+ u, v, w = (V - centre) @ axes[0], (V - centre) @ axes[1], (V - centre) @ n
555
+ basis = np.c_[np.ones(len(V)), u, v] if shape == "plane" else np.c_[np.ones(len(V)), u, v, u * u, u * v, v * v]
556
+ target = basis @ np.linalg.lstsq(basis[mask], w[mask], rcond=None)[0]
557
+ weight = np.where(mask, np.clip(_distance(A, V, ~mask, feather) / max(feather, 1e-6), 0, 1), 0)
558
+ V = V + np.clip((target - w) * weight, -cap, cap)[:, None] * n
559
+ self.changes.append(("changed", f"{name}: made {'flat' if shape == 'plane' else 'smooth'} "
560
+ f"({float(np.sqrt(np.mean((target - w)[mask] ** 2))):.2f} mm rms of scan wobble removed)"))
561
+ vn = _vertex_normals(V, F)
562
+ body = mf.Manifold(mf.Mesh(vert_properties=np.ascontiguousarray(V, np.float32),
563
+ tri_verts=np.ascontiguousarray(F, np.uint32)))
564
+ if body.status() != mf.Error.NoError:
565
+ raise ValueError(f"the cleaned scan is not a closed solid ({body.status().name})")
566
+ shapes = []
567
+ for kind, mask, d, proud, name in self._parts:
568
+ pts, nrm = V[mask], vn[mask]
569
+ centre = pts.mean(0)
570
+ n = nrm.mean(0)
571
+ n /= np.linalg.norm(n) + 1e-20
572
+ flat = (pts - centre) - np.outer((pts - centre) @ n, n)
573
+ if kind == "bead":
574
+ d = float(d or 2 * np.sqrt(2) * np.sqrt((flat ** 2).sum(1).mean()))
575
+ proud = 0.35 * d if proud is None else float(proud)
576
+ surface = V[np.argmin(np.linalg.norm(V - centre, axis=1))]
577
+ shapes.append(mf.Manifold.sphere(d / 2, 64).translate(tuple(surface + (proud - d / 2) * n)))
578
+ self.changes.append(("assumed", f"{name}: {d:.1f} mm bead, {proud:.1f} mm proud, placed from the scan's colour"))
579
+ continue
580
+ axis = np.linalg.svd(flat, full_matrices=False)[2][0]
581
+ side = np.cross(n, axis)
582
+ s, t = flat @ axis, flat @ side
583
+ lo, hi = np.percentile(s, [1, 99])
584
+ step = max(0.5, (hi - lo) / 24)
585
+ stations, widths = [], []
586
+ for a in np.arange(lo, hi + 1e-9, step):
587
+ sel = np.abs(s - a) <= 0.75 * step
588
+ if sel.sum() >= 3:
589
+ stations.append((a, np.median(t[sel])))
590
+ widths.append(np.percentile(t[sel], 95) - np.percentile(t[sel], 5))
591
+ st = np.array(stations)
592
+ if len(st) >= 5:
593
+ st[:, 1] = np.convolve(np.pad(st[:, 1], 1, mode="edge"), [0.25, 0.5, 0.25], mode="valid")
594
+ d = float(d or np.median(widths))
595
+ proud = 0.45 * d if proud is None else float(proud)
596
+ path = centre + st[:, :1] * axis + st[:, 1:2] * side
597
+ near = [int(np.argmin(np.linalg.norm(flat - (p - centre - ((p - centre) @ n) * n), axis=1))) for p in path]
598
+ path = path + ((pts[near] - path) @ n)[:, None] * n
599
+ normals = nrm[near] / (np.linalg.norm(nrm[near], axis=1, keepdims=True) + 1e-20)
600
+ m = len(path)
601
+ taper = np.minimum(1.0, 0.7 + 0.3 * np.minimum(np.arange(m), np.arange(m)[::-1]) / max(1, min(3, m // 2)))
602
+ radii = d / 2 * taper
603
+ centres = path + (proud * taper - radii)[:, None] * normals
604
+ balls = [mf.Manifold.sphere(float(r), 32).translate(tuple(c)) for c, r in zip(centres, radii)]
605
+ shapes.append(mf.Manifold.batch_boolean([mf.Manifold.batch_hull([balls[i], balls[i + 1]]) for i in range(m - 1)]
606
+ or balls, mf.OpType.Add))
607
+ self.changes.append(("assumed", f"{name}: {d:.1f} mm cord, {hi - lo:.0f} mm along the scan's line, {proud:.1f} mm proud"))
608
+ if shapes:
609
+ body = mf.Manifold.batch_boolean([body] + shapes, mf.OpType.Add)
610
+ if self._seat is not None:
611
+ cut = float(body.bounding_box()[2]) + self._seat
612
+ body = body.trim_by_plane((0.0, 0.0, 1.0), cut).translate((0.0, 0.0, -cut))
613
+ self.changes.append(("changed", f"flat seat cut {self._seat:g} mm up"))
614
+ out = body.to_mesh()
615
+ result = trimesh.Trimesh(np.asarray(out.vert_properties)[:, :3], np.asarray(out.tri_verts), process=False)
616
+ print(json.dumps({"scan_touchup": {"changes": [{"tag": t, "text": x} for t, x in self.changes], "stats": self.stats}}))
617
+ return result
618
+
619
+
620
+ def scan_touchup_factory(inputs):
621
+ """scan_touchup(scan, colour=None, normal=None, **settings) for build(): map names are declared inputs."""
622
+ declared = dict(inputs)
623
+
624
+ def scan_touchup(scan, *, colour=None, normal=None, edge_mm=0.4, clusters=6, min_region_mm2=3.0, clean=True):
625
+ for name in (colour, normal):
626
+ if name is not None and name not in declared:
627
+ raise ValueError(f"scan_touchup: {name!r} is not a declared input")
628
+ return ScanTouchup(scan, declared.get(colour) if colour else None, declared.get(normal) if normal else None,
629
+ edge_mm=edge_mm, clusters=clusters, min_region_mm2=min_region_mm2, clean=clean)
630
+ return scan_touchup
package/src/cad/worker.py CHANGED
@@ -102,7 +102,9 @@ def main():
102
102
  tree, declaration, merged = parameters(source, json.loads(Path(request['parameters']).read_text()))
103
103
  declaration.value = ast.Name(id='__cad_parameters__', ctx=ast.Load())
104
104
  ast.fix_missing_locations(tree)
105
- namespace = {'__name__': 'cad_design', '__file__': request['script'], '__cad_parameters__': merged, 'INPUTS': request.get('inputs', {}), 'load_scan': scan_loader(request.get('inputs', {}))}
105
+ from scan_touchup import scan_touchup_factory
106
+ namespace = {'__name__': 'cad_design', '__file__': request['script'], '__cad_parameters__': merged, 'INPUTS': request.get('inputs', {}), 'load_scan': scan_loader(request.get('inputs', {})),
107
+ 'scan_touchup': scan_touchup_factory(request.get('inputs', {}))}
106
108
  exec(compile(tree, request['script'], 'exec'), namespace)
107
109
  shape = namespace['build']()
108
110
  out = Path(request['output']) / request['name']
package/src/cad-engine.ts CHANGED
@@ -330,6 +330,7 @@ export class CadEngine {
330
330
  "requirements.lock",
331
331
  "worker.py",
332
332
  "geometry.py",
333
+ "scan_touchup.py",
333
334
  "process.ts",
334
335
  "storage.ts",
335
336
  "serial.ts",