added uv unwarp export

README.md

@@ -73,7 +73,7 @@ Four commands for v1:
 # 1) Check revision metadata and (optionally) Blender scene conventions
 orisys-design validate sensors/finger/r01
 
-# 2) Export nominal geometry for a profile (compute → SDK layout)
+# 2) Export nominal geometry plus the unwarp/valid-mask map (compute → SDK layout)
 orisys-design export sensors/finger/r01 --profile compute
 
 # 3) Generate the colored patch texture headlessly
@@ -109,9 +109,27 @@ build/export/finger/r01/
 └── compute/                  # clean SDK-shaped payload
     ├── mesh.npz
     ├── camera_intrinsics.npz
-    └── world_to_cam.npy
+    ├── world_to_cam.npy
+    └── unroll_map_uv_s0.42.npz  # unwarp/valid-mask domain (name carries source_scale)
 ```
 
+The last one is the **UV domain** the application treats as sensing: everything outside
+its `valid_mask` island renders grey. Blender writes no mask, so the export builds it
+afterwards with the SDK's own builder (`orisys.unroll.precompute`), from the profile's
+`uv_map:` block — no Blender involved, so the mask can also be rebuilt from an exported
+payload alone:
+
+```powershell
+python tools/build_uv_map.py --export-dir build/export/finger/r01/compute `
+  --profile sensors/finger/r01/profiles/compute.yaml
+```
+
+The parameters are never guessed (a wrong output size or source scale still produces a
+plausible-looking mask), and a failed map build exits non-zero *before* the artifact check,
+so a bundle whose mask is missing or stale cannot be reported as complete. The SDK asset
+copy is updated only when the revision is promoted — gated by
+`orisys-app/tools/scene_assets/compare_uv_map.py`.
+
 ## Texture patches (headless)
 
 `orisys-design texture` generates a PNG, editable SVG, and native vector PDF for
@@ -564,8 +582,9 @@ Compare patterns only with the radius, ROI and scale held fixed — which is why
 
 - **`compute`** — `sensing_surface` + `cam_sensor` relative to `origin_sensor`. Writes
   `mesh.npz`, `camera_intrinsics.npz`, `world_to_cam.npy` (here “world” means the
-  sensor frame). Studio and the wheel build consume this tree via `orisys-sdk` →
-  `assets_dir`.
+  sensor frame) and `unroll_map_uv_s<scale>.npz`, the unwarp/valid-mask domain built from
+  the profile's `uv_map:` block. Studio and the wheel build consume this tree via
+  `orisys-sdk` → `assets_dir`.
 - **`studio`** — documents how to compile a `.oryscene` from the **compute** export
   plus the measured unroll map in SDK. Observation cameras in Studio are derived from
   mesh bounds; no Blender `cam_viz` is required.
@@ -579,7 +598,9 @@ After export:
    (or publish as a release artifact).
 3. Keep `build/export/finger/r01/manifest.json` beside the payload, and update
    optional `design-lock.json` in `orisys-sdk` with commit + bundle SHA256.
-4. Run `orisys-app` `compile_scene.py` using the locked compute export + SDK unroll map.
+4. Run `orisys-app` `compile_scene.py` using the locked compute export + the exported
+   unroll map. The map now travels with the payload; the SDK asset copy is refreshed only
+   here, and only after `tools/scene_assets/compare_uv_map.py` agrees with what ships.
 
 Example lock file: `examples/design-lock.json`.