Rasterex API/docs/components/3d/tools

3D Tools

Tool-by-tool examples for controlling 3D model behavior from the host application.

Command Pattern

3D tools are sent as direct canvas messages. The command is the message `type`, and the payload contains the tool state.

Use `requestId` on every command. The canvas returns a result event with the same request id when the command completes.

Send `type: "set3DTransparency"`, not `type: "toolControl"`.
Use `enabled: true` to activate a toggle tool.
Use `enabled: false` to deactivate a toggle tool.
Listen for the matching `...Result` event before treating the host UI state as confirmed.

const requestId = '3d-command-' + Date.now();

iframe.contentWindow.postMessage({
  type: 'set3DTransparency',
  payload: {
    requestId,
    enabled: true,
    valuePercent: 50
  }
}, viewerOrigin);

Command Pattern

Reset 3D Model

Use `reset3DModel` to restore the model to its default 3D state. This is a one-shot command, so it does not need `enabled`.

Send reset3DModel

iframe.contentWindow.postMessage({
  type: 'reset3DModel',
  payload: {
    requestId: 'reset-3d-model-1'
  }
}, viewerOrigin);

Expected result

{
  type: 'reset3DModelResult',
  payload: {
    requestId: 'reset-3d-model-1',
    success: true
  }
}

3D Select

Use `set3DSelect` when the host needs the user to select model parts. Add `emitSelectionEvents: true` to receive part selection events.

Enable part selection

iframe.contentWindow.postMessage({
  type: 'set3DSelect',
  payload: {
    requestId: 'select-parts-1',
    enabled: true,
    emitSelectionEvents: true
  }
}, viewerOrigin);

Listen for selected parts

window.addEventListener('message', (event) => {
  if (event.origin !== viewerOrigin) return;

  if (event.data?.type === 'threeDPartSelected') {
    console.log('Selected 3D part', event.data.payload);
  }

  if (event.data?.type === 'threeDPartSelectionCleared') {
    console.log('3D part selection cleared');
  }
});

Walkthrough & Hide Parts

Use walkthrough for model navigation mode. Use hide-parts mode when the user needs to select and hide parts from the model view.

Enable walkthrough

iframe.contentWindow.postMessage({
  type: 'set3DWalkthrough',
  payload: {
    requestId: 'walkthrough-on-1',
    enabled: true
  }
}, viewerOrigin);

Enable hide-parts mode

iframe.contentWindow.postMessage({
  type: 'set3DHidePartsMode',
  payload: {
    requestId: 'hide-parts-1',
    enabled: true
  }
}, viewerOrigin);

Explode

Use `set3DExplode` to separate model parts visually. Send `distance` from 0 to 100. In the built-in UI, explode and transparency are treated as conflicting visual modes.

Set explode distance

iframe.contentWindow.postMessage({
  type: 'set3DExplode',
  payload: {
    requestId: 'explode-50',
    enabled: true,
    distance: 50
  }
}, viewerOrigin);

Transparency

Use `set3DTransparency` to make model parts transparent. Send `valuePercent` from 0 to 100.

`0` means no transparency effect.
`100` means maximum transparency effect.

Set model transparency

iframe.contentWindow.postMessage({
  type: 'set3DTransparency',
  payload: {
    requestId: 'transparency-50',
    enabled: true,
    valuePercent: 50
  }
}, viewerOrigin);

Cross Section

Use `set3DCrossSection` to clip the model along the X, Y, and Z axes. Send `x`, `y`, and `z` values from 0 to 100.

Set cross-section planes

iframe.contentWindow.postMessage({
  type: 'set3DCrossSection',
  payload: {
    requestId: 'cross-section-midpoint',
    enabled: true,
    x: 50,
    y: 50,
    z: 50
  }
}, viewerOrigin);

Result Listener

Use one listener for all 3D result events. This keeps host UI state synchronized with what the canvas actually accepted.

const threeDResultTypes = new Set([
  'reset3DModelResult',
  'set3DSelectResult',
  'set3DWalkthroughResult',
  'set3DHidePartsModeResult',
  'set3DExplodeResult',
  'set3DTransparencyResult',
  'set3DCrossSectionResult'
]);

window.addEventListener('message', (event) => {
  if (event.origin !== viewerOrigin) return;
  if (!threeDResultTypes.has(event.data?.type)) return;

  const { requestId, success, enabled, error } = event.data.payload ?? {};
  console.log('3D tool result', {
    type: event.data.type,
    requestId,
    success,
    enabled,
    error
  });
});

Result Listener