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