API References

A 3D integration has three moving parts: the host sends a command, the canvas returns a result event, and some selection tools can emit part events.

• Host command: { type: "set3DExplode", payload: { requestId, enabled, distance } }
• Canvas result: { type: "set3DExplodeResult", payload: { requestId, success, enabled } }
• Selection event: { type: "threeDPartSelected", payload: { ...partData } }

3D commands are sent as direct postMessage types. All command payloads require requestId.

type ThreeDToolEventType =
  | 'setBirdEyeView'
  | 'reset3DModel'
  | 'set3DSelect'
  | 'set3DMarkupSelect'
  | 'set3DWalkthrough'
  | 'set3DHidePartsMode'
  | 'set3DExplode'
  | 'set3DTransparency'
  | 'set3DCrossSection';

type ThreeDToolMessage = {
  type: ThreeDToolEventType;
  payload: ThreeDToolPayload;
};

The payload type is shared, but each command uses only the fields that apply to that tool.

• requestId: Required. Unique command id supplied by the host.
• enabled: Optional. Turns toggle-style tools on or off.
• emitSelectionEvents: Optional. Used with set3DSelect when the host needs threeDPartSelected events.
• distance: Used by set3DExplode. Number from 0 to 100.
• valuePercent: Used by set3DTransparency. Number from 0 to 100.
• x / y / z: Used by set3DCrossSection. Each value is 0 to 100.

type ThreeDToolPayload = {
  requestId: string;
  enabled?: boolean;
  emitSelectionEvents?: boolean;
  distance?: number;
  valuePercent?: number;
  x?: number;
  y?: number;
  z?: number;
};

Use this mapping when building buttons, sliders, or host-side forms for 3D tools.

• reset3DModel: requestId
• set3DSelect: requestId, enabled, emitSelectionEvents
• set3DMarkupSelect: requestId, enabled
• set3DWalkthrough: requestId, enabled
• set3DHidePartsMode: requestId, enabled
• set3DExplode: requestId, enabled, distance
• set3DTransparency: requestId, enabled, valuePercent
• set3DCrossSection: requestId, enabled, x, y, z

Result event names are generated by appending Result to the command type. Use requestId to match the result to the command the host sent.

{
  type: 'set3DExplodeResult',
  payload: {
    requestId: 'explode-50',
    success: true,
    enabled: true
  }
}

type ThreeDToolResultEvent = {
  type: `${ThreeDToolEventType}Result`;
  payload: {
    requestId?: string;
    success?: boolean;
    enabled?: boolean;
    emitSelectionEvents?: boolean;
    error?: string;
    [key: string]: unknown;
  };
};

When set3DSelect is enabled with emitSelectionEvents, the canvas can emit selected and cleared events. The selected payload is intentionally open-ended because model metadata varies by source file.

type ThreeDPartSelectedEvent = {
  type: 'threeDPartSelected';
  payload: Record<string, unknown>;
};

type ThreeDPartSelectionClearedEvent = {
  type: 'threeDPartSelectionCleared';
  payload?: Record<string, unknown>;
};

The built-in toolbar uses internal action ids, but the host-facing API sends the direct message types shown below.

• RESET_3D_MODEL -> reset3DModel
• SET_3D_SELECT -> set3DSelect
• SET_3D_MARKUP_SELECT -> set3DMarkupSelect
• SET_3D_WALKTHROUGH -> set3DWalkthrough
• SET_3D_HIDE_PARTS_MODE -> set3DHidePartsMode
• SET_3D_EXPLODE -> set3DExplode
• SET_3D_TRANSPARENCY -> set3DTransparency
• SET_3D_CROSS_SECTION -> set3DCrossSection