@deepblend/dsh-blender-tool 0.20.0 → 0.22.0

package/lib/tools.js

@@ -125,18 +125,82 @@ export function apply(ctx) {
   ctx.tools.register(sceneGet(ctx))
   ctx.tools.register(scenePatch(ctx))
   ctx.tools.register(placeOnSurface(ctx))
+  ctx.tools.register(cameraFit(ctx))
   ctx.tools.register(previewRender(ctx))
   ctx.tools.register(sceneValidate(ctx))
   ctx.tools.register(revisionRestore(ctx))
   ctx.tools.register(assetIngest(ctx))
 }
 
+/** Fit complete evaluated meshes through the Host, keeping original photography. */
+function cameraFit(ctx) {
+  return defineTool({
+    name: 'blender_camera_fit',
+    description: 'Save a new static camera that frames all explicitly selected product meshes at one frame, with an editable Blender checkpoint and preview. ' +
+      'Read blender_scene_get first for the current baseRevision, entity IDs and source camera; for a supported complete recipe use every scene.assemblyPlacement.memberEntityIds entry, including the cable. ' +
+      'Pass an unused fittedCameraId. The source camera may be animated: its evaluated viewing direction and roll at frame are preserved in the static copy, together with its measured optics. ' +
+      'Original cameras, camera order, animation tracks, shots, entities, materials and lights are retained. Depth of field focuses the new view at the selected product’s bounds center depth. ' +
+      'The Host measures actual whole evaluated mesh sets and independently checks the compiled candidate’s frame margin and clipping before publication. ' +
+      'Select 1–64 distinct generated entities or whole asset instances, within 128 mesh objects, two million evaluated vertices and two million polygons in total. Supports perspective cameras and matching viewport/render geometry; unsupported or hidden geometry is refused. ' +
+      'margin is a fraction of each image edge (default 0.03). Evidence applies to this frame and the saved checkpoint’s preview render aspect; a different delivery aspect needs its own check. ' +
+      'This proves framing and clipping of the selected vertices, not visibility through other objects, artistic quality, shader displacement, transparency or an animation range. ' +
+      'Always saves one checkpoint; renderPreview defaults to true. Resolve returned relative artifact paths against projectDirectory. ' +
+      'Reuse one idempotencyKey only for an identical request; a successful retry returns its earlier fitted view without creating another camera.',
+    parameters: {
+      projectId: { type: 'string', required: true, description: 'The existing project.' },
+      baseRevision: { type: 'string', required: true, description: 'Current revision from blender_scene_get. A new stale request is refused.' },
+      entityIds: { type: 'array', items: { type: 'string' }, required: true, description: '1–64 distinct complete mesh entity or asset-instance IDs. Include every part of the product; do not include an unrelated floor or support.' },
+      cameraId: { type: 'string', required: true, description: 'Existing perspective camera whose evaluated viewing direction, roll and optics should be retained.' },
+      fittedCameraId: { type: 'string', required: true, description: 'Unused ID for the new static fitted camera. Existing cameras are preserved.' },
+      frame: { type: 'integer', required: true, description: 'Explicit integer frame from 0 to 1000000 to evaluate, fit, verify and preview.' },
+      margin: { type: 'number', description: 'Fractional margin at each image edge, 0–0.25; default 0.03. The Host validates this range.' },
+      renderPreview: { type: 'boolean', description: 'Attach the committed fitted view’s preview, default true. False still saves the checkpoint.' },
+      idempotencyKey: { type: 'string', description: 'Unique logical fit request. Reuse only for an identical retry, including its original baseRevision.' },
+    },
+    output: TOOL_OUTPUT_WITH_IMAGE,
+    async execute(args, exec) {
+      const resolved = resolveStudio(ctx)
+      if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
+      try {
+        if (resolved.studio.cameraFitSupported !== true || typeof resolved.studio.fitCamera !== 'function') {
+          throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE,
+            'This Host cannot save verified fitted views. Update the DeepBlend Host bundle and restart the profile before retrying.')
+        }
+        const { projectId, baseRevision, entityIds, cameraId, fittedCameraId, frame, margin, renderPreview, idempotencyKey, ...extra } = args
+        const { data, canonicalWarnings } = await canonicalCall(resolved.studio.fitCamera({
+          ...extra, projectId, baseRevision, entityIds, cameraId, fittedCameraId, frame,
+          ...(margin === undefined ? {} : { margin }),
+          ...(renderPreview === undefined ? {} : { renderPreview }),
+          ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+          signal: exec?.signal,
+        }), warning)
+        const value = { ok: true,
+          text: renderSuccess(`${data.idempotentReplay === true ? 'Reused' : 'Saved'} fitted view "${data.cameraFitReceipt?.fittedCameraId ?? args.fittedCameraId}" in revision ${data.revision}.`, data,
+            { warnings: [...(data.warnings ?? []), ...canonicalWarnings] }), data }
+        return args.renderPreview !== false
+          ? await attachCommittedPreview(ctx, exec, resolved, value, { projectId: args.projectId, summary: data }) : value
+      } catch (cause) {
+        const failure = renderFailure(cause, 'CAMERA_FIT_FAILED')
+        if (failure.data.errorCode === BlenderErrorCode.REVISION_CONFLICT) {
+          failure.text += '\n\nRead blender_scene_get again, then retry blender_camera_fit with the new baseRevision and an unused fittedCameraId.'
+        }
+        return { ok: false, ...failure }
+      }
+    },
+    presentCall: args => ({ card: 'generic', title: `Save complete view "${args?.fittedCameraId ?? ''}"`,
+      kind: 'edit', projectId: args?.projectId }),
+  })
+}
+
 /** A measured placement is committed by the Host, not guessed as a transform patch. */
 function placeOnSurface(ctx) {
   return defineTool({
     name: 'blender_place_on_surface',
-    description: 'Place a saved entity above a chosen support using their actual evaluated meshes, then save an editable Blender revision and preview. ' +
-      'Moves only the subject’s world Z; keeps its XY, rotation and scale. Supports generated meshes and whole imported asset instances, including sloped supports. ' +
+    description: 'Place a saved entity or a complete saved lamp above a chosen support using actual evaluated meshes, then save one editable Blender revision and preview. ' +
+      'Default entity scope moves only the selected subject’s world Z and keeps its XY, rotation and scale; supports generated meshes and whole imported asset instances. ' +
+      'For the complete pinned metal-lamp2.2 assembly, use scope="recipe-assembly" and the subjectEntityId returned in scene.assemblyPlacement. ' +
+      'This moves every lamp member, including the cable: optional pose applies relative world translation in mm and upright yaw in degrees, then the complete native mesh union settles vertically onto the selected support. ' +
+      'pose.pivotMm defaults to the saved base origin; translation is applied after rotation. All camera/light settings are retained; after a large move use blender_camera_fit to save a complete fitted view or explicitly edit photography. ' +
       'Read blender_scene_get first and pass its current baseRevision, both entity IDs and an explicit frame. ' +
       'clearanceMm is a vertical gap, not distance along a surface normal. Requires static geometry without related cross-entity geometry dependencies. ' +
       'The receipt describes this selected pair at that frame; it does not certify physical stability, collisions with other objects or the movement path. ' +
@@ -146,6 +210,13 @@ function placeOnSurface(ctx) {
       projectId: { type: 'string', required: true, description: 'The existing project.' },
       baseRevision: { type: 'string', required: true, description: 'Current revision returned by blender_scene_get. Stale revisions are refused.' },
       subjectEntityId: { type: 'string', required: true, description: 'Entity to move vertically; use the whole entity ID for an imported asset instance.' },
+      scope: { type: 'string', enum: ['entity', 'recipe-assembly'], description: 'Default entity preserves existing single-entity semantics. recipe-assembly explicitly selects every member of the supported saved complete metal lamp2.2.' },
+      pose: { type: 'object', additionalProperties: false, description: 'For recipe-assembly only. Apply a relative world pose first, then settle the complete lamp in world Z; no scale or tilt.',
+        properties: {
+          translationMm: { type: 'array', items: { type: 'number' }, description: 'Relative world [dx,dy,dz] in mm, exactly3 finite numbers within ±1000000. Default[0,0,0]. The provisional Z is adjusted by surface settling.' },
+          yawDegrees: { type: 'number', description: 'Relative rotation about world Z in degrees, ±360; default0. Positive is counter-clockwise viewed from above.' },
+          pivotMm: { type: 'array', items: { type: 'number' }, description: 'World [x,y,z] rotation pivot in mm, exactly3 finite numbers within ±1000000. Default is the current saved base origin. Rotate first, then translate.' },
+        } },
       supportEntityId: { type: 'string', required: true, description: 'Different entity whose evaluated surface should support the subject.' },
       frame: { type: 'integer', required: true, description: 'Explicit frame to measure and verify, from 0 to 1000000. The Host enforces this range.' },
       clearanceMm: { type: 'number', description: 'Required vertical gap in millimetres, 0–1000; defaults to 0. The Host enforces this range.' },
@@ -162,10 +233,16 @@ function placeOnSurface(ctx) {
           throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE,
             'This Host cannot perform measured surface placement. Update the DeepBlend Host bundle and restart the profile before retrying.')
         }
+        if (args.scope === 'recipe-assembly' && resolved.studio.assemblyPlacementSupported !== true) {
+          throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE,
+            'This Host cannot place the complete lamp assembly. Update the DeepBlend Host bundle and restart the profile before retrying.')
+        }
         const { data, canonicalWarnings } = await canonicalCall(resolved.studio.placeOnSurface({
           // Preserve unknown fields so the Host can reject them rather than silently changing the intent.
           ...args,
           projectId: args.projectId, baseRevision: args.baseRevision,
+          ...(args.scope === undefined ? {} : { scope: args.scope }),
+          ...(args.pose === undefined ? {} : { pose: args.pose }),
           subjectEntityId: args.subjectEntityId, supportEntityId: args.supportEntityId, frame: args.frame,
           clearanceMm: args.clearanceMm ?? 0, renderPreview: args.renderPreview ?? true,
           cameraId: args.cameraId, idempotencyKey: args.idempotencyKey, signal: exec?.signal,
@@ -186,7 +263,9 @@ function placeOnSurface(ctx) {
         return { ok: false, ...failure }
       }
     },
-    presentCall: args => ({ card: 'generic', title: `Place "${args?.subjectEntityId ?? ''}" on "${args?.supportEntityId ?? ''}"`,
+    presentCall: args => ({ card: 'generic', title: args?.scope === 'recipe-assembly'
+      ? `Place the complete lamp on "${args?.supportEntityId ?? ''}"`
+      : `Place "${args?.subjectEntityId ?? ''}" on "${args?.supportEntityId ?? ''}"`,
       kind: 'move', projectId: args?.projectId }),
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "Agent-preset tool consumer: registers the model-visible DeepBlend Blender tools. Publishes no service.",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.20.0"
+    "@deepblend/dsh-blender-contracts": "0.22.0"
   },
   "license": "MIT",
   "repository": {