Annotation Visibility

Use `annotationVisibility` when the host needs to show or hide one or more existing measurements or annotations by GUID.

The command is request-driven: the host sends `annotationVisibility`, then the canvas responds with `annotationVisibilityChanged` so the host can confirm which IDs were updated.

• The broker only accepts this message from `window.parent`.
• `annotationIds` must be an array of GUID strings. A single string is not accepted.
• `visible: true` shows annotations and `visible: false` hides annotations. If `visible` is omitted, the canvas defaults it to `true`.
• `requestId` is optional and is echoed back in the response.

Send the request to the canvas iframe with event type `annotationVisibility`.

const iframe = document.querySelector('[data-viewer-iframe]');

iframe.contentWindow?.postMessage(
  {
    type: 'annotationVisibility',
    payload: {
      visible: false,
      annotationIds: [
        '5BD72F1C-0C05-4467-BD75-C6FE7C8121BB'
      ],
      requestId: 'optional-client-request-id'
    }
  },
  viewerOrigin
);

The payload identifies the target annotations and the visibility value to apply.

• `visible` (`boolean`, optional): `true` shows annotations and `false` hides annotations. Defaults to `true` if omitted.
• `annotationIds` (`string[]`, required): Annotation GUIDs or UniqueIDs to update. Must be an array.
• `requestId` (`string`, optional): Client request identifier echoed back in the response.

type AnnotationVisibilityRequest = {
  type: 'annotationVisibility';
  payload: {
    visible?: boolean;
    annotationIds: string[];
    requestId?: string;
  };
};

After applying the request, the canvas posts `annotationVisibilityChanged` back to the parent.

iframe.contentWindow?.postMessage({
  type: 'annotationVisibility',
  payload: {
    visible: false,
    annotationIds: ['5BD72F1C-0C05-4467-BD75-C6FE7C8121BB'],
    requestId: 'hide-annotation-1'
  }
}, viewerOrigin);

{
  type: 'annotationVisibilityChanged',
  payload: {
    success: true,
    visible: false,
    annotationIds: [
      '5BD72F1C-0C05-4467-BD75-C6FE7C8121BB'
    ],
    updatedCount: 1,
    missingAnnotationIds: [],
    requestId: 'hide-annotation-1'
  }
}

`success` is `true` only when every requested annotation is found and updated. Partial success is possible: found annotations are updated, missing annotations are returned in `missingAnnotationIds`, and `success` becomes `false`.

• `success` (`boolean`): `true` only when every requested annotation was found and updated.
• `visible` (`boolean`): The visibility value applied.
• `annotationIds` (`string[]`): IDs that were successfully updated.
• `updatedCount` (`number`): Count of updated annotations.
• `missingAnnotationIds` (`string[]`): IDs that were not found or failed to update.
• `requestId` (`string`, optional): Echo from the request.
• `error` (`string`, optional): Possible values are `missing_annotation_ids` and `annotations_not_found`.

type AnnotationVisibilityChangedPayload = {
  success: boolean;
  visible: boolean;
  annotationIds: string[];
  updatedCount: number;
  missingAnnotationIds: string[];
  requestId?: string;
  error?: 'missing_annotation_ids' | 'annotations_not_found';
};

The canvas normalizes and resolves annotation IDs before applying the display state.

• Event type must be `annotationVisibility`.
• Annotation IDs are normalized by trimming whitespace, removing `{}` braces, and uppercasing.
• Duplicate IDs are ignored.
• Each annotation is resolved by `RXCore.getMarkupObjByGUID`, `RXCore.getmarkupobjByGUID`, or a fallback GUI markup list lookup.
• Visibility is applied with `markup.setdisplay(visible)`.
• If at least one annotation changes, the canvas redraws with `RXCore.markUpRedraw()`.

Use the same request shape for show and hide actions. Only the `visible` value changes.

iframe.contentWindow?.postMessage({
  type: 'annotationVisibility',
  payload: {
    visible: true,
    annotationIds: ['5BD72F1C-0C05-4467-BD75-C6FE7C8121BB'],
    requestId: 'show-annotation-1'
  }
}, viewerOrigin);

iframe.contentWindow?.postMessage({
  type: 'annotationVisibility',
  payload: {
    visible: false,
    annotationIds: ['5BD72F1C-0C05-4467-BD75-C6FE7C8121BB'],
    requestId: 'hide-annotation-1'
  }
}, viewerOrigin);

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'annotationVisibilityChanged') return;

  const {
    success,
    visible,
    annotationIds,
    missingAnnotationIds,
    requestId,
    error
  } = event.data.payload;

  console.log('annotationVisibilityChanged', {
    success,
    visible,
    annotationIds,
    missingAnnotationIds,
    requestId,
    error
  });
});

Continue with related measurement workflows and API references.

• Selection: Select Measurement
• Delete: Delete Measurement
• Data Extraction: Data Extraction
• Technical: API Reference