Message APINPM Package/docs/components/measurement/visibility

Annotation Visibility

Change visibility for one or more annotations and measurements using the SDK.

Overview

Use viewer.annotations.show(...), viewer.annotations.hide(...), and viewer.annotations.setVisibility(...) to change visibility for one or more annotations.

Visibility commands are available after the viewer is mounted, Canvas is ready, and a document is open.

typescript
import { createViewer } from "@rasterex/viewer";

const viewer = createViewer({
  container: "#viewer"
});

await viewer.mount();
await viewer.ready();

await viewer.documents.open({
  url: "https://files.example.com/sample.pdf",
  displayName: "Sample PDF.pdf"
});
Overview

Visibility Commands

Perform visibility modification actions programmatically:

  • show(...) is shorthand for setVisibility({ visible: true }).
  • hide(...) is shorthand for setVisibility({ visible: false }).
typescript
// Hide multiple annotations
await viewer.annotations.hide({
  annotationIds: ["annotation-guid-1", "annotation-guid-2"]
});

// Show an annotation
await viewer.annotations.show({
  annotationIds: ["annotation-guid-1"]
});

// Set visibility using explicit boolean value
await viewer.annotations.setVisibility({
  annotationIds: ["annotation-guid-1"],
  visible: false
});
Visibility Commands

Result Shape

Visibility operations resolve asynchronously with status properties:

  • updatedCount is the number of annotations Canvas updated.
  • missingAnnotationIds lists requested IDs Canvas could not find.
typescript
type AnnotationVisibilityResult = {
  success: boolean;
  visible: boolean;
  annotationIds: string[];
  updatedCount: number;
  missingAnnotationIds: string[];
  requestId: string;
  error?: "missing_annotation_ids" | "annotations_not_found" | string;
};
Result Shape

Vanilla Example

Complete integration code setup for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<div>
  <button type="button" id="hide-selected">Hide Selected</button>
  <button type="button" id="show-selected">Show Selected</button>
</div>
<p id="status"></p>
Vanilla Example

React Integration

Complete React Component implementation details:

tsx
import { useEffect, useRef, useState } from "react";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";

export function AnnotationVisibility() {
  const hostRef = useRef<HTMLDivElement | null>(null);
  const viewerRef = useRef<RasterexViewer | null>(null);
  const [selectedIds, setSelectedIds] = useState<string[]>([]);
  const [status, setStatus] = useState("Loading viewer");

  useEffect(() => {
    let disposed = false;
    const viewer = createViewer({ container: hostRef.current! });
    viewerRef.current = viewer;

    const stopSelected = viewer.annotations.on("selected", (event) => {
      if (!disposed) {
        setSelectedIds((ids) => [...new Set([...ids, event.guid])]);
        setStatus(`Selected ${event.guid}`);
      }
    });

    async function start() {
      await viewer.mount();
      await viewer.ready();
      await viewer.documents.open({
        url: "https://files.example.com/sample.pdf",
        displayName: "Sample PDF.pdf"
      });
      if (!disposed) setStatus("Ready");
    }

    void start().catch((error) => {
      if (!disposed) setStatus(error instanceof Error ? error.message : "Viewer failed");
    });

    return () => {
      disposed = true;
      stopSelected();
      viewer.destroy();
      viewerRef.current = null;
    };
  }, []);

  async function setSelectedVisible(visible: boolean) {
    if (selectedIds.length === 0) {
      setStatus("Select annotations first");
      return;
    }

    const result = await viewerRef.current?.annotations.setVisibility({
      annotationIds: selectedIds,
      visible
    });

    setStatus(
      `${result?.updatedCount ?? 0} updated, ${result?.missingAnnotationIds.length ?? 0} missing`
    );
  }

  return (
    <section>
      <div ref={hostRef} style={{ height: 640 }} />
      <button type="button" onClick={() => void setSelectedVisible(false)}>
        Hide Selected
      </button>
      <button type="button" onClick={() => void setSelectedVisible(true)}>
        Show Selected
      </button>
      <p>{status}</p>
    </section>
  );
}
React Integration

Canvas Broker Mapping

Broker message mapping for visibility APIs:

  • viewer.annotations.show(...) maps to annotationVisibility / annotationVisibilityChanged.
  • viewer.annotations.hide(...) maps to annotationVisibility / annotationVisibilityChanged.
  • viewer.annotations.setVisibility(...) maps to annotationVisibility / annotationVisibilityChanged.