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

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

@@ -0,0 +1,62 @@
+"""Short strand groom from explicit image-space brow polygons and comb guides.
+
+Sampling places designed fibers inside authored regions; it does not recognize hair.
+"""
+import numpy as np
+
+
+def inside_polygon(points, polygon):
+    polygon=np.asarray(polygon,float);inside=np.zeros(len(points),bool)
+    for a,b in zip(polygon,np.roll(polygon,-1,axis=0)):
+        if abs(b[1]-a[1])<1e-12:continue
+        inside^=((a[1]>points[:,1])!=(b[1]>points[:,1]))&(points[:,0]<(b[0]-a[0])*(points[:,1]-a[1])/(b[1]-a[1])+a[0])
+    return inside
+
+
+def build_brow(profile,points,triangles,normals,target,right,up,direction,span,size,unit,inverse,origin):
+    polygon=np.asarray(profile['polygonPx'],float);guides=np.asarray(profile['combGuidesPx'],float)
+    if polygon.ndim!=2 or polygon.shape[1]!=2 or len(polygon)<3 or not np.isfinite(polygon).all():raise ValueError('Brow needs an explicit finite polygon')
+    if guides.ndim!=3 or guides.shape[1:]!=(2,2) or len(guides)<2 or not np.isfinite(guides).all():raise ValueError('Brow needs at least two explicit comb guides')
+    vectors=guides[:,1]-guides[:,0];lengths=np.linalg.norm(vectors,axis=1)
+    if np.any(lengths<1e-6):raise ValueError('Brow comb guides must have a direction')
+    vectors/=lengths[:,None]
+    pigment=np.asarray(profile['colorLinear'],float)
+    if pigment.shape!=(3,) or not np.isfinite(pigment).all() or np.any(pigment<0) or np.any(pigment>1):raise ValueError('Brow pigment must be finite linear RGB')
+    count=int(profile['strandCount']);radii=float(profile['radiusM'])*unit
+    low,high=np.asarray(profile['lengthRangeM'],float)*unit
+    if not 1<=count<=1000 or not 0<radii<.0001*unit or not 0<low<=high<.015*unit:raise ValueError('Invalid authored brow fiber dimensions')
+    rng=np.random.default_rng(profile['seed']);roots=[]
+    for batch in range(100):
+        candidates=rng.uniform(polygon.min(0),polygon.max(0),size=(count*4,2))
+        roots.extend(candidates[inside_polygon(candidates,polygon)])
+        if len(roots)>=count:break
+    if len(roots)<count:raise ValueError('Brow polygon has insufficient area')
+    roots=np.asarray(roots[:count])
+    projected=np.stack([((points-target)@right/span+.5)*size,(.5-(points-target)@up/span)*size],1)
+    bounds=projected[triangles];selected=np.all(bounds.max(1)>=polygon.min(0)-1,axis=1)&np.all(bounds.min(1)<=polygon.max(0)+1,axis=1)
+    triangles=triangles[selected];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)
+    vertices=[];vertex_normals=[];faces=[];color=[]
+    for pixel in roots:
+        ray=target+right*((pixel[0]+.5)/size-.5)*span+up*(.5-(pixel[1]+.5)/size)*span-direction*span*4
+        s=ray-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 brow root misses visible source geometry')
+        face=int(np.argmin(np.where(valid,t,np.inf)));root=ray+direction*t[face]
+        normal=normals[triangles[face]].T@np.array([1-u[face]-v[face],u[face],v[face]]);normal/=np.linalg.norm(normal)
+        weights=1/np.maximum(np.sum((guides[:,0]-pixel)**2,axis=1),9);comb=weights@vectors/weights.sum()
+        tangent=right*comb[0]-up*comb[1];tangent-=normal*np.dot(normal,tangent);tangent/=np.linalg.norm(tangent)
+        length=rng.uniform(low,high);curve=[]
+        for fraction in np.linspace(0,1,8):
+            curve.append(root+tangent*length*fraction+normal*unit*(.00004+.00018*np.sin(np.pi*fraction)+.00008*fraction))
+        curve=np.asarray(curve);along=np.gradient(curve,axis=0);along/=np.linalg.norm(along,axis=1,keepdims=True)
+        side=np.cross(along,normal);side/=np.linalg.norm(side,axis=1,keepdims=True);other=np.cross(along,side)
+        angle=np.arange(5)*2*np.pi/5;tube_normals=side[:,None,:]*np.cos(angle)[None,:,None]+other[:,None,:]*np.sin(angle)[None,:,None]
+        tube=curve[:,None,:]+tube_normals*radii*np.linspace(1,.05,8)[:,None,None];start=len(vertices)
+        vertices.extend((tube.reshape(-1,3)-origin)@inverse.T)
+        transformed=tube_normals.reshape(-1,3)@np.linalg.inv(inverse);transformed/=np.linalg.norm(transformed,axis=1,keepdims=True);vertex_normals.extend(transformed)
+        shade=np.clip(pigment*rng.uniform(.8,1.2),0,1);color.extend(np.broadcast_to(shade,(40,3)))
+        for row in range(7):
+            for k in range(5):
+                i=start+row*5+k;j=start+row*5+(k+1)%5;faces.extend([[i,j,i+5],[j,j+5,i+5]])
+    return np.asarray(vertices),np.asarray(vertex_normals),np.asarray(color),np.asarray(faces)

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

@@ -0,0 +1,107 @@
+"""Register an attributed scan detail atlas to a generated face, preserving identity.
+
+This transfers band-limited displacement, not the scan's face shape. Height scale
+is an authoring calibration (not recovered physical capture metadata). No MERL or
+MetaHuman textures are used. All derivatives carry source/license/hash provenance.
+"""
+from pathlib import Path
+import hashlib,json
+import numpy as np
+from PIL import Image,ImageDraw
+from scipy.ndimage import gaussian_filter, distance_transform_edt
+from face_atlas import rasterize,sample,register
+from glb_arrays import read,accessor
+from workspace_paths import workspace_root
+ROOT=workspace_root(__file__)
+REFERENCE=ROOT/'highquality/references/lee-perry-smith'
+
+def pixels_to_coords(points,bounds,n=900):
+    p=np.asarray(points,dtype=float)/n;p[:,1]=1-p[:,1]
+    return np.asarray(bounds[:2])+p*(np.asarray(bounds[2:])-bounds[:2])
+
+def region_image(profile,size=2048):
+    im=Image.new('L',(size,size),0);draw=ImageDraw.Draw(im)
+    for value,kind in enumerate(['eyes','brows','lips'],1):
+        for polygon in profile['regions'][kind]:
+            draw.polygon([(x/profile['annotationImageSize']*(size-1),(1-y/profile['annotationImageSize'])*(size-1)) for x,y in polygon],fill=value)
+    return np.array(im)
+
+def verify_landmark_evidence(profile,root,source):
+    if profile.get('version',1)<2:return 'legacy_unbound_landmarks'
+    if hashlib.sha256(source.read_bytes()).hexdigest()!=profile['sourceSha256']:
+        raise ValueError('Face landmarks belong to a different source mesh')
+    image=root/profile['evidenceImage']
+    if hashlib.sha256(image.read_bytes()).hexdigest()!=profile['evidenceImageSha256']:
+        raise ValueError('Face landmark evidence image changed')
+    with Image.open(image) as pixels:
+        if pixels.size!=(profile['annotationImageSize'],profile['annotationImageSize']):
+            raise ValueError('Face landmark evidence dimensions differ')
+    return 'source_and_image_hash_verified'
+
+def build(sid='b3662'):
+    profile_path=ROOT/'highquality/materials/faces'/f'{sid}.json';profile=json.loads(profile_path.read_text())
+    evidence_status=verify_landmark_evidence(profile,ROOT,ROOT/'characters'/sid/'high/v1/source/hy31pro.glb')
+    folder=ROOT/'characters'/sid/'high/v1/materials/v2';folder.mkdir(parents=True,exist_ok=True)
+    source=REFERENCE/'LeePerrySmith.glb';j,b=read(source);pr=j['meshes'][0]['primitives'][0]
+    p=accessor(j,b,pr['attributes']['POSITION']);uv=accessor(j,b,pr['attributes']['TEXCOORD_0']);uv[:,1]=1-uv[:,1]
+    ids=accessor(j,b,pr['indices']).reshape(-1,3)
+    size=profile.get('atlasSize',2048)
+    if size not in (2048,4096):raise ValueError('Facial atlasSize must be 2048 or 4096')
+    pixel_scale=size/2048
+    scan_uv,scan_valid=rasterize(p,ids,uv,profile['sourceBounds'],size)
+    displacement=np.asarray(Image.open(REFERENCE/'Infinite-Level_02_Disp_NoSmoothUV-4096.jpg').convert('L'),dtype=float)/255
+    scan_height=sample(displacement,scan_uv)
+    # Inpaint uncovered pixels before filtering to avoid silhouette impulses.
+    nearest=distance_transform_edt(~scan_valid,return_distances=False,return_indices=True)
+    scan_height=scan_height[tuple(nearest)]
+    # Remove identity-scale form; retain scan-correlated intermediate and fine detail.
+    band=gaussian_filter(scan_height,.65*pixel_scale)-gaussian_filter(scan_height,24*pixel_scale)
+    central=band[size//3:3*size//4,size//3:2*size//3]
+    amplitude=np.percentile(np.abs(central),95)
+    band*=profile['detailAmplitudeM']/max(amplitude,1.e-6)
+    np.save(folder/'scan-band-height-m.npy',band.astype('float32'))
+    yy,xx=np.mgrid[0:size,0:size];coords=np.stack([xx,yy],-1)/(size-1)
+    bounds=np.array(profile['bounds']);target=coords*(bounds[2:]-bounds[:2])+bounds[:2]
+    mapped,valid=register(target.reshape(-1,2),pixels_to_coords(profile['targetPixels'],profile['bounds'],profile['annotationImageSize']),pixels_to_coords(profile['sourcePixels'],profile['sourceBounds'],profile.get('sourceAnnotationImageSize',900)))
+    sb=np.array(profile['sourceBounds']);lookup=((mapped-sb[:2])/(sb[2:]-sb[:2])).reshape(size,size,2)
+    height=sample(band,lookup)
+    regions=region_image(profile,size)
+    coverage=valid.reshape(size,size)&(regions==0)
+    if not coverage.any():raise ValueError('Registration has no uncovered skin; review landmark hull and exclusion polygons')
+    feather=np.clip(distance_transform_edt(coverage)/(48*pixel_scale),0,1)
+    # Roughness follows the transferred relief's local variation, with coarse oil regions.
+    dy,dx=np.gradient(height);variance=gaussian_filter(dx*dx+dy*dy,3*pixel_scale)
+    relief=np.clip(np.sqrt(variance)/max(np.percentile(np.sqrt(variance[coverage]),95),1e-9),0,1)
+    # Transfer only gentle chromatic variation from clean upper-face skin;
+    # reject beard/jaw pigment so the donor's stubble does not enter the queen.
+    scan_color=sample(np.asarray(Image.open(REFERENCE/'Map-COL.jpg'),dtype=float)/255,scan_uv)
+    chroma=np.log(np.maximum(scan_color[:,:,0],.02)/np.maximum(scan_color[:,:,1],.02))
+    chroma=gaussian_filter(chroma,4*pixel_scale)-gaussian_filter(chroma,50*pixel_scale)
+    pigment=sample(chroma,lookup)*np.clip((lookup[:,:,1]-.53)/.09,0,1)
+    pigment=np.clip(pigment*4,-.3,.3)
+    packed=np.stack([np.clip(.5+height/profile['detailHeightRangeM'],0,1),.45+.20*relief,.5+pigment,feather],axis=-1)
+    Image.fromarray(np.round(packed*255).astype('uint8'),'RGBA').save(folder/'face-detail.png')
+    # Authored appearance deltas, NOT captured expression scans. Modulate the
+    # registered relief within facial regions; the source HY geometry stays intact.
+    x=coords[:,:,0];z=coords[:,:,1]
+    forehead=np.exp(-((x-.5)/.22)**2-((z-.69)/.11)**2)
+    smile=np.exp(-((abs(x-.5)-.15)/.10)**2-((z-.23)/.13)**2)
+    squint=np.exp(-((abs(x-.5)-.19)/.10)**2-((z-.46)/.09)**2)
+    delta=np.stack([height*forehead*.8,height*smile*.6,height*squint*.7],-1)
+    dynamic=np.concatenate([np.clip(.5+delta/profile['detailHeightRangeM'],0,1),np.clip((smile+forehead+squint)*feather,0,1)[...,None]],axis=-1)
+    Image.fromarray(np.round(dynamic*255).astype('uint8'),'RGBA').save(folder/'face-expression.png')
+    np.save(folder/'face-height-m.npy' ,height.astype('float32'))
+    Image.fromarray(regions.astype('uint8')).save(folder/'face-regions.png')
+    # Useful independent normal preview in the registered face plane.
+    physical_height=json.loads((ROOT/'characters'/sid/'high/v1/output/viewer-profile.json').read_text())['height']
+    spacing=(bounds[2:]-bounds[:2])*physical_height/(size-1)
+    dy,dx=np.gradient(height,spacing[1],spacing[0]);n=np.stack([-dx,-dy,np.ones_like(height)],-1);n/=np.linalg.norm(n,axis=-1,keepdims=True)
+    Image.fromarray(np.round((n*.5+.5)*255).astype('uint8')).save(folder/'face-normal-preview.png')
+    report={'id':sid,'landmarkEvidence':evidence_status,'method':'landmark-registered, band-limited scan displacement','author':'Lee Perry-Smith / Infinite Realities','license':'CC BY 3.0','licenseUrl':'https://creativecommons.org/licenses/by/3.0/','sourceUrl':'https://github.com/mrdoob/three.js/tree/r186/examples/models/gltf/LeePerrySmith','changes':'Projected into a facial atlas, band-pass filtered, amplitude calibrated, landmark-warped and masked. Only upper-face chromatic residual is transferred; beard pigment and face shape are not copied.','expressionMaps':'Authored modulation of scan relief; not captured expressions or a biological color model','scale':'Authoring estimate, not measured displacement units','heightRangeM':profile['detailHeightRangeM'],'profile_sha256':hashlib.sha256(profile_path.read_bytes()).hexdigest(),'inputs':{f.name:hashlib.sha256(f.read_bytes()).hexdigest() for f in REFERENCE.iterdir() if f.is_file()},'source_sha256':hashlib.sha256((ROOT/'characters'/sid/'high/v1/source/hy31pro.glb').read_bytes()).hexdigest()}
+    report['atlasSize']=size;report['texelSpacingM']=spacing.tolist();report['filterScaleRelativeTo2048']=pixel_scale
+    (folder/'face-detail-provenance.json').write_text(json.dumps(report,indent=2)+'\n')
+    (folder/'ATTRIBUTION.txt').write_text('Facial detail adapted from Infinite, 3D Head Scan by Lee Perry-Smith / Infinite Realities.\nCC BY 3.0: https://creativecommons.org/licenses/by/3.0/\nSource: three.js r186 examples/models/gltf/LeePerrySmith.\nModified by landmark registration, filtering, masking and amplitude calibration.\n')
+    print(json.dumps({'id':sid,'atlasSize':size,'heightP95Mm':float(np.percentile(abs(height[coverage]),95)*1000)}))
+if __name__=='__main__':
+    import argparse
+    parser=argparse.ArgumentParser();parser.add_argument('--id',default='b3662');build(parser.parse_args().id)

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

@@ -0,0 +1,28 @@
+"""Build reviewed evidence into a separate surface/eye/runtime candidate, fail-fast.
+
+Authoring and visual acceptance remain agent tasks. This command never selects anatomy,
+promotes viewer readiness, modifies the original model, or runs paid generation.
+"""
+import argparse,json,subprocess,sys
+from pathlib import Path
+
+from workspace_paths import workspace_root
+ROOT=workspace_root(__file__)
+
+def build(character,evidence,masks,eyes=None,assemble=False):
+    base=ROOT/'characters'/character/'high/v1'
+    for file in [evidence/'manifest.json',masks/'report.json',masks/'material-0-surface.npz',base/'materials/v2/face-detail.png',base/'materials/v2/face-expression.png',base/'materials/v2/scan-band-height-m.npy']:
+        if not file.is_file():raise ValueError(f'Missing authored input: {file}')
+    if eyes and json.loads(eyes.read_text())['id']!=character:raise ValueError('Eye profile character mismatch')
+    def run(script,*args):
+        subprocess.run([sys.executable,str(Path(__file__).resolve().parent/script),*map(str,args)],cwd=ROOT,check=True)
+    run('vision_materials.py','--id',character,'--evidence',evidence,'--masks',masks)
+    run('vision_blend_materials.py','--id',character,'--all-surfaces')
+    if eyes:run('eye_assets.py','--profile',eyes)
+    if assemble:
+        run('assemble_character.py','--id',character,'--input','materials/v4/character.glb','--variant','surfaces')
+        if eyes:run('assemble_character.py','--id',character,'--input','eyes/v1/character.glb','--variant','eyes')
+
+if __name__=='__main__':
+    p=argparse.ArgumentParser(description=__doc__);p.add_argument('--id',required=True);p.add_argument('--evidence',required=True,type=Path);p.add_argument('--masks',required=True,type=Path);p.add_argument('--eyes-profile',type=Path);p.add_argument('--assemble',action='store_true');a=p.parse_args()
+    build(a.id,a.evidence.resolve(),a.masks.resolve(),a.eyes_profile.resolve() if a.eyes_profile else None,a.assemble)

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

@@ -0,0 +1,57 @@
+"""Designed lining between an explicitly authored canthus and the globe."""
+import numpy as np
+from eyelid_morph import conform_open_lid,surface_normals,surface_normal_groups
+from eyelid_patch import lid_contact_depth,corner_contact_depth
+
+def lining_depth_at_radius(radial,corner_radial,source_depth,radius,iris,unit,reconstructed=True):
+    """Depth on the authored corner lining, for tissue supported by that lining."""
+    swept=iris*np.cos(.35)+np.sqrt(radius*radius-iris*iris)*np.sin(.35)
+    inner=max(radius*.88,swept+.00035*unit)
+    if inner>=radius or not inner<=radial<=corner_radial or corner_radial<=inner:
+        raise ValueError('Authored corner tissue lies outside its lining support')
+    globe=np.sqrt(max(0,radius*radius-corner_radial*corner_radial))
+    if reconstructed:boundary=float(lid_contact_depth(corner_radial,radius,globe,source_depth))+.00025*unit
+    else:boundary=max(source_depth,globe+.00025*unit) if corner_radial<radius and source_depth>0 else source_depth
+    inner_depth=np.sqrt(radius*radius-inner*inner)-.00035*unit
+    t=(radial-inner)/(corner_radial-inner)
+    return inner_depth*(1-t)+(boundary-.0003*unit)*t
+
+
+def build_canthus_wall(profile,opening,sample_surface,inverse,origin):
+    contour=np.asarray(opening['contour']);indices=profile['contourIndices']
+    if len(indices)<3:raise ValueError('A corner wall needs upper, corner and lower landmarks')
+    path=contour[indices];pixels=np.concatenate([a[None,:]*(1-np.arange(12)[:,None]/12)+b[None,:]*(np.arange(12)[:,None]/12) for a,b in zip(path[:-1],path[1:])]+[path[-1:]])
+    right=opening['right'];up=opening['up'];forward=-opening['direction'];center=opening['center'];radius=opening['radius'];unit=opening['unit']
+    plane=opening['target']+right[None,:]*((pixels[:,0]/opening['size']-.5)*opening['span'])[:,None]+up[None,:]*((.5-pixels[:,1]/opening['size'])*opening['span'])[:,None]
+    xy=np.stack([(plane-center)@right,(plane-center)@up],1);rad=np.linalg.norm(xy,axis=1)
+    swept_iris=opening['iris']*np.cos(.35)+np.sqrt(radius*radius-opening['iris']**2)*np.sin(.35)
+    inner_radius=max(radius*.88,swept_iris+.00035*unit)
+    if inner_radius>=radius:raise ValueError('Authored optical dimensions leave no lining clearance for the reviewed gaze range')
+    active=np.flatnonzero(rad>inner_radius)
+    if len(active)<3 or np.any(np.diff(active)!=1):raise ValueError('Reviewed corner must form one contiguous lining outside the globe center')
+    plane=plane[active];xy=xy[active];rad=rad[active]
+    boundary=np.asarray([sample_surface(p) for p in plane])
+    if profile.get('contactMethod') == 'reconstructed-lid-v1':
+        # Use precisely the reconstructed aperture's depth, rather than the
+        # old source eye surface, which is removed by the lid-band exporter.
+        source_depth=(boundary-center)@forward
+        globe_depth=np.sqrt(np.maximum(0,radius*radius-rad*rad))
+        depth=np.array([corner_contact_depth(r,g,s,p,opening) for r,g,s,p in zip(rad,globe_depth,source_depth,plane)])+.00025*unit
+        boundary=center+xy[:,0,None]*right+xy[:,1,None]*up+depth[:,None]*forward
+    elif profile.get('contactMethod') is not None:
+        raise ValueError('Unsupported canthus contact method')
+    boundary,_=conform_open_lid(boundary,opening)
+    inner_xy=xy*(inner_radius/rad)[:,None];inner=center+inner_xy[:,0,None]*right+inner_xy[:,1,None]*up+forward*(np.sqrt(radius*radius-inner_radius*inner_radius)-.00035*unit)
+    rows=7;vertices=[];roots=[];weights=[];faces=[];count=len(boundary)
+    for row,t in enumerate(np.linspace(0,1,rows)):
+        # The near-lid edge shares its support point with the source lid, but is
+        # slightly recessed. The far edge remains behind the globe during blink.
+        vertices.extend(inner*(1-t)+(boundary-forward*.0003*unit)*t)
+        roots.extend(boundary);weights.extend(np.full(count,t))
+        if row:
+            for j in range(count-1):
+                a=(row-1)*count+j;b=a+1;faces.extend([[a,b,a+count],[b,b+count,a+count]])
+    vertices=(np.asarray(vertices)-origin)@inverse.T;faces=np.asarray(faces)
+    normals=surface_normals(vertices,faces,surface_normal_groups(vertices))
+    colors=np.broadcast_to(profile['colorLinear'],vertices.shape).copy()
+    return (vertices,normals,colors,faces),(np.asarray(roots)-origin)@inverse.T,np.asarray(weights)

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

@@ -0,0 +1,54 @@
+"""Run the reviewed character exporters from an installed skill and explicit workspace.
+
+This assembles authored inputs. It performs no anatomical recognition, asset download,
+paid generation, rig fitting or automatic visual acceptance.
+"""
+import argparse,json,os,re,subprocess,sys
+from pathlib import Path
+
+def command(args):
+    root=args.workspace.expanduser().resolve()
+    if not root.is_dir():raise ValueError('Workspace must be an existing directory')
+    if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_-]*',args.id):raise ValueError('Character ID must be one path component')
+    base=root/'characters'/args.id/'high/v1'
+    if root not in base.resolve().parents:raise ValueError('Character output escapes workspace')
+    def path(value):return (root/value).resolve() if value else None
+    evidence,masks,eyes=map(path,[args.evidence,args.masks,args.eyes_profile])
+    script=Path(__file__).resolve().parent;required=[]
+    if args.stage=='face':
+        required=[root/'highquality/materials/faces'/f'{args.id}.json',base/'source/hy31pro.glb',base/'output/viewer-profile.json']
+        required += [root/'highquality/references/lee-perry-smith'/name for name in ['LeePerrySmith.glb','Infinite-Level_02_Disp_NoSmoothUV-4096.jpg','Map-COL.jpg']]
+        argv=[sys.executable,str(script/'build_face_detail.py'),'--id',args.id]
+    elif args.stage=='surfaces':
+        if not evidence or not masks:raise ValueError('Surfaces require --evidence and --masks')
+        required=[evidence/'manifest.json',masks/'report.json',masks/'material-0-surface.npz',base/'output/viewer-profile.json',root/'highquality/materials/faces'/f'{args.id}.json']
+        required += [base/'materials/v2'/name for name in ['face-detail.png','face-expression.png','scan-band-height-m.npy','ATTRIBUTION.txt']]
+        argv=[sys.executable,str(script/'build_surface_candidate.py'),'--id',args.id,'--evidence',str(evidence),'--masks',str(masks)]
+        if eyes:argv+=['--eyes-profile',str(eyes)]
+        if args.assemble:argv+=['--assemble']
+    elif args.stage=='eyes':
+        if not eyes:raise ValueError('Eyes require --eyes-profile')
+        argv=[sys.executable,str(script/'eye_assets.py'),'--profile',str(eyes)]
+    else:
+        required=[base/args.input]
+        argv=[sys.executable,str(script/'assemble_character.py'),'--id',args.id,'--input',args.input,'--variant',args.variant]
+    if eyes:
+        required += [eyes,root/'highquality/references/makehuman-eyes/blue_eye.png',root/'highquality/references/makehuman-eyes/LICENSE.md']
+        if eyes.is_file() and json.loads(eyes.read_text()).get('id')!=args.id:raise ValueError('Eye profile character mismatch')
+    if args.assemble or args.stage=='assemble':required += [base/'output/character.glb',base/'rig-report.json']
+    missing=[str(p) for p in required if not p.is_file()]
+    if missing:raise ValueError('Missing authored inputs:\n'+'\n'.join(missing))
+    return root,argv,required
+
+def main():
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--workspace',required=True,type=Path);p.add_argument('--id',required=True)
+    p.add_argument('--stage',choices=['face','surfaces','eyes','assemble'],default='surfaces')
+    p.add_argument('--evidence',type=Path);p.add_argument('--masks',type=Path);p.add_argument('--eyes-profile',type=Path)
+    p.add_argument('--assemble',action='store_true');p.add_argument('--input',default='eyes/v1/character.glb');p.add_argument('--variant',choices=['eyes','surfaces'],default='eyes')
+    p.add_argument('--check',action='store_true',help='Check required inputs without modifying assets; exporters validate their full contracts when run')
+    args=p.parse_args();root,argv,required=command(args)
+    if args.check:print(json.dumps({'status':'inputs_present_not_visual_acceptance','workspace':str(root),'stage':args.stage,'requiredFiles':len(required)}));return
+    subprocess.run(argv,cwd=root,env={**os.environ,'BITMAGIC_CHARACTER_WORKSPACE':str(root)},check=True)
+
+if __name__=='__main__':main()