@vgai/editor-sdk 0.5.0 → 0.5.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.0"
+    "@vgai/sdk": "0.5.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/client.ts

@@ -1,15 +1,18 @@
 import type { GenerationJobsDocument } from '@vgai/sdk/generations';
 import type {
   ActiveDocumentCapture,
+  AssetCompareCapture,
+  AssetCompareOptions,
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
+  AssetPreviewShotSetDefinition,
   AssetPreviewSource,
   EditorState,
   EditorView,
   GameCapture,
   HelperVisibility,
-  HumanoidShotSetCapture,
+  LabeledShotSetCapture,
   PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
@@ -188,23 +191,25 @@ export class EditorClient {
   }
 
   /**
-   * B7.6 — the canonical humanoid verify shot set (`vgai asset-preview
-   * --shots humanoid`): four turntable angles, tight zooms on the
-   * historical seam sites (head/hands/feet/shoulder), and a deep-bend pose
-   * pair, all framed by the editor from the loaded GLB's OWN skeleton — see
-   * `packages/editor/src/asset-preview.ts`'s `captureHumanoidShotSetAssetPreview`.
-   * Throws (via `command`'s `{ok:false}` unwrap) with a clear message naming
-   * the missing joint(s) when the asset has no Mixamo-named skeleton.
+   * A project-defined labeled shot set (`vgai asset-preview --shots <set>`):
+   * the DEFINITION travels with the command (project data — see
+   * `AssetPreviewShotSetDefinition`; the CLI resolves it from the registered
+   * `project.<set>.previewShots` tool), and the editor's generic
+   * capture engine renders it — see `packages/editor/src/asset-preview.ts`'s
+   * `captureShotSetAssetPreview`. Throws (via `command`'s `{ok:false}`
+   * unwrap) with a clear message naming the missing joint(s) when the asset
+   * lacks a bone the definition requires.
    */
-  async captureHumanoidShotSetPreview(
+  async captureShotSetPreview(
     source: AssetPreviewSource,
+    definition: AssetPreviewShotSetDefinition,
     options: AssetPreviewOptions = {},
-  ): Promise<HumanoidShotSetCapture> {
-    const data = await this.command<HumanoidShotSetCapture>({
+  ): Promise<LabeledShotSetCapture> {
+    const data = await this.command<LabeledShotSetCapture>({
       type: 'capture-asset-preview',
       ...source,
       ...options,
-      shots: 'humanoid',
+      shotSet: definition,
     });
     return {
       width: data.width,
@@ -214,6 +219,29 @@ export class EditorClient {
     };
   }
 
+  /**
+   * B8.4 — score the asset against a reference GLB (`vgai asset-preview
+   * --compare <ref.glb>`): matched orthographic front + side silhouettes
+   * (equal-height bounding-box framing, both yaw-normalized to face the
+   * camera), per-view IoU numbers, and overlay evidence images. The
+   * reference GLB's raw bytes travel base64 in the command; the editor
+   * renders and scores — the SDK never interprets Three.js assets itself.
+   */
+  async captureAssetComparePreview(
+    source: AssetPreviewSource,
+    refGlbBase64: string,
+    options: AssetCompareOptions = {},
+  ): Promise<AssetCompareCapture> {
+    const { refForward, ...dimensions } = options;
+    const data = await this.command<AssetCompareCapture>({
+      type: 'capture-asset-preview',
+      ...source,
+      ...dimensions,
+      compare: { glbBase64: refGlbBase64, ...(refForward ? { forward: refForward } : {}) },
+    });
+    return { width: data.width, height: data.height, views: data.views };
+  }
+
   // --- Panels ---
 
   async showViewport(tab: 'scene' | 'game'): Promise<void> {

package/src/index.ts

@@ -24,10 +24,14 @@ export type {
 } from './extension.js';
 export type {
   ActiveDocumentCapture,
+  AssetCompareCapture,
+  AssetCompareOptions,
+  AssetCompareView,
   AssetKind,
   AssetPreviewBackground,
   AssetPreviewCapture,
   AssetPreviewOptions,
+  AssetPreviewShotSetDefinition,
   AssetPreviewSource,
   AssetPreviewView,
   EditorCameraState,
@@ -37,8 +41,7 @@ export type {
   EditorViewDocument,
   GameCapture,
   HelperVisibility,
-  HumanoidShotLabel,
-  HumanoidShotSetCapture,
+  LabeledShotSetCapture,
   PresentedEditorView,
   ProjectInfo,
   ProjectTemplate,
@@ -48,10 +51,11 @@ export type {
   ProjectToolOutcome,
   RecentProject,
   ShadingMode,
+  ShotSetPoseRotation,
+  ShotSetShot,
   TransformMode,
   TransformSpace,
   Vec3Value,
   ViewPreset,
   ViewportCapture,
 } from './types.js';
-export { HUMANOID_SHOT_LABELS } from './types.js';

package/src/types.ts

@@ -89,29 +89,82 @@ export interface AssetPreviewCapture {
 }
 
 /**
- * B7.6 — the canonical humanoid verify shot set (`vgai asset-preview --shots
- * humanoid`): four turntable angles, tight zooms on the historical seam
- * sites (head/hands/feet/shoulder), and a deep-bend pose pair, all framed
- * from the loaded GLB's OWN skeleton (see `packages/editor/src/asset-preview.ts`).
+ * B8.4 — the asset-preview compare mode (`vgai asset-preview --compare
+ * <ref.glb>`): the asset and a caller-supplied reference GLB rendered with
+ * matched orthographic front + side framing (equal-height bounding-box
+ * normalization, both yaw-normalized to face the camera), scored by
+ * silhouette IoU with per-view overlay evidence (orange asset / cyan
+ * reference / near-white agreement). See
+ * `packages/editor/src/asset-compare.ts`.
  */
-export const HUMANOID_SHOT_LABELS = [
-  'front',
-  'back',
-  'left',
-  'right',
-  'zoom-head',
-  'zoom-hands',
-  'zoom-feet',
-  'zoom-shoulder',
-  'bend-front',
-  'bend-quarter',
-] as const;
-export type HumanoidShotLabel = (typeof HUMANOID_SHOT_LABELS)[number];
+export type AssetCompareView = 'front' | 'side';
 
-export interface HumanoidShotSetCapture {
+export interface AssetCompareOptions {
+  width?: number;
+  height?: number;
+  /** Override the reference GLB's ground-plane forward vector; defaults to
+   *  its `userData.forward` extras when present, else glTF's +Z. */
+  refForward?: [number, number, number];
+}
+
+export interface AssetCompareCapture {
+  width: number;
+  height: number;
+  views: Array<{
+    view: AssetCompareView;
+    /** Silhouette intersection-over-union in [0, 1]. */
+    iou: number;
+    overlay: ViewportCapture;
+    asset: ViewportCapture;
+    ref: ViewportCapture;
+  }>;
+}
+
+/**
+ * A project-defined labeled shot set (`vgai asset-preview --shots <set>`).
+ * The DEFINITION is project data: a registered project tool named
+ * `project.<set>.previewShots` returns it (installed capabilities register
+ * theirs — e.g. the humanoid capability contributes its canonical verify set),
+ * and the editor's generic capture engine renders it — turntable yaw angles
+ * and skeleton-anchored zoom crops, optionally under a named pose applied to
+ * a disposable snapshot (see `packages/editor/src/asset-preview.ts`).
+ */
+export interface ShotSetPoseRotation {
+  bone: string;
+  axis: 'x' | 'y' | 'z';
+  radians: number;
+}
+
+export type ShotSetShot =
+  | { label: string; view: 'turntable'; yaw: number; pose?: string | undefined }
+  | {
+      label: string;
+      view: 'bone-zoom';
+      bones: string[];
+      spanFraction: number;
+      pose?: string | undefined;
+    };
+
+export interface AssetPreviewShotSetDefinition {
+  /** The set's name (the CLI's `--shots <name>`), echoed in error messages. */
+  name: string;
+  /** Joints that must exist on the loaded GLB's OWN skeleton (zoom anchors
+   *  plus a loud failure naming the missing joints — never a silent
+   *  bounding-box fallback for a set that promised skeleton anchoring). */
+  requiredBones?: string[];
+  /** Optional clause appended to rig-requirement errors,
+   *  e.g. "a Mixamo-named humanoid skeleton". */
+  rigRequirementHint?: string;
+  /** Named poses (bone rotations applied to a disposable snapshot only);
+   *  shots opt in via their `pose` field. */
+  poses?: Record<string, ShotSetPoseRotation[]>;
+  shots: ShotSetShot[];
+}
+
+export interface LabeledShotSetCapture {
   width: number;
   height: number;
-  shots: Array<ViewportCapture & { label: HumanoidShotLabel }>;
+  shots: Array<ViewportCapture & { label: string }>;
   contactSheet: ViewportCapture & { width: number; height: number };
 }