bambu-printer-mcp 1.1.88 → 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.
@@ -100,7 +100,7 @@ export const CAD_TOOLS = [
100
100
  },
101
101
  {
102
102
  name: "cad_run",
103
- description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six renders and a contact sheet; valid geometry is not a physical-fit or motion proof.",
103
+ description: "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six renders and a contact sheet, the closest approach between every pair of solids (bodies), problems, and what was checked and not checked; valid means only that the exported geometry is sound, never that the part fits, holds, moves or prints.",
104
104
  inputSchema: {
105
105
  type: "object",
106
106
  properties: {
@@ -189,6 +189,17 @@ export const CAD_TOOLS = [
189
189
  type: "object",
190
190
  additionalProperties: { type: ["boolean", "null"] },
191
191
  },
192
+ bodies: {
193
+ type: "object",
194
+ description: "Solid mode: near pairs of solids screened on tessellations and measured exactly on the STEP where the screen cannot clear them, against a print-in-place clearance from P.print_in_place_clearance_mm or 0.3 mm (touching or overlap only when P.print_in_place is false); touching or overlapping pairs, pairs under the clearance, pairs only screened, solids below the print plate (Z = 0) or above it with no solid under them that reaches it, and labelled bodies that are not exactly one solid.",
195
+ },
196
+ problems: {
197
+ type: "array",
198
+ items: { type: "string" },
199
+ description: "Defects found by the checks that valid does not cover (fused or too-close bodies, a severed body, a solid below the plate or starting in mid-air, pairs not measured). Each kind lists up to eight, then a count of the rest. Empty when none were found, which is not a pass on anything listed in not_checked.",
200
+ },
201
+ checked: { type: "array", items: { type: "string" } },
202
+ not_checked: { type: "array", items: { type: "string" } },
192
203
  renders: { type: "object", additionalProperties: { type: "string" } },
193
204
  seconds: { type: "number" },
194
205
  }, [
@@ -278,13 +289,14 @@ export const CAD_DESIGN_PROMPT = {
278
289
  title: "Parametric code-CAD design",
279
290
  description: "MCP-owned rules for headless build123d designs and one-call parameter revisions.",
280
291
  text: `Use code-CAD for dimensioned functional designs and parameter edits. Build in millimetres with build123d 0.13.0; the MCP owns the Python environment, execution, export, validation and rendering. Check cad_status and use cad_setup with install: true when needed. No Blender, Fusion, network or printer access is available to your script.
281
- Declare exactly one top-level P = {...} dictionary of JSON-compatible literal named parameters. Put every functional dimension in P; derive geometry from P. Define build() to return a build123d Shape or Compound of disjoint solid parts. Do not put construction or exports in a __main__ block: cad_run calls build() and exports the result. Imports, functions and derived P entries are fine. Parameters are applied to the literal defaults before derived expressions execute. For solid designs without inputs, the script and parameters file alone reconstruct it. For input-dependent designs, declare inputs as an array of {name, path} files: cad_run snapshots only those allowed files, exposes INPUTS[alias] to your script, and saves an inputs manifest. Retain the snapshots too for recovery; subsequent script_path edits reuse them unless inputs is explicitly supplied. No other personal files are readable. For a mesh-only experiment use mode: "mesh" and return a trimesh.Trimesh from build(); it exports and checks STL plus six renders, with step: null and an explicit reason. It does not manufacture a fake parametric STEP or promise scan-cleanup capability.
292
+ Declare exactly one top-level P = {...} dictionary of JSON-compatible literal named parameters. Put every functional dimension in P; derive geometry from P. Define build() to return a build123d Shape or Compound of disjoint solid parts. When a design has separate bodies (print-in-place parts, a captive wheel, links of a fabric), return Compound(children=[...]) with a label on each body: cad_run then checks that each labelled body is exactly one solid, so a piece cut off one body cannot hide behind two bodies fused into one. Near pairs of solids are screened and, where the screen cannot clear them, measured exactly against P["print_in_place_clearance_mm"] when you declare it, else 0.3 mm. If the bodies are shown assembled rather than printed in place (a shaft in its hole at a fit clearance), set P["print_in_place"] = False: only touching or overlap is then a problem. Export in print orientation with the plate at Z = 0: a solid below it, or above it with nothing under it that reaches it, is a problem. Do not put construction or exports in a __main__ block: cad_run calls build() and exports the result. Imports, functions and derived P entries are fine. Parameters are applied to the literal defaults before derived expressions execute. For solid designs without inputs, the script and parameters file alone reconstruct it. For input-dependent designs, declare inputs as an array of {name, path} files: cad_run snapshots only those allowed files, exposes INPUTS[alias] to your script, and saves an inputs manifest. Retain the snapshots too for recovery; subsequent script_path edits reuse them unless inputs is explicitly supplied. No other personal files are readable. For a mesh-only experiment use mode: "mesh" and return a trimesh.Trimesh from build(); it exports and checks STL plus six renders, with step: null and an explicit reason. It does not manufacture a fake parametric STEP or promise scan-cleanup capability.
282
293
  Call cad_run with script, output_dir and a plain name. It saves <name>.py and <name>.parameters.json before running, then exports <name>.stl and <name>.step in a fresh subfolder. For an edit, one cad_run with script_path pointing to the earlier .py, parameters containing just the changed dimension, output_dir and name regenerates it without resending the script. Existing parameter values are retained; unknown names and type changes are refused. A killed run can be retried from its checkpoint in a new workspace; mutations are never replayed automatically.
283
294
  Captured mesh preparation: load_scan(name, source_units="m" or "mm", up_axis="x"|"-x"|"y"|"-y"|"z"|"-z", ground=True) is provided to build(). Name must be a declared input. Declare source units and the object's usage-up axis explicitly: the helper converts metres to millimetres, applies a rigid up-axis rotation and translates the lowest Z to zero; it never guesses scale or fits to calipers. Geometry/texture references must be declared inputs too; snapshots preserve distinct original filenames. Exports must be millimetres, Z up, in the orientation the object is used.
284
295
  Fit reference workflow: return load_scan("scan", source_units="m", up_axis="y") from build() in mode: "mesh" to export an unchanged, prepared reference STL for cad_check_fit. Declare every linked OBJ/MTL/texture asset. If you crop, simplify, fill, or otherwise alter this reference, report exactly what you excluded/changed and that the fit check proves only that reduced reference in the stated pose. A fit check against a scan is information; it must never resize or override an interface specified by measured dimensions. Keep those measured interfaces and report the discrepancy.
285
296
  Result selection and edits: set final: true only on the result you select. cad-result.json in each immediate run folder is protected from script writes and retains final, completed_at, lineage_id (source hash), full checks and artifact paths; clients can discover the latest completed final record after restart without rebuilding. Final is a selection marker, not a replacement for valid/checks. Queued calls may expire with cad-queue-timeout before dispatch; do not automatically replay. Unchanged declared files reuse a read-only content-addressed bundle under output_dir/.cad-inputs, preserving filenames and restricting reads to that bundle. Keep this shared cache with the saved runs.
286
297
  Mesh cleanup workflow: return a trimesh.Trimesh in mode: "mesh". Load the prepared mesh, fit needed geometry with NumPy/SciPy, rebuild regular sections/features with build123d or manifold3d CrossSection/extrusion/revolve, and combine meshes with manifold3d booleans. scikit-image supplies marching cubes for voxel/SDF work; Shapely supplies planar operations; Pillow supplies image/texture reads. Keep numeric choices in P and regenerate from declared inputs. Validate closure, winding, manifold status, dimensions and all six views using cad_run. What to regularise, infer, preserve or label comes from the caller's cleanup rules, not this engine prompt.
287
- The result includes paths, millimetre bounds/size, mesh and STEP volumes, solid count, watertight/manifold/winding/STEP checks, six orthographic renders (front, back, left, right, top, bottom) and contact sheet. Inspect all six; revise visible defects. A valid mesh or nominal parameter does not prove the requested dimension: measure the actual exported interfaces. Use cad_check_fit on a model and reference STL with an explicit rigid transform; report raw-scan interference and minimum gap. Calipers are authoritative but disagreement with a scan is unresolved measurement evidence, not permission to silently rescale it. Check assembly/insertion paths and actual articulated poses, not sums of local joint limits or reference points alone. Printing, clearance under load, supports and motion need separate evidence.
298
+ Captured scan touch-up: t = scan_touchup(load_scan("scan", source_units="m", up_axis="y", ground=False), colour="colour", normal="normal", edge_mm=0.4) takes a textured capture (declare its OBJ, MTL and colour and normal map PNGs as inputs; pass the map aliases). It removes loose pieces and spikes, closes holes and refines to edge_mm without shrinking the body. t.regions() prints the colour regions (id, colour, area, size, flatness; 0 is the body) to build.log and saves regions.png in the run folder: read both, then name regions by id in the same scan and edge_mm. t.flatten(ids, shape="plane" or "curved"), t.bead(id, diameter_mm, proud_mm), t.cord(id, diameter_mm, proud_mm) (a cord follows its region's own curve) and t.seat(height_mm) record steps; return t.mesh(relief_gain=1.0), which adds the normal map's measured relief, applies the steps with manifold3d and prints its changes. Keep relief_gain at 1: a larger gain amplifies the map's noise, not stitches. When the caller's rules call for a textile's relief the scan missed (fabric, knit, crochet the photos show raised), t.texture_relief(height_mm, regions=None) raises its stitch pattern from the colour texture on the textile only (never flattened, beaded or corded regions); about 0.6 to 1.0 mm peak to peak prints visibly. It is off unless called: never for hard objects, printed graphics or labels.
299
+ The result includes paths, millimetre bounds/size, mesh and STEP volumes, solid count, watertight/manifold/winding/STEP checks, bodies (closest approach between solids, contact with the print plate at Z = 0, labelled bodies that are not one solid), problems, checked and not_checked, six orthographic renders (front, back, left, right, top, bottom) and contact sheet. Fix every entry in problems before selecting a result; an empty problems list proves nothing listed in not_checked. Inspect all six; revise visible defects. A valid mesh or nominal parameter does not prove the requested dimension: measure the actual exported interfaces. Use cad_check_fit on a model and reference STL with an explicit rigid transform; report raw-scan interference and minimum gap. Calipers are authoritative but disagreement with a scan is unresolved measurement evidence, not permission to silently rescale it. Check assembly/insertion paths and actual articulated poses, not sums of local joint limits or reference points alone. Printing, clearance under load, supports and motion need separate evidence.
288
300
  Fit, flexure and thread parameters: put each interface's nominal size, its source (measured, published, or assumed), the print correction, and the design fit in P as separate named values, so a fit report revises one number without resending the script. Model every dimension you claim: a parameter the geometry never uses (a wallet or case width that no cut or wall reads) is a defect; use it or remove it. Shape flexures so their bending lies in the layer plane of the exported print orientation, with the stroke, preload, and hard-stop gap as P values; build the stopped pose as well as the rest pose when checking. Model printed threads as explicit coarse geometry with the same pitch on both sides and clearance as a radial P offset; never scale a screw to clear its hole.
289
301
  Check insertion and articulated poses with cad_check_fit against each object state that matters (the bare product, the product in its case, and the case with its attachment as its own reference envelope), including the widest section on the way in. Report interference and minimum gap per state. In your summary, attach each "fits", "holds", and "prints without supports" claim to the check or slice number that shows it; a valid flag alone shows none of them. Apply fdm_design and fdm_slicing too, with fdm_fit and fdm_flexures when they apply; never invoke a printer as part of constructing CAD.`,
290
302
  };
@@ -205,6 +205,7 @@ export class CadEngine {
205
205
  "requirements.lock",
206
206
  "worker.py",
207
207
  "geometry.py",
208
+ "scan_touchup.py",
208
209
  "process.ts",
209
210
  "storage.ts",
210
211
  "serial.ts",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bambu-printer-mcp",
3
- "version": "1.1.88",
3
+ "version": "1.1.89",
4
4
  "description": "MCP server for Bambu Lab 3D printers with STL manipulation, slicing, and print management",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -110,7 +110,7 @@ export const CAD_TOOLS = [
110
110
  {
111
111
  name: "cad_run",
112
112
  description:
113
- "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six renders and a contact sheet; valid geometry is not a physical-fit or motion proof.",
113
+ "Build parametric CAD headlessly in OS confinement. Read cad_design first: declare literal P = {...} and build() returning a build123d Shape. Supply script OR script_path; parameters overrides saved named values in one call before derived dimensions. Calls wait for the environment’s exclusive execution slot up to their own deadline and report queue_wait_ms. Each call creates a private immutable subfolder under allowed output_dir, never overwriting previous artifacts. The saved .py and .parameters.json are the recovery checkpoint even after cancellation. Returns independently measured geometry, STL/STEP, six renders and a contact sheet, the closest approach between every pair of solids (bodies), problems, and what was checked and not checked; valid means only that the exported geometry is sound, never that the part fits, holds, moves or prints.",
114
114
  inputSchema: {
115
115
  type: "object" as const,
116
116
  properties: {
@@ -208,6 +208,19 @@ export const CAD_TOOLS = [
208
208
  type: "object",
209
209
  additionalProperties: { type: ["boolean", "null"] },
210
210
  },
211
+ bodies: {
212
+ type: "object",
213
+ description:
214
+ "Solid mode: near pairs of solids screened on tessellations and measured exactly on the STEP where the screen cannot clear them, against a print-in-place clearance from P.print_in_place_clearance_mm or 0.3 mm (touching or overlap only when P.print_in_place is false); touching or overlapping pairs, pairs under the clearance, pairs only screened, solids below the print plate (Z = 0) or above it with no solid under them that reaches it, and labelled bodies that are not exactly one solid.",
215
+ },
216
+ problems: {
217
+ type: "array",
218
+ items: { type: "string" },
219
+ description:
220
+ "Defects found by the checks that valid does not cover (fused or too-close bodies, a severed body, a solid below the plate or starting in mid-air, pairs not measured). Each kind lists up to eight, then a count of the rest. Empty when none were found, which is not a pass on anything listed in not_checked.",
221
+ },
222
+ checked: { type: "array", items: { type: "string" } },
223
+ not_checked: { type: "array", items: { type: "string" } },
211
224
  renders: { type: "object", additionalProperties: { type: "string" } },
212
225
  seconds: { type: "number" },
213
226
  },
@@ -307,13 +320,14 @@ export const CAD_DESIGN_PROMPT = {
307
320
  description:
308
321
  "MCP-owned rules for headless build123d designs and one-call parameter revisions.",
309
322
  text: `Use code-CAD for dimensioned functional designs and parameter edits. Build in millimetres with build123d 0.13.0; the MCP owns the Python environment, execution, export, validation and rendering. Check cad_status and use cad_setup with install: true when needed. No Blender, Fusion, network or printer access is available to your script.
310
- Declare exactly one top-level P = {...} dictionary of JSON-compatible literal named parameters. Put every functional dimension in P; derive geometry from P. Define build() to return a build123d Shape or Compound of disjoint solid parts. Do not put construction or exports in a __main__ block: cad_run calls build() and exports the result. Imports, functions and derived P entries are fine. Parameters are applied to the literal defaults before derived expressions execute. For solid designs without inputs, the script and parameters file alone reconstruct it. For input-dependent designs, declare inputs as an array of {name, path} files: cad_run snapshots only those allowed files, exposes INPUTS[alias] to your script, and saves an inputs manifest. Retain the snapshots too for recovery; subsequent script_path edits reuse them unless inputs is explicitly supplied. No other personal files are readable. For a mesh-only experiment use mode: "mesh" and return a trimesh.Trimesh from build(); it exports and checks STL plus six renders, with step: null and an explicit reason. It does not manufacture a fake parametric STEP or promise scan-cleanup capability.
323
+ Declare exactly one top-level P = {...} dictionary of JSON-compatible literal named parameters. Put every functional dimension in P; derive geometry from P. Define build() to return a build123d Shape or Compound of disjoint solid parts. When a design has separate bodies (print-in-place parts, a captive wheel, links of a fabric), return Compound(children=[...]) with a label on each body: cad_run then checks that each labelled body is exactly one solid, so a piece cut off one body cannot hide behind two bodies fused into one. Near pairs of solids are screened and, where the screen cannot clear them, measured exactly against P["print_in_place_clearance_mm"] when you declare it, else 0.3 mm. If the bodies are shown assembled rather than printed in place (a shaft in its hole at a fit clearance), set P["print_in_place"] = False: only touching or overlap is then a problem. Export in print orientation with the plate at Z = 0: a solid below it, or above it with nothing under it that reaches it, is a problem. Do not put construction or exports in a __main__ block: cad_run calls build() and exports the result. Imports, functions and derived P entries are fine. Parameters are applied to the literal defaults before derived expressions execute. For solid designs without inputs, the script and parameters file alone reconstruct it. For input-dependent designs, declare inputs as an array of {name, path} files: cad_run snapshots only those allowed files, exposes INPUTS[alias] to your script, and saves an inputs manifest. Retain the snapshots too for recovery; subsequent script_path edits reuse them unless inputs is explicitly supplied. No other personal files are readable. For a mesh-only experiment use mode: "mesh" and return a trimesh.Trimesh from build(); it exports and checks STL plus six renders, with step: null and an explicit reason. It does not manufacture a fake parametric STEP or promise scan-cleanup capability.
311
324
  Call cad_run with script, output_dir and a plain name. It saves <name>.py and <name>.parameters.json before running, then exports <name>.stl and <name>.step in a fresh subfolder. For an edit, one cad_run with script_path pointing to the earlier .py, parameters containing just the changed dimension, output_dir and name regenerates it without resending the script. Existing parameter values are retained; unknown names and type changes are refused. A killed run can be retried from its checkpoint in a new workspace; mutations are never replayed automatically.
312
325
  Captured mesh preparation: load_scan(name, source_units="m" or "mm", up_axis="x"|"-x"|"y"|"-y"|"z"|"-z", ground=True) is provided to build(). Name must be a declared input. Declare source units and the object's usage-up axis explicitly: the helper converts metres to millimetres, applies a rigid up-axis rotation and translates the lowest Z to zero; it never guesses scale or fits to calipers. Geometry/texture references must be declared inputs too; snapshots preserve distinct original filenames. Exports must be millimetres, Z up, in the orientation the object is used.
313
326
  Fit reference workflow: return load_scan("scan", source_units="m", up_axis="y") from build() in mode: "mesh" to export an unchanged, prepared reference STL for cad_check_fit. Declare every linked OBJ/MTL/texture asset. If you crop, simplify, fill, or otherwise alter this reference, report exactly what you excluded/changed and that the fit check proves only that reduced reference in the stated pose. A fit check against a scan is information; it must never resize or override an interface specified by measured dimensions. Keep those measured interfaces and report the discrepancy.
314
327
  Result selection and edits: set final: true only on the result you select. cad-result.json in each immediate run folder is protected from script writes and retains final, completed_at, lineage_id (source hash), full checks and artifact paths; clients can discover the latest completed final record after restart without rebuilding. Final is a selection marker, not a replacement for valid/checks. Queued calls may expire with cad-queue-timeout before dispatch; do not automatically replay. Unchanged declared files reuse a read-only content-addressed bundle under output_dir/.cad-inputs, preserving filenames and restricting reads to that bundle. Keep this shared cache with the saved runs.
315
328
  Mesh cleanup workflow: return a trimesh.Trimesh in mode: "mesh". Load the prepared mesh, fit needed geometry with NumPy/SciPy, rebuild regular sections/features with build123d or manifold3d CrossSection/extrusion/revolve, and combine meshes with manifold3d booleans. scikit-image supplies marching cubes for voxel/SDF work; Shapely supplies planar operations; Pillow supplies image/texture reads. Keep numeric choices in P and regenerate from declared inputs. Validate closure, winding, manifold status, dimensions and all six views using cad_run. What to regularise, infer, preserve or label comes from the caller's cleanup rules, not this engine prompt.
316
- The result includes paths, millimetre bounds/size, mesh and STEP volumes, solid count, watertight/manifold/winding/STEP checks, six orthographic renders (front, back, left, right, top, bottom) and contact sheet. Inspect all six; revise visible defects. A valid mesh or nominal parameter does not prove the requested dimension: measure the actual exported interfaces. Use cad_check_fit on a model and reference STL with an explicit rigid transform; report raw-scan interference and minimum gap. Calipers are authoritative but disagreement with a scan is unresolved measurement evidence, not permission to silently rescale it. Check assembly/insertion paths and actual articulated poses, not sums of local joint limits or reference points alone. Printing, clearance under load, supports and motion need separate evidence.
329
+ Captured scan touch-up: t = scan_touchup(load_scan("scan", source_units="m", up_axis="y", ground=False), colour="colour", normal="normal", edge_mm=0.4) takes a textured capture (declare its OBJ, MTL and colour and normal map PNGs as inputs; pass the map aliases). It removes loose pieces and spikes, closes holes and refines to edge_mm without shrinking the body. t.regions() prints the colour regions (id, colour, area, size, flatness; 0 is the body) to build.log and saves regions.png in the run folder: read both, then name regions by id in the same scan and edge_mm. t.flatten(ids, shape="plane" or "curved"), t.bead(id, diameter_mm, proud_mm), t.cord(id, diameter_mm, proud_mm) (a cord follows its region's own curve) and t.seat(height_mm) record steps; return t.mesh(relief_gain=1.0), which adds the normal map's measured relief, applies the steps with manifold3d and prints its changes. Keep relief_gain at 1: a larger gain amplifies the map's noise, not stitches. When the caller's rules call for a textile's relief the scan missed (fabric, knit, crochet the photos show raised), t.texture_relief(height_mm, regions=None) raises its stitch pattern from the colour texture on the textile only (never flattened, beaded or corded regions); about 0.6 to 1.0 mm peak to peak prints visibly. It is off unless called: never for hard objects, printed graphics or labels.
330
+ The result includes paths, millimetre bounds/size, mesh and STEP volumes, solid count, watertight/manifold/winding/STEP checks, bodies (closest approach between solids, contact with the print plate at Z = 0, labelled bodies that are not one solid), problems, checked and not_checked, six orthographic renders (front, back, left, right, top, bottom) and contact sheet. Fix every entry in problems before selecting a result; an empty problems list proves nothing listed in not_checked. Inspect all six; revise visible defects. A valid mesh or nominal parameter does not prove the requested dimension: measure the actual exported interfaces. Use cad_check_fit on a model and reference STL with an explicit rigid transform; report raw-scan interference and minimum gap. Calipers are authoritative but disagreement with a scan is unresolved measurement evidence, not permission to silently rescale it. Check assembly/insertion paths and actual articulated poses, not sums of local joint limits or reference points alone. Printing, clearance under load, supports and motion need separate evidence.
317
331
  Fit, flexure and thread parameters: put each interface's nominal size, its source (measured, published, or assumed), the print correction, and the design fit in P as separate named values, so a fit report revises one number without resending the script. Model every dimension you claim: a parameter the geometry never uses (a wallet or case width that no cut or wall reads) is a defect; use it or remove it. Shape flexures so their bending lies in the layer plane of the exported print orientation, with the stroke, preload, and hard-stop gap as P values; build the stopped pose as well as the rest pose when checking. Model printed threads as explicit coarse geometry with the same pitch on both sides and clearance as a radial P offset; never scale a screw to clear its hole.
318
332
  Check insertion and articulated poses with cad_check_fit against each object state that matters (the bare product, the product in its case, and the case with its attachment as its own reference envelope), including the widest section on the way in. Report interference and minimum gap per state. In your summary, attach each "fits", "holds", and "prints without supports" claim to the check or slice number that shows it; a valid flag alone shows none of them. Apply fdm_design and fdm_slicing too, with fdm_fit and fdm_flexures when they apply; never invoke a printer as part of constructing CAD.`,
319
333
  };
@@ -1,5 +1,6 @@
1
1
  """Independent geometry checks, six orthographic views and triangle-exact surface separation."""
2
2
  from pathlib import Path
3
+ import json
3
4
  import math
4
5
  import numpy as np
5
6
  import trimesh
@@ -31,13 +32,216 @@ def inspect(request):
31
32
  checks = {'watertight': bool(m.is_watertight), 'winding_consistent': bool(m.is_winding_consistent), 'positive_volume': bool(m.is_volume),
32
33
  'manifold': mm.status() == mf.Error.NoError, 'step_valid': bool(step.is_valid) if step is not None else None,
33
34
  'stl_step_bounds_agree': bool(np.max(np.abs(m.bounds - np.array(step_bounds))) <= 0.2) if step_bounds is not None else None}
35
+ try:
36
+ assembly = bodies(step, request) if step is not None else None
37
+ except Exception as e: # a failed measurement must not cost the person the export; it is reported, not passed
38
+ assembly = {'error': f'{type(e).__name__}: {e}'[:300]}
34
39
  return {'valid': all(v for v in checks.values() if v is not None), 'units': 'mm', 'bounds_mm': bounds,
35
40
  'size_mm': m.extents.tolist(), 'volume_mm3': float(m.volume) if m.is_volume else None,
36
41
  'step_volume_mm3': float(step.volume) if step is not None else None, 'solid_count': len(step.solids()) if step is not None else len(m.split(only_watertight=True)),
37
42
  'mesh_components': len(m.split(only_watertight=False)), 'checks': checks,
43
+ **evidence(assembly),
38
44
  'renders': render(m, base.parent / (base.name + '.renders'))}
39
45
 
40
46
 
47
+ # Starting print-in-place gap between separate bodies: Prusa's first value for movable parts is "at least 0.3 mm"
48
+ # (design guidance, fdm_fit [F3]). A script sets its own with a literal P["print_in_place_clearance_mm"], and says
49
+ # its bodies are shown assembled (not printed in place) with P["print_in_place"] = False.
50
+ PIP_CLEARANCE_MM = 0.3
51
+ BED_TOLERANCE_MM = 0.05
52
+ SCREEN_ANGLE = 0.1 # tessellation angular deflection (radians) for the gap screen
53
+ EXACT_CAP = 32 # exact B-rep distance calls per result
54
+
55
+
56
+ def clearance_setting(request):
57
+ try:
58
+ params = json.loads(Path(request['parameters']).read_text()) if request.get('parameters') else {}
59
+ except (OSError, ValueError):
60
+ params = {}
61
+ params = params if isinstance(params, dict) else {}
62
+ value = params.get('print_in_place_clearance_mm')
63
+ in_place = params.get('print_in_place', True) is not False
64
+ if isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) and 0 <= value <= 10:
65
+ return float(value), 'P["print_in_place_clearance_mm"]', in_place
66
+ return PIP_CLEARANCE_MM, 'default: Prusa\'s "at least 0.3 mm" for movable parts (fdm_fit)', in_place
67
+
68
+
69
+ def bodies(step, request, budget_s=20.0):
70
+ """Every pair of solids in the exported STEP: closest approach (screened on tessellations, measured exactly on the
71
+ B-rep for every pair the screen cannot clear), overlap, whether each labelled body the script returned is still one
72
+ solid, and whether each solid stands on the print plate (Z = 0) or on a solid that does. Council 2026-11-11
73
+ (scan-to-make #734): chainmail links fused at 48 interfaces, a pawl grazing its wheel while a severed bar kept the
74
+ solid count right, discs starting in mid-air, all with valid: true."""
75
+ import time
76
+ from build123d import Compound
77
+ clearance, source, in_place = clearance_setting(request)
78
+ started = time.monotonic()
79
+ over = lambda: time.monotonic() - started > budget_s
80
+ # Declared bodies: the top-level children of a returned Compound, named by their labels.
81
+ declared, names = [], []
82
+ children = list(step.children) if isinstance(step, Compound) else []
83
+ # STEP import names an unlabelled shape after its type ("SOLID", "COMPOUND"): only the script's own labels declare
84
+ labelled = lambda c: bool(c.label) and c.label != type(c).__name__.upper() and c.label.upper() not in ('SOLID', 'COMPOUND', 'COMPSOLID', 'SHELL')
85
+ if children and all(labelled(c) for c in children):
86
+ for child in children:
87
+ pieces = child.solids()
88
+ declared.append({'body': child.label, 'solids': len(pieces)})
89
+ names += [child.label if len(pieces) == 1 else f'{child.label} piece {k + 1}' for k in range(len(pieces))]
90
+ solids = [s for c in children for s in c.solids()]
91
+ else:
92
+ solids = list(step.solids())
93
+ names = [f'solid {k + 1}' for k in range(len(solids))]
94
+ boxes = [s.bounding_box() for s in solids]
95
+ r3 = lambda v: [round(v[0], 3), round(v[1], 3), round(v[2], 3)]
96
+ mid = lambda pa, pb: r3(((pa.X + pb.X) / 2, (pa.Y + pb.Y) / 2, (pa.Z + pb.Z) / 2))
97
+ # The screen's error on a curved face is its chord sag, at most R a^2 / 8 per surface for angular deflection a; R is
98
+ # bounded by half the pair's larger box diagonal. Every pair the screen reads within the clearance + 0.2 mm + that
99
+ # sag is measured exactly on the B-rep.
100
+ sag = lambda i: (boxes[i].diagonal / 2) * SCREEN_ANGLE ** 2 / 8
101
+ window = lambda i, j: clearance + 0.2 + sag(i) + sag(j)
102
+ def solid_manifold(s):
103
+ v, f = s.tessellate(0.01, SCREEN_ANGLE)
104
+ t = trimesh.Trimesh(np.array([[p.X, p.Y, p.Z] for p in v], dtype=float), np.array(f, dtype=np.int64), process=True)
105
+ t.merge_vertices()
106
+ return manifold(t)
107
+ meshes = [None] * len(solids)
108
+ rows, unmeasured, errors, exact_calls, screened_only = [], [], [], 0, 0
109
+ near_pairs = [] # (i, j, gap) for every pair within its window: what rests on what
110
+ for i in range(len(solids)):
111
+ for j in range(i + 1, len(solids)):
112
+ a, b = boxes[i], boxes[j]
113
+ gap = math.sqrt(sum(max(0.0, lo2 - hi1, lo1 - hi2) ** 2 for lo1, hi1, lo2, hi2 in
114
+ ((a.min.X, a.max.X, b.min.X, b.max.X), (a.min.Y, a.max.Y, b.min.Y, b.max.Y), (a.min.Z, a.max.Z, b.min.Z, b.max.Z))))
115
+ w = window(i, j)
116
+ if gap >= w: continue
117
+ if over():
118
+ unmeasured.append((names[i], names[j], 'time budget'))
119
+ continue
120
+ try:
121
+ for k in (i, j):
122
+ if meshes[k] is None: meshes[k] = solid_manifold(solids[k])
123
+ if meshes[i].status() == mf.Error.NoError and meshes[j].status() == mf.Error.NoError:
124
+ d = meshes[i].min_gap(meshes[j], w)
125
+ else: # a tessellation that does not close: only the exact measurement can say
126
+ d = 0.0
127
+ if d >= w: continue
128
+ exact = exact_calls < EXACT_CAP and not over()
129
+ if exact:
130
+ exact_calls += 1
131
+ d, pa, pb = solids[i].distance_to_with_closest_points(solids[j])
132
+ at = mid(pa, pb)
133
+ holds = lambda x, y: all(getattr(x.min, c) <= getattr(y.min, c) and getattr(y.max, c) <= getattr(x.max, c) for c in 'XYZ')
134
+ if d > 1e-6 and (holds(a, b) or holds(b, a)) and not over() and getattr(solids[i] & solids[j], 'volume', 0.0) > 1e-6:
135
+ d = 0.0 # one wholly inside the other: the surfaces never meet
136
+ else: # past the exact cap or the time budget: the screened gap, marked as such
137
+ screened_only += 1
138
+ at = r3([(max(getattr(a.min, c), getattr(b.min, c)) + min(getattr(a.max, c), getattr(b.max, c))) / 2 for c in 'XYZ'])
139
+ rows.append({'a': names[i], 'b': names[j], 'gap_mm': round(d, 4), 'at': at, 'exact': exact})
140
+ near_pairs.append((i, j, d))
141
+ except Exception as e: # one pair that cannot be measured does not cost the others
142
+ errors.append(f'{names[i]} / {names[j]}: {type(e).__name__}: {e}'[:200])
143
+ unmeasured.append((names[i], names[j], 'error'))
144
+ fused = [r for r in rows if r['gap_mm'] <= 1e-6]
145
+ under = [r for r in rows if 1e-6 < r['gap_mm'] < clearance - 1e-9]
146
+ # a screened-only row read at or past the clearance is still within the screen's error of it: not cleared
147
+ unsure = [r for r in rows if not r['exact'] and r['gap_mm'] >= clearance - 1e-9]
148
+ closest = min(rows, key=lambda r: r['gap_mm']) if rows else None
149
+ # The print plate is Z = 0 of the exported frame. A solid below it is cut off by the plate; one above it prints on
150
+ # air unless it rests on a solid that reaches the plate: material directly under its first layer, within the pair's
151
+ # window (print-in-place stacks).
152
+ below = [{'solid': names[k], 'lowest_z_mm': round(boxes[k].min.Z, 3)} for k in range(len(solids)) if boxes[k].min.Z < -BED_TOLERANCE_MM]
153
+ grounded = {k for k in range(len(solids)) if abs(boxes[k].min.Z) <= BED_TOLERANCE_MM}
154
+ rests, support_unknown, supports = {}, set(), {}
155
+ def held_up(up, low):
156
+ # Support is material of low directly under up's first layer: the footprint of up's lowest 0.2 mm overlaps
157
+ # the footprint of low within the pair's window below it. A neighbour beside the solid is not under it
158
+ # (Codex review, 2026-11-11: a box 10 mm up, 0.4 mm beside a taller grounded box, read as resting on it).
159
+ if (up, low) not in supports:
160
+ z, w = boxes[up].min.Z, window(up, low)
161
+ if meshes[up] is None or meshes[low] is None or meshes[up].status() != mf.Error.NoError or meshes[low].status() != mf.Error.NoError:
162
+ supports[(up, low)] = None
163
+ else:
164
+ lo = [min(boxes[up].min.X, boxes[low].min.X) - 1, min(boxes[up].min.Y, boxes[low].min.Y) - 1]
165
+ size = [max(boxes[up].max.X, boxes[low].max.X) + 1 - lo[0], max(boxes[up].max.Y, boxes[low].max.Y) + 1 - lo[1]]
166
+ band = lambda m, z0, z1: (m ^ mf.Manifold.cube((size[0], size[1], z1 - z0)).translate((lo[0], lo[1], z0))).project()
167
+ supports[(up, low)] = (band(meshes[up], z, z + 0.2) ^ band(meshes[low], z - w, z + BED_TOLERANCE_MM)).area() > 1e-3
168
+ return supports[(up, low)]
169
+ changed = True
170
+ while changed:
171
+ changed = False
172
+ for i, j, d in near_pairs:
173
+ for up, low in ((i, j), (j, i)):
174
+ if up not in grounded and low in grounded and boxes[low].min.Z < boxes[up].min.Z - BED_TOLERANCE_MM:
175
+ try:
176
+ held = held_up(up, low)
177
+ except Exception as e:
178
+ held = None
179
+ errors.append(f'support of {names[up]} on {names[low]}: {type(e).__name__}: {e}'[:200])
180
+ if held is None: support_unknown.add(up)
181
+ elif held: grounded.add(up); rests[up] = (low, d); changed = True
182
+ above = []
183
+ for k in range(len(solids)):
184
+ z = boxes[k].min.Z
185
+ if z <= BED_TOLERANCE_MM: continue
186
+ row = {'solid': names[k], 'starts_mm_above_bed': round(z, 3), 'at': r3(((boxes[k].min.X + boxes[k].max.X) / 2, (boxes[k].min.Y + boxes[k].max.Y) / 2, z))}
187
+ if k in rests: row.update(rests_on=names[rests[k][0]], gap_below_mm=round(rests[k][1], 4))
188
+ elif k in support_unknown: row['support_not_measured'] = True
189
+ above.append(row)
190
+ floating = [r for r in above if 'rests_on' not in r]
191
+ severed = [d for d in declared if d['solids'] != 1]
192
+ def capped(items, say, kind):
193
+ out = [say(x) for x in items[:8]]
194
+ if len(items) > 8: out.append(f'... and {len(items) - 8} more {kind} (see bodies)')
195
+ return out
196
+ weld = 'they weld when printed' if in_place else 'a fit, not checked against print-in-place (P["print_in_place"] is False)'
197
+ problems = (capped(fused, lambda r: f'{r["a"]} and {r["b"]} touch or overlap at {r["at"]}: they print as one piece', 'touching or overlapping pairs') +
198
+ (capped(under, lambda r: f'{r["a"]} and {r["b"]} are {r["gap_mm"]} mm apart at {r["at"]}{"" if r["exact"] else " (screened, not measured exactly)"}, under the {clearance} mm print-in-place clearance: {weld}; if these bodies are shown assembled rather than printed in place, set P["print_in_place"] = False', 'pairs under the clearance') if in_place else []) +
199
+ capped(unsure, lambda r: f'{r["a"]} and {r["b"]} screen at {r["gap_mm"]} mm, within the screen error of the {clearance} mm clearance, and were not measured exactly (exact cap or time budget)', 'unconfirmed pairs') +
200
+ [f'body "{d["body"]}" is {d["solids"]} separate solids: something cuts it apart' if d['solids'] > 1 else f'body "{d["body"]}" has no solid' for d in severed] +
201
+ capped(below, lambda r: f'{r["solid"]} reaches {r["lowest_z_mm"]} mm, below the print plate (Z = 0): the plate cuts it off', 'solids below the plate') +
202
+ capped(floating, lambda r: f'{r["solid"]} starts {r["starts_mm_above_bed"]} mm above the print plate (Z = 0) and whether a solid under it reaches the plate could not be measured (a tessellation that does not close)' if r.get('support_not_measured') else f'{r["solid"]} starts {r["starts_mm_above_bed"]} mm above the print plate (Z = 0) with no solid under it that reaches the plate: its first layer is printed on air', 'floating solids'))
203
+ if unmeasured:
204
+ problems.append(f'{len(unmeasured)} near pair(s) were not measured ({", ".join(sorted({u[2] for u in unmeasured}))}); see bodies.pairs_not_measured')
205
+ return {'solids': len(solids), 'clearance_mm': clearance, 'clearance_source': source, 'print_in_place': in_place,
206
+ 'declared_bodies': declared or None, 'pairs_measured': len(rows), 'exact_measurements': exact_calls, 'screened_only': screened_only,
207
+ 'pairs_not_measured': [{'a': u[0], 'b': u[1], 'why': u[2]} for u in unmeasured], 'errors': errors,
208
+ 'fused': fused, 'too_close': under, 'unconfirmed': unsure, 'closest': closest,
209
+ 'above_bed': above, 'below_bed': below, 'severed': severed, 'problems': problems,
210
+ 'seconds': round(time.monotonic() - started, 3)}
211
+
212
+
213
+ def evidence(assembly):
214
+ """What this result does and does not establish, so valid geometry is never read as a working part."""
215
+ checked = ['the exported mesh is closed, manifold and consistently wound, and the STEP agrees with it (valid, checks)',
216
+ 'bounds, size, volumes and solid count of the exported files']
217
+ not_checked = ['fit to the real object or a mating part (use cad_check_fit per state)',
218
+ 'strength, stiffness or how it holds under load',
219
+ 'motion, articulated poses and snap or flex behaviour',
220
+ 'printing: supports, bridges and bed adhesion are the slicer\'s answer']
221
+ if assembly is None:
222
+ not_checked.append('gaps between separate bodies and contact with the print plate (mesh mode has no solids)')
223
+ return {'checked': checked, 'not_checked': not_checked, 'problems': []}
224
+ if 'error' in assembly:
225
+ not_checked.append('gaps between separate bodies: the measurement failed (' + assembly['error'] + ')')
226
+ return {'bodies': assembly, 'checked': checked, 'not_checked': not_checked, 'problems': ['bodies could not be measured: ' + assembly['error']]}
227
+ checked.append('whether each solid stands on the print plate (Z = 0 of the exported frame) or rests on a solid that does, and whether any reaches below it (bodies; failures are in problems)')
228
+ if assembly['solids'] > 1:
229
+ pairs = f'the closest approach of each near pair of the {assembly["solids"]} solids'
230
+ rule = (f'against a {assembly["clearance_mm"]} mm print-in-place clearance ({assembly["clearance_source"]})' if assembly['print_in_place']
231
+ else 'for touching or overlap only: the script says its bodies are shown assembled (P["print_in_place"] is False)')
232
+ if assembly['pairs_not_measured'] or assembly['unconfirmed']:
233
+ not_checked.append(f'{pairs} {rule}: {len(assembly["pairs_not_measured"])} pair(s) were not measured and {len(assembly["unconfirmed"])} only screened (bodies)')
234
+ else:
235
+ checked.append(f'{pairs} {rule}, screened on tessellations and measured exactly where the screen could not clear them (bodies; failures are in problems)')
236
+ if not assembly['print_in_place']:
237
+ not_checked.append('print-in-place clearance: the bodies are declared as shown assembled')
238
+ if assembly['declared_bodies']:
239
+ checked.append('whether each labelled body is exactly one solid (bodies.declared_bodies; failures are in problems)')
240
+ elif assembly['solids'] > 1:
241
+ not_checked.append('which solids are meant to be separate bodies: return Compound(children=[...]) with a label on each body so a severed piece cannot pass for one')
242
+ return {'bodies': assembly, 'problems': assembly['problems'], 'checked': checked, 'not_checked': not_checked}
243
+
244
+
41
245
  def render(m, folder):
42
246
  folder.mkdir(exist_ok=True)
43
247
  tri, centres, normals = m.triangles, m.triangles.mean(axis=1), m.face_normals
@@ -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",