@hatiolab/figure-model 0.6.6 → 0.7.0

package/docs/prototypes/kernel.test.mjs

@@ -1,144 +0,0 @@
-import fs from 'node:fs'
-import assert from 'node:assert/strict'
-import {test} from 'node:test'
-import {resolve,point,DesignError} from './kernel.mjs'
-
-const seeds=JSON.parse(fs.readFileSync(new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url)))
-const robot=JSON.parse(fs.readFileSync(new URL('../../src/fixtures/robot-arm-6dof.json',import.meta.url)))
-const source=t=>seeds.find(s=>s.type===t).source
-const part=(s,n)=>s.parts.find(p=>p.name===n)
-const add=(...args)=>({op:'add',args}),mul=(a,b)=>({op:'mul',args:[a,b]})
-const range=(min,max)=>({min,max})
-const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-7,`${a} != ${b}`)
-const xyz=v=>[v.x,v.y,v.z]
-const equal=(a,b)=>a.forEach((v,i)=>near(v,b[i]))
-const diff=(a,b)=>a.map((x,i)=>x-b[i])
-
-// Authored fixture adapters only. They are not general-purpose v2 migration.
-function conveyor() {
-  const s=source('CONVEYOR'),p=part(s,'roller'),pitch=p.repeat.pitch,r=p.transform.size.x/2
-  return {inputs:{width:range(100,16000),depth:range(81,1800),angle:range(-360,360)},
-    values:{length:add('depth',-80)},assertions:[],
-    frames:{row:{position:[add(mul(-.5,'width'),pitch/2),p.transform.position.y,0],orientation:{axis:[1,0,0],angle:90},joint:{type:'hinge',axis:[0,1,0],value:'angle'}}},
-    geometry:{roller:{frame:'row',kind:'cylinder',dimensions:{radius:r,length:'length'},repeat:{mode:'pitch',span:'width',pitch,axis:[1,0,0],limit:100}}}}
-}
-// Repetition is a placement operation, not movement around the roller's own axis.
-// Give each roller a spinning feature via separate evaluation in the test below.
-// The candidate above deliberately exposes whether joint order corrupts row placement.
-function cradle() {
-  const s=source('ROLL_CRADLE'),roll=part(s,'roll'),core=part(s,'core')
-  return {inputs:{radial:range(.5,2),axial:range(.5,2),fed:range(0,100)},
-    values:{fraction:add(1,mul(-.0068,'fed')),radius:mul(mul(roll.transform.size.x/2,'radial'),'fraction'),coreRadius:mul(core.transform.size.x/2,'radial')},
-    assertions:[{id:'roll-outside-core',op:'gte',left:'radius',right:'coreRadius'}],
-    frames:{axis:{position:xyz(roll.transform.position),orientation:{axis:[0,0,1],angle:90}}},
-    geometry:{roll:{frame:'axis',kind:'cylinder',dimensions:{radius:'radius',length:mul(roll.transform.size.y,'axial')}},core:{frame:'axis',kind:'cylinder',dimensions:{radius:'coreRadius',length:mul(core.transform.size.y,'axial')}}}}
-}
-function robotModel() {
-  const model={inputs:{linkScale:range(.5,2)},values:{},frames:{},geometry:{}}
-  for(const j of robot.joints)model.inputs[j.name]=range(j.limits?.min??-360,j.limits?.max??360)
-  for(const p of robot.parts) {
-    const parent=p.parent?xyz(part(robot,p.parent).transform.position):[0,0,0]
-    const relative=diff(xyz(p.transform.position),parent),j=robot.joints.find(j=>j.child===p.name)
-    model.frames[p.name]={parent:p.parent,position:relative.map((v,i)=>i===1?mul(v,'linkScale'):v)}
-    if(j)model.frames[p.name].joint={type:'hinge',axis:xyz(j.axis),value:j.name,
-      pivot:diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?mul(v,'linkScale'):v)}
-    const size=p.transform.size
-    model.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?
-      {radius:size.x/2,length:mul(size.y,'linkScale')}:{width:size.x,height:mul(size.y,'linkScale'),depth:size.z}}
-  }
-  return model
-}
-function forklift() {
-  const s=source('FORKLIFT'),m={inputs:{heightScale:range(.5,2),lift:range(0,2000),reach:range(0,400)},values:{},frames:{},geometry:{}}
-  // Motion-only frames at rest origin; all descendants retain original source rest coordinates.
-  m.frames.reach={joint:{type:'slide',axis:[0,0,1],value:'reach'}}
-  m.frames.stage={parent:'reach',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
-  m.frames.carriageMotion={parent:'stage',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
-  for(const p of s.parts) {
-    const parent=p.name.startsWith('mast-')?'reach':p.name.startsWith('stage-')?'stage':(p.name==='carriage'||p.name.startsWith('fork-'))?'carriageMotion':undefined
-    m.frames[p.name]={parent,position:xyz(p.transform.position).map((v,i)=>i===1?mul(v,'heightScale'):v)}
-    if(p.transform.rotation)m.frames[p.name].orientation={axis:[0,0,1],angle:p.transform.rotation.z}
-    const d=p.transform.size
-    m.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?{radius:d.x/2,length:d.y}:{width:d.x,height:mul(d.y,'heightScale'),depth:d.z}}
-  }
-  return m
-}
-
-test('robot: common kernel, 3 link scales × 32 poses; shared pivots and rest geometry',()=>{
-  const model=robotModel();let checks=0
-  for(const scale of [.5,1,2])for(let n=0;n<32;n++) {
-    const inputs={linkScale:scale,...Object.fromEntries(robot.joints.map((j,i)=>[j.name,n===0?0:(j.limits?.min??-360)+(n*(i+1)%31)/30*((j.limits?.max??360)-(j.limits?.min??-360))]))}
-    const out=resolve(model,inputs)
-    assert.equal(out.instances.length,10)
-    for(const j of robot.joints) {
-      const p=part(robot,j.child),parent=part(robot,p.parent)
-      const childPivot=diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?v*scale:v)
-      const parentPivot=diff(xyz(j.origin),xyz(parent.transform.position)).map((v,i)=>i===1?v*scale:v)
-      equal(point(out.frames[p.name],childPivot),point(out.frames[parent.name],parentPivot));checks++
-    }
-    if(n===0)for(const p of robot.parts)equal(out.frames[p.name].position,xyz(p.transform.position).map((v,i)=>i===1?v*scale:v))
-  }
-  console.log({robotStates:96,pivotChecks:checks})
-})
-
-test('cradle: common kernel, 3 radial × 3 axial × 5 feed states',()=>{
-  const model=cradle()
-  for(const radial of [.5,1,2])for(const axial of [.5,1,2])for(const fed of [0,25,50,75,100]) {
-    const out=resolve(model,{radial,axial,fed}),[roll,core]=out.instances
-    near(roll.dimensions.radius,350*radial*(1-.0068*fed));near(roll.dimensions.length,1000*axial)
-    assert.ok(roll.dimensions.radius>=core.dimensions.radius)
-    equal(roll.frame.position,core.frame.position)
-  }
-})
-
-test('forklift: common kernel, 3 sizes × 3 lifts × 3 reaches, no double inheritance',()=>{
-  const model=forklift()
-  for(const heightScale of [.5,1,2])for(const lift of [0,1000,2000])for(const reach of [0,200,400]) {
-    const {frames:f,instances}=resolve(model,{heightScale,lift,reach})
-    assert.equal(instances.length,20)
-    equal(f.carriage.position,[0,260*heightScale+lift,338+reach])
-    near(f['stage-left'].position[1],940*heightScale+lift/2)
-    near(f['fork-high-left'].position[1]-f['fork-low-left'].position[1],400*heightScale)
-    near(f.body.position[2],-700)
-  }
-})
-
-test('conveyor: spin must not rotate repeat offsets; prototype rejects naive composition via oracle',()=>{
-  const m=conveyor(),a=resolve(m,{width:2400,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:90})
-  // Counterexample: placing repetition after owner joint makes the entire row orbit.
-  assert.ok(Math.hypot(...diff(a.instances[1].frame.position,b.instances[1].frame.position))>100)
-})
-
-test('conveyor: corrected placement-before-local-orientation, 5 widths × 3 depths × 3 spins',()=>{
-  const m=conveyor()
-  delete m.frames.row.joint
-  m.geometry.roller.orientation={axis:[0,1,0],angle:'angle'}
-  for(const width of [1200,2399.99,2400,2400.01,4800])for(const depth of [300,600,1200])for(const angle of [0,90,180]) {
-    const out=resolve(m,{width,depth,angle})
-    assert.equal(out.instances.length,Math.floor(width/150))
-    for(const [i,p] of out.instances.entries()) {
-      equal(p.frame.position,[-width/2+75+i*150,500,0])
-      near(p.dimensions.radius,48);near(p.dimensions.length,depth-80)
-      assert.ok(p.frame.position[0]-48>=-width/2&&p.frame.position[0]+48<=width/2)
-      equal(point(p.frame,[0,p.dimensions.length/2,0]),[p.frame.position[0],500,p.dimensions.length/2])
-    }
-  }
-  const a=resolve(m,{width:2399.99,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:0})
-  assert.deepEqual(a.instances.map(x=>x.id),b.instances.slice(0,15).map(x=>x.id))
-})
-
-test('rejection is explicit and does not mutate source; order independent',()=>{
-  const m=cradle(),before=JSON.stringify(m),input={radial:1,axial:1,fed:50}
-  const result=resolve(m,input),reversed={...m,values:Object.fromEntries(Object.entries(m.values).reverse()),frames:Object.fromEntries(Object.entries(m.frames).reverse())}
-  assert.deepEqual(resolve(reversed,input).instances,result.instances)
-  for(const [model,args,code] of [
-    [m,{...input,fed:101},'INPUT_RANGE'],
-    [{...m,values:{...m.values,radius:'missing'}},input,'UNKNOWN_REFERENCE'],
-    [{...m,values:{...m.values,radius:'radius'}},input,'VALUE_CYCLE'],
-    [{...m,frames:{axis:{parent:'axis'}}},input,'FRAME_CYCLE'],
-    [{...m,values:{...m.values,radius:0}},input,'ASSERTION'],
-    [conveyor(),{width:16000,depth:600,angle:0},'REPEAT_DOMAIN'],
-    [m,{...input,radial:NaN},'NON_FINITE']
-  ])assert.throws(()=>resolve(model,args),e=>e instanceof DesignError&&e.code===code)
-  assert.equal(JSON.stringify(m),before)
-})

package/docs/prototypes/more-samples.test.mjs

@@ -1,182 +0,0 @@
-// Design probes, not a implementation. No source assets are modified.
-import fs from 'node:fs'
-import assert from 'node:assert/strict'
-import { test } from 'node:test'
-import { createHash } from 'node:crypto'
-import { validate } from '../../src/validate.ts'
-import { centredPart } from '../../src/origin.ts'
-import { sizingPosition, sizingScale, rotatedExtent, repeatPlanOfPart, repeatOffset } from '../../src/sizing.ts'
-
-const files = [new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url),
-  new URL('../../src/fixtures/robot-arm-6dof.json',import.meta.url),new URL('../../src/fixtures/gantry-crane-3dof.json',import.meta.url)]
-const all = [...JSON.parse(fs.readFileSync(files[0])).map(x=>x.source),...files.slice(1).map(f=>JSON.parse(fs.readFileSync(f)))]
-const source = type => all.find(s=>s.type===type)
-const part = (s,n) => { const p=s.parts.find(p=>p.name===n);assert.ok(p,n);return p }
-const axes=['x','y','z'], unit={x:1,y:1,z:1}
-const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-7,`${a} != ${b}`)
-// Bounds of the declared rotated box, NOT exact polygon/rounded shape contact.
-function bounds(s,n,scale=unit) {
-  const p=centredPart({...part(s,n),sizing:part(s,n).sizing??'scale'},s.base)
-  const at=sizingPosition(p,scale,s.base),factor=sizingScale(p,scale,s.base),extent=rotatedExtent(p)
-  return Object.fromEntries(axes.map(a=>{
-    const center=at[a]*scale[a]+(a==='y'?s.base.y*scale.y/2:0),size=extent[a]*factor[a]*scale[a]
-    return [a,{center,size,min:center-size/2,max:center+size/2}]
-  }))
-}
-function channel(s,param,target) {
-  const p=s.parameters.find(p=>p.name===param),c=p.clip.channels.find(c=>c.target===target)
-  assert.ok(c);assert.equal(c.keys.length,2);assert.equal(c.keys[0].at,0);assert.equal(c.keys[1].at,1)
-  return {p,c}
-}
-function sampleChannel(c,t) {
-  return Object.fromEntries(axes.map(a=>[a,c.keys[0].value[a]*(1-t)+c.keys[1].value[a]*t]))
-}
-
-test('16 sources: validation, finite sizing at 27 scales, baseline positions; provenance',()=>{
-  let checks=0
-  for(const s of all) {
-    assert.deepEqual(validate(s).errors,[],s.type)
-    for(const x of [.5,1,2])for(const y of [.5,1,2])for(const z of [.5,1,2])for(const p of s.parts) {
-      const b=bounds(s,p.name,{x,y,z})
-      for(const a of axes) {assert.ok(Number.isFinite(b[a].center));assert.ok(Number.isFinite(b[a].size)&&b[a].size>0)}
-      if(x===1&&y===1&&z===1)for(const a of axes)near(b[a].center,p.transform.position[a])
-      checks++
-    }
-  }
-  console.log(JSON.stringify({models:all.length,partScaleChecks:checks,provenance:files.map(f=>({path:f.pathname,sha256:createHash('sha256').update(fs.readFileSync(f)).digest('hex')})),scope:'finite numbers and source validity, NOT assembly correctness'}))
-})
-
-test('MIXER: fixed motor attachment cannot be inferred from independent scale positions',()=>{
-  const s=source('MIXER'),body=part(s,'body'),motor=part(s,'motor')
-  const overlap=body.transform.position.y+body.transform.size.y/2-(motor.transform.position.y-motor.transform.size.y/2)
-  near(overlap,5)
-  for(const h of [400,800,1600]) {
-    // Explicit proposed intent: motor height fixed; body height proportional.
-    const top=500*h/800,motorCenter=top-overlap+motor.transform.size.y/2
-    near(top-(motorCenter-80),5)
-  }
-})
-
-test('AGV: concentric wheels/hubs survive scaling but wheel ground contact does not always',()=>{
-  const s=source('AGV'),rows=[]
-  for(const scale of [unit,{x:1,y:2,z:1},{x:2,y:1,z:2}])for(const suffix of ['front-left','front-right','rear-left','rear-right']) {
-    const w=bounds(s,`wheel-${suffix}`,scale),h=bounds(s,`hub-${suffix}`,scale),r=w.y.size/2
-    for(const a of axes)near(w[a].center,h[a].center)
-    near(w.y.size,w.z.size)
-    rows.push({scale,suffix,bottom:w.y.min,radius:r})
-  }
-  assert.ok(rows.some(r=>Math.abs(r.bottom)>1))
-  console.log(JSON.stringify({agv:rows.filter(r=>r.suffix==='front-left'),gap:'roundness does not imply floor contact; wheel center must reference radius'}))
-})
-
-test('SIGNAL_TOWER_3: real contact chain survives height changes with fixed lamp sizes',()=>{
-  const s=source('SIGNAL_TOWER_3')
-  const pairs=[['foot','pole'],['pole','bracket'],['bracket','lamp-lower'],['lamp-lower','ring-lower'],['ring-lower','lamp-middle'],['lamp-middle','ring-upper'],['ring-upper','lamp-upper'],['lamp-upper','cap']]
-  for(const height of [550,1100,2200,3300])for(const [a,b] of pairs) {
-    const before=bounds(s,b).y.min-bounds(s,a).y.max
-    near(bounds(s,b,{x:1,y:height/s.base.y,z:1}).y.min-bounds(s,a,{x:1,y:height/s.base.y,z:1}).y.max,before)
-  }
-  for(const n of ['lamp-lower','lamp-middle','lamp-upper'])near(bounds(s,n,{x:1,y:3,z:1}).y.size,90)
-})
-
-test('WORKER: intentional non-round primitives must not be forced to circular profiles',()=>{
-  const s=source('WORKER'),scale={x:2,y:1,z:.5}
-  for(const n of ['leg-left','arm-left','hand-left','helmet','helmet-brim']) {
-    assert.equal(part(s,n).keepRound,false)
-    const b=bounds(s,n,scale)
-    for(const a of axes)near(b[a].size,part(s,n).transform.size[a]*scale[a])
-  }
-  assert.equal(s.joints,undefined)
-  console.log(JSON.stringify({worker:'static sample only; no walk/pose animation evidence',gap:'ellipse/ellipsoid semantics must coexist with circular rollers'}))
-})
-
-test('KIOSK: screen aperture margins and protrusion are distinct from same-center attachment',()=>{
-  const s=source('KIOSK'),screen=bounds(s,'screen'),bezel=bounds(s,'bezel')
-  near((bezel.x.size-screen.x.size)/2,30);near((bezel.y.size-screen.y.size)/2,30)
-  near(screen.z.max-bezel.z.max,8)
-  for(const width of [205,410,820]) {
-    const opening=width-60;assert.ok(opening>0);near((width-opening)/2,30)
-  }
-  assert.ok(50-60<0) // candidate fixed-margin intent must reject a too-small bezel.
-})
-
-for(const type of ['CELL_TRAY','FORMATION_TRAY'])test(`${type}: fixed count, wall clearance and cell/contact correspondence`,()=>{
-  const s=source(type),cell=part(s,'cell'),tub=part(s,'tub')
-  for(const scale of [.5,1,2]) {
-    const plan=repeatPlanOfPart(cell,{x:scale,y:1,z:1},s.base)
-    assert.equal(plan.count,8)
-    const edge=(repeatOffset(plan.count-1,plan.count,plan.pitch)+cell.transform.size.x/2)*scale
-    // Explicit candidate: wall thickness remains 30mm. Geometry fits only above a bound.
-    const clearance=s.base.x*scale/2-tub.shape.hollow.wall-edge
-    near(clearance,36*scale-30)
-    if(type==='FORMATION_TRAY') {
-      const other=repeatPlanOfPart(part(s,'contact'),{x:scale,y:1,z:1},s.base)
-      assert.equal(other.count,plan.count);near(other.pitch,plan.pitch)
-    }
-  }
-  console.log(JSON.stringify({type,fixedCount:8,candidateFixedWallClearanceAtHalfScaleMm:-12,minimumScale:30/36,scope:'fixed-wall candidate; not a claim about current rendered wall scaling'}))
-})
-
-test('ROLL_CRADLE: state-driven diameter is geometry change, not rigid joint motion',()=>{
-  const s=source('ROLL_CRADLE'),{c}=channel(s,'fed','roll'),r=part(s,'roll'),core=part(s,'core')
-  assert.equal(c.path,'scale')
-  for(const t of [0,.25,.5,.75,1]) {
-    const v=sampleChannel(c,t)
-    near(v.x,v.z);near(v.y,1)
-    assert.ok(r.transform.size.x*v.x>=core.transform.size.x)
-    near(r.transform.size.y*v.y,1000)
-  }
-  near(r.transform.size.x*sampleChannel(c,1).x,224)
-  console.log(JSON.stringify({cradle:{diameterRangeMm:[700,224],coreDiameterMm:200},gap:'state-dependent shape dimensions needed beyond rigid J; resizing radius times state factor is bilinear if both are variable'}))
-})
-
-test('MODULE_PALLET: terminals exceed base height; base is not automatic containment',()=>{
-  const s=source('MODULE_PALLET'),deck=bounds(s,'deck'),module=bounds(s,'module')
-  near(deck.y.max,module.y.min)
-  for(const n of ['terminal-left','terminal-right'])near(bounds(s,n).y.max-s.base.y,45)
-  for(const n of ['foot-front-left','foot-front-right','foot-back-left','foot-back-right']) {
-    near(bounds(s,n).y.min,0);near(bounds(s,n).y.max,deck.y.min)
-  }
-})
-
-test('ROLL_PRESS: opening state versus finite web thickness exposes collision intent ambiguity',()=>{
-  const s=source('ROLL_PRESS'),upper=bounds(s,'roll-upper'),lower=bounds(s,'roll-lower'),web=bounds(s,'web')
-  const uc=channel(s,'nip','roll-upper').c,wc=channel(s,'nip','web').c,rows=[]
-  for(const opening of [0,12,24,120,240]) {
-    const u=sampleChannel(uc,opening/240).y,w=sampleChannel(wc,opening/240).y
-    near((upper.y.min+u)-lower.y.max,opening)
-    near(web.y.center+w,(upper.y.min+u+lower.y.max)/2)
-    const clearance=(opening-web.y.size)/2
-    near(web.y.min+w-lower.y.max,clearance)
-    rows.push({opening,clearancePerSideMm:clearance})
-  }
-  console.log(JSON.stringify({rollPress:rows,gap:'24mm web at zero gap overlaps both rolls by 12mm; distinguish schematic compression from forbidden collision'}))
-})
-
-test('FORMATION_CHARGER: shelf/lamp repeat pairing and envelope at count thresholds',()=>{
-  const s=source('FORMATION_CHARGER'),rows=[]
-  for(const height of [1400,2799.99,2800,2800.01,5600]) {
-    const scale={x:1,y:height/s.base.y,z:1}
-    const a=repeatPlanOfPart(part(s,'shelf'),scale,s.base),b=repeatPlanOfPart(part(s,'channel-lamp'),scale,s.base)
-    assert.equal(a.count,b.count);near(a.pitch,b.pitch)
-    near(bounds(s,'shelf',scale).y.center,bounds(s,'channel-lamp',scale).y.center)
-    const first=bounds(s,'shelf',scale).y.center+repeatOffset(0,a.count,a.pitch)-20
-    rows.push({height,count:a.count,firstShelfBottom:first})
-  }
-  console.log(JSON.stringify({charger:rows,gap:'paired instances need common stable index; whole-base count does not guarantee plinth/HMI clearance'}))
-})
-
-test('GANTRY_CRANE_3DOF: 27 travel combinations inherit each translation exactly once',()=>{
-  const s=source('GANTRY_CRANE_3DOF')
-  for(const x of [-1600,0,1600])for(const z of [-900,0,900])for(const drop of [0,900,1800]) {
-    const q={'bridge-travel':x,'trolley-traverse':z,'hoist-drop':drop},offsets={}
-    for(const p of s.parts) {
-      const inherited=p.parent?offsets[p.parent]:{x:0,y:0,z:0},j=s.joints.find(j=>j.child===p.name)
-      if(j)assert.equal(j.type,'prismatic')
-      offsets[p.name]=Object.fromEntries(axes.map(a=>[a,inherited[a]+(j?j.axis[a]*q[j.name]:0)]))
-    }
-    near(offsets['hook-seat'].x,x);near(offsets['hook-seat'].z,z);near(offsets['hook-seat'].y,-drop)
-    near(part(s,'hook').transform.position.y+offsets.hook.y-(part(s,'hook-seat').transform.position.y+offsets['hook-seat'].y),60)
-    near(offsets['leg-1'].x,0)
-  }
-})

package/docs/prototypes/payload-collision.mjs

@@ -1,54 +0,0 @@
-import {compilePayloadInspection} from './payload-fit.mjs'
-import {ContractError} from './typed-plan.mjs'
-const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
-const cross=(a,b)=>[a[1]*b[2]-a[2]*b[1],a[2]*b[0]-a[0]*b[2],a[0]*b[1]-a[1]*b[0]]
-const columns=r=>[0,1,2].map(i=>r.map(row=>row[i]))
-export function boxRelation(a,b,tolerance=1e-6){
- // Static OBB SAT: 3 + 3 face normals and 9 cross-product axes.
- for(const box of [a,b]){
-  if(!box||!Array.isArray(box.center)||box.center.length!==3||!Array.isArray(box.half)||box.half.length!==3||!Array.isArray(box.axes)||box.axes.length!==3||box.axes.some(v=>!Array.isArray(v)||v.length!==3)||[...box.center,...box.half,...box.axes.flat()].some(v=>!Number.isFinite(v))||box.half.some(v=>v<=0))throw new ContractError('OBB_DOMAIN','collision','finite positive OBB required')
-  for(let i=0;i<3;i++)for(let j=0;j<3;j++)if(Math.abs(dot(box.axes[i],box.axes[j])-(i===j?1:0))>1e-9)throw new ContractError('OBB_FRAME','collision','orthonormal axes required')
- }
- if(!Number.isFinite(tolerance)||tolerance<0)throw new ContractError('OBB_DOMAIN','collision','invalid tolerance')
- const delta=b.center.map((v,i)=>v-a.center[i]),axes=[...a.axes,...b.axes,...a.axes.flatMap(x=>b.axes.map(y=>cross(x,y)))]
- let minOverlap=Infinity,uncertain=false
- for(const axis of axes){
-  const norm=Math.hypot(...axis)
-  if(norm===0)continue
-  if(norm<1e-12){uncertain=true;continue}
-  const n=axis.map(v=>v/norm),radius=box=>box.half.reduce((s,h,i)=>s+h*Math.abs(dot(box.axes[i],n)),0)
-  const overlap=radius(a)+radius(b)-Math.abs(dot(delta,n))
-  if(overlap < -tolerance)return {relation:'separated',separationMm:-overlap}
-  minOverlap=Math.min(minOverlap,overlap)
- }
- if(uncertain)return {relation:'unverified',reason:'NEAR_PARALLEL_NUMERICS'}
- return {relation:minOverlap<=tolerance?'touching':'penetrating',minimumAxisOverlapMm:Math.max(0,minOverlap)}
-}
-function envelope(g){
- const d=g.shape.dimensions;let half
- if(['box','roundedBox'].includes(g.shape.provider))half=[d.width/2,d.height/2,d.depth/2]
- else if(g.shape.provider==='cylinder')half=[d.radius,d.length/2,d.radius]
- else return null
- return {center:g.pose.t,axes:columns(g.pose.r),half}
-}
-export function compileCollisionInspection(model,declaration){
- const plan=compilePayloadInspection(model,declaration)
- return {evaluate(input,payload){
-  const result=plan.evaluate(input,payload),binding=result.evaluation.bindings.find(b=>b.id===payload.bindingId)
-  const a=payload.yawDeg*Math.PI/180,c=Math.cos(a),s=Math.sin(a),r=binding.pose.r
-  const mv=v=>r.map(row=>dot(row,v)),axes=[[c,0,-s],[0,1,0],[s,0,c]].map(mv)
-  const box={center:mv(payload.center).map((v,i)=>v+binding.pose.t[i]),axes,half:payload.dimensions.map(v=>v/2)}
-  const pairs=result.evaluation.geometry.map(g=>{
-   const bounds=envelope(g)
-   if(!bounds)return {geometryId:g.id,status:'unverified',reason:'UNSUPPORTED_ENVELOPE'}
-   const relation=boxRelation(box,bounds),exact=g.shape.provider==='box'
-   if(relation.relation==='separated')return {geometryId:g.id,status:'satisfied',reason:exact?'BOX_SEPARATED':'CONSERVATIVE_ENVELOPE_SEPARATED',...relation}
-   if(!exact)return {geometryId:g.id,status:'unverified',reason:'ENVELOPE_OVERLAP_NEEDS_NARROW_PHASE'}
-   if(relation.relation==='unverified')return {geometryId:g.id,status:'unverified',reason:relation.reason}
-   return {geometryId:g.id,status:relation.relation==='penetrating'?'failed':'satisfied',reason:relation.relation==='penetrating'?'BOX_PENETRATION':'TOUCH_WITHIN_TOLERANCE',...relation}
-  })
-  const status=pairs.some(p=>p.status==='failed')?'failed':pairs.some(p=>p.status==='unverified')?'unverified':'satisfied'
-  result.inspection.collision={status,scope:'payload-vs-every-model-part-at-current-state',method:'obb-sat-v1',distanceToleranceMm:1e-6,pairs}
-  return result
- }}
-}

package/docs/prototypes/payload-collision.test.mjs

@@ -1,68 +0,0 @@
-import {test} from 'node:test'
-import assert from 'node:assert/strict'
-import {boxRelation,compileCollisionInspection} from './payload-collision.mjs'
-import {forkliftBindings} from './capability-samples.mjs'
-import {defaults} from './full-forklift.mjs'
-import {OBB} from '../../../things-scene/node_modules/three/examples/jsm/math/OBB.js'
-import * as THREE from '../../../things-scene/node_modules/three/build/three.module.js'
-const identity=[[1,0,0],[0,1,0],[0,0,1]],box=(center,half=[1,1,1],axes=identity)=>({center,half,axes})
-const payload={bindingId:'load-low',type:'PALLET',occupied:0,dimensions:[620,100,850],center:[260,50,0],yawDeg:0}
-const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-7)
-test('SAT separates, touches, penetrates and handles complete containment symmetrically',()=>{
- for(const [x,expected] of [[3,'separated'],[2,'touching'],[1,'penetrating'],[0,'penetrating']]){
-  const a=box([0,0,0]),b=box([x,0,0]);assert.equal(boxRelation(a,b).relation,expected);assert.equal(boxRelation(b,a).relation,expected)
- }
- assert.equal(boxRelation(box([0,0,0],[10,10,10]),box([0,0,0])).relation,'penetrating')
- assert.equal(boxRelation(box([0,0,0]),box([2+2e-6,0,0])).relation,'separated')
- assert.equal(boxRelation(box([0,0,0]),box([2+5e-7,0,0])).relation,'touching')
-})
-test('rotated boxes with overlapping world AABBs can be separated',()=>{
- const t=Math.PI/4,axes=[[Math.cos(t),0,-Math.sin(t)],[0,1,0],[Math.sin(t),0,Math.cos(t)]]
- const a=box([0,0,0],[5,1,.1],axes),b=box([.5,0,.5],[5,1,.1],axes)
- assert.equal(boxRelation(a,b).relation,'separated')
-})
-test('payload bottom contact does not hide upper fork penetration',()=>{
- const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration)
- const r=p.evaluate(defaults,{...payload,dimensions:[620,500,850],center:[260,250,0]})
- assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.inspection.collision.status,'failed')
- for(const side of ['left','right'])assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-high-'+side).reason,'BOX_PENETRATION')
- assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-low-left').reason,'TOUCH_WITHIN_TOLERANCE')
- assert.equal(r.inspection.safety.status,'unverified')
-})
-test('all parts are checked, curved envelope overlap stays unverified, never automatically excluded',()=>{
- const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration)
- const r=p.evaluate(defaults,{...payload,dimensions:[50,50,50],center:[260,343,-1485]})
- assert.equal(r.inspection.collision.pairs.length,20)
- assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='body').status,'unverified')
- assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='body').reason,'ENVELOPE_OVERLAP_NEEDS_NARROW_PHASE')
-})
-test('225 state combinations retain upper-fork collision and lower-fork touching',()=>{
- const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration);let states=0
- for(const forkLength of [425,850,1700])for(const lift of [0,500,1000,1500,2000])for(const reach of [0,200,400])for(const yawDeg of [-30,-15,0,15,30]){
-  const r=p.evaluate({...defaults,forkLength,lift,reach},{...payload,dimensions:[620,500,forkLength],center:[260,250,0],yawDeg})
-  assert.equal(r.inspection.collision.status,'failed')
-  for(const side of ['left','right'])assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-high-'+side).reason,'BOX_PENETRATION')
-  states++
- }
- assert.equal(states,225);console.log({payloadCollisionStates:states,pairChecks:states*20})
-})
-test('invalid OBB and numerical near-parallel ambiguity fail closed',()=>{
- assert.throws(()=>boxRelation(box([0,0,0],[-1,1,1]),box([0,0,0])))
- assert.throws(()=>boxRelation(box([0,0,0],[1,1,1],[[2,0,0],[0,1,0],[0,0,1]]),box([0,0,0])))
- const a=1e-14,rot=[[Math.cos(a),Math.sin(a),0],[-Math.sin(a),Math.cos(a),0],[0,0,1]]
- assert.equal(boxRelation(box([0,0,0]),box([0,0,0],[1,1,1],rot)).relation,'unverified')
-})
-test('1000 deterministic general 3D pairs agree with Three.js OBB implementation',()=>{
- let state=983451,intersections=0,separations=0
- const random=()=>{state=(Math.imul(1664525,state)+1013904223)>>>0;return state/2**32}
- const make=()=>{const matrix=new THREE.Matrix3().setFromMatrix4(new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(random()*6,random()*6,random()*6)))
-  const e=matrix.elements,center=Array.from({length:3},()=>random()*20-10),half=Array.from({length:3},()=>.1+random()*6)
-  return {ours:box(center,half,[[e[0],e[1],e[2]],[e[3],e[4],e[5]],[e[6],e[7],e[8]]]),reference:new OBB(new THREE.Vector3(...center),new THREE.Vector3(...half),matrix)}}
- for(let i=0;i<1000;i++){
-  const a=make(),b=make(),expected=a.reference.intersectsOBB(b.reference),r=boxRelation(a.ours,b.ours)
-  assert.notEqual(r.relation,'unverified');assert.equal(r.relation!=='separated',expected)
-  assert.equal(boxRelation(b.ours,a.ours).relation,r.relation)
-  if(expected)intersections++;else separations++
- }
- assert.ok(intersections>0&&separations>0);console.log({obbReferencePairs:1000,intersections,separations})
-})

package/docs/prototypes/payload-fit.mjs

@@ -1,58 +0,0 @@
-// Bounded geometric inspection, not a load-bearing or collision-safety certificate.
-import {compileCapabilities} from './capability-plan.mjs'
-import {ContractError} from './typed-plan.mjs'
-const fail=(code,message)=>{throw new ContractError(code,'payload',message)}
-const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
-const mv=(r,v)=>r.map(row=>dot(row,v))
-const local=(pose,p)=>[0,1,2].map(i=>pose.r.reduce((s,row,j)=>s+row[i]*(p[j]-pose.t[j]),0))
-const world=(pose,p)=>mv(pose.r,p).map((v,i)=>v+pose.t[i])
-function clip(poly,axis,bound,sign){
- const out=[]
- for(let i=0;i<poly.length;i++){
-  const a=poly[i],b=poly[(i+1)%poly.length],da=sign*(a[axis]-bound),db=sign*(b[axis]-bound),inside=da<=0,next=db<=0
-  if(inside)out.push(a)
-  if(inside!==next){const t=da/(da-db);out.push(a.map((v,j)=>v+t*(b[j]-v)))}
- }
- return out
-}
-function overlapArea(poly,width,depth){
- for(const [axis,bound,sign] of [[0,width/2,1],[0,-width/2,-1],[1,depth/2,1],[1,-depth/2,-1]])poly=clip(poly,axis,bound,sign)
- return Math.abs(poly.reduce((sum,p,i)=>{const q=poly[(i+1)%poly.length];return sum+p[0]*q[1]-q[0]*p[1]},0))/2
-}
-export function compilePayloadInspection(model,declaration){
- const plan=compileCapabilities(model,declaration)
- return {evaluate(input,payload){
-  const keys=['bindingId','type','occupied','dimensions','center','yawDeg']
-  if(!payload||typeof payload!=='object'||Array.isArray(payload)||Object.keys(payload).length!==keys.length||keys.some(k=>!Object.hasOwn(payload,k)))fail('SCHEMA','expected bindingId,type,occupied,dimensions,center,yawDeg')
-  if(typeof payload.bindingId!=='string')fail('SCHEMA','bindingId required')
-  for(const key of ['dimensions','center'])if(!Array.isArray(payload[key])||payload[key].length!==3||payload[key].some(v=>typeof v!=='number'||!Number.isFinite(v)))fail('PAYLOAD_DOMAIN','finite 3D vectors required')
-  if(payload.dimensions.some(v=>v<=0)||!Number.isFinite(payload.yawDeg))fail('PAYLOAD_DOMAIN','positive dimensions and finite yaw required')
-  // Explicit supported numeric envelope. Never silently clamp a larger asset.
-  if([...payload.dimensions,...payload.center].some(v=>Math.abs(v)>1e6)||Math.abs(payload.yawDeg)>360)fail('PAYLOAD_LIMIT','experimental envelope: 1e6 mm and yaw ±360 degrees')
-  const evaluation=plan.evaluate(input,{[payload.bindingId]:{type:payload.type,occupied:payload.occupied}})
-  const binding=evaluation.bindings.find(b=>b.id===payload.bindingId)
-  if(!binding)fail('TARGET_ABSENT',payload.bindingId)
-  const [w,h,d]=payload.dimensions,a=payload.yawDeg*Math.PI/180,c=Math.cos(a),s=Math.sin(a)
-  const rotate=([x,y,z])=>[c*x+s*z,y,-s*x+c*z].map((v,i)=>v+payload.center[i])
-  const bottom=[[-w/2,-h/2,-d/2],[w/2,-h/2,-d/2],[w/2,-h/2,d/2],[-w/2,-h/2,d/2]].map(rotate)
-  const corners=[...bottom,...bottom.map(v=>[v[0],v[1]+h,v[2]])]
-  const distanceToleranceMm=1e-6,areaToleranceMm2=1e-6
-  let containment={status:'unverified',reason:'NO_REGION'}
-  if(binding.region){const excess=Math.max(...corners.flatMap(p=>p.map((v,i)=>Math.abs(v)-binding.region.dimensions[i]/2)));containment={status:excess<=distanceToleranceMm?'satisfied':'failed',reason:excess<=distanceToleranceMm?'BOX_CONTAINED':'OUTSIDE_REGION',excessMm:Math.max(0,excess)}}
-  const up=mv(binding.pose.r,[0,1,0]),bottomWorld=bottom.map(p=>world(binding.pose,p))
-  const contacts=binding.contacts.map(surface=>{
-   const base={geometryId:surface.geometryId,feature:surface.feature}
-   if(binding.role!=='seat'||surface.provider!=='box'||surface.face!=='top')return {...base,status:'unverified',reason:'UNSUPPORTED_CONTACT_PAIR'}
-   if(Math.abs(dot(up,surface.normal)-1)>1e-9)return {...base,status:'unverified',reason:'NONPARALLEL_FACES'}
-   const geometry=evaluation.geometry.find(g=>g.id===surface.geometryId)
-   if(!geometry)fail('TARGET_ABSENT',surface.geometryId)
-   const points=bottomWorld.map(p=>local(surface.pose,p)),dim=geometry.shape.dimensions
-   const overlap=overlapArea(points.map(p=>[p[0],p[2]]),dim.width,dim.depth)
-   const minGap=Math.min(...points.map(p=>p[1])),maxGap=Math.max(...points.map(p=>p[1]))
-   const reason=overlap<=areaToleranceMm2?'NO_POSITIVE_CONTACT_AREA':minGap < -distanceToleranceMm?'PENETRATES_SUPPORT_PLANE':maxGap>distanceToleranceMm?'ABOVE_SUPPORT':'PLANAR_CONTACT'
-   return {...base,status:reason==='PLANAR_CONTACT'?'satisfied':'failed',reason,overlapAreaMm2:overlap,minGapMm:minGap,maxGapMm:maxGap}
-  })
-  const contactStatus=!contacts.length?'unverified':contacts.some(c=>c.status==='failed')?'failed':contacts.some(c=>c.status==='unverified')?'unverified':'satisfied'
-  return {evaluation,inspection:{bindingId:binding.id,method:'box-payload/box-top-v1',distanceToleranceMm,areaToleranceMm2,containment,contact:{status:contactStatus,surfaces:contacts},collision:{status:'unverified',reason:'GLOBAL_COLLISION_NOT_CHECKED'},stability:{status:'unverified',reason:'CENTER_OF_MASS_AND_FORCES_NOT_CHECKED'},safety:{status:'unverified',reason:'NOT_CHECKED'}}}
- }}
-}

package/docs/prototypes/payload-fit.test.mjs

@@ -1,59 +0,0 @@
-import {test} from 'node:test'
-import assert from 'node:assert/strict'
-import {compilePayloadInspection} from './payload-fit.mjs'
-import {forkliftBindings,robotBinding} from './capability-samples.mjs'
-import {defaults} from './full-forklift.mjs'
-import {defaults as robotDefaults} from './full-robot.mjs'
-const payload={bindingId:'load-low',type:'PALLET',occupied:0,dimensions:[620,100,850],center:[260,50,0],yawDeg:0}
-const plan=s=>compilePayloadInspection(s.model,s.declaration)
-const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-5,`${a} != ${b}`)
-test('both physical fork surfaces support the payload through size/lift/reach/yaw states',()=>{
- const p=plan(forkliftBindings());let states=0
- for(const forkLength of [425,850,1700])for(const lift of [0,1000,2000])for(const reach of [0,200,400])for(const yawDeg of [-30,0,30]){
-  const q={...payload,dimensions:[620,100,forkLength],yawDeg},r=p.evaluate({...defaults,forkLength,lift,reach},q)
-  assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.inspection.containment.status,'unverified')
-  assert.equal(r.evaluation.geometry.length,20)
-  for(const c of r.inspection.contact.surfaces){near(c.minGapMm,0);near(c.maxGapMm,0);assert.ok(c.overlapAreaMm2>0);if(!yawDeg)near(c.overlapAreaMm2,90*forkLength)}
-  states++
- }
- console.log({payloadContactStates:states})
-})
-test('floating, penetration, missing one fork and zero-area edge touch fail explicitly',()=>{
- const p=plan(forkliftBindings())
- for(const [center,reason] of [[[260,51,0],'ABOVE_SUPPORT'],[[260,49,0],'PENETRATES_SUPPORT_PLANE'],[[0,50,0],'NO_POSITIVE_CONTACT_AREA'],[[-355,50,0],'NO_POSITIVE_CONTACT_AREA']]){
-  const r=p.evaluate(defaults,{...payload,center}).inspection
-  assert.equal(r.contact.status,'failed');assert.ok(r.contact.surfaces.some(c=>c.reason===reason))
-  if(center[0]===-355)assert.equal(r.contact.surfaces[0].overlapAreaMm2,0)
- }
- // Narrow object fits between the forks: no support, even though a broad region could contain it.
- const r=p.evaluate(defaults,{...payload,dimensions:[100,100,850]}).inspection;assert.ok(r.contact.surfaces.every(c=>c.reason==='NO_POSITIVE_CONTACT_AREA'))
-})
-test('containment checks all rotated box corners and does not imply support',()=>{
- const s=forkliftBindings();for(const [id,value] of [['regionW',1200],['regionH',400],['regionD',900]])s.model.constants.push({id,value,unit:'mm'})
- s.declaration.bindings[0].region={kind:'centered-box',dimensions:['regionW','regionH','regionD']}
- const p=plan(s),ok=p.evaluate(defaults,payload).inspection;assert.equal(ok.containment.status,'satisfied')
- const outside=p.evaluate(defaults,{...payload,yawDeg:45}).inspection;assert.equal(outside.containment.status,'failed')
- const floating=p.evaluate(defaults,{...payload,center:[260,60,0]}).inspection;assert.equal(floating.containment.status,'satisfied');assert.equal(floating.contact.status,'failed')
-})
-test('contact result invariant under shared rigid rotation; not a gravity stability proof',()=>{
- const original=plan(forkliftBindings()).evaluate(defaults,payload).inspection
- for(const angle of [-65,30,90]){
-  const s=forkliftBindings();s.model.constants.push({id:'tilt',value:angle,unit:'deg'});s.model.nodes.find(n=>n.id==='mastPose').args[5]='tilt'
-  const r=plan(s).evaluate({...defaults,lift:700,reach:120},payload).inspection
-  assert.equal(r.contact.status,'satisfied');r.contact.surfaces.forEach((c,i)=>near(c.overlapAreaMm2,original.contact.surfaces[i].overlapAreaMm2));assert.equal(r.stability.status,'unverified')
- }
-})
-test('contact never certifies global collision, eligibility or safety',()=>{
- const p=plan(forkliftBindings())
- // Height 500 crosses the upper fork level. Bottom contact remains correct, not globally safe.
- const r=p.evaluate(defaults,{...payload,type:'NOT_ACCEPTED',occupied:1,dimensions:[620,500,850],center:[260,250,0]})
- assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.evaluation.bindings[0].checks.eligibility.status,'failed')
- assert.equal(r.inspection.collision.status,'unverified');assert.equal(r.inspection.safety.status,'unverified')
- const robot=plan(robotBinding()).evaluate(robotDefaults,{...payload,bindingId:'tool-grip',type:'BOX'})
- assert.equal(robot.inspection.contact.status,'unverified')
-})
-test('invalid payloads reject and subsequent evaluations recover without model mutation',()=>{
- const s=forkliftBindings(),snapshot=structuredClone(s),p=plan(s),baseline=p.evaluate(defaults,payload)
- for(const change of [{dimensions:[0,1,1]},{center:[NaN,0,0]},{yawDeg:Infinity},{dimensions:[1e7,1,1]},{extra:1}])assert.throws(()=>p.evaluate(defaults,{...payload,...change}))
- assert.deepEqual(p.evaluate(defaults,payload),baseline);assert.deepEqual(s,snapshot)
-})

package/docs/prototypes/render-dryroom.py

@@ -1,60 +0,0 @@
-"""Software orthographic rendering of the actual generated triangle meshes.
-Input: JSON from dryroom-mesh.mjs on stdin. Requires Pillow, no product changes.
-Output path must be explicitly supplied. Not a screenshot of the product renderer.
-"""
-import json,sys,math
-import numpy as np
-from PIL import Image,ImageDraw,ImageFont
-data=json.load(sys.stdin)
-im=Image.new('RGB',(1440,1000),'#101923');draw=ImageDraw.Draw(im)
-font=ImageFont.truetype('/System/Library/Fonts/Helvetica.ttc',22)
-small=ImageFont.truetype('/System/Library/Fonts/Helvetica.ttc',17)
-title=ImageFont.truetype('/System/Library/Fonts/Helvetica.ttc',29)
-draw.text((30,20),'DRY ROOM / actual seed portal mesh',font=title,fill='white')
-draw.text((30,62),'Orthographic mesh render, not the application viewport. Original asset unchanged.',font=small,fill='#a9bdcc')
-for col,panel in enumerate(data['panels']):
-    x0=25+col*720
-    draw.text((x0,108),'BEFORE  |  bottom -60 mm' if col==0 else 'AFTER  |  bottom 0 mm',font=font,fill='#ffd189' if col==0 else '#85dfc7')
-    for zoom in [False,True]:
-        y0=155 if not zoom else 715
-        w,h=675,520 if not zoom else 215
-        canvas=Image.new('RGB',(w,h),'#192733');d=ImageDraw.Draw(canvas)
-        scale=.151 if not zoom else .235
-        def project(v):
-            x,y,z=v;z-=3050
-            return (w/2+(x+.40*z)*scale, (h-50 if not zoom else h-70)-y*scale+.16*z*scale)
-        pixels=np.full((h,w,3),(25,39,51),dtype=np.uint8)
-        zbuffer=np.full((h,w),-np.inf)
-        for part in panel['parts']:
-            for tri in part['triangles']:
-                a,b,c=tri
-                u=[b[i]-a[i] for i in range(3)];v=[c[i]-a[i] for i in range(3)]
-                normal=[u[1]*v[2]-u[2]*v[1],u[2]*v[0]-u[0]*v[2],u[0]*v[1]-u[1]*v[0]]
-                norm=math.sqrt(sum(x*x for x in normal))
-                illumination=.58+.42*abs(sum(x*y for x,y in zip(normal,[.3,.4,.866]))/norm)
-                base=(51,184,176) if part['id']=='placedPortal' else (245,185,60)
-                color=tuple(int(x*illumination) for x in base)
-                poly=[project(v) for v in tri]
-                (ax,ay),(bx,by),(cx,cy)=poly
-                den=(by-cy)*(ax-cx)+(cx-bx)*(ay-cy)
-                if abs(den)<1e-9:continue
-                loX=max(0,math.floor(min(v[0] for v in poly)));hiX=min(w-1,math.ceil(max(v[0] for v in poly)))
-                loY=max(0,math.floor(min(v[1] for v in poly)));hiY=min(h-1,math.ceil(max(v[1] for v in poly)))
-                if loX>hiX or loY>hiY:continue
-                yy,xx=np.mgrid[loY:hiY+1,loX:hiX+1];xx=xx+.5;yy=yy+.5
-                wa=((by-cy)*(xx-cx)+(cx-bx)*(yy-cy))/den
-                wb=((cy-ay)*(xx-cx)+(ax-cx)*(yy-cy))/den;wc=1-wa-wb
-                depths=[v[2]-.40*v[0]+.16*v[1] for v in tri]
-                zz=wa*depths[0]+wb*depths[1]+wc*depths[2]
-                region=zbuffer[loY:hiY+1,loX:hiX+1]
-                mask=(wa>=-1e-8)&(wb>=-1e-8)&(wc>=-1e-8)&(zz>region)
-                region[mask]=zz[mask];pixels[loY:hiY+1,loX:hiX+1][mask]=color
-        canvas=Image.fromarray(pixels);d=ImageDraw.Draw(canvas)
-        # Reference line on front face plane; no opaque floor hiding the original protrusion.
-        a=project([-2000,0,3200]);b=project([2000,0,3200]);d.line([a,b],fill='#ff6b73',width=3)
-        d.text((12,h-28),'Y = 0  /  floor reference',font=small,fill='#ff9ba1')
-        if zoom:d.text((12,10),'BOTTOM DETAIL',font=small,fill='white')
-        im.paste(canvas,(x0,y0))
-    draw.text((x0,682),'Top 2900 mm / opening top 2200 mm / lamp unchanged',font=small,fill='#a9bdcc')
-draw.text((30,954),'Mesh checks: closed, oriented edges; 28 triangles per portal. Both inlet and outlet tested.',font=small,fill='#a9bdcc')
-im.save(sys.argv[1])