@deepblend/dsh-blender-tool 0.11.0 → 0.12.0

package/lib/assembly-origins.js

@@ -0,0 +1,87 @@
+/** Endpoint origins from verified native reports; these are not surface clearances. */
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+
+const refuse = message => { throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, `Native assembly origins: ${message}`) }
+const finite = values => {
+  if (!values.every(Number.isFinite)) refuse('the derived origin/span values exceed the finite numeric range.')
+  return values
+}
+const subtract = (a, b) => finite(a.map((value, axis) => value - b[axis]))
+const subtractMm = (a, b) => finite(subtract(a, b).map(value => value * 1000))
+const identity = report => ({ projectId: report.projectId, revision: report.sourceRevision,
+  checkpointSha256: report.sourceCheckpointSha256, frame: report.frame })
+const limitations = [
+  'Offsets join evaluated native OBJECT ORIGINS in world XYZ axes, not surface points. They are not protrusion, contact, seating depth or clearance.',
+  'World-axis offsets and spans change under rotation; they are not intrinsic dimensions or anchor-local coordinates.',
+  'Only the selected parts, ordered pairs and explicit frame are measured. Unavailable parts have no numeric values, never zero.',
+  'No whole-assembly attachment, collision absence, minimum clearance, manufacturing tolerance or artistic approval is established.',
+]
+
+export function validateAssemblyPairs(pairs, entityIds) {
+  if (!Array.isArray(entityIds) || !Array.isArray(pairs) || pairs.length < 1 || pairs.length > 8) refuse('select 1–8 explicit ordered pairs within geometryEntityIds.')
+  const ids = new Set()
+  for (const pair of pairs) {
+    if (!pair || typeof pair !== 'object' || Array.isArray(pair) ||
+        Object.keys(pair).some(key => !['pairId', 'entityId', 'anchorEntityId'].includes(key)) ||
+        typeof pair.pairId !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(pair.pairId) || ids.has(pair.pairId) ||
+        !entityIds.includes(pair.entityId) || !entityIds.includes(pair.anchorEntityId) || pair.entityId === pair.anchorEntityId) {
+      refuse('each pair requires a distinct pairId and two different selected entity/anchor IDs; arbitrary fields are refused.')
+    }
+    ids.add(pair.pairId)
+  }
+}
+
+function origin(object) {
+  const matrix = object.worldMatrix
+  if (!Array.isArray(matrix) || matrix.length !== 4 || matrix.some(row => !Array.isArray(row) || row.length !== 4 || row.some(value => !Number.isFinite(value))) ||
+      matrix[3].some((value, axis) => value !== (axis === 3 ? 1 : 0))) refuse('the native world matrix is not finite affine geometry.')
+  return matrix.slice(0, 3).map(row => row[3])
+}
+
+export function readAssemblyOrigins(report, pairs) {
+  validateAssemblyPairs(pairs, report.objects.map(object => object.entityId))
+  const objects = new Map(report.objects.map(object => [object.entityId, object]))
+  return { schemaVersion: 'deepblend.assembly-origins/v1', source: identity(report), coordinateSystem: 'world',
+    pairs: pairs.map(pair => {
+      const entity = objects.get(pair.entityId), anchor = objects.get(pair.anchorEntityId)
+      if (!entity.available || !anchor.available) return { ...pair, status: 'unavailable',
+        unavailableParts: [entity, anchor].filter(object => !object.available).map(object => ({ entityId: object.entityId, reason: object.unavailableReason })) }
+      const entityOriginMeters = origin(entity), anchorOriginMeters = origin(anchor)
+      return { ...pair, status: 'measured', entityOriginMeters, anchorOriginMeters,
+        worldOriginOffsetMm: subtractMm(entityOriginMeters, anchorOriginMeters) }
+    }), limitations }
+}
+
+export function compareAssemblyOrigins(before, after) {
+  if (before.source.projectId !== after.source.projectId || before.source.frame !== after.source.frame || before.pairs.length !== after.pairs.length) refuse('comparison requires the same project, frame and ordered pairs.')
+  const pairs = after.pairs.map((current, index) => {
+    const reference = before.pairs[index]
+    if (['pairId', 'entityId', 'anchorEntityId'].some(key => reference[key] !== current[key])) refuse('comparison pair identities differ.')
+    return { pairId: current.pairId, entityId: current.entityId, anchorEntityId: current.anchorEntityId,
+      before: reference, after: current,
+      ...(reference.status === 'measured' && current.status === 'measured' ? { worldOriginOffsetChangeMm: subtract(current.worldOriginOffsetMm, reference.worldOriginOffsetMm) } : {}) }
+  })
+  return { schemaVersion: 'deepblend.assembly-origin-comparison/v1', referenceSource: before.source, currentSource: after.source,
+    pairs, comparedPairs: pairs.filter(pair => pair.worldOriginOffsetChangeMm !== undefined).length,
+    limitations: ['Changes are current minus reference; offset preservation does not establish surface contact or attachment correctness.', ...limitations] }
+}
+
+/** Inputs have already passed source/selection/frame and native report verification. */
+export function compareGeometryReports(reference, current) {
+  if (reference.projectId !== current.projectId || reference.frame !== current.frame || reference.objects.length !== current.objects.length) refuse('comparison requires the same project, frame and ordered entities.')
+  const objects = current.objects.map((after, index) => {
+    const before = reference.objects[index]
+    if (before.entityId !== after.entityId) refuse('comparison entity identities differ.')
+    const values = object => object.available ? { status: 'measured', worldAxisExtentMm: object.worldAxisExtentMm, worldOriginMeters: origin(object) } :
+      { status: 'unavailable', reason: object.unavailableReason }
+    const row = { entityId: after.entityId, before: values(before), after: values(after) }
+    if (before.available && after.available) {
+      row.worldAxisExtentChangeMm = subtract(after.worldAxisExtentMm, before.worldAxisExtentMm)
+      row.worldOriginChangeMm = subtractMm(row.after.worldOriginMeters, row.before.worldOriginMeters)
+    }
+    return row
+  })
+  return { schemaVersion: 'deepblend.geometry-comparison/v1', referenceInspection: reference, currentSource: identity(current), objects,
+    summary: { requestedEntities: objects.length, comparedEntities: objects.filter(object => object.worldAxisExtentChangeMm !== undefined).length },
+    limitations: ['Changes are current minus reference for the same selected native parts and frame; their cause is not established.', ...limitations] }
+}

package/lib/tools.js

@@ -54,6 +54,7 @@ import {
   resolveStudio,
 } from './shared.js'
 import { compareSurfaceReports } from './geometry-comparison.js'
+import { validateAssemblyPairs, readAssemblyOrigins, compareAssemblyOrigins, compareGeometryReports } from './assembly-origins.js'
 
 /** A short parameter description of a SceneSpec engine key. */
 const ENGINE_KEY_DESCRIPTION =
@@ -398,7 +399,7 @@ function sceneGet(ctx) {
       'Optional geometrySurfaceSamples measures 1–8 explicit local surface chords and pair separations on the same saved source. ' +
       'The chord runs from source entry to exit; separation runs from source EXIT to target entry and excludes that chord. ' +
       'Use geometryOnly:true for a compact verified measurement receipt without the scene catalogue. ' +
-      'When comparing revisions, add geometryCompareRevision with identical surface samples; the tool computes per-sample changes and maxima, including chord-only samples. ' +
+      'Add geometryAssemblyPairs to measure explicit ordered object-origin offsets in world XYZ, not surface clearances. When comparing revisions, geometryCompareRevision computes current-minus-reference native spans and origin moves; if surface samples are supplied, their existing local comparison is used. ' +
       'Choose outside world seeds and directions from the actual scene/bounds; missed or unsupported samples remain unavailable. ' +
       'Local samples do not prove full-surface minimum wall thickness, whole-assembly clearance, no collision or quality approval. ' +
       'ALWAYS use the revision this returns as `baseRevision` for your next blender_scene_patch.',
@@ -410,7 +411,13 @@ function sceneGet(ctx) {
       geometryFrame: { type: 'integer',
         description: 'Explicit integer frame from 0 to 1000000 for native geometry measurement. Use the frame of the preview being checked. Requires geometryEntityIds.' },
       geometryOnly: { type: 'boolean', description: 'Return only source identity and verified geometry evidence, without the scene catalogue. Requires geometryEntityIds and geometryFrame; cannot be combined with full:true. Ordinary reads keep their existing shape.' },
-      geometryCompareRevision: { type: 'string', description: 'Optional explicit reference revision (e.g. r0004). Requires geometrySurfaceSamples. Re-measures that saved source with identical parts, seeds and frame, and computes current-minus-reference changes and maxima for all comparable samples. Unavailable pairs remain unavailable. No global minima or change cause is established.' },
+      geometryCompareRevision: { type: 'string', description: 'Optional explicit reference revision (e.g. r0004). Requires geometryEntityIds and geometryFrame. Re-measures identical selected parts/frame and computes current-minus-reference native world-axis spans and origin moves. If geometrySurfaceSamples is supplied, compares those same local samples instead. Requested geometryAssemblyPairs also return origin-offset changes. Unavailable evidence stays unavailable; no clearance, global minima or change cause is established.' },
+      geometryAssemblyPairs: { type: 'array', description: 'Optional 1–8 ordered native object-origin pairs. Requires geometryEntityIds containing both ends and geometryFrame. Offsets use world XYZ in millimeters; they are not surface protrusion, contact, clearance or whole-assembly certification.',
+        items: { type: 'object', additionalProperties: false, properties: {
+          pairId: { type: 'string', required: true, description: 'Distinct letters/numbers/underscore/hyphen identifier (1–64 characters).' },
+          entityId: { type: 'string', required: true, description: 'Selected native mesh whose object origin is measured.' },
+          anchorEntityId: { type: 'string', required: true, description: 'Different selected mesh origin used as anchor; offset is entity minus anchor in world XYZ.' },
+        } } },
       geometrySurfaceSamples: { type: 'array', description: 'Optional 1–8 local surface samples. Requires geometryEntityIds including every source/target and geometryFrame. Numeric results are local evidence only.',
         items: { type: 'object', additionalProperties: false, properties: {
           sampleId: { type: 'string', required: true, description: 'Distinct short letters/numbers/underscore/hyphen identifier (1–64 characters).' },
@@ -444,9 +451,10 @@ function sceneGet(ctx) {
           throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Surface samples require geometryEntityIds and geometryFrame.')
         }
         if (args.geometryCompareRevision !== undefined && (typeof args.geometryCompareRevision !== 'string' ||
-            !/^r\d{4,}$/.test(args.geometryCompareRevision) || args.geometrySurfaceSamples === undefined)) {
-          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryCompareRevision requires an explicit saved revision and surface samples.')
+            !/^r\d{4,}$/.test(args.geometryCompareRevision) || args.geometryEntityIds === undefined)) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryCompareRevision requires an explicit saved revision, geometryEntityIds and geometryFrame.')
         }
+        if (args.geometryAssemblyPairs !== undefined) validateAssemblyPairs(args.geometryAssemblyPairs, args.geometryEntityIds)
         if (args.geometryEntityIds !== undefined) validateGeometrySelection({ entityIds: args.geometryEntityIds,
           frame: args.geometryFrame, checkpointSha256: '0'.repeat(64), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) })
         const { data, canonicalWarnings } = await canonicalCall(resolved.studio.getScene(args.projectId, {
@@ -474,16 +482,20 @@ function sceneGet(ctx) {
             checkpointSha256: data.geometryInspection.sourceCheckpointSha256, ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) })
         }
         verifyScene(data, args.revision)
+        if (args.geometryAssemblyPairs !== undefined) data.geometryAssemblyOrigins = readAssemblyOrigins(data.geometryInspection, args.geometryAssemblyPairs)
         if (args.geometryCompareRevision !== undefined) {
           const reference = await canonicalCall(resolved.studio.getScene(args.projectId, { revision: args.geometryCompareRevision,
-            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame, surfaceSamples: args.geometrySurfaceSamples }, signal: exec?.signal }), warning)
+            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame, ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) }, signal: exec?.signal }), warning)
           verifyScene(reference.data, args.geometryCompareRevision)
           canonicalWarnings.push(...reference.canonicalWarnings)
-          data.geometryComparison = compareSurfaceReports(reference.data.geometryInspection, data.geometryInspection)
+          data.geometryComparison = hasSamples ? compareSurfaceReports(reference.data.geometryInspection, data.geometryInspection) : compareGeometryReports(reference.data.geometryInspection, data.geometryInspection)
+          if (args.geometryAssemblyPairs !== undefined) data.geometryComparison.assemblyOriginComparison = compareAssemblyOrigins(
+            readAssemblyOrigins(reference.data.geometryInspection, args.geometryAssemblyPairs), data.geometryAssemblyOrigins)
         }
         if (args.geometryOnly === true) {
           const receipt = { projectId: args.projectId, revision: data.revision, digest: data.digest,
             isCurrent: data.isCurrent, geometryInspection: data.geometryInspection,
+            ...(data.geometryAssemblyOrigins ? { geometryAssemblyOrigins: data.geometryAssemblyOrigins } : {}),
             ...(data.geometryComparison ? { geometryComparison: data.geometryComparison } : {}) }
           return { ok: true, text: renderSuccess(`Saved native measurement receipt for "${args.projectId}" at ${data.revision}.`, receipt,
             { warnings: canonicalWarnings, compact: true }), data: receipt }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.11.0",
+  "version": "0.12.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.11.0"
+    "@deepblend/dsh-blender-contracts": "0.12.0"
   },
   "license": "MIT",
   "repository": {