@bitmagic/cli 0.1.66-dev.5 → 0.1.66-dev.7

package/assets/character-skin-authoring/references/playground.md

@@ -0,0 +1,78 @@
+# Applying the reviewed maps in the character-forger playground
+
+The maintained helpers are in `highquality/src/` at the character-forger repository root.
+They are not standalone engine binaries. Use the project's Python with NumPy, Pillow and
+SciPy, and Blender for projection. Keep this adapter's single mesh/primitive limitation
+explicit; do not silently flatten a rigged or instanced scene to make it pass.
+
+1. Prepare and annotate exact views; dense-bake with `--surface-data --triangle-labels`.
+2. Author `highquality/materials/faces/ID.json` from this character's face view. The target
+   bounds describe normalized body X/Z in Blender world space. Pixel dimensions belong to
+   their respective source and target views. Reusing donor correspondence is valid; reusing
+   another character's target landmarks is not. Hair surrounding a face is an enclosure,
+   not one filled exclusion polygon covering the face.
+3. Run `python highquality/src/build_face_detail.py --id ID`. It registers band-limited
+   licensed scan relief and emits attribution. The amplitude is an authoring estimate,
+   not measured displacement. Empty coverage is an error requiring a profile correction.
+4. Run `python highquality/src/vision_materials.py --id ID --masks MASK_REVISION --evidence EVIDENCE`.
+   The adapter writes `characters/ID/high/v1/materials/v2/character.glb` and a report. It
+   preserves source geometry/buffer bytes, nodes, existing skin data and animation data.
+   This does not add a missing body rig. Inputs are currently the immutable HY source.
+5. Rebuild the viewer with `node hero/viewer/build.mjs`. Run
+   `CHARACTER_ID=ID node highquality/tests/vision_skin_smoke.mjs` on both renderers, then
+   inspect the screenshots. Tests check loading and camera stability, not anatomical truth.
+
+The detail atlas uses source UVs and includes all explicitly observed skin. Face detail is
+registered from a licensed scan; other follicular skin currently uses reduced scan relief.
+Palms/soles use authored nonfollicular ridges. This is not a library of captured regional
+hand/foot exemplars. Source geometry retains its existing larger creases. The report keeps
+unresolved labels and texture defects visible.
+
+Engine contract: explicitly tagged skin/hair materials opt into `createCharacterSurfaceMaterial`.
+RGBA detail stores signed height around .5, roughness, chromatic residual and coverage.
+`_FACE_UV` supplies coordinates, `_FACE_WEIGHT` coverage, `_SCATTER` the fallback transmission
+attribute. Atlas data is linear; albedo is sRGB. The helper excludes defective HY normals on
+labelled skin, keeps native materials elsewhere, and performs geometry-corresponding skin
+UV seam colour equalization. It cannot remove arbitrary baked lighting or interior texture
+stitches merely by correcting normal maps.
+
+Material reports remain `shaded_review_required` until actual exposed regions and rendered
+maps have been reviewed. Do not convert low conflict counts into a whole-character quality
+claim. The b3658 scalp albedo stitch, ambiguous nails and b3843 palm colour spill are examples
+of asset defects that require separate correction.
+
+## Per-pixel material boundaries
+
+After the v2 evidence build, `python highquality/src/vision_blend_materials.py --id ID`
+creates an opt-in v3 revision. `--all-surfaces` creates v4 with hair/lip/nail PBR maps
+as well. Both preserve geometry. They currently require one shared source material/UV
+layout; unsupported native specular or fiber maps fail rather than being overwritten.
+
+`skinSurfaceBlend: true` makes the engine use atlas alpha for skin response, including
+diffusion and thin-skin transmission. Zero coverage retains the native response. Coverage
+must have UV gutters: copy nearest occupied texels into unused atlas space, never into
+unobserved surface regions. This distinction fixes false seams without inventing anatomy.
+At skin/hair/lip boundaries, known material weights must sum to one. Independently fading
+both sides to zero exposes the source material as a bright halo.
+
+V4 expresses fiber and lip response through standard glTF ORM/specular/anisotropy/sheen
+maps. The current fiber direction is provisional; author a comb-flow field before calling
+hair finished. Its skin inspector shows actual skin coverage (white), not an entire mixed
+primitive falsely labelled as skin. `viewerReady` only selects a tested local preview;
+it is not the region-level semantic or final character quality approval.
+
+## Runtime adoption
+
+The engine now provides `RealisticCharacter.create(root, options)` for the loaded GLTF.
+Use the engine's `createGltfLoader()` and resolve embedded atlas indices through its parser.
+The adapter validates UV attributes, retains native untagged materials, preserves coverage
+when detail is disabled, and exposes independent eye controls. It commits material changes
+only after texture resolution succeeds. Scene postprocessing and the body mixer remain
+caller-owned. See the GDK engine document `agent-docs/character-surfaces.md` for ownership
+and pass ordering; do not copy the lab's former material-loading loops into each game.
+
+For a rigged playground derivative, use `highquality/src/assemble_character.py` after
+shared Blender binding. It converts refined geometry to canonical bind coordinates and
+keeps canonical inverse-bind matrices; exercise pose reset and body motion, not only a
+rest-position comparison. Unrigged material/eye previews can coexist with a rigged body
+variant. Determine normalization from the loaded asset, not a catalog-wide rigging flag.

package/assets/character-skin-authoring/references/profiles.md

@@ -0,0 +1,97 @@
+# Face and eye profile authoring
+
+These schemas describe authored inputs to the installed exporters. Values that locate
+anatomy must come from images of this character. Keep the physical dimensions and source
+hashes beside the profile; never copy another character's target coordinates.
+
+## Facial detail registration
+
+Write `highquality/materials/faces/ID.json` with:
+
+- `version: 2`, `id`, `sourceSha256`, `evidenceImage` (workspace-relative), and
+  `evidenceImageSha256` identifying the exact source and reviewed frontal image.
+- `annotationImageSize`: the square target image's actual pixel dimension.
+- `bounds: [minX, minZ, maxX, maxZ]`: the target image rectangle in normalized body
+  coordinates. The current adapter requires a frontal view with direction `[0,1,0]`
+  and up `[0,0,1]`; align an arbitrarily oriented source explicitly before preparing
+  evidence. Normalized X is `(worldX - boundsCenterX) / bodyHeight`; normalized Z is
+  `(worldZ - boundsCenterZ) / bodyHeight + .5`. For a frontal evidence camera, its
+  `targetOffset` and `span` give this rectangle directly:
+  `[offsetX-span/2, .5+offsetZ-span/2, offsetX+span/2, .5+offsetZ+span/2]`.
+- `sourceBounds` and `sourceAnnotationImageSize`: the donor registration view's
+  rectangle and pixel size. Generate and inspect it with the helper below.
+- `landmarkNames`, `sourcePixels`, `targetPixels`: equal-length ordered arrays of
+  corresponding points. Use a well-spread non-collinear set spanning forehead,
+  temples, cheek/jaw/chin boundary, eye corners, nose and mouth. These define the
+  correspondence and its supported hull; points outside the hull receive no face detail.
+- `regions: {"eyes": [...], "brows": [...], "lips": [...]}`: each list contains polygons
+  of target image pixels. These exclude those regions from ordinary facial detail.
+  Include facial-hair exclusions in the exclusion polygons too. Empty lists are valid
+  only when that exclusion is actually absent in the selected patch.
+- `atlasSize`: 2048 or 4096. `independentFacialDetail: true` retains the full facial
+  resolution in the packed runtime atlas.
+- `detailHeightRangeM`: full signed encoding range in metres (zero is .5).
+  `detailAmplitudeM`: authored donor-band calibration, not measured scan amplitude.
+  Compare the resulting relief at face-sized framing under side light; do not compensate
+  for missing texel density by increasing amplitude.
+- `diffusionProfile`: three positive authored channel falloff ratios, such as the
+  renderer's human-skin default `[1,.55,.3]`. Fantasy skin ratios are appearance choices.
+
+Generate the fixed licensed donor's reference image without a playground checkout:
+
+```sh
+python scripts/prepare_face_reference.py --workspace /path/to/assets \
+  --out /path/to/assets/evidence/donor --size 900
+```
+
+Use `donor-front.png` and `registration-view.json` to author `sourcePixels`. Pixel origin
+is top-left for both source and target. The helper uses the same donor projection and
+UV convention as the atlas builder; choosing points from a differently framed photo
+will misregister the relief. It renders the existing licensed files and downloads nothing.
+
+## Optical eye fit
+
+An eye profile has `id`, `sourceSha256`, `evidence` (absolute prepared-view folder),
+`skinRevision: "v4"`, and exactly two entries in `eyes`. Each entry requires:
+
+- `name`, `anatomicalSide: "left" | "right"`, and `view`, matching a manifest view.
+- `irisCenterPx: [x,y]`, `irisRadiusPx`, and `openingPx`: an ordered convex aperture
+  polygon in that exact view. Inspect both obliques before choosing the final depth.
+- `upperContourIndices` and `lowerContourIndices`: ordered indices along the corresponding
+  aperture edges, including their corners. These guide contacts, lashes and closure.
+- `globeRadiusM`, `corneaBulgeM`, `frontOffsetM`, `pupilRatio`, `irisColorLinear` (RGB).
+  These are designed optical dimensions and pigment. The iris must fit inside the globe;
+  confirm against the character's physical height and side views.
+
+Use `openingAuthority: "reviewed-contours"` only after explicitly inspecting the aperture
+when the source has no separately classified ocular primitive. `conformOpenLids: true`
+pushes intersecting source lid tissue outside the fitted globe; inspect its effect.
+Optional `lashes` uses `upperCount`, `lowerCount`, `upperLengthM`, `lowerLengthM`,
+`radiusM` and an authoring note. Reconstructed bands (`outerLidPx`, `lidSkinSamplesPx`),
+corner lining (`canthusWalls`), medial tissue (`caruncle`) and brow strands (`browGroom`)
+are described in [eyes.md](eyes.md). Start with the source-preserving fit; optional
+reconstruction is not automatically an improvement, as the rejected elf trial showed.
+
+The current blink is a fitted geometric morph, not a biomechanical eyelid simulation.
+Preserve source folds unless an independently reviewed correction improves the result.
+Simple smoothing of the closed support band was rejected because it created visible
+rings. Treat any future smoothing as a new fit experiment requiring matched neutral
+and closed-eye review.
+
+### Several independent source-color repairs
+
+`materials/repair-profile.json` may retain the single-operation form or contain
+`{"repairs": [operation, ...]}`. Each operation has its own `mask`, `purpose`,
+optional `cleanSwatches`, `blendWidthM` and optional `evidence` workspace path.
+The latter permits fresh, color-faithful swatch views without invalidating a
+separate anatomical bake whose camera/geometry evidence is unchanged. Source,
+image and correspondence hashes are checked. Every donor must still land on
+independently classified skin. Operations run in order and report separately;
+use disjoint selections unless the overlap is explicitly intentional.
+
+Baked illumination in a generated albedo can make a correctly lit surface dark
+or plastic. Inspect the unlit runtime albedo and color-faithful evidence first.
+A swatch-based correction is an art-directed reconstruction, not measured
+reflectance recovery. Do not globally brighten skin or infer defects from RGB.
+Review the selected region, donor color, transitions and the final relit result;
+retain the original and the rejected candidates.

package/assets/character-skin-authoring/references/projection.md

@@ -0,0 +1,190 @@
+# Projection contract
+
+The portable helper produces evidence and UV labels. It does not fit a detail exemplar,
+change a GLB, or claim a sparse projected label map is a production-ready skin mask.
+Use its coverage report to drive further agent inspection.
+
+Run with a local Python containing NumPy and Pillow. Blender supplies its own NumPy.
+The lab uses `lowpoly/.venv/bin/python`; elsewhere choose the project's environment.
+
+```sh
+python <skill>/scripts/skin_views.py prepare --source character.glb --views views.json --output evidence-v1 --size 1024 --blender /path/to/blender
+python <skill>/scripts/skin_views.py bake --evidence evidence-v1 --annotations annotations.json --output masks-v1 --resolution 4096 --dense --blender /path/to/blender
+```
+
+Omit `--blender` when available on PATH. `prepare` uses Blender's imported mesh and
+world transform, BVH visibility, interpolated UVs and unlit base-color image. It currently
+supports directly linked Principled base-color textures and the active UV set. Complex
+material graphs must first receive a faithful albedo bake; the helper fails instead of
+guessing. Animated models are inspected in the imported pose. Validate orientation and
+texture appearance against the original before annotating.
+
+Evidence PNGs preserve sRGB byte textures as encoded values. Blender's non-float
+`Image.pixels` exposes those byte values normalized to 0–1; applying an additional
+linear-to-sRGB transfer would brighten the evidence incorrectly. Constant Principled
+base colors are linear and receive exactly one transfer. Float images are rejected
+until a faithful sRGB albedo bake is supplied. New manifests explicitly record
+`evidenceColorSpace` and `byteImageTransfer`. The playground's known-color Blender
+regression verifies both byte-texture and constant-color paths within one byte value.
+
+Older evidence made before this correction may be too bright. Preserve those immutable
+revisions and annotations, prepare a new color-correct revision, and visually review it.
+Identical camera/UV correspondence can justify transferring polygon coordinates, but
+never claim a new visual review merely because the geometry stayed unchanged. This
+helper correction does not alter the runtime GLB texture color pipeline.
+
+`views.json` is a list. `direction` points **from camera into the scene** in Blender world
+coordinates, `up` defaults to +Z. `span` is square orthographic width divided by model
+height. `targetOffset` is relative to bounding-box center, also in model-height units.
+Directions are geometric, not assumptions about front/back or left/right anatomy.
+
+```json
+[
+  {"name":"minus-y","direction":[0,1,0],"span":1.45},
+  {"name":"plus-y","direction":[0,-1,0],"span":1.45}
+]
+```
+
+After the survey, choose offsets and tighter spans by inspecting the actual character.
+For a top view, supply an up vector perpendicular to its direction. Each view yields a
+PNG and NPZ containing material index, UV and viewing-angle confidence for every visible
+pixel. Manifest records source hash, cameras, dimensions, material names and world bounds.
+Rasterized sample coordinates refer to pixel centers; polygon coordinates are image
+pixels from top-left, x right and y down. Use precisely the named image dimensions.
+
+```json
+{
+  "sourceSha256":"copy the manifest hash",
+  "views":{
+    "minus-y":[
+      {"label":"skin","polygon":[[100,100],[140,100],[140,160],[100,160]]},
+      {"label":"eyes","polygon":[[110,110],[120,110],[120,120],[110,120]]}
+    ]
+  }
+}
+```
+
+These coordinates are format examples, not annotations for any character. Later polygons
+overwrite earlier ones within a view. Across views, contradictory labels become unknown
+and appear in the conflict map. Grazing samples are excluded deterministically. UVs outside
+0–1 remain unclassified rather than being wrapped into a different region.
+
+Outputs: per-material label, observed and conflict PNGs; per-view annotation overlays,
+reprojected atlas overlays and raw reprojected labels; archived annotations; and a JSON report. Label IDs: unknown 0, skin 1, palm 2, sole 3, lips 4, eyes 5, hair 6, nails 7,
+non_skin 8, dorsal_hand 9. Material ordering belongs to this evidence manifest, not a promised GLB index.
+UV labels use top-left image rows (Blender UV V is inverted during baking).
+
+The bake does not interpolate unknown texels or decide by majority vote: conflicting
+observations require review. Low-resolution survey rays are insufficient to cover a 4K UV
+atlas; use region close-ups and appropriate resolution for final maps. Do not count unknown
+background texels as missed skin without examining the UV occupancy of the actual model.
+
+
+## Dense bake and review (tested on three additional characters)
+
+Use `--dense` for reviewed deliverables. The default sparse mode remains useful as a small
+projection diagnostic. Dense mode rasterizes the source UV triangles, finds the 3D point
+for each occupied texel, projects it into annotated cameras and ray-tests visibility against
+the exact mesh. It does not interpolate semantic labels across unseen geometry. Distinct
+surfaces sharing UV texels are reported as overlaps and remain unknown. Increasing atlas
+resolution cannot add semantic accuracy beyond the annotation images.
+
+Prepare hashes the PNG/NPZ evidence. Bake checks these hashes and the source mesh hash;
+editing an image after annotation invalidates that evidence. Legacy manifests without
+image hashes remain readable; prepare fresh evidence for new work. Preserve the original
+manifest with its camera definitions. Evidence must not be resized or relit for annotation.
+
+Review BOTH `<view>-overlay.png` (your polygons) and `<view>-reprojected.png` (the actual
+baked atlas). All prepared views are reprojected, including views without annotations.
+Palette: green skin, mint dorsal hand, cyan palm, blue eyes, purple hair, pink lips, pale
+yellow nails, gray non-skin. Red means unknown; orange means conflict. Unknown clothing
+is not missing skin. The raw `*-reprojected-labels.png` images retain categorical IDs.
+
+The report distinguishes total visible pixels from annotated visible pixels. Use
+`unresolvedAnnotatedPixels` and `disagreeingAnnotatedPixels` to detect projection losses;
+these are NOT whole-character skin coverage or semantic accuracy scores. Low-resolution
+atlases lose samples near small islands and seams even in dense mode. Match the source
+atlas resolution, inspect the result, and keep unresolved seams visible. Do not hide them
+with unrestricted dilation. A synthetic Blender regression exercises dense coverage,
+occluded back surfaces and overlapping UVs.
+
+Trials found source albedo spill on soldier b3843's palms, pale hair/ear ambiguity on b5588,
+and missing side scalp coverage on b3658. These require different responses: record a
+source-texture defect separately; correct hair/skin boundaries from multiple views; add
+views/annotations for exposed surfaces. Indistinct nails require closer views. Do not
+claim a material or skin-detail improvement from a semantic mask alone.
+
+## Runtime packaging evidence
+
+For the full-UV material adapter, add `--surface-data --triangle-labels` to the dense bake.
+
+To investigate a seam or conflict, use `scripts/inspect_skin_point.py --evidence <folder>
+--masks <dense-bake> --view <name> --x <pixel-x> --y <pixel-y>`. Coordinates belong to the
+original evidence image. The read-only helper reports the UV texel and every visible
+contributing view, its source pixel, authored label and geometric facing. It checks the
+source, annotations and archived camera contract; it does not resolve the labels.
+
+Add `--height-m <known-character-height>` to report surface distances to adjacent
+occupied atlas texels in metres. Inspect individual neighbours: crossing a UV discontinuity
+can produce a large distance. This diagnoses texture density, not anatomy or recovered
+detail. If a face uses half-millimetre texels, increasing bump strength cannot recover
+sub-texel pores. Preserve the registered detail in its own atlas instead of increasing
+coverage or exaggerating relief to hide lost resolution.
+
+Inspect the reported image pixels. A one-pixel garment-boundary mistake in a grazing
+view can project into a much wider strip on the model. If that source boundary is
+ambiguous and another view clearly shows the anatomy, explicitly mark the narrow
+uncertain region in the ambiguous view as unknown and retain the reviewed clear view.
+Do not automatically select a label by facing score or shrink all boundaries globally.
+The first writes occupied texel positions, normals and geometric visibility bits in
+Blender world space. The second classifies actual triangle centers with the same camera
+annotations and exact visibility tests. Packaging matches those centers bijectively to the
+GLB scene transform and fails if they differ; never assume Blender and GLB vertex ordering
+match. This avoids assigning a whole triangle by a sparsely sampled UV center.
+
+`triangles.npz` contains centers, labels and conflicts. `material-N-surface.npz` contains
+position, normal, occupied, viewBits and visibilityBits. `viewBits` records views supporting
+an annotation; `visibilityBits` independently records geometric visibility, including
+unannotated views and unlabelled visible texels. Use the latter for projecting registered
+detail, never an annotation's polygon boundary. Neither field assigns an anatomical label.
+Older bakes without `visibilityBits` must be regenerated, not silently substituted.
+Before consuming visibility bits, compare the archived `dense-request.json` source,
+ordered cameras, image size, material ordering and world bounds against the supplied
+manifest. A source hash alone cannot detect reordered camera bits. A color-only evidence
+revision may preserve that geometric contract; changed cameras require a new bake.
+These are build intermediates, not game textures.
+The current visibility bit field supports up to 32 views in one revision. Blender workers
+return a nonzero exit code on Python errors. Keep output revisions separate when changing
+annotations; do not overwrite evidence to bypass a hash check.
+
+Generic `skin` agrees with an observed `palm`, `sole` or `dorsal_hand` label. Two distinct
+specific labels still conflict. This hierarchy combines semantic observations; it does not
+recognize anatomy. A hard material boundary magnifies small polygon gaps: overlap enclosing
+skin and its explicit hair/lip exclusions within the same view instead of leaving a narrow
+unlabelled strip between them. Never fill an unseen nail or a contradictory observation.
+
+### Thin unresolved folds
+
+A closer view in the same direction does not necessarily resolve visibility gaps. The
+b3658 rear-neck test retained a thin unobserved strip in a shallow fold until an oblique
+view showed the recessed surface. Inspect source, coverage and shaded images separately.
+Add that new view and annotate actual anatomy; never increase ray tolerance or fill unknown
+regions merely to remove a line. Sample-level coverage improvements do not prove that all
+residual albedo or filtering seams have disappeared. Keep those review results distinct.
+
+
+### Source-color repair across UV islands
+
+A harmonic image fill assumes the selected patch has clean boundaries. UV seams can split one anatomical patch into many islands whose boundaries remain contaminated. If a reviewed color repair remains unchanged, inspect the repaired albedo reprojected onto the exact mesh before extending semantic labels. For such defects, author clean color swatches on the same visible anatomical surface and interpolate in surface space, keeping the repair selection separate from anatomy. Check every donor against source hashes and independently reviewed skin. Record the swatch coordinates and inspect the final render. This is texture reconstruction, not segmentation or recovered source detail.
+
+Designed features such as a nail plate absent from the source must be explicitly recorded as authored additions. They must not silently override contradictory anatomical observations; reconcile the views or keep the design unaccepted.
+
+## Occluding silhouettes need precise annotations
+
+A bottom-foot view may show the shin or clothing immediately beyond the heel and
+between toes. A polygon around the apparent foot outline must exclude those visible
+surfaces too; they are not necessarily empty background. In the b3662 trial, a few pixels
+of excess sole annotation produced a curved sole-detail strip on the shin. The ray test
+correctly saw that shin surface—the semantic polygon was wrong. Trace a bad rendered
+point with `scripts/inspect_skin_point.py`, inspect the contributing source pixel, correct
+that specific polygon, and reproject. Do not move a shader cutoff to conceal the artifact.

package/assets/character-skin-authoring/references/regional-detail.md

@@ -0,0 +1,72 @@
+# Regional detail helpers
+
+The shipped `scripts/authored_detail.py` and `scripts/authored_surface_patch.py` are
+Blender-independent NumPy/Pillow/SciPy libraries. They evaluate already-authored curves
+and roughness patches. They do not recognize anatomy, load a rig, or export materials.
+Keep profiles and licensed images in the character workspace, outside the refreshed skill.
+
+Pass the exact evidence manifest and physical character height in metres. Surface points
+must use the evidence's Blender world axes, centered on `worldBounds` and scaled by
+physical height divided by the source bounds' Z extent. Normals use those same axes.
+`visibility` is the dense bake's **geometric `visibilityBits`**, not annotation `viewBits`.
+The label array is the reviewed semantic map. Both helpers leave other regions unchanged.
+
+`AuthoredDetail(profile_path, manifest, height_m).evaluate(points, normals, labels,
+visibility)` returns signed relief in metres. The profile contains `sourceSha256`,
+`evidenceHashes`, `provenance`, and `curves`. Each curve specifies `view`, `region`,
+`pointsPx`, `widthM`, and `depthM`. Regions supported here are `skin`, `palm`, `sole`,
+and `dorsal_hand`. Coordinates belong to the exact source-view image. Record the curves
+as designed enhancements, not measured anatomy.
+
+`AuthoredSurfacePatch(profile_path, manifest, height_m, workspace_root).evaluate(points,
+normals, labels, visibility, base_roughness)` returns blended roughness. The profile has
+`sourceSha256`, `evidenceHashes`, and `patches`. Each patch contains:
+
+- `view`, `region`, ordered `targetPixels` around the selected polygon.
+- `roughnessTexture`, `textureSha256`, `sourceAnnotationImageSize`, and corresponding
+  `sourcePixels` from the independently inspected donor image.
+- `featherM` and `roughnessRange` as an explicit authored response range.
+- `provenance`: `title`, `url`, `licenseFile`, and `licenseSha256`.
+
+Texture and license paths are relative to the supplied workspace root. The helper checks
+the current evidence image, texture and license hashes. Retain its `report` and append
+all `attributions` to the exported asset's notices. Exemplar roughness is not necessarily
+measured: record its origin accurately. This helper transfers neither color nor normals.
+Normal-map RGB is not height data; integrating normals requires a declared tangent
+convention and surface metric, followed by independent relief review.
+
+An optional `height` record supplies an already prepared signed-height NumPy array:
+`path`, `sha256`, `boundsPx` in the donor annotation coordinates, explicit `scale`,
+and `provenance`. Values are metres, not RGB channels. The separate
+`relief(points, normals, labels, visibility)` method returns the feathered height
+contribution, leaving roughness evaluation unchanged. Preserve the method, source
+normal convention, assumed metric and any artistic amplitude change in provenance.
+Use known or explicitly designed height; this helper does not integrate normal maps.
+
+For a square, locally planar exemplar with a declared isotropic metric,
+`scripts/normal_patch_height.py` exposes `normal_patch_height(rgb, width_m, normal_y)`.
+RGB is the raw linear normal-map data in [0,1]; `normal_y` must explicitly be `up` or
+`down`. It uses [Frankot/Chellappa discrete slope integration](https://doi.org/10.1109/34.3909),
+a reflected periodic extension, and physically specified band limiting. Save its output
+as a signed-metre NumPy array and inspect the reconstructed folds before transfer. It
+does not recover an unknown donor metric, recognize a skin region, or make artist-authored
+normal maps into measured scans. The playground's Hafnia palm test explicitly assumes an
+80mm planar crop and records that assumption; it is not a universal scale for hand assets.
+
+`sampleResolution` can increase field sampling independently of the annotation image.
+Physical feather width stays unchanged. When the project's exporter supports regional
+atlas packing, `independentDetail: true` exposes the patch through `independent_planes()`.
+The exporter must then exclude it from the coarse body bake (`include_independent=False`)
+and register its texture coordinates separately. Do not silently omit it in an exporter
+that lacks this path. Overlapping independent bindings require a deliberately combined
+patch; there is no automatic regional winner.
+
+Inspect the transferred patch at region-sized framing under side and specular lighting.
+A small central-palm experiment is not acceptance of the whole hand, fingers or nails.
+If the full-body atlas cannot resolve the patch, address texel density before amplifying it.
+
+For independent atlas slots, keep a transparent margin around the authored patch inside
+the evidence view. The playground packer rejects edge-touching patches rather than
+clamping visible relief into a seam. Widen/reframe the evidence and review the annotation
+again. Packing a patch at higher resolution is not a visual acceptance: inspect its relief
+at an ordinary region-sized view and with side light before claiming improved skin.