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

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

@@ -0,0 +1,171 @@
+"""Rest-space eyelid closure from authored ocular contours; eyeballs never scale."""
+import numpy as np
+from scipy.spatial.transform import Rotation
+from glb_arrays import accessor
+from glb_output import append_accessor
+from vision_materials import source_world_points
+
+def surface_normal_groups(rest):
+    """Weld geometric duplicates for deformation normals, retaining every UV vertex."""
+    tolerance=max(float(np.ptp(rest,axis=0).max())*1e-8,1e-12)
+    return np.unique(np.round(rest/tolerance).astype(np.int64),axis=0,return_inverse=True)[1]
+
+def surface_normals(vertices,faces,groups):
+    face=np.cross(vertices[faces[:,1]]-vertices[faces[:,0]],vertices[faces[:,2]]-vertices[faces[:,0]])
+    summed=np.zeros((int(groups.max())+1,3),dtype=np.float64)
+    for k in range(3):np.add.at(summed,groups[faces[:,k]],face)
+    summed/=np.maximum(np.linalg.norm(summed,axis=1,keepdims=True),1e-12)
+    return summed[groups]
+
+def transport_normals(original,rest,deformed):
+    """Rotate authored normals with the geometric frame instead of adding vectors."""
+    result=np.asarray(original,dtype=float).copy()
+    valid=(np.linalg.norm(rest,axis=1)>1e-8)&(np.linalg.norm(deformed,axis=1)>1e-8)
+    a=rest[valid]/np.linalg.norm(rest[valid],axis=1,keepdims=True)
+    b=deformed[valid]/np.linalg.norm(deformed[valid],axis=1,keepdims=True)
+    n=result[valid];cosine=np.clip((a*b).sum(1),-1,1);axis=np.cross(a,b)
+    regular=cosine>-1+1e-8
+    v=axis[regular];x=n[regular]
+    n[regular]=x+np.cross(v,x)+np.cross(v,np.cross(v,x))/(1+cosine[regular,None])
+    if (~regular).any():
+        # The shortest rotation is ambiguous at 180 degrees; select a stable
+        # perpendicular axis, retaining unit length and the geometric endpoint.
+        old=a[~regular];basis=np.eye(3)[np.argmin(abs(old),axis=1)]
+        v=np.cross(old,basis);v/=np.linalg.norm(v,axis=1,keepdims=True)
+        x=n[~regular];n[~regular]=2*v*(v*x).sum(1)[:,None]-x
+    n/=np.maximum(np.linalg.norm(n,axis=1,keepdims=True),1e-12)
+    result[valid]=n
+    return result
+
+def closed_lid(points,o,band_pixels=36):
+    target=o['target'];right=o['right'];up=o['up'];forward=-o['direction'];span=o['span'];size=o['size'];contour=np.asarray(o['contour'])
+    xy=np.stack([((points-target)@right/span+.5)*size,(.5-(points-target)@up/span)*size],1);x=xy[:,0];y=xy[:,1]
+    upper=np.full(len(points),np.inf);lower=np.full(len(points),-np.inf)
+    for a,b in zip(contour,np.roll(contour,-1,axis=0)):
+        if abs(b[0]-a[0])<1e-9:continue
+        valid=(x>=min(a[0],b[0]))&(x<=max(a[0],b[0]));yy=a[1]+(x-a[0])/(b[0]-a[0])*(b[1]-a[1]);upper[valid]=np.minimum(upper[valid],yy[valid]);lower[valid]=np.maximum(lower[valid],yy[valid])
+    valid=np.isfinite(upper)&np.isfinite(lower)&(np.linalg.norm(points-o['center'],axis=1)<o['radius']*2)&((points-o['center'])@forward>0)
+    # Invalid columns are neutral; avoid infinities entering the deformation arithmetic.
+    upper[~valid]=y[~valid];lower[~valid]=y[~valid]
+    middle=upper*.3+lower*.7;top=y<=middle;edge=np.where(top,upper,lower);distance=abs(y-edge)
+    weight=np.clip(1-distance/band_pixels,0,1);weight=weight*weight*(3-2*weight);weight*=valid
+    movement=(middle-edge)*weight;out=points-up[None,:]*(movement*span/size)[:,None]
+    lateral=np.stack([(out-o['center'])@right,(out-o['center'])@up],1);rad=np.linalg.norm(lateral,axis=1)
+    depth=np.sqrt(np.maximum(0,o['radius']**2-rad**2));limbus=np.sqrt(o['radius']**2-o['iris']**2)
+    depth=np.where(rad<o['iris'],limbus+o['bulge']*np.maximum(0,1-(rad/o['iris'])**2),depth)+o['unit']*.00025
+    current=(out-o['center'])@forward
+    correction=depth-current
+    # Follow the globe where closure requires it, without dragging the whole
+    # orbital support band inward. Fade inward fitting at the canthi, where
+    # the authored upper and lower contours already meet and do not travel.
+    canthus=np.clip((lower-upper)/8,0,1)
+    inward=weight**8*canthus
+    correction=np.where(correction>0,correction*weight,correction*inward)
+    out+=forward[None,:]*correction[:,None]
+    return out,weight
+
+def conform_open_lid(points,o,band_pixels=36):
+    """Push intersecting lid tissue outside the authored globe, never pull skin in.
+
+    Selection is the explicitly fitted opening and its local support band. This
+    is a geometric fit operation, not an anatomical segmentation algorithm.
+    """
+    forward=-o['direction'];rel=points-o['center']
+    xy=np.stack([((points-o['target'])@o['right']/o['span']+.5)*o['size'],(.5-(points-o['target'])@o['up']/o['span'])*o['size']],1)
+    distance=np.full(len(points),np.inf)
+    contour=np.asarray(o['contour'],float)
+    for a,b in zip(contour,np.roll(contour,-1,axis=0)):
+        edge=b-a;t=np.clip(((xy-a)*edge).sum(1)/np.dot(edge,edge),0,1)
+        distance=np.minimum(distance,np.linalg.norm(xy-a-t[:,None]*edge,axis=1))
+    lateral=np.stack([rel@o['right'],rel@o['up']],1);rad=np.linalg.norm(lateral,axis=1);current=rel@forward
+    support=(distance<band_pixels)&(current>0)&(rad<o['radius'])
+    depth=np.sqrt(np.maximum(0,o['radius']**2-rad**2))+o['unit']*.00025
+    limbus=np.sqrt(o['radius']**2-o['iris']**2)
+    depth=np.where(rad<o['iris'],limbus+o['bulge']*np.maximum(0,1-(rad/o['iris'])**2)+o['unit']*.00025,depth)
+    delta=np.where(support,np.maximum(0,depth-current),0)
+    return points+delta[:,None]*forward,delta>0
+
+def follow_lid(points,o,direction):
+    _,weight=closed_lid(points,o)
+    xy=np.stack([((points-o['target'])@o['right']/o['span']+.5)*o['size'],(.5-(points-o['target'])@o['up']/o['span'])*o['size']],1)
+    contour=np.asarray(o['contour']);lo,hi=contour[:,0].min(),contour[:,0].max()
+    across=np.clip((xy[:,0]-lo)/(hi-lo),0,1)
+    canthus=np.sin(np.pi*across)**2
+    gains=o.get('lidFollowGains',[.55,.2])
+    gain=np.where(xy[:,1]<contour[:,1].mean(),gains[0],gains[1])
+    offset=direction*.35*o['radius']*gain*weight*canthus
+    moved=points+offset[:,None]*o['up']
+    # Refit only vertices affected by this target; a neutral eye's unrelated
+    # support vertices must not move when the gaze controller changes.
+    fitted,_=conform_open_lid(moved,o);active=abs(offset)>1e-12
+    moved[active]=fitted[active]
+    return moved,active
+
+def add_blinks(doc,data,source,openings,eye_nodes):
+    mesh=doc['meshes'][0]
+    if any(p.get('targets') for p in mesh['primitives']):raise ValueError('Compose existing facial morphs explicitly before adding eyelid targets')
+    prim=mesh['primitives'][0];local=accessor(doc,data,prim['attributes']['POSITION']);world=source_world_points(source,local)
+    origin=source_world_points(source,np.zeros((1,3)))[0];basis=(source_world_points(source,np.eye(3))-origin).T;inverse=np.linalg.inv(basis)
+    names=['eyeBlink'+o['side'].title() for o in openings];targets=[];counts=[]
+    faces=np.concatenate([accessor(doc,data,p['indices']).reshape(-1,3) for p in mesh['primitives']]);original_normals=accessor(doc,data,prim['attributes']['NORMAL'])
+    groups=surface_normal_groups(local)
+    def geometric_normals(vertices):return surface_normals(vertices,faces,groups)
+    base_normals=geometric_normals(local)
+    for o in openings:
+        closed,weight=closed_lid(world,o);delta=(closed-world)@inverse.T
+        adjusted=transport_normals(original_normals,base_normals,geometric_normals(local+delta));normal_delta=adjusted-original_normals;normal_delta[weight==0]=0
+        targets.append({'POSITION':append_accessor(doc,data,delta.astype('<f4'),'VEC3',5126),'NORMAL':append_accessor(doc,data,normal_delta.astype('<f4'),'VEC3',5126)});counts.append(int((weight>0).sum()))
+    for o in openings:
+        for direction,title in [(1,'Up'),(-1,'Down')]:
+            followed,active=follow_lid(world,o,direction);delta=(followed-world)@inverse.T
+            adjusted=transport_normals(original_normals,base_normals,geometric_normals(local+delta))
+            normal_delta=adjusted-original_normals;normal_delta[~active]=0
+            targets.append({'POSITION':append_accessor(doc,data,delta.astype('<f4'),'VEC3',5126),'NORMAL':append_accessor(doc,data,normal_delta.astype('<f4'),'VEC3',5126)})
+            names.append('eyeLidLook'+title+o['side'].title())
+    for p in mesh['primitives']:p['targets']=targets.copy()
+    mesh['weights']=[0]*len(names);mesh.setdefault('extras',{})['targetNames']=names
+    times=np.array([0,.8,.9,.98,1.12,2],dtype='<f4');values=np.array([0,0,1,1,0,0],dtype='<f4');time_index=append_accessor(doc,data,times,'SCALAR',5126)
+    animation={'name':'Eyes Blink','samplers':[],'channels':[]}
+    def channel(node,weights):
+        i=len(animation['samplers']);animation['samplers'].append({'input':time_index,'output':append_accessor(doc,data,weights.astype('<f4').reshape(-1),'SCALAR',5126),'interpolation':'LINEAR'});animation['channels'].append({'sampler':i,'target':{'node':node,'path':'weights'}})
+    parent=next(i for i,n in enumerate(doc['nodes']) if n.get('mesh')==0);channel(parent,np.column_stack([values,values,np.zeros((len(values),len(names)-2))]))
+    gaze_bindings=[(parent,names)]
+    # Orbital backing stays head-fixed behind the optical envelope. Moving it
+    # toward the cornea during closure crosses the recessed iris at partial blinks.
+    for node_index,node in enumerate(doc['nodes']):
+        if 'mesh' not in node or node['mesh']==0:continue
+        m=doc['meshes'][node['mesh']];p=m['primitives'][0];material=doc['materials'][p['material']]
+        if material.get('extras',{}).get('eyeLayer') not in ['lid-contact','tear-meniscus','eyelashes','eyelid-skin','canthus-wall']:continue
+        side=next(i for i,o in enumerate(openings) if o['side']==material['extras']['eyeSide'])
+        p0=accessor(doc,data,p['attributes']['POSITION']);motion_points=accessor(doc,data,p['attributes']['_LID_WALL_ROOT']) if '_LID_WALL_ROOT' in p['attributes'] else accessor(doc,data,p['attributes']['_LASH_ROOT']) if '_LASH_ROOT' in p['attributes'] else p0;world0=source_world_points(source,motion_points);closed,weight=closed_lid(world0,openings[side])
+        transport=accessor(doc,data,p['attributes']['_LID_WALL_WEIGHT']).reshape(-1,1) if '_LID_WALL_WEIGHT' in p['attributes'] else 1
+        delta=((closed-world0)@inverse.T)*transport
+        p['targets']=[{'POSITION':append_accessor(doc,data,delta.astype('<f4'),'VEC3',5126)}]
+        def add_patch_normals(target,offset):
+            if material['extras']['eyeLayer'] not in ['eyelid-skin','canthus-wall']:return
+            faces=accessor(doc,data,p['indices']).reshape(-1,3);groups=surface_normal_groups(p0)
+            original=accessor(doc,data,p['attributes']['NORMAL'])
+            adjusted=transport_normals(original,surface_normals(p0,faces,groups),surface_normals(p0+offset,faces,groups))
+            target['NORMAL']=append_accessor(doc,data,(adjusted-original).astype('<f4'),'VEC3',5126)
+        add_patch_normals(p['targets'][-1],delta)
+        local_names=[names[side]]
+        for direction,title in [(1,'Up'),(-1,'Down')]:
+            followed,_=follow_lid(world0,openings[side],direction);delta=((followed-world0)@inverse.T)*transport
+            p['targets'].append({'POSITION':append_accessor(doc,data,delta.astype('<f4'),'VEC3',5126)})
+            add_patch_normals(p['targets'][-1],delta)
+            local_names.append('eyeLidLook'+title+openings[side]['side'].title())
+        m['weights']=[0]*len(local_names);m['extras']={'targetNames':local_names}
+        channel(node_index,np.column_stack([values,np.zeros((len(values),2))]));gaze_bindings.append((node_index,local_names))
+    doc.setdefault('animations',[]).append(animation)
+    gaze={'name':'Eyes Gaze','samplers':[],'channels':[]};gaze_times=append_accessor(doc,data,np.array([0,1,2,3,4],dtype='<f4'),'SCALAR',5126)
+    for i,node in enumerate(eye_nodes):
+        rest=Rotation.from_quat(doc['nodes'][node]['rotation']);rotations=np.array([(rest*Rotation.from_euler('yx',[yaw,pitch])).as_quat() for yaw,pitch in [(0,0),(.2,0),(0,.1),(-.2,0),(0,0)]],dtype='<f4')
+        gaze['samplers'].append({'input':gaze_times,'output':append_accessor(doc,data,rotations,'VEC4',5126),'interpolation':'LINEAR'});gaze['channels'].append({'sampler':i,'target':{'node':node,'path':'rotation'}})
+    for node,target_names in gaze_bindings:
+        weights=np.zeros((5,len(target_names)),dtype='<f4')
+        for j,name in enumerate(target_names):
+            if name.startswith('eyeLidLookDown'):weights[2,j]=.1/.35
+        sampler=len(gaze['samplers']);gaze['samplers'].append({'input':gaze_times,'output':append_accessor(doc,data,weights.reshape(-1),'SCALAR',5126),'interpolation':'LINEAR'})
+        gaze['channels'].append({'sampler':sampler,'target':{'node':node,'path':'weights'}})
+    doc['animations'].append(gaze)
+    return {'controls':names,'affectedVertices':counts,'method':'contour-defined eyelid closure with surface-following depth and smooth outer falloff','normals':'shortest-frame rotation transports authored normals with area-weighted deformed surface normals'}

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

@@ -0,0 +1,173 @@
+"""Reconstruct a lid band between two explicitly authored ocular contours."""
+import numpy as np
+from eyelid_morph import conform_open_lid,surface_normals,surface_normal_groups
+
+def authored_corner_support(hit,plane,opening):
+    """Apply an explicitly reviewed corner depth, fading to source support."""
+    result=np.asarray(hit,float).copy();forward=-opening['direction']
+    pixel=np.array([((plane-opening['target'])@opening['right']/opening['span']+.5)*opening['size'],(.5-(plane-opening['target'])@opening['up']/opening['span'])*opening['size']])
+    for patch in opening.get('cornerDepths',[]):
+        radius=patch['radiusM']*opening['unit']/opening['span']*opening['size']
+        if radius<=0 or not np.isfinite([radius,patch['depthM']]).all():raise ValueError('Invalid authored corner depth')
+        t=np.clip(1-np.linalg.norm(pixel-np.asarray(patch['pixel']))/radius,0,1);weight=t*t*(3-2*t)
+        result+=forward*((patch['depthM']*opening['unit']-(result-opening['center'])@forward)*weight)
+    return result
+
+def lid_contact_depth(radial_distance,radius,globe_depth,source_depth):
+    """Beyond the sphere, retain authored face support instead of collapsing to zero."""
+    t=np.clip((radial_distance/radius-.85)/.15,0,1)
+    t=t*t*(3-2*t)
+    return globe_depth+t*np.maximum(0,source_depth-globe_depth)
+
+def corner_contact_depth(radial,globe,source,plane,o):
+    depth=lid_contact_depth(radial,o['radius'],globe,source)
+    for patch in o.get('cornerDepths',[]):
+        pixel=np.asarray(patch['pixel']);corner=o['target']+o['right']*(pixel[0]/o['size']-.5)*o['span']+o['up']*(.5-pixel[1]/o['size'])*o['span']
+        rel=corner-o['center'];end=np.linalg.norm(rel-(rel@o['direction'])*o['direction']);start=.85*o['radius']
+        if end<=start:raise ValueError('Authored corner must lie outside the inner globe support')
+        axis=rel-(rel@o['direction'])*o['direction'];axis/=end
+        lateral=plane-o['center'];lateral-=((lateral@o['direction'])*o['direction'])
+        distance=np.linalg.norm(lateral-(lateral@axis)*axis)
+        width=patch['radiusM']*o['unit']
+        w=np.clip((width-distance)/(width*.5),0,1);w=w*w*(3-2*w)
+        if lateral@axis<=0:w=0
+        if radial>start and w>0:
+            t=np.clip((radial-start)/(end-start),0,1);z=np.sqrt(o['radius']**2-start**2);slope=-start/z
+            curve=(2*t**3-3*t*t+1)*z+(t**3-2*t*t+t)*slope*(end-start)+(-2*t**3+3*t*t)*patch['depthM']*o['unit']
+            # Preserve the globe clearance and blend away from the authored corner.
+            depth=max(globe,depth*(1-w)+curve*w)
+    return depth
+
+def sample_paired_contours(inner,outer,projected_triangles=None):
+    """Preserve source-edge breakpoints on the reconstructed band's outer rim."""
+    inner=np.asarray(inner,float);outer=np.asarray(outer,float);inside=[];outside=[]
+    if projected_triangles is not None:
+        a=projected_triangles.reshape(-1,2)
+        b=np.roll(projected_triangles,-1,axis=1).reshape(-1,2);edge=b-a
+    for i,p in enumerate(outer):
+        q=outer[(i+1)%len(outer)];d=q-p;ts=list(np.arange(8)/8)
+        if projected_triangles is not None:
+            offset=a-p;den=d[0]*edge[:,1]-d[1]*edge[:,0];valid=abs(den)>1e-12
+            safe=np.where(valid,den,1)
+            t=(offset[:,0]*edge[:,1]-offset[:,1]*edge[:,0])/safe
+            u=(offset[:,0]*d[1]-offset[:,1]*d[0])/safe
+            valid&=(t>0)&(t<1)&(u>=-1e-10)&(u<=1+1e-10)
+            ts.extend(t[valid])
+            collinear=(~(abs(den)>1e-12))&(abs(offset[:,0]*d[1]-offset[:,1]*d[0])<1e-10)
+            for endpoints in [a[collinear],b[collinear]]:
+                along=(endpoints-p)@d/np.dot(d,d);ts.extend(along[(along>0)&(along<1)])
+        t=np.unique(np.round(ts,12));t=t[t<1]
+        outside.extend(p[None,:]*(1-t[:,None])+q[None,:]*t[:,None])
+        inside.extend(inner[i][None,:]*(1-t[:,None])+inner[(i+1)%len(inner)][None,:]*t[:,None])
+    return np.asarray(inside),np.asarray(outside)
+
+def sample_hit(origin,direction,points,triangles,uv,rgb,normals):
+    a=points[triangles[:,0]];e1=points[triangles[:,1]]-a;e2=points[triangles[:,2]]-a
+    h=np.cross(direction,e2);det=(e1*h).sum(1);safe=np.where(abs(det)>1e-12,det,1)
+    s=origin-a;u=(s*h).sum(1)/safe;q=np.cross(s,e1);v=(q*direction).sum(1)/safe;t=(e2*q).sum(1)/safe
+    valid=(abs(det)>1e-12)&(u>=0)&(v>=0)&(u+v<=1)&(t>0)
+    if not valid.any():raise ValueError('Authored outer lid contour misses the source surface')
+    index=np.argmin(np.where(valid,t,np.inf));tex=np.array([1-u[index]-v[index],u[index],v[index]])@uv[triangles[index]]
+    x=np.clip(tex[0]*rgb.shape[1]-.5,0,rgb.shape[1]-1);y=np.clip(tex[1]*rgb.shape[0]-.5,0,rgb.shape[0]-1)
+    ix,iy=int(x),int(y);jx,jy=min(ix+1,rgb.shape[1]-1),min(iy+1,rgb.shape[0]-1)
+    c=(rgb[iy,ix]*(1-(x-ix))+rgb[iy,jx]*(x-ix))*(1-(y-iy))+(rgb[jy,ix]*(1-(x-ix))+rgb[jy,jx]*(x-ix))*(y-iy)
+    c=c/255;c=np.where(c<=.04045,c/12.92,((c+.055)/1.055)**2.4)
+    normal=np.array([1-u[index]-v[index],u[index],v[index]])@normals[triangles[index]]
+    normal/=max(np.linalg.norm(normal),1e-12)
+    return origin+direction*t[index],c,normal
+
+def fair_lid_depth(vertices,faces,forward,boundary):
+    """Harmonic depth fairing on the projected mesh, with both rims fixed."""
+    from scipy.sparse import coo_matrix,diags
+    from scipy.sparse.linalg import spsolve
+    vertices=np.asarray(vertices);depth=vertices@forward
+    xy=vertices-depth[:,None]*forward
+    edges=np.unique(np.sort(np.concatenate([faces[:,[0,1]],faces[:,[1,2]],faces[:,[2,0]]]),axis=1),axis=0)
+    length=np.linalg.norm(xy[edges[:,0]]-xy[edges[:,1]],axis=1)
+    weight=1/np.maximum(length,1e-10)
+    row=np.r_[edges[:,0],edges[:,1]];col=np.r_[edges[:,1],edges[:,0]]
+    adjacency=coo_matrix((np.r_[weight,weight],(row,col)),shape=(len(vertices),len(vertices))).tocsr()
+    lap=diags(np.asarray(adjacency.sum(1)).ravel())-adjacency
+    free=np.flatnonzero(~boundary);fixed=np.flatnonzero(boundary)
+    fitted=depth.copy();fitted[free]=spsolve(lap[free][:,free],-lap[free][:,fixed]@depth[fixed])
+    result=vertices+(fitted-depth)[:,None]*forward;result[boundary]=vertices[boundary]
+    return result
+
+def build_lid_band(o,outer,points,triangles,uv,rgb,inverse,origin_basis,source_normals=None,skin_samples=None,outer_edge_sampling=None,depth_fairing=False):
+    inner=np.asarray(o['contour'],float);outer=np.asarray(outer,float)
+    if outer.shape!=inner.shape:raise ValueError('Lid contours need paired authored vertices')
+    area=np.sum(outer[:,0]*np.roll(outer[:,1],-1)-outer[:,1]*np.roll(outer[:,0],-1))
+    sign=1 if area>0 else -1
+    for a,b in zip(outer,np.roll(outer,-1,axis=0)):
+        edge=b-a
+        if np.any(sign*(edge[0]*(inner[:,1]-a[1])-edge[1]*(inner[:,0]-a[0]))<0):raise ValueError('Outer lid contour must contain the optical aperture')
+    direction=o['direction'];forward=-direction;right=o['right'];up=o['up'];target=o['target'];span=o['span'];size=o['size']
+    projection=np.stack([((points-target)@right/span+.5)*size,(.5-(points-target)@up/span)*size],1)
+    lo=outer.min(0)-1;hi=outer.max(0)+1;projected=projection[triangles]
+    candidates=(projected.min(1)<=hi).all(1)&(projected.max(1)>=lo).all(1)
+    candidates&=np.linalg.norm(points[triangles].mean(1)-o['center'],axis=1)<o['radius']*3
+    local_triangles=triangles[candidates]
+    if not len(local_triangles):raise ValueError('No source triangles behind authored lid band')
+    if outer_edge_sampling not in [None,'source-intersections-v1']:raise ValueError('Unsupported lid boundary sampling')
+    if source_normals is None:source_normals=surface_normals(points,triangles,surface_normal_groups(points))
+    inner,outer=sample_paired_contours(inner,outer,projection[local_triangles] if outer_edge_sampling else None)
+    edge_points=[];edge_colors=[];edge_normals=[];inside=[]
+    ray_offset=np.ptp(points,axis=0).max()*2
+    for p,q in zip(inner,outer):
+        plane=target+right*((q[0]/size)-.5)*span+up*(.5-q[1]/size)*span
+        hit,color,normal=sample_hit(plane-direction*ray_offset,direction,points,local_triangles,uv,rgb,source_normals)
+        edge_points.append(hit);edge_colors.append(color);edge_normals.append(normal)
+        plane=target+right*(p[0]/size-.5)*span+up*(.5-p[1]/size)*span
+        xy=np.array([(plane-o['center'])@right,(plane-o['center'])@up]);r=np.linalg.norm(xy)
+        depth=np.sqrt(max(0,o['radius']**2-r*r))
+        if r<o['iris']:depth=np.sqrt(o['radius']**2-o['iris']**2)+o['bulge']*max(0,1-(r/o['iris'])**2)
+        # Canthus support belongs to the aperture point, not the outer band's
+        # cheek/upper-fold sample. Reusing the latter pulls the inner corner
+        # toward a different facial depth and creates a visible ramp.
+        support_hit=hit
+        if r>o['radius']*.85:
+            support_hit,_,_=sample_hit(plane-direction*ray_offset,direction,points,local_triangles,uv,rgb,source_normals)
+            support_hit=authored_corner_support(support_hit,plane,o)
+        depth=corner_contact_depth(r,depth,(support_hit-o['center'])@forward,plane,o)
+        inside.append(o['center']+right*xy[0]+up*xy[1]+forward*(depth+.00025*o['unit']))
+    edge_points=np.asarray(edge_points);inside=np.asarray(inside);edge_colors=np.asarray(edge_colors);edge_normals=np.asarray(edge_normals)
+    inner_colors=edge_colors.copy()
+    if skin_samples is not None:
+        samples=np.asarray(skin_samples,float)
+        if samples.ndim!=2 or samples.shape[1]!=2 or len(samples)<3 or not np.isfinite(samples).all():
+            raise ValueError('Reconstructed lid skin requires at least three explicit valid donor pixels')
+        donors=[];donor_colors=[]
+        for q in samples:
+            plane=target+right*((q[0]+.5)/size-.5)*span+up*(.5-(q[1]+.5)/size)*span
+            hit,color,_=sample_hit(plane-direction*ray_offset,direction,points,triangles,uv,rgb,source_normals)
+            donors.append(hit);donor_colors.append(color)
+        distances=np.linalg.norm(inside[:,None,:]-np.asarray(donors)[None,:,:],axis=2)
+        weights=1/np.maximum(distances,1e-8)**2;weights/=weights.sum(1,keepdims=True)
+        inner_colors=weights@np.asarray(donor_colors)
+    chord=inside-edge_points
+    inner_normals=inside-o['center'];inner_normals/=np.maximum(np.linalg.norm(inner_normals,axis=1,keepdims=True),1e-12)
+    outer_tangent=chord-edge_normals*(chord*edge_normals).sum(1)[:,None]
+    inner_tangent=chord-inner_normals*(chord*inner_normals).sum(1)[:,None]
+    vertices=[];colors=[];faces=[];count=len(inner);rings=9
+    for row,t in enumerate(np.linspace(0,1,rings)):
+        # Outer boundary stays on the sampled source. The inner boundary follows
+        # the optical envelope. Existing source eye paint is not resampled inside.
+        vertices.extend((2*t**3-3*t*t+1)*edge_points+(t**3-2*t*t+t)*outer_tangent+(-2*t**3+3*t*t)*inside+(t**3-t*t)*inner_tangent);blend=t*t*(3-2*t);colors.extend(edge_colors*(1-blend)+inner_colors*blend)
+        if row:
+            for j in range(count):
+                a=(row-1)*count+j;b=(row-1)*count+(j+1)%count;faces.extend([[a,b,a+count],[b,b+count,a+count]])
+    world=np.asarray(vertices);faces=np.asarray(faces)
+    if depth_fairing:
+        # Hermite tangents can also bunch the projected columns at the canthi.
+        # Use the paired contours' straight projected strips for the solve.
+        linear=np.concatenate([edge_points*(1-t)+inside*t for t in np.linspace(0,1,rings)])
+        world=linear+((world-linear)@forward)[:,None]*forward
+        boundary=np.zeros(len(world),bool);boundary[:count]=True;boundary[-count:]=True
+        world=fair_lid_depth(world,faces,forward,boundary)
+    world,_=conform_open_lid(world,o);local=(world-origin_basis)@inverse.T
+    cross=np.cross(local[faces[:,1]]-local[faces[:,0]],local[faces[:,2]]-local[faces[:,0]])
+    if np.mean(cross@(inverse@forward))<0:faces=faces[:,::-1]
+    normals=surface_normals(local,faces,surface_normal_groups(local))
+    outer_local_normals=edge_normals@np.linalg.inv(inverse);outer_local_normals/=np.maximum(np.linalg.norm(outer_local_normals,axis=1,keepdims=True),1e-12)
+    normals[:count]=outer_local_normals
+    return local,normals,np.asarray(colors),faces

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

@@ -0,0 +1,51 @@
+"""Offline front-face atlas rasterization and landmark correspondence.
+
+Coordinates are authoring space, not guesses made by the renderer. Rasterization
+keeps the closest triangle and its interpolated attributes, including UV seams.
+"""
+import numpy as np
+from scipy.ndimage import map_coordinates
+from scipy.spatial import Delaunay
+from scipy.interpolate import RBFInterpolator
+
+
+def rasterize(points, triangles, values, bounds, size=1024):
+    lo=np.asarray(bounds[:2]);hi=np.asarray(bounds[2:])
+    xy=(points[:,:2]-lo)/(hi-lo)*(size-1)
+    image=np.zeros((size,size,values.shape[1]),np.float32)
+    depth=np.full((size,size),-np.inf,np.float32)
+    for ids in triangles:
+        t=xy[ids];d=points[ids,2]
+        if not np.isfinite(t).all():continue
+        xmin,ymin=np.maximum(np.floor(t.min(0)).astype(int),0)
+        xmax,ymax=np.minimum(np.ceil(t.max(0)).astype(int),size-1)
+        if xmax<xmin or ymax<ymin:continue
+        den=(t[1,1]-t[2,1])*(t[0,0]-t[2,0])+(t[2,0]-t[1,0])*(t[0,1]-t[2,1])
+        if abs(den)<1.e-8:continue
+        yy,xx=np.mgrid[ymin:ymax+1,xmin:xmax+1]
+        a=((t[1,1]-t[2,1])*(xx-t[2,0])+(t[2,0]-t[1,0])*(yy-t[2,1]))/den
+        b=((t[2,1]-t[0,1])*(xx-t[2,0])+(t[0,0]-t[2,0])*(yy-t[2,1]))/den
+        c=1-a-b;z=a*d[0]+b*d[1]+c*d[2]
+        dst=depth[ymin:ymax+1,xmin:xmax+1]
+        mask=(a>=-1.e-5)&(b>=-1.e-5)&(c>=-1.e-5)&(z>dst)
+        dst[mask]=z[mask]
+        field=image[ymin:ymax+1,xmin:xmax+1]
+        field[mask]=(a[...,None]*values[ids[0]]+b[...,None]*values[ids[1]]+c[...,None]*values[ids[2]])[mask]
+    return image,np.isfinite(depth)
+
+
+def sample(image,uv):
+    coords=np.array([uv[...,1]*(image.shape[0]-1),uv[...,0]*(image.shape[1]-1)])
+    if image.ndim==2:return map_coordinates(image,coords,order=1,mode='nearest')
+    return np.stack([map_coordinates(image[:,:,i],coords,order=1,mode='nearest') for i in range(image.shape[2])],axis=-1)
+
+
+def register(points,target_landmarks,source_landmarks):
+    """Smooth thin-plate anatomical correspondence; rejects points outside the hull."""
+    tri=Delaunay(target_landmarks);ids=tri.find_simplex(points)
+    landmarks=np.asarray(target_landmarks)
+    center=landmarks.mean(0);scale=np.ptp(landmarks,axis=0)
+    # Smooth first derivatives avoid shading seams at affine triangle boundaries.
+    warp=RBFInterpolator((landmarks-center)/scale,np.asarray(source_landmarks),kernel='thin_plate_spline',smoothing=0.0001)
+    mapped=np.concatenate([warp((chunk-center)/scale) for chunk in np.array_split(points,64)])
+    return mapped,ids>=0

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

@@ -0,0 +1,112 @@
+"""Repair an explicitly reviewed surface patch, retaining source rig correspondence.
+
+The agent selects the patch and a clean surrounding annulus. No defect detection runs.
+"""
+import hashlib,json
+from pathlib import Path
+import numpy as np
+from scipy.ndimage import distance_transform_edt
+from glb_arrays import accessor
+from glb_output import append_accessor,append_texture,image_array
+from vision_materials import source_world_points
+from eyelid_morph import surface_normals,surface_normal_groups,transport_normals
+from texture_repair import harmonic_fill,surface_swatch_fill
+
+def evidence_texel(uv,shape):
+    """Evidence uses Blender UVs; decoded image arrays have a top-left origin."""
+    return np.clip((np.array([1-uv[1],uv[0]])*np.array(shape)).astype(int),0,np.array(shape)-1)
+
+def quadratic_patch(points,pixels,direction,center,full_radius,outer_radius,fit_ring,depth_center,depth_tolerance):
+    points=np.asarray(points,float);pixels=np.asarray(pixels,float);direction=np.asarray(direction,float)
+    if not 0<full_radius<outer_radius<fit_ring[0]<fit_ring[1]:raise ValueError('Repair and clean support annulus must be separate')
+    q=(pixels-center)/fit_ring[1];r=np.linalg.norm(pixels-center,axis=1);depth=points@direction
+    visible=abs(depth-depth_center)<depth_tolerance
+    fit=visible&(r>=fit_ring[0])&(r<=fit_ring[1])
+    if fit.sum()<30:raise ValueError('Insufficient clean surface support for authored geometry repair')
+    def basis(v):return np.stack([np.ones(len(v)),v[:,0],v[:,1],v[:,0]**2,v[:,0]*v[:,1],v[:,1]**2],1)
+    coefficients,_,rank,_=np.linalg.lstsq(basis(q[fit]),depth[fit],rcond=None)
+    if rank!=6:raise ValueError('Degenerate support annulus')
+    weight=np.clip((outer_radius-r)/(outer_radius-full_radius),0,1);weight=weight*weight*(3-2*weight);weight*=visible
+    delta=(basis(q)@coefficients-depth)*weight
+    result=points+delta[:,None]*direction
+    result[weight==0]=points[weight==0]
+    residual=basis(q[fit])@coefficients-depth[fit]
+    return result,weight,{'supportVertices':int(fit.sum()),'movedVertices':int((weight>0).sum()),'maximumDisplacement':float(abs(delta).max()),'supportResidualP95':float(np.percentile(abs(residual),95))}
+
+def apply_geometry_repair(doc,data,profile_path,out,source_sha):
+    profile_path=Path(profile_path);profile=json.loads(profile_path.read_text())
+    if profile['sourceSha256']!=source_sha:raise ValueError('Geometry repair belongs to a different source')
+    evidence=Path(profile['evidence']);manifest=json.loads((evidence/'manifest.json').read_text())
+    if manifest['sourceSha256']!=source_sha:raise ValueError('Geometry repair evidence source mismatch')
+    view=next(v for v in manifest['views'] if v['name']==profile['view'])
+    image=evidence/(profile['view']+'.png')
+    if hashlib.sha256(image.read_bytes()).hexdigest()!=manifest['evidenceHashes'][image.name]:raise ValueError('Geometry repair evidence image changed')
+    primitives=doc['meshes'][0]['primitives'];attributes=primitives[0]['attributes']
+    if any(p['attributes']['POSITION']!=attributes['POSITION'] for p in primitives):raise ValueError('Repair requires shared source positions')
+    local=accessor(doc,data,attributes['POSITION']);world=source_world_points(doc,local)
+    source_height=float(np.ptp(world[:,2]));unit=source_height/profile['heightM'];center=(world.min(0)+world.max(0))*.5
+    direction=np.asarray(view['direction'],float);direction/=np.linalg.norm(direction)
+    up=np.asarray(view.get('up',[0,0,1]),float);right=np.cross(direction,up);right/=np.linalg.norm(right);up=np.cross(right,direction)
+    target=center+source_height*np.asarray(view.get('targetOffset',[0,0,0]));span=source_height*view['span'];size=manifest['size']
+    def project(p):return np.stack([((p-target)@right/span+.5)*size,(.5-(p-target)@up/span)*size],-1)
+    pixel_center=np.asarray(profile['centerPx'],float)
+    on_plane=target+right*(pixel_center[0]/size-.5)*span+up*(.5-pixel_center[1]/size)*span
+    faces=np.concatenate([accessor(doc,data,p['indices']).reshape(-1,3) for p in primitives])
+    from eye_assets import ray_hit
+    hit=ray_hit(on_plane-direction*source_height*2,direction,world,faces);depth_center=hit@direction
+    changed,weight,receipt=quadratic_patch(world,project(world),direction,pixel_center,profile['fullRadiusPx'],profile['outerRadiusPx'],profile['supportRingPx'],depth_center,profile['depthToleranceM']*unit)
+    if receipt['maximumDisplacement']/unit>profile['maximumDisplacementM']:raise ValueError('Geometry correction exceeds the authored displacement bound')
+    origin=source_world_points(doc,np.zeros((1,3)))[0];basis=(source_world_points(doc,np.eye(3))-origin).T
+    corrected=local+(changed-world)@np.linalg.inv(basis).T
+    groups=surface_normal_groups(local);old_normals=accessor(doc,data,attributes['NORMAL'])
+    new_geometric=surface_normals(corrected,faces,groups)
+    normals=transport_normals(old_normals,surface_normals(local,faces,groups),new_geometric)
+    normals=normals*(1-weight[:,None])+new_geometric*weight[:,None]
+    normals/=np.maximum(np.linalg.norm(normals,axis=1,keepdims=True),1e-12)
+    touched=np.zeros(len(local),bool);touched[np.unique(faces[np.any(weight[faces]>0,axis=1)])]=True;normals[~touched]=old_normals[~touched]
+    position_index=append_accessor(doc,data,corrected.astype('<f4'),'VEC3',5126);normal_index=append_accessor(doc,data,normals.astype('<f4'),'VEC3',5126)
+    for p in primitives:
+        p['attributes'].setdefault('_BIND_SOURCE_POSITION',p['attributes']['POSITION'])
+        p['attributes']['POSITION']=position_index;p['attributes']['NORMAL']=normal_index
+    # Exact UV-surface positions come from the reviewed dense evidence bake.
+    surfaces=Path(profile['surfaceEvidence']);mask_report=json.loads((surfaces.parent/'report.json').read_text())
+    if mask_report['sourceSha256']!=source_sha:raise ValueError('Repair UV evidence belongs to a different source')
+    atlas=np.load(surfaces);positions=atlas['position'];occupied=atlas['occupied'];pixels=project(positions)
+    r=np.linalg.norm(pixels-pixel_center,axis=-1);near=occupied&(abs(positions@direction-depth_center)<profile['depthToleranceM']*unit)
+    distance,nearest=distance_transform_edt(~occupied,return_indices=True)
+    gutter=(~occupied)&(distance<=4)
+    r[gutter]=r[tuple(nearest[:,gutter])];near[gutter]=near[tuple(nearest[:,gutter])]
+    positions=positions.copy();positions[gutter]=positions[tuple(nearest[:,gutter])]
+    del distance,nearest,pixels
+    material=doc['materials'][primitives[0]['material']];texture=material['pbrMetallicRoughness']['baseColorTexture']['index'];color=image_array(doc,data,texture).copy()
+    if color.shape[:2]!=occupied.shape:raise ValueError('Repair atlas and base color resolution differ')
+    paint=profile['paint'];cleanup=near&(r<paint['cleanupRadiusPx'])
+    if paint.get('skinSamplesPx'):
+        uv_path=evidence/(profile['view']+'.npz')
+        if hashlib.sha256(uv_path.read_bytes()).hexdigest()!=manifest['evidenceHashes'][uv_path.name]:raise ValueError('Paint donor correspondence changed')
+        correspondence=np.load(uv_path);donors=[]
+        for x,y in paint['skinSamplesPx']:
+            if correspondence['material'][y,x]!=0:raise ValueError('Paint donor is outside the reviewed source material')
+            uv=correspondence['uv'][y,x];yx=evidence_texel(uv,occupied.shape)
+            if not occupied[tuple(yx)]:
+                region=occupied[max(0,yx[0]-2):yx[0]+3,max(0,yx[1]-2):yx[1]+3];candidates=np.argwhere(region)+np.maximum(0,yx-2)
+                if not len(candidates):raise ValueError('Paint donor misses occupied UV surface')
+                yx=candidates[np.argmin(((candidates-yx)**2).sum(1))]
+            donors.append(yx)
+        color=surface_swatch_fill(color[:,:,:3],cleanup,positions,donors,allowed_mask=near,blend_width=paint.get('blendWidthM',.001)*unit)
+    else:color=harmonic_fill(color[:,:,:3],cleanup)
+    alpha=np.clip((paint['radiusPx']+.5-r),0,1)*near
+    original=color.astype(float)/255;original=np.where(original<=.04045,original/12.92,((original+.055)/1.055)**2.4)
+    pigment=np.asarray(paint['colorSRGB'],float)/255;pigment=np.where(pigment<=.04045,pigment/12.92,((pigment+.055)/1.055)**2.4)
+    mixed=original*(1-alpha[:,:,None])+pigment*alpha[:,:,None];encoded=np.where(mixed<=.0031308,mixed*12.92,1.055*mixed**(1/2.4)-.055)
+    painted=color.copy();active=alpha>0;painted_count=int(active.sum());painted[active]=np.round(np.clip(encoded[active],0,1)*255).astype(np.uint8)
+    material['pbrMetallicRoughness']['baseColorTexture']={'index':append_texture(doc,data,painted,'geometry-repair-base-color',out)}
+    if material.get('normalTexture'):
+        normal=image_array(doc,data,material['normalTexture']['index']).copy()
+        if normal.shape[:2]!=occupied.shape:raise ValueError('Repair normal atlas resolution differs')
+        w=np.clip((profile['outerRadiusPx']-r)/(profile['outerRadiusPx']-profile['fullRadiusPx']),0,1);w=w*w*(3-2*w)*near
+        active=w>0;normal[active,:3]=np.round(normal[active,:3]*(1-w[active,None])+np.array([128,128,255])*w[active,None]).astype(np.uint8)
+        material['normalTexture']={**material['normalTexture'],'index':append_texture(doc,data,normal,'geometry-repair-normal',out)}
+    receipt.update(method='agent-authored quadratic patch from clean surrounding surface; feathered boundary',sourceSha256=source_sha,profileSha256=hashlib.sha256(profile_path.read_bytes()).hexdigest(),maximumDisplacementM=receipt.pop('maximumDisplacement')/unit,supportResidualP95M=receipt.pop('supportResidualP95')/unit,paintedTexels=painted_count,topologyAndUVsPreserved=True,sourceBindingPreserved=True)
+    (Path(out)/'geometry-repair.json').write_text(json.dumps(receipt,indent=2)+'\n')
+    return receipt

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

@@ -0,0 +1,13 @@
+"""GLB binary array readers usable from Python and Blender without Pillow."""
+import json,struct
+import numpy as np
+
+def read(path):
+ raw=path.read_bytes();n=struct.unpack_from('<I',raw,12)[0];doc=json.loads(raw[20:20+n]);off=20+n;size=struct.unpack_from('<I',raw,off)[0]
+ return doc,bytearray(raw[off+8:off+8+size])
+
+def accessor(doc,data,index):
+ a=doc['accessors'][index];v=doc['bufferViews'][a['bufferView']]
+ dt=np.dtype({5126:'<f4',5125:'<u4',5123:'<u2',5121:'u1'}[a['componentType']]);w={'SCALAR':1,'VEC2':2,'VEC3':3,'VEC4':4,'MAT4':16}[a['type']]
+ return np.ndarray((a['count'],w),dtype=dt,buffer=data,offset=v.get('byteOffset',0)+a.get('byteOffset',0),strides=(v.get('byteStride',dt.itemsize*w),dt.itemsize)).copy()
+

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

@@ -0,0 +1,21 @@
+"""Shared embedded-GLB output helpers; no semantic classification."""
+import io
+import numpy as np
+from PIL import Image
+
+def image_array(doc,data,texture,mode='RGB'):
+ im=doc['images'][doc['textures'][texture]['source']];v=doc['bufferViews'][im['bufferView']];start=v.get('byteOffset',0)
+ return np.array(Image.open(io.BytesIO(data[start:start+v['byteLength']])).convert(mode))
+
+def append_view(doc,data,raw):
+ data.extend(b'\0'*((-len(data))%4));offset=len(data);data.extend(raw)
+ doc['bufferViews'].append({'buffer':0,'byteOffset':offset,'byteLength':len(raw)});return len(doc['bufferViews'])-1
+
+def append_accessor(doc,data,values,kind,component):
+ view=append_view(doc,data,values.tobytes());doc['accessors'].append({'bufferView':view,'componentType':component,'count':len(values),'type':kind});return len(doc['accessors'])-1
+
+def append_texture(doc,data,pixels,name,folder):
+ im=Image.fromarray(pixels.astype(np.uint8));raw=io.BytesIO();im.save(raw,format='PNG');(folder/(name+'.png')).write_bytes(raw.getvalue())
+ if not doc.get('samplers'):doc['samplers']=[{}]
+ view=append_view(doc,data,raw.getvalue());doc['images'].append({'bufferView':view,'mimeType':'image/png','name':name});doc['textures'].append({'source':len(doc['images'])-1,'sampler':0});return len(doc['textures'])-1
+

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

@@ -0,0 +1,66 @@
+"""Trace a reviewed image pixel to its UV texel and contributing authoring views.
+
+Read-only geometry/provenance diagnostic. Never chooses or changes an anatomical label.
+Requires a dense bake made with --surface-data.
+"""
+import argparse,hashlib,json
+from pathlib import Path
+import numpy as np
+from PIL import Image
+from skin_views import LABELS
+
+def digest(path):return hashlib.sha256(path.read_bytes()).hexdigest()
+
+def texel_footprint(positions,occupied,row,col,source_height,physical_height):
+    if not np.isfinite(physical_height) or physical_height<=0:raise ValueError('Physical height must be positive and finite')
+    if not np.isfinite(source_height) or source_height<=0:raise ValueError('Source height must be positive and finite')
+    result=[];h,w=occupied.shape
+    for dx,dy in [(-1,0),(1,0),(0,-1),(0,1)]:
+        x=col+dx;y=row+dy
+        if 0<=x<w and 0<=y<h and occupied[y,x]:
+            result.append({'atlasOffset':[dx,dy],'distanceM':float(np.linalg.norm(positions[y,x]-positions[row,col])*physical_height/source_height)})
+    return {'physicalHeightM':physical_height,'neighbours':result,'interpretation':'Local occupied-texel spacing, not guaranteed detail resolution. UV discontinuities can make a neighbour distant; inspect individual values.'}
+
+def inspect(evidence,masks,view_name,x,y,physical_height=None):
+    evidence=Path(evidence);masks=Path(masks)
+    manifest=json.loads((evidence/'manifest.json').read_text())
+    report=json.loads((masks/'report.json').read_text())
+    archived=json.loads((masks/'dense-request.json').read_text())
+    for key in ['sourceSha256','size','views','materials','worldBounds']:
+        if archived.get(key)!=manifest.get(key):raise ValueError('Bake/evidence mismatch: '+key)
+    if report['sourceSha256']!=manifest['sourceSha256'] or digest(Path(manifest['source']))!=manifest['sourceSha256']:
+        raise ValueError('Source identity changed')
+    if digest(masks/'annotations.json')!=report['annotationSha256']:raise ValueError('Baked annotations changed')
+    if view_name not in [v['name'] for v in manifest['views']]:raise ValueError('Unknown evidence view')
+    if not 0<=x<manifest['size'] or not 0<=y<manifest['size']:raise ValueError('Pixel outside evidence image')
+    for ext in ['.png','.npz']:
+        name=view_name+ext
+        if digest(evidence/name)!=manifest['evidenceHashes'][name]:raise ValueError('Evidence changed: '+name)
+    with np.load(evidence/(view_name+'.npz')) as data:
+        material=int(data['material'][y,x]);uv=data['uv'][y,x]
+    if material<0 or not np.isfinite(uv).all() or (uv<0).any() or (uv>1).any():raise ValueError('Pixel has no supported source UV surface')
+    labels=np.asarray(Image.open(masks/f'material-{material}-labels.png'));h,w=labels.shape
+    col=min(int(uv[0]*w),w-1);row=min(int((1-uv[1])*h),h-1)
+    footprint=None
+    with np.load(masks/f'material-{material}-surface.npz') as surface:
+        occupied=surface['occupied'];positions=surface['position']
+        if not occupied[row,col]:raise ValueError('Selected UV texel is unoccupied')
+        point=positions[row,col];normal=surface['normal'][row,col]
+        visible=int(surface['visibilityBits'][row,col]);voted=int(surface['viewBits'][row,col])
+        if physical_height is not None:footprint=texel_footprint(positions,occupied,row,col,np.ptp(np.asarray(manifest['worldBounds'])[:,2]),physical_height)
+    conflicts=np.asarray(Image.open(masks/f'material-{material}-conflicts.png'))
+    bounds=np.asarray(manifest['worldBounds']);height=bounds[1,2]-bounds[0,2];center=bounds.mean(0);names={v:k for k,v in LABELS.items()};contributors=[]
+    for index,view in enumerate(manifest['views']):
+        if not visible&(1<<index):continue
+        direction=np.asarray(view['direction'],float);direction/=np.linalg.norm(direction)
+        up=np.asarray(view.get('up',[0,0,1]),float);right=np.cross(direction,up);right/=np.linalg.norm(right);up=np.cross(right,direction)
+        target=center+height*np.asarray(view.get('targetOffset',[0,0,0]));span=height*view.get('span',1.1)
+        px=int(np.floor(((point-target)@right/span+.5)*manifest['size']));py=int(np.floor((.5-(point-target)@up/span)*manifest['size']))
+        if not 0<=px<manifest['size'] or not 0<=py<manifest['size']:raise ValueError('Visibility bit projects outside its archived camera')
+        label_file=masks/(view['name']+'-annotation.npy');kind=int(np.load(label_file)[py,px]) if label_file.exists() else 0
+        contributors.append({'view':view['name'],'pixel':[px,py],'label':names[kind],'facing':float(abs(normal@direction)),'contributed':bool(voted&(1<<index))})
+    return {'sourceSha256':manifest['sourceSha256'],'annotationSha256':report['annotationSha256'],'view':view_name,'pixel':[x,y],'material':material,'atlasPixel':[col,row],'label':names[int(labels[row,col])],'conflict':bool(conflicts[row,col]),'contributors':contributors,'texelFootprint':footprint,'decision':'No semantic decision made; inspect the listed source pixels before editing annotations.'}
+
+if __name__=='__main__':
+    parser=argparse.ArgumentParser(description=__doc__);parser.add_argument('--evidence',required=True,type=Path);parser.add_argument('--masks',required=True,type=Path);parser.add_argument('--view',required=True);parser.add_argument('--x',required=True,type=int);parser.add_argument('--y',required=True,type=int);parser.add_argument('--height-m',type=float,help='Known authored physical height, for local texel-spacing diagnostics');a=parser.parse_args()
+    print(json.dumps(inspect(a.evidence,a.masks,a.view,a.x,a.y,a.height_m),indent=2))