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