Rasterex APINPM Package/docs/components/measurement/selection

Annotation Selection

Select an annotation in Canvas, and clear the current annotation selection using the SDK.

Overview

Use viewer.annotations.select(...) to select an annotation in Canvas, and viewer.annotations.unselect() to clear the current annotation selection.

Selection 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

Select and Unselect

Perform selection operations programmatically:

If both uniqueId and guid are provided, Canvas uses uniqueId first and falls back to guid.

typescript

// Select by GUID
viewer.annotations.select({
  guid: "annotation-guid"
});

// Select by Unique ID
viewer.annotations.select({
  uniqueId: "annotation-unique-id"
});

// Clear selection
viewer.annotations.unselect();

Select and Unselect

Listen For Selection Updates

Listen for user or host selection changes natively:

typescript

const stopSelected = viewer.annotations.on("selected", (event) => {
  console.log("Selected annotation:", event.guid);
});

viewer.annotations.select({
  guid: "annotation-guid"
});

Listen For Selection Updates

Vanilla Example

Complete integration code setup for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<input id="annotation-guid" placeholder="Annotation GUID" />
<button type="button" id="select-annotation">Select</button>
<button type="button" id="unselect-annotation">Unselect</button>
<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 AnnotationSelection() {
  const hostRef = useRef<HTMLDivElement | null>(null);
  const viewerRef = useRef<RasterexViewer | null>(null);
  const [guid, setGuid] = useState("");
  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) 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;
    };
  }, []);

  function selectAnnotation() {
    viewerRef.current?.annotations.select({ guid });
  }

  function unselectAnnotation() {
    viewerRef.current?.annotations.unselect();
    setStatus("Selection cleared");
  }

  return (
    <section>
      <div ref={hostRef} style={{ height: 640 }} />
      <input value={guid} onChange={(event) => setGuid(event.currentTarget.value)} />
      <button type="button" onClick={selectAnnotation}>Select</button>
      <button type="button" onClick={unselectAnnotation}>Unselect</button>
      <p>{status}</p>
    </section>
  );
}

React Integration

Canvas Broker Mapping

Broker message mapping for selection APIs:

viewer.annotations.select(...) maps to selectAnnotation.
viewer.annotations.unselect() maps to unselectAnnotation.
viewer.annotations.on("selected", ...) listens to annotationSelected.