@deepblend/dsh-blender-host 0.12.0 → 0.14.0

package/lib/cup-hero-framing.js

@@ -0,0 +1,39 @@
+/** Continue one recognized default hero using an actual Blender vertex/frustum measurement. */
+import { BlenderError } from '@deepblend/dsh-blender-contracts'
+const vector = value => Array.isArray(value) && value.length === 3 && value.every(Number.isFinite)
+const near = (a, b) => vector(a) && vector(b) && a.every((value, axis) => Math.abs(value-b[axis]) <= 1e-6)
+const refuse = message => { throw new BlenderError('PROTOCOL_VERSION_MISMATCH', `Cannot verify recipe hero framing: ${message}`) }
+
+export function fitCupHeroFromNative(spec, report, selector) {
+  if (!selector) return null
+  const camera = spec.cameras.find(item => item.id === selector.cameraId)
+  const native = report?.cameraFraming
+  if (selector.cameraId !== 'hero' || selector.entityId !== 'cup' || selector.margin !== 0.03
+      || !camera || !vector(camera.targetPoint) || !vector(camera.transform.location)
+      || native?.schemaVersion !== 'deepblend.camera-framing/v1'
+      || native.entityId !== selector.entityId || native.cameraId !== selector.cameraId
+      || native.margin !== selector.margin || native.cameraType !== 'PERSP'
+      || !near(native.cameraLocation, camera.transform.location)
+      || !Number.isFinite(native.lens) || Math.abs(native.lens-camera.lens) > 1e-6
+      || !Number.isFinite(native.sensorWidth) || Math.abs(native.sensorWidth-(camera.sensorWidth??36)) > 1e-6
+      || !Number.isFinite(native.backoffM) || native.backoffM < 0
+      || !Number.isInteger(native.vertices) || native.vertices < 1 || native.vertices > 2000000
+      || native.scope !== 'evaluated-cup-vertices-at-reported-frame-and-render-aspect'
+      || !Number.isInteger(native.frame) || native.frame !== report.renderConfig?.frameStart
+      || native.resolutionPercentage !== 100 || !Array.isArray(native.pixelAspect)
+      || native.pixelAspect.length !== 2 || !native.pixelAspect.every(value => Number.isFinite(value) && Math.abs(value-1) <= 1e-9)
+      || !Number.isFinite(native.nearestDepthM) || native.nearestDepthM <= 0
+      || !Number.isFinite(native.farthestDepthM) || native.farthestDepthM < native.nearestDepthM
+      || native.nearestDepthM <= (camera.clipping?.[0] ?? 0.1)
+      || native.farthestDepthM >= (camera.clipping?.[1] ?? 1000)
+      || !Array.isArray(native.resolution) || native.resolution.length !== 2
+      || !native.resolution.every((value, axis) => Number.isInteger(value) && value > 0 && value === report.renderConfig?.resolution?.[axis])) refuse('missing or inconsistent measured facts')
+  if (spec.animationTracks.some(track => track.targetKind === 'camera' && track.targetEntityId === camera.id)) refuse('animated camera')
+  const away = camera.transform.location.map((value, axis) => value-camera.targetPoint[axis])
+  const distance = Math.hypot(...away)
+  if (!(distance > 0)) refuse('invalid target')
+  const location = camera.transform.location.map((value, axis) => value+away[axis]/distance*native.backoffM)
+  if (!vector(location)) refuse('non-finite fitted camera')
+  return { ...structuredClone(native), location,
+    source: 'native-evaluated-vertices-and-blender-camera-frame' }
+}

package/lib/geometry-inspection.js

@@ -66,17 +66,20 @@ export async function inspectRevisionGeometry(host, projectId, revision, selecti
     if (selection.surfaceSamples !== undefined && result?.report?.schemaVersion === 'deepblend.geometry-inspection/v1') {
       refuse(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'the runtime does not support local surface samples; upgrade DeepBlend. Ordinary native geometry reads remain available.')
     }
+    if (selection.objectAxes === true && result?.report?.schemaVersion !== 'deepblend.geometry-inspection/v3') refuse(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The runtime does not support object-local native bounds; upgrade DeepBlend. Ordinary reads remain available.')
     const native = verifyGeometryReport(result?.report, request)
     verifySource()
     const hasSamples = selection.surfaceSamples !== undefined
-    return { schemaVersion: hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1', projectId, sourceRevision: revision,
+    return { schemaVersion: selection.objectAxes === true ? 'deepblend.scene-geometry/v3' : hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1', projectId, sourceRevision: revision,
       sourceDigest: digest, sourceSpecHash: manifest.specHashAfter, sourceCheckpointSha256: expected,
+      ...(selection.objectAxes === true ? { objectAxisBasis: native.objectAxisBasis } : {}),
       sourceUnchanged: true, frame: native.frame, objects: native.objects, blenderVersion: native.blenderVersion,
       ...(hasSamples ? { surfaceSamples: native.surfaceSamples } : {}),
       excludedMeasurements: hasSamples ? ['globalWallThickness', 'assemblyClearance', 'minimumClearance', 'collision', 'selfIntersection'] :
         ['wallThickness', 'shellToLinerClearance', 'minimumClearance', 'collision'],
       execution: { transport: 'batch' }, limitations: [
-        'World-axis spans include rotations, handles and protrusions; they are not intrinsic body dimensions.',
+        'World-axis spans include rotations, handles and protrusions; they are not intrinsic body dimensions. Never invert a world-axis bounding box to recover local bounds.',
+        ...(selection.objectAxes === true ? ['objectAxisBoundsMeters and objectAxisExtentMm bound actual evaluated mesh vertices in physical orthogonal axes of the selected object. They include evaluated modifiers, protrusions and native object/world scale, exclude placement rotation/translation, and are not semantic body dimensions or assembly extents. objectAxisWorldMatrix supplies the normalized axes and native origin. Sheared or degenerate object-axis bases have explicit unavailable objectAxisStatus while world bounds remain measured; these dimensions are not inferred from world bounds. Native scale can include generator construction transforms; it is not itself proof of a manual scaling edit. These extents already include that scale; do not apply it again.'] : []),
         'This evaluates saved native mesh geometry, not shader displacement or rendered pixels.',
         ...(hasSamples ? [
           'Surface samples are finite local chords along evaluated triangle-face normals, not shader or smoothed shading normals.',

package/lib/index.js

@@ -712,7 +712,7 @@ export default class BlenderStudio extends Service {
    * whole spec on every turn spends its context on fields it is not changing.
    *
    * @param {string} projectId
-   * @param {{ revision?: string, full?: boolean, geometry?: { entityIds: string[], frame: number, surfaceSamples?: object[] }, signal?: AbortSignal }} [options]
+   * @param {{ revision?: string, full?: boolean, geometry?: { entityIds: string[], frame: number, objectAxes?: boolean, surfaceSamples?: object[] }, signal?: AbortSignal }} [options]
    * @returns {Promise<Record<string, unknown>>}
    */
   async getScene(projectId, options = {}) {
@@ -833,6 +833,7 @@ export default class BlenderStudio extends Service {
     return { ...toCanonicalRevisionSummary({ manifest: outcome.revision, checkpointPath: outcome.revision.checkpoint }),
       unchanged: outcome.unchanged === true, idempotentReplay: outcome.idempotentReplay === true,
       parameterState: outcome.parameterState, preservedCameraIds: outcome.preservedCameraIds, placementChanges,
+      ...(outcome.revision.cameraFraming ? { cameraFraming: structuredClone(outcome.revision.cameraFraming) } : {}),
       parameters: await this.getRecipeParameters(input.projectId, { revision: outcome.revision.revision }),
       ...(outcome.job ? { job: toCanonicalJobRecord(outcome.job) } : {}) }
   }

package/lib/revision-transaction.js

@@ -42,6 +42,7 @@
  */
 
 import { assertRuntimeSceneFeatures } from './runtime-scene-features.js'
+import { fitCupHeroFromNative } from './cup-hero-framing.js'
 import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
@@ -325,7 +326,7 @@ export class RevisionTransaction {
       const checked = validateScenePatch(patch)
       if (!checked.ok) throw new BlenderError(BlenderErrorCode.SCENE_PATCH_INVALID, checked.summary)
       const state = { ...planned.parameterState, originRevision: context.originRevision }
-      const outcome = await this._applyScenePatch(patch, { ...options, recipeParameters: state, verifyNativeSource })
+      const outcome = await this._applyScenePatch(patch, { ...options, recipeParameters: state, verifyNativeSource, cameraFraming: planned.cameraFraming })
       const committed = readRecipeContext(this.store, request.projectId, outcome.revision.revision)
       if (!committed?.state) throw new BlenderError('RECIPE_LOCK_INVALID', 'The recorded outcome has no recipe parameter state')
       return { ...outcome, parameterState: committed.state, preservedCameraIds: planned.preservedCameraIds }
@@ -481,6 +482,7 @@ export class RevisionTransaction {
       kind: 'scene_patch',
       recipeParameters: options.recipeParameters ?? null,
       verifyNativeSource: options.verifyNativeSource,
+      cameraFraming: options.cameraFraming,
       summary,
       actor: patch.actor ?? null,
       stage: patch.stage ?? null,
@@ -611,21 +613,51 @@ export class RevisionTransaction {
       try {
         const featureCheck = assertRuntimeSceneFeatures(this.runtime, plan.spec, { signal: plan.signal })
         if (featureCheck) await featureCheck
-        const run = await this.runtime.compileScene({
-          sceneSpecPath: specPath,
-          profile: plan.spec.renderProfiles?.preview === undefined ? undefined : 'preview',
-          projectRoot: this.store.projectDirectory(projectId),
-          jobId,
-          signal: plan.signal,
-          onWorkingDirectory: info => {
-            const produced = join(info.directory, 'result.blend')
-            if (isFile(produced)) {
-              // Same filesystem (both are inside the project's staging tree), so
-              // this rename is atomic and cannot half-copy a large file.
-              renameSync(produced, checkpointStaging)
-            }
-          },
-        })
+        const compile = async () => {
+          writeFileAtomic(specPath, sceneSpecCanonicalText(plan.spec))
+          return this.runtime.compileScene({
+            sceneSpecPath: specPath,
+            cameraFraming: plan.cameraFraming,
+            // Automatic framing compiles in isolation, preserving any live editor scene.
+            session: plan.cameraFraming ? false : undefined,
+            profile: plan.spec.renderProfiles?.preview === undefined ? undefined : 'preview',
+            projectRoot: this.store.projectDirectory(projectId),
+            jobId,
+            signal: plan.signal,
+            onWorkingDirectory: info => {
+              const produced = join(info.directory, 'result.blend')
+              if (isFile(produced)) {
+                // Same filesystem (both are inside the project's staging tree), so
+                // this rename is atomic and cannot half-copy a large file.
+                renameSync(produced, checkpointStaging)
+              }
+            },
+          })
+        }
+        let run = await compile()
+        if (plan.cameraFraming) {
+          const initialFit = fitCupHeroFromNative(plan.spec, run.report, plan.cameraFraming)
+          if (initialFit.backoffM > 0) {
+            for (const entry of run.envelope.warnings ?? []) warnings.push(entry)
+            for (const entry of run.envelope.notices ?? []) warnings.push(warning(BlenderWarningCode.SCENE_COMPILER_DECISION, entry.message, { code: entry.code, framingStage: 'before-correction' }))
+            const correction = { op: 'camera.update', cameraId: initialFit.cameraId, transform: { location: initialFit.location } }
+            const corrected = applyPatchToSpec(plan.spec, { projectId, baseRevision: plan.baseRevision, operations: [correction] })
+            plan.spec = compileSceneSpec(corrected.spec).spec
+            const validation = validateSceneSpec(plan.spec)
+            if (!validation.ok) throw new BlenderError(BlenderErrorCode.SCENE_SPEC_INVALID, validation.summary)
+            plan.operations = [...plan.operations, correction]
+            plan.operationRecords = [...plan.operationRecords, ...corrected.operations]
+            plan.digestAfter = sceneSpecDigest(plan.spec)
+            plan.specHashAfter = specHash(plan.spec)
+            run = await compile()
+          }
+          const finalFit = fitCupHeroFromNative(plan.spec, run.report, plan.cameraFraming)
+          if (finalFit.backoffM !== 0) throw new BlenderError(BlenderErrorCode.SCENE_VALIDATION_FAILED, 'The recompiled hero still needs a framing correction; no revision was published')
+          plan.cameraFramingReceipt = { ...finalFit, appliedBackoffM: initialFit.backoffM, beforeCameraLocation: initialFit.cameraLocation }
+          plan.recipeParameters.cupCameraRig = { schemaVersion: 'deepblend.cup-camera-rig/v1',
+            anchor: structuredClone(plan.spec.entities.find(entity => entity.id === 'cup').transform),
+            camera: structuredClone(plan.spec.cameras.find(camera => camera.id === 'hero')) }
+        }
         compileReport = run.report
         technical = run.report?.validation ?? null
         for (const entry of run.envelope.warnings ?? []) warnings.push(entry)
@@ -809,6 +841,7 @@ export class RevisionTransaction {
         animatedObjects: technical.animatedObjects ?? null,
         cameraParameters: technical.cameraParameters ?? null,
       },
+      ...(plan.cameraFramingReceipt ? { cameraFraming: plan.cameraFramingReceipt } : {}),
       renderConfig: compileReport?.renderConfig ?? null,
       sceneFingerprint: compileReport?.sceneFingerprint ?? null,
       assetParts: (compileReport?.objects ?? [])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-host",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "DeepBlend Host service: the blenderStudio business facade over the BlenderRuntime seam.",
   "main": "lib/index.js",
@@ -20,7 +20,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.12.0",
+    "@deepblend/dsh-blender-contracts": "0.14.0",
     "sharp": "0.35.5"
   },
   "license": "MIT",