@bitmagic/cli 0.1.66-dev.1 → 0.1.66-dev.10

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.

package/assets/character-skin-authoring/scripts/assemble_character.py

@@ -0,0 +1,205 @@
+"""Attach the shared body rig without re-exporting authored materials or eye layers.
+
+Original surface vertices match the dense bound mesh. Newly clipped eye vertices
+use a unanimous rigid-head field or exact bound-triangle interpolation. Optical
+rest fitting retains its pre-fit correspondence; off-surface evidence is rejected.
+"""
+import argparse,copy,hashlib,json,shutil
+from pathlib import Path
+import numpy as np
+from scipy.spatial import cKDTree
+from scipy.spatial.transform import Rotation
+from glb_arrays import read,accessor
+from glb_output import append_accessor
+from vision_materials import source_world_points
+from eye_assets import write_glb
+
+from workspace_paths import workspace_root
+ROOT=workspace_root(__file__)
+
+def node_matrix(node):
+    if 'matrix' in node:return np.asarray(node['matrix']).reshape(4,4).T
+    matrix=np.eye(4);matrix[:3,:3]=Rotation.from_quat(node.get('rotation',[0,0,0,1])).as_matrix()@np.diag(node.get('scale',[1,1,1]));matrix[:3,3]=node.get('translation',[0,0,0]);return matrix
+
+def world_matrices(doc):
+    parents={child:i for i,n in enumerate(doc['nodes']) for child in n.get('children',[])};cache={}
+    def world(i):
+        if i not in cache:cache[i]=(world(parents[i]) if i in parents else np.eye(4))@node_matrix(doc['nodes'][i])
+        return cache[i]
+    return [world(i) for i in range(len(doc['nodes']))]
+
+def set_transform(node,matrix):
+    scale=np.linalg.norm(matrix[:3,:3],axis=0);rotation=matrix[:3,:3]/scale
+    if not np.allclose(rotation.T@rotation,np.eye(3),atol=1e-5) or np.linalg.det(rotation)<0:raise ValueError('Eye attachment requires a non-sheared positive transform')
+    node.pop('matrix',None);node.update(translation=matrix[:3,3].tolist(),rotation=Rotation.from_matrix(rotation).as_quat().tolist(),scale=scale.tolist())
+
+def skin_points(points,joints,weights,matrices):
+    result=np.zeros_like(points,dtype=float);p=np.c_[points,np.ones(len(points))]
+    for slot in range(4):result+=np.einsum('nij,nj->ni',matrices[joints[:,slot]],p)[:,:3]*weights[:,slot,None]
+    return result
+
+def surface_weight_transfer(query,points,faces,joints,weights,tolerance):
+    """Exact closest-triangle interpolation; reject points off the bound surface."""
+    triangles=points[faces];centers=triangles.mean(1)
+    radius=np.linalg.norm(triangles-centers[:,None,:],axis=2).max()
+    tree=cKDTree(centers);vertices=cKDTree(points[np.unique(faces)])
+    result_j=[];result_w=[]
+    for point in query:
+        upper=vertices.query(point)[0]
+        ids=tree.query_ball_point(point,float(upper+radius+tolerance))
+        tri=triangles[ids];a=tri[:,0];u=tri[:,1]-a;v=tri[:,2]-a;p=point-a
+        uu=(u*u).sum(1);uv=(u*v).sum(1);vv=(v*v).sum(1);pu=(p*u).sum(1);pv=(p*v).sum(1)
+        determinant=uu*vv-uv*uv;safe=np.where(determinant>1e-24,determinant,1)
+        b=(vv*pu-uv*pv)/safe;c=(uu*pv-uv*pu)/safe
+        bary=np.stack([1-b-c,b,c],1);inside=(bary>=0).all(1)&(determinant>1e-24)
+        distance=np.linalg.norm(np.einsum('ni,nij->nj',bary,tri)-point,axis=1)
+        distance[~inside]=np.inf
+        for first,last in [(0,1),(1,2),(2,0)]:
+            edge=tri[:,last]-tri[:,first];length=(edge*edge).sum(1)
+            t=np.clip(((point-tri[:,first])*edge).sum(1)/np.maximum(length,1e-24),0,1)
+            candidate=np.linalg.norm(tri[:,first]+edge*t[:,None]-point,axis=1);better=candidate<distance
+            distance[better]=candidate[better];bary[better]=0;bary[better,first]=1-t[better];bary[better,last]=t[better]
+        closest=int(np.argmin(distance))
+        if distance[closest]>tolerance:raise ValueError('Binding provenance is not on the validated source surface')
+        corners=faces[ids[closest]];combined={}
+        for vertex,factor in zip(corners,bary[closest]):
+            for joint,weight in zip(joints[vertex],weights[vertex]):combined[int(joint)]=combined.get(int(joint),0)+float(factor*weight)
+        strongest=sorted(combined.items(),key=lambda item:item[1],reverse=True)[:4]
+        strongest += [(0,0)]*(4-len(strongest));total=sum(w for _,w in strongest)
+        if total<=0:raise ValueError('Bound triangle has no skin weights')
+        result_j.append([j for j,_ in strongest]);result_w.append([w/total for _,w in strongest])
+    return np.asarray(result_j),np.asarray(result_w)
+
+def assemble(sid,relative_input,variant='eyes'):
+    base=ROOT/'characters'/sid/'high/v1';input_path=(base/relative_input).resolve()
+    if base.resolve() not in input_path.parents:raise ValueError('Input must be a revision inside this character')
+    doc,data=read(input_path);rig_path=base/'output/character.glb';rig,rig_data=read(rig_path);rig_report=json.loads((base/'rig-report.json').read_text())
+    if hashlib.sha256(rig_path.read_bytes()).hexdigest()!=rig_report['output_sha256']:raise ValueError('Body rig changed after validation')
+    if rig_report['geometry_displacement_max_m']>1e-6:raise ValueError('Reshaped sources require an explicit surface deformation transfer')
+    if len(rig.get('skins',[]))!=1 or doc.get('skins'):raise ValueError('This assembly adapter adds exactly one new body skin')
+    body_node=next(i for i,n in enumerate(doc['nodes']) if n.get('mesh')==0)
+    rig_body=next(i for i,n in enumerate(rig['nodes']) if n.get('skin')==0)
+    if any('mesh' in n for i,n in enumerate(rig['nodes']) if i!=rig_body):raise ValueError('Unexpected extra body geometry')
+    worlds=world_matrices(doc);rig_world=world_matrices(rig)
+    if not np.allclose(rig_world[rig_body],np.eye(4),atol=1e-6):raise ValueError('Bound mesh needs an explicit nonidentity bind-space adapter')
+    primitives=doc['meshes'][0]['primitives'];positions=accessor(doc,data,primitives[0]['attributes']['POSITION'])
+    if any(p['attributes']['POSITION']!=primitives[0]['attributes']['POSITION'] for p in primitives):raise ValueError('Expected a shared surface vertex pool')
+    rp=rig['meshes'][rig['nodes'][rig_body]['mesh']]['primitives'][0]
+    bound_positions=accessor(rig,rig_data,rp['attributes']['POSITION']);bound_joints=accessor(rig,rig_data,rp['attributes']['JOINTS_0']).astype(np.int32);bound_weights=accessor(rig,rig_data,rp['attributes']['WEIGHTS_0'])
+    if not np.issubdtype(bound_weights.dtype,np.floating):raise ValueError('Decode normalized integer weight attributes explicitly')
+    scale=rig_report['normalization']['scale'];center=np.asarray(rig_report['normalization']['center']);normalization=np.eye(4);normalization[:3,:3]*=scale;normalization[:3,3]=-center[[0,2,1]]*np.array([1,1,-1])*scale
+    transform=normalization@worlds[body_node];expected=positions@transform[:3,:3].T+transform[:3,3]
+    binding_index=primitives[0]['attributes'].get('_BIND_SOURCE_POSITION')
+    if any(p['attributes'].get('_BIND_SOURCE_POSITION')!=binding_index for p in primitives):raise ValueError('Expected shared source binding positions across material partitions')
+    binding_positions=positions if binding_index is None else accessor(doc,data,binding_index)
+    if binding_positions.shape!=positions.shape or not np.isfinite(binding_positions).all():raise ValueError('Invalid source binding positions')
+    binding_expected=binding_positions@transform[:3,:3].T+transform[:3,3]
+    distance,index=cKDTree(bound_positions).query(binding_expected);tolerance=max(np.ptp(bound_positions,axis=0))*2e-6
+    joints=bound_joints[index].copy();weights=bound_weights[index].copy();unmatched=distance>tolerance
+    source_skin=rig['skins'][0];head_indices=[k for k,i in enumerate(source_skin['joints']) if rig['nodes'][i].get('name') in ['Head','mixamorigHead','mixamorig:Head']]
+    if len(head_indices)!=1:raise ValueError('The shared rig must identify one Head joint')
+    head=head_indices[0]
+    barycentric_count=0
+    if unmatched.any():
+        # A clipped ocular vertex is safe only within the explicit rigid-head field.
+        d,near=cKDTree(bound_positions).query(binding_expected[unmatched],k=4)
+        head_weight=np.sum(bound_weights[near]*(bound_joints[near]==head),axis=2)
+        rigid=(d<=.003).all(1)&(head_weight>=.9999).all(1)
+        missing_ids=np.flatnonzero(unmatched);joints[missing_ids[rigid]]=head;weights[missing_ids[rigid]]=[1,0,0,0]
+        if not rigid.all():
+            selected=missing_ids[~rigid]
+            faces=np.concatenate([accessor(rig,rig_data,p['indices']).reshape(-1,3) for p in rig['meshes'][rig['nodes'][rig_body]['mesh']]['primitives']])
+            joints[selected],weights[selected]=surface_weight_transfer(binding_expected[selected],bound_positions,faces,bound_joints,bound_weights,tolerance)
+            barycentric_count=len(selected)
+    if not np.isfinite(weights).all() or np.max(abs(weights.sum(1)-1))>1e-5:raise ValueError('Invalid transferred weights')
+    original_length=len(data);mapping={}
+    for i,n in enumerate(rig['nodes']):
+        if i!=rig_body:mapping[i]=len(doc['nodes']);doc['nodes'].append(copy.deepcopy(n))
+    for old,new in mapping.items():
+        if 'children' in doc['nodes'][new]:doc['nodes'][new]['children']=[mapping[c] for c in rig['nodes'][old]['children'] if c!=rig_body]
+    roots=rig['scenes'][rig.get('scene',0)]['nodes'];doc['scenes'][doc.get('scene',0)]['nodes'] += [mapping[i] for i in roots if i!=rig_body]
+    inverse_bind=accessor(rig,rig_data,source_skin['inverseBindMatrices']).reshape(-1,4,4).transpose(0,2,1)
+    # Keep the rig's canonical inverse binds: Skeleton.pose() reconstructs its
+    # rest world matrices from them. Convert mesh coordinates instead of hiding
+    # a mesh-space transform inside the inverse binds.
+    coordinate_scale=np.linalg.norm(transform[:3,:3],axis=0)
+    if not np.allclose(coordinate_scale,coordinate_scale[0],rtol=1e-5):raise ValueError('Nonuniform bind-space conversion needs explicit normal handling')
+    rotation=transform[:3,:3]/coordinate_scale[0]
+    if not np.allclose(rotation.T@rotation,np.eye(3),atol=1e-5):raise ValueError('Sheared bind-space conversion is unsupported')
+    converted={}
+    def convert_attribute(index,kind,delta=False):
+        key=(index,kind,delta)
+        if key not in converted:
+            values=accessor(doc,data,index)
+            if kind=='POSITION':values=values@transform[:3,:3].T+(0 if delta else transform[:3,3])
+            elif kind=='TANGENT':values[:,:3]=values[:,:3]@rotation.T
+            else:values=values@rotation.T
+            converted[key]=append_accessor(doc,data,values.astype('<f4'),'VEC4' if kind=='TANGENT' else 'VEC3',5126)
+            if kind=='POSITION':doc['accessors'][converted[key]].update(min=values.min(0).tolist(),max=values.max(0).tolist())
+        return converted[key]
+    for p in primitives:
+        # Authoring correspondence is consumed here; it is not a renderer input.
+        p['attributes'].pop('_BIND_SOURCE_POSITION',None)
+        for kind in ['POSITION','NORMAL','TANGENT']:
+            if kind in p['attributes']:p['attributes'][kind]=convert_attribute(p['attributes'][kind],kind)
+        for target in p.get('targets',[]):
+            for kind in ['POSITION','NORMAL']:
+                if kind in target:target[kind]=convert_attribute(target[kind],kind,True)
+    adjusted=inverse_bind
+    pose_error=float(np.max(abs(np.linalg.inv(adjusted)-np.asarray([rig_world[i] for i in source_skin['joints']]))))
+    if pose_error>2e-5:raise ValueError('Inverse binds are incompatible with the engine skeleton pose reset')
+    ibm_index=append_accessor(doc,data,adjusted.transpose(0,2,1).reshape(-1,16).astype('<f4'),'MAT4',5126)
+    doc['skins']=[{'name':source_skin.get('name','SharedBodyRig'),'joints':[mapping[i] for i in source_skin['joints']],'inverseBindMatrices':ibm_index}];doc['nodes'][body_node]['skin']=0
+    ji=append_accessor(doc,data,joints.astype('<u2'),'VEC4',5123);wi=append_accessor(doc,data,weights.astype('<f4'),'VEC4',5126)
+    for p in primitives:p['attributes'].update(JOINTS_0=ji,WEIGHTS_0=wi)
+    # Optical roots and head-fixed tissue now follow the animated Head joint.
+    head_node=mapping[source_skin['joints'][head]];head_world=rig_world[source_skin['joints'][head]];rotation_changes={};attachments=list(doc['nodes'][body_node].get('children',[]))
+    for child in attachments:
+        node=doc['nodes'][child]
+        optical=node.get('extras',{}).get('characterEye') or ('mesh' in node and all(doc['materials'][p['material']].get('extras',{}).get('eyeLayer') for p in doc['meshes'][node['mesh']]['primitives']))
+        if not optical:raise ValueError('Nonocular body attachments require explicit parenting')
+        old_rotation=Rotation.from_quat(node.get('rotation',[0,0,0,1]));set_transform(node,np.linalg.inv(head_world)@normalization@worlds[child]);rotation_changes[child]=Rotation.from_quat(node['rotation'])*old_rotation.inv()
+        doc['nodes'][head_node].setdefault('children',[]).append(child)
+    doc['nodes'][body_node]['children']=[]
+    for i,node in enumerate(doc['nodes']):
+        if i!=body_node and body_node in node.get('children',[]):node['children'].remove(body_node)
+    set_transform(doc['nodes'][body_node],np.eye(4))
+    scene_nodes=doc['scenes'][doc.get('scene',0)]['nodes']
+    if body_node not in scene_nodes:scene_nodes.append(body_node)
+    for animation in doc.get('animations',[]):
+        for channel in animation['channels']:
+            target=channel['target']
+            if target.get('path')=='rotation' and target['node'] in rotation_changes:
+                sampler=animation['samplers'][channel['sampler']]
+                if sampler.get('interpolation','LINEAR')!='LINEAR':raise ValueError('Eye rotation retarget requires linear quaternion tracks')
+                q=accessor(doc,data,sampler['output']);q=(rotation_changes[target['node']]*Rotation.from_quat(q)).as_quat();sampler['output']=append_accessor(doc,data,q.astype('<f4'),'VEC4',5126)
+    copied={}
+    def copy_accessor(index):
+        if index not in copied:
+            original=rig['accessors'][index];copied[index]=append_accessor(doc,data,accessor(rig,rig_data,index),original['type'],original['componentType'])
+            for key in ['min','max','normalized']:
+                if key in original:doc['accessors'][copied[index]][key]=original[key]
+        return copied[index]
+    for animation in rig.get('animations',[]):
+        a=copy.deepcopy(animation)
+        for sampler in a['samplers']:sampler['input']=copy_accessor(sampler['input']);sampler['output']=copy_accessor(sampler['output'])
+        for channel in a['channels']:channel['target']['node']=mapping[channel['target']['node']]
+        doc.setdefault('animations',[]).append(a)
+    matrices=np.asarray([rig_world[i] for i in source_skin['joints']])@adjusted
+    maximum=0.
+    for batch in np.array_split(np.arange(len(positions)),max(1,len(positions)//100000)):
+        error=np.linalg.norm(skin_points(expected[batch],joints[batch],weights[batch],matrices)-expected[batch],axis=1);maximum=max(maximum,float(error.max()))
+    if maximum>2e-5:raise ValueError(f'Assembled bind pose does not preserve the source: {maximum}m')
+    out=base/'runtime/v1';out.mkdir(parents=True,exist_ok=True)
+    report={'id':sid,'status':'motion_review_required','viewerReady':False,'surfaceInput':relative_input,'surfaceSha256':hashlib.sha256(input_path.read_bytes()).hexdigest(),'rigSha256':rig_report['output_sha256'],'restPositionErrorM':maximum,'rigidHeadInsertedVertices':int(unmatched.sum()),'bodyBones':len(source_skin['joints']),'headAttachments':len(attachments),'clips':[a['name'] for a in doc.get('animations',[])],'sourceBufferBytesPreserved':bytes(data[:original_length])==bytes(read(input_path)[1]),'geometryChange':'Rigid uniform bind-space coordinate conversion of positions, normals and morph deltas; no surface reshaping','limitations':['Shared body rig currently has no independent finger bones','Motion and eye contact require visual acceptance']}
+    report['variant']=variant
+    report['barycentricWeightVertices']=barycentric_count
+    report['rigidHeadInsertedVertices']=int(unmatched.sum())-barycentric_count
+    report['poseResetMatrixError']=pose_error
+    report['outputSha256']=write_glb(doc,data,out/f'{variant}.glb');(out/f'{variant}-report.json').write_text(json.dumps(report,indent=2))
+    for name in ['ATTRIBUTION.txt','MakeHuman-LICENSE.md']:
+        if (input_path.parent/name).exists():shutil.copyfile(input_path.parent/name,out/name)
+    print(json.dumps(report))
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser();p.add_argument('--id',required=True);p.add_argument('--input',required=True);p.add_argument('--variant',choices=['eyes','surfaces'],default='eyes');a=p.parse_args();assemble(a.id,a.input,a.variant)

package/assets/character-skin-authoring/scripts/authored_detail.py

@@ -0,0 +1,47 @@
+"""Bake agent-authored regional crease curves; never infer anatomy or landmarks."""
+import hashlib,json
+import numpy as np
+
+LABELS={'skin':1,'palm':2,'sole':3,'dorsal_hand':9}
+
+def curve_distance(points,curve):
+    distance=np.full(len(points),np.inf)
+    for a,b in zip(curve[:-1],curve[1:]):
+        edge=b-a;length=np.dot(edge,edge)
+        if length<=0:raise ValueError('Crease curve has a repeated point')
+        t=np.clip((points-a)@edge/length,0,1)
+        distance=np.minimum(distance,np.linalg.norm(points-a-t[:,None]*edge,axis=1))
+    return distance
+
+class AuthoredDetail:
+    def __init__(self,path,manifest,physical_height):
+        self.curves=[];self.report=None
+        if not path.exists():return
+        raw=path.read_bytes();profile=json.loads(raw)
+        if profile['sourceSha256']!=manifest['sourceSha256']:raise ValueError('Body detail profile belongs to another source')
+        for record in profile['curves']:
+            index=next(i for i,v in enumerate(manifest['views']) if v['name']==record['view'])
+            image=record['view']+'.png'
+            if profile['evidenceHashes'].get(image)!=manifest['evidenceHashes'].get(image):raise ValueError('Body detail coordinates belong to different view evidence')
+            view=manifest['views'][index];direction=np.asarray(view['direction'],float);direction/=np.linalg.norm(direction)
+            right=np.cross(direction,view.get('up',[0,0,1]));right/=np.linalg.norm(right);up=np.cross(right,direction)
+            curve=np.asarray(record['pointsPx'],float)
+            if curve.ndim!=2 or curve.shape[1]!=2 or len(curve)<2 or not np.isfinite(curve).all():raise ValueError('Invalid authored crease polyline')
+            width=record['widthM'];depth=record['depthM']
+            if not 0<width<=.003 or not 0<depth<=.00025:raise ValueError('Crease dimensions exceed the supported skin-detail range')
+            self.curves.append((index,np.asarray(view.get('targetOffset',[0,0,0]))*physical_height,right,up,direction,view['span']*physical_height,manifest['size'],curve,width,depth,LABELS[record['region']]))
+        self.report={'profileSha256':hashlib.sha256(raw).hexdigest(),'curves':len(self.curves),'provenance':profile['provenance'],'method':'agent-authored regional curves projected only onto visible independently labelled skin; physical width/depth'}
+
+    def evaluate(self,points,normals,labels,visibility):
+        result=np.zeros(len(points),np.float32)
+        for index,target,right,up,direction,span,size,curve,width,depth,region in self.curves:
+            selected=(labels==region)&((visibility&(1<<index))!=0)
+            if not selected.any():continue
+            local=points[selected]-target
+            xy=np.stack([(local@right/span+.5)*size,(.5-local@up/span)*size],1)
+            distance=curve_distance(xy,curve)*span/size
+            facing=np.clip((abs(normals[selected]@direction)-.2)/.3,0,1)
+            # A compact smooth groove avoids hard tube ends and adds no pigment.
+            relief=-depth*np.exp(-.5*(distance/width)**2)*facing*facing*(3-2*facing)
+            result[selected]=np.minimum(result[selected],relief)
+        return result

package/assets/character-skin-authoring/scripts/authored_surface_patch.py

@@ -0,0 +1,83 @@
+"""Vision-registered roughness/height exemplars, limited by labels and visibility.
+
+No inferred anatomy and no conversion of normal RGB into displacement.
+"""
+import hashlib,json
+from pathlib import Path
+import numpy as np
+from PIL import Image,ImageDraw
+from scipy.interpolate import RBFInterpolator
+from scipy.ndimage import distance_transform_edt,map_coordinates,gaussian_filter
+from authored_detail import LABELS
+
+class AuthoredSurfacePatch:
+ def __init__(self,path,manifest,physical_height,root):
+  self.patches=[];self.independent=[];self.report=None;self.attributions={}
+  if not path.exists():return
+  raw=path.read_bytes();profile=json.loads(raw)
+  if profile['sourceSha256']!=manifest['sourceSha256']:raise ValueError('Surface patch belongs to another source')
+  receipts=[]
+  for record in profile['patches']:
+   index=next(i for i,v in enumerate(manifest['views'])if v['name']==record['view']);view=manifest['views'][index];image=record['view']+'.png'
+   image_path=Path(manifest['output'])/image
+   if profile['evidenceHashes'].get(image)!=manifest['evidenceHashes'].get(image) or hashlib.sha256(image_path.read_bytes()).hexdigest()!=profile['evidenceHashes'][image]:raise ValueError('Surface patch evidence changed')
+   texture_path=root/record['roughnessTexture'];data=texture_path.read_bytes()
+   if hashlib.sha256(data).hexdigest()!=record['textureSha256']:raise ValueError('Surface patch exemplar changed')
+   provenance=record['provenance'];license_bytes=(root/provenance['licenseFile']).read_bytes()
+   if hashlib.sha256(license_bytes).hexdigest()!=provenance['licenseSha256']:raise ValueError('Surface patch license receipt changed')
+   self.attributions[provenance['licenseSha256']]=provenance['title']+'\n'+provenance['url']+'\nAdapted by vision registration and roughness remapping.\n'+license_bytes.decode()
+   donor=np.asarray(Image.open(texture_path).convert('L'),float)/255
+   source=np.asarray(record['sourcePixels'],float);target=np.asarray(record['targetPixels'],float)
+   if source.shape!=target.shape or source.ndim!=2 or source.shape[1]!=2 or len(source)<3 or not np.isfinite(source).all() or not np.isfinite(target).all():raise ValueError('Invalid surface patch correspondences')
+   size=manifest['size'];donor_size=record['sourceAnnotationImageSize'];resolution=record.get('sampleResolution',size)
+   if not isinstance(resolution,int) or not 16<=resolution<=4096:raise ValueError('Invalid patch sampling resolution')
+   if (target<0).any() or (target>=size).any() or (source<0).any() or (source>=donor_size).any():raise ValueError('Surface patch pixel outside evidence')
+   if not 0<record['featherM']<=.02:raise ValueError('Invalid surface patch feather')
+   low,high=record['roughnessRange']
+   if not 0<=low<high<=1:raise ValueError('Invalid surface patch roughness range')
+   target_mask=Image.new('L',(resolution,resolution));ImageDraw.Draw(target_mask).polygon([tuple(p*resolution/size)for p in target],fill=255);inside=np.asarray(target_mask)>0
+   yy,xx=np.nonzero(inside);mapped=RBFInterpolator(target/size,source/donor_size,kernel='thin_plate_spline',smoothing=0)(np.column_stack([xx,yy])/resolution)
+   sampled=map_coordinates(gaussian_filter(donor,1),[mapped[:,1]*(donor.shape[0]-1),mapped[:,0]*(donor.shape[1]-1)],order=1,mode='nearest')
+   # Preserve exemplar variation inside a declared art-directed physical response range.
+   rough=np.full((resolution,resolution),.5*(low+high));rough[yy,xx]=low+(high-low)*sampled
+   height=None
+   if record.get('height'):
+    h=record['height'];height_path=root/h['path']
+    if hashlib.sha256(height_path.read_bytes()).hexdigest()!=h['sha256']:raise ValueError('Surface height exemplar changed')
+    field=np.load(height_path,allow_pickle=False);bounds=np.asarray(h['boundsPx'],float)
+    if field.ndim!=2 or not np.isfinite(field).all() or np.max(abs(field))>.001 or bounds.shape!=(4,) or not np.isfinite(bounds).all() or np.any(bounds[2:]<=bounds[:2]) or not 0<h['scale']<=4 or not h.get('provenance'):
+     raise ValueError('Invalid physical surface height field or provenance')
+    coordinates=(mapped*donor_size-bounds[:2])/(bounds[2:]-bounds[:2])
+    height=np.zeros((resolution,resolution));height[yy,xx]=map_coordinates(field,[coordinates[:,1]*(field.shape[0]-1),coordinates[:,0]*(field.shape[1]-1)],order=1,mode='nearest')*h['scale']
+    self.attributions[provenance['licenseSha256']]+='\nHeight adaptation: '+json.dumps(h['provenance'])+'\n'
+   feather=np.clip(distance_transform_edt(inside)*view['span']*physical_height/resolution/record['featherM'],0,1);feather=feather*feather*(3-2*feather)
+   direction=np.asarray(view['direction'],float);direction/=np.linalg.norm(direction);right=np.cross(direction,view.get('up',[0,0,1]));right/=np.linalg.norm(right);up=np.cross(right,direction)
+   self.patches.append((index,np.asarray(view.get('targetOffset',[0,0,0]))*physical_height,right,up,direction,view['span']*physical_height,resolution,LABELS[record['region']],rough,feather,height))
+   self.independent.append(record.get('independentDetail',False))
+   receipts.append({'view':record['view'],'region':record['region'],'roughnessTexture':record['roughnessTexture'],'textureSha256':record['textureSha256'],'roughnessRange':record['roughnessRange'],'height':record.get('height'),'provenance':record['provenance'],'independentDetail':self.independent[-1],'sampleResolution':resolution})
+  self.report={'profileSha256':hashlib.sha256(raw).hexdigest(),'patches':receipts,'method':'independent vision correspondences; optional physical height; semantic labels and geometric visibility constrain application'}
+
+ def evaluate(self,points,normals,labels,visibility,base,include_independent=True):
+  return self._evaluate(points,normals,labels,visibility,base,False,include_independent)
+
+ def relief(self,points,normals,labels,visibility,include_independent=True):
+  return self._evaluate(points,normals,labels,visibility,np.zeros(len(points)),True,include_independent)
+
+ def _evaluate(self,points,normals,labels,visibility,base,use_height,include_independent):
+  total=np.zeros(len(points));value=np.zeros(len(points))
+  for independent,patch in zip(self.independent,self.patches):
+   if independent and not include_independent:continue
+   index,target,right,up,direction,span,size,region,rough,feather,height=patch
+   field=height if use_height else rough
+   if field is None:continue
+   selected=(labels==region)&((visibility&(1<<index))!=0)
+   if not selected.any():continue
+   local=points[selected]-target;xy=np.stack([(local@right/span+.5)*size,(.5-local@up/span)*size],1)
+   weight=map_coordinates(feather,[xy[:,1],xy[:,0]],order=1,mode='constant',cval=0)
+   facing=np.clip((abs(normals[selected]@direction)-.2)/.3,0,1);weight*=facing*facing*(3-2*facing)
+   value[selected]+=map_coordinates(field,[xy[:,1],xy[:,0]],order=1,mode='nearest')*weight;total[selected]+=weight
+  return base*(1-np.minimum(total,1))+value/np.maximum(total,1e-12)*np.minimum(total,1)
+
+ def independent_planes(self):
+  names=['index','target','right','up','direction','span','size','region','roughness','feather','height']
+  return [dict(zip(names,patch)) for independent,patch in zip(self.independent,self.patches) if independent]