@cornerstonejs/tools 0.56.1 → 0.56.3

package/src/stateManagement/annotation/annotationSelection.ts

@@ -0,0 +1,163 @@
+import { eventTarget, triggerEvent } from '@cornerstonejs/core';
+import { Events } from '../../enums';
+import { AnnotationSelectionChangeEventDetail } from '../../types/EventTypes';
+import { getAnnotation } from './annotationState';
+
+/*
+ * Constants
+ */
+
+const selectedAnnotationUIDs: Set<string> = new Set();
+
+/*
+ * Interface (Public API)
+ */
+
+/**
+ * Set a given annotationUID as selected or deselected based on the provided
+ * selected value.
+ *
+ * @param annotationUID - The annotation UID to be selected
+ * @param selected - When true, the annotation is selected. When false, the annotation is deselected.
+ * @param preserveSelected - When true, preserves existing
+ *  selections (i.e., the given annotation is appended to the selection set).
+ *  When false (the default behavior) the currently selected items are discarded
+ *  (i.e., the given annotation instance replaces the currently selected ones).
+ */
+function setAnnotationSelected(
+  annotationUID: string,
+  selected = true,
+  preserveSelected = false
+): void {
+  if (selected) {
+    selectAnnotation(annotationUID, preserveSelected);
+  } else {
+    deselectAnnotation(annotationUID);
+  }
+}
+
+/**
+ * Set a given annotation as selected.
+ *
+ * @param annotationUID - The annotation UID to be selected
+ * @param preserveSelected - When true, preserves existing
+ *  selections (i.e., the given annotation is appended to the selection set).
+ *  When false (the default behavior) the currently selected items are discarded
+ *  (i.e., the given annotation instance replaces the currently selected ones).
+ */
+function selectAnnotation(
+  annotationUID: string,
+  preserveSelected = false
+): void {
+  const detail = makeEventDetail();
+  if (!preserveSelected) {
+    clearSelectionSet(selectedAnnotationUIDs, detail);
+  }
+  if (annotationUID && !selectedAnnotationUIDs.has(annotationUID)) {
+    selectedAnnotationUIDs.add(annotationUID);
+    detail.added.push(annotationUID);
+  }
+  publish(detail, selectedAnnotationUIDs);
+}
+
+/**
+ * Deselect one or all annotations.
+ *
+ * @param annotationUID - If an annotation is provided that instance will be removed from
+ * the internal selection set. If none is given, ALL selections will be cleared.
+ */
+function deselectAnnotation(annotationUID?: string): void {
+  const detail = makeEventDetail();
+  if (annotationUID) {
+    if (selectedAnnotationUIDs.delete(annotationUID)) {
+      detail.removed.push(annotationUID);
+    }
+  } else {
+    clearSelectionSet(selectedAnnotationUIDs, detail);
+  }
+  publish(detail, selectedAnnotationUIDs);
+}
+
+/**
+ * Return an array of ALL the selected annotationUIDs
+ * @returns An array of Annotation UIDs
+ */
+function getAnnotationsSelected(): Array<string> {
+  return Array.from(selectedAnnotationUIDs);
+}
+
+/**
+ * Given a tool name, return ALL the annotationUIDs for that tool that are selected
+ * @param toolName - The name of the tool you want to get the selected annotation for
+ * @returns An array of annotationUIDs
+ */
+function getAnnotationsSelectedByToolName(toolName: string): Array<string> {
+  return getAnnotationsSelected().filter((annotationUID) => {
+    const annotation = getAnnotation(annotationUID);
+    return annotation.metadata.toolName === toolName;
+  });
+}
+
+/**
+ * Given an annotationUID, return true if it is selected, false
+ * otherwise.
+ * @param annotationUID - Annotation UID
+ * @returns A boolean value.
+ */
+function isAnnotationSelected(annotationUID: string): boolean {
+  return selectedAnnotationUIDs.has(annotationUID);
+}
+
+/**
+ * Return the number of the selected annotation
+ * @returns The size of the selected annotation set
+ */
+function getAnnotationsSelectedCount(): number {
+  return selectedAnnotationUIDs.size;
+}
+
+/*
+ * Private Helpers
+ */
+
+function makeEventDetail(): AnnotationSelectionChangeEventDetail {
+  return Object.freeze({
+    added: [],
+    removed: [],
+    selection: [],
+  });
+}
+
+function clearSelectionSet(
+  selectionSet: Set<string>,
+  detail: AnnotationSelectionChangeEventDetail
+): void {
+  selectionSet.forEach((value) => {
+    if (selectionSet.delete(value)) {
+      detail.removed.push(value);
+    }
+  });
+}
+
+function publish(
+  detail: AnnotationSelectionChangeEventDetail,
+  selectionSet: Set<string>
+) {
+  if (detail.added.length > 0 || detail.removed.length > 0) {
+    selectionSet.forEach((item) => void detail.selection.push(item));
+    triggerEvent(eventTarget, Events.ANNOTATION_SELECTION_CHANGE, detail);
+  }
+}
+
+/*
+ * Exports
+ */
+
+export {
+  setAnnotationSelected,
+  getAnnotationsSelected,
+  getAnnotationsSelectedByToolName,
+  getAnnotationsSelectedCount,
+  deselectAnnotation,
+  isAnnotationSelected,
+};

package/src/stateManagement/annotation/annotationState.ts

@@ -0,0 +1,180 @@
+import {
+  triggerEvent,
+  eventTarget,
+  utilities as csUtils,
+} from '@cornerstonejs/core';
+import { Events } from '../../enums';
+import { defaultFrameOfReferenceSpecificAnnotationManager } from './FrameOfReferenceSpecificAnnotationManager';
+import { Annotations, Annotation } from '../../types/AnnotationTypes';
+import { AnnotationRemovedEventDetail } from '../../types/EventTypes';
+import { AnnotationGroupSelector } from '../../types';
+import {
+  triggerAnnotationAddedForElement,
+  triggerAnnotationAddedForFOR,
+} from './helpers/state';
+
+// our default annotation manager
+let defaultManager = defaultFrameOfReferenceSpecificAnnotationManager;
+
+/**
+ * It returns the default annotations manager.
+ * @returns the singleton default annotations manager.
+ */
+function getAnnotationManager() {
+  return defaultManager;
+}
+
+/**
+ * Set the annotation manager to be used for rendering, adding, removing, etc.
+ * @param annotationManager - The annotation manager to be used
+ */
+function setAnnotationManager(annotationManager) {
+  defaultManager = annotationManager;
+}
+
+// set back to default frameOfReferenceSpecificAnnotationManager
+function resetAnnotationManager() {
+  defaultManager = defaultFrameOfReferenceSpecificAnnotationManager;
+}
+
+/**
+ * Returns the annotations for a given tool with the provided options that is
+ * used to filter annotations based on the annotation manager.
+ *
+ * In our default implementation, the options are the element and/or the FrameOfReferenceUID.
+ * Hence, the getAnnotations function will return the annotations for the given tool
+ * that are associated with the FrameOfReferenceUID.
+ *
+ * @param toolName - The name of the tool.
+ * @param annotationGroupSelector - element or FrameOfReferenceUID that is used
+ * to group annotations in the annotation manager.
+ * @returns The annotations corresponding to the Frame of Reference and the toolName.
+ */
+function getAnnotations(
+  toolName: string,
+  annotationGroupSelector: AnnotationGroupSelector
+): Annotations {
+  const manager = getAnnotationManager();
+  const groupKey = manager.getGroupKey(annotationGroupSelector);
+  return manager.getAnnotations(groupKey, toolName) as Annotations;
+}
+
+/**
+ * Add the annotation to the annotation manager along with the options that is
+ * used to filter the annotation manager and the annotation group that
+ * the annotation belongs to.
+ *
+ * As a result, our default implementation will add the annotation to the
+ * default manager using the FrameOfReferenceUID as the group key.
+ *
+ * @param annotation - The annotation that is being added to the annotations manager.
+ * @param annotationGroupSelector - element or FrameOfReferenceUID that is used
+ * to group annotations in the annotation manager.
+ */
+function addAnnotation(
+  annotation: Annotation,
+  annotationGroupSelector: AnnotationGroupSelector
+): string {
+  if (annotation.annotationUID === undefined) {
+    annotation.annotationUID = csUtils.uuidv4() as string;
+  }
+
+  const manager = getAnnotationManager();
+  const groupKey = manager.getGroupKey(annotationGroupSelector);
+
+  manager.addAnnotation(annotation, groupKey);
+
+  // if the annotation manager selector is an element, trigger the
+  // annotation added event for that element.
+  if (annotationGroupSelector instanceof HTMLDivElement) {
+    triggerAnnotationAddedForElement(annotation, annotationGroupSelector);
+  }
+
+  // if no element is provided, render all viewports that have the
+  // same frame of reference.
+  // Todo: we should do something else here for other types of annotation managers.
+  triggerAnnotationAddedForFOR(annotation);
+
+  return annotation.annotationUID;
+}
+
+/**
+ * Get the number of annotations for a given tool with the provided options that is
+ * used to filter annotations based on the annotation manager.
+ *
+ * In our default implementation, the options are the element and/or the FrameOfReferenceUID.
+ * Hence, the getNumberOfAnnotations function will return the number of annotations for the given tool
+ * that are associated with the FrameOfReferenceUID.
+ *
+ * @param toolName - The name of the tool
+ * @param annotationGroupSelector - element or FrameOfReferenceUID that is used
+ * to group annotations in the annotation manager.
+ *
+ */
+function getNumberOfAnnotations(
+  toolName: string,
+  annotationGroupSelector: AnnotationGroupSelector
+): number {
+  const manager = getAnnotationManager();
+  const groupKey = manager.getGroupKey(annotationGroupSelector);
+
+  return manager.getNumberOfAnnotations(groupKey, toolName);
+}
+
+/**
+ * Remove the annotation by UID of the annotation.
+ * @param annotationUID - The unique identifier for the annotation.
+ */
+function removeAnnotation(annotationUID: string): void {
+  const manager = getAnnotationManager();
+  const annotation = manager.getAnnotation(annotationUID);
+
+  // no need to continue in case there is no annotation.
+  if (!annotation) {
+    return;
+  }
+
+  manager.removeAnnotation(annotationUID);
+
+  // trigger annotation removed
+  const eventType = Events.ANNOTATION_REMOVED;
+
+  const eventDetail: AnnotationRemovedEventDetail = {
+    annotation,
+    annotationManagerUID: manager.uid,
+  };
+
+  triggerEvent(eventTarget, eventType, eventDetail);
+}
+
+/**
+ * Get the Annotation object by its UID
+ * @param annotationUID - The unique identifier of the annotation.
+ */
+function getAnnotation(annotationUID: string): Annotation {
+  const manager = getAnnotationManager();
+  const annotation = manager.getAnnotation(annotationUID);
+
+  return annotation;
+}
+
+/**
+ * It removes all annotations from the default annotation manager
+ */
+function removeAllAnnotations(): void {
+  const manager = getAnnotationManager();
+  manager.removeAllAnnotations();
+}
+
+export {
+  getAnnotations,
+  getNumberOfAnnotations,
+  addAnnotation,
+  getAnnotation,
+  removeAnnotation,
+  removeAllAnnotations,
+  // annotation manager
+  setAnnotationManager,
+  getAnnotationManager,
+  resetAnnotationManager,
+};

package/src/stateManagement/annotation/annotationVisibility.ts

@@ -0,0 +1,156 @@
+import { eventTarget, triggerEvent } from '@cornerstonejs/core';
+import { getAnnotation } from './annotationState';
+import { Events } from '../../enums';
+import { Annotation } from '../../types';
+import { AnnotationVisibilityChangeEventDetail } from '../../types/EventTypes';
+import {
+  isAnnotationSelected,
+  deselectAnnotation,
+} from './annotationSelection';
+
+/*
+ * It stores all hidden annotation uids.
+ */
+const globalHiddenAnnotationUIDsSet: Set<string> = new Set();
+
+/*
+ * Interface (Public API)
+ */
+
+/**
+ * Set the "visible" state of a given annotation instance.
+ *
+ * @event ANNOTATION_VISIBILITY_CHANGE
+ *
+ * @param annotationUID - The annotation uid which will have
+ * its visible state changed. An event will only be triggered if the visible state
+ * of the given annotation instance changed.
+ * @param visible - A boolean value indicating if the instance should
+ * be visible (true) or not (false)
+ */
+function setAnnotationVisibility(annotationUID: string, visible = true): void {
+  const detail = makeEventDetail();
+  if (annotationUID) {
+    if (visible) {
+      show(annotationUID, globalHiddenAnnotationUIDsSet, detail);
+    } else {
+      hide(annotationUID, globalHiddenAnnotationUIDsSet, detail);
+    }
+  }
+  publish(detail);
+}
+
+/**
+ * Clears all the hidden annotations.
+ *
+ */
+function showAllAnnotations(): void {
+  const detail = makeEventDetail();
+  globalHiddenAnnotationUIDsSet.forEach((annotationUID) => {
+    show(annotationUID, globalHiddenAnnotationUIDsSet, detail);
+  });
+  publish(detail);
+}
+
+/**
+ * Given an annotation UID, return true if it is visible, false if hidden and undefined if does not exist.
+ * @param annotationUID - The annotation uid to tell if is visible or not.
+ * @returns A boolean value or value if does not exist.
+ */
+function isAnnotationVisible(annotationUID: string): boolean | undefined {
+  const annotation = getAnnotation(annotationUID);
+
+  if (annotation) {
+    return !globalHiddenAnnotationUIDsSet.has(annotationUID);
+  }
+}
+/**
+ * It decorates given annotation with isVisible property.
+ * It properly initializes the isVisible on annotation(the property will be create if does not exist yet)
+ *
+ * @param annotation - The annotation object to be checked.
+ */
+function checkAndDefineIsVisibleProperty(annotation: Annotation): void {
+  if (annotation) {
+    const isVisible = annotation.isVisible ?? true;
+    if (shouldDefineIsVisibleProperty(annotation)) {
+      Object.defineProperty(annotation, 'isVisible', {
+        configurable: false,
+        enumerable: true,
+        set: setIsVisible,
+        get: getIsVisible,
+      });
+    }
+    setAnnotationVisibility(annotation.annotationUID, isVisible);
+  }
+}
+
+/*
+ * Private Helpers
+ */
+function makeEventDetail(): AnnotationVisibilityChangeEventDetail {
+  return Object.freeze({
+    lastVisible: [],
+    lastHidden: [],
+    hidden: [],
+  });
+}
+
+function show(
+  annotationUID: string,
+  annotationUIDsSet: Set<string>,
+  detail: AnnotationVisibilityChangeEventDetail
+): void {
+  if (annotationUIDsSet.delete(annotationUID)) {
+    detail.lastVisible.push(annotationUID);
+  }
+}
+
+function hide(
+  annotationUID: string,
+  annotationUIDsSet: Set<string>,
+  detail: AnnotationVisibilityChangeEventDetail
+): void {
+  if (!annotationUIDsSet.has(annotationUID)) {
+    annotationUIDsSet.add(annotationUID);
+    if (isAnnotationSelected(annotationUID)) {
+      deselectAnnotation(annotationUID);
+    }
+    detail.lastHidden.push(annotationUID);
+  }
+}
+
+function publish(detail: AnnotationVisibilityChangeEventDetail) {
+  if (detail.lastHidden.length > 0 || detail.lastVisible.length > 0) {
+    globalHiddenAnnotationUIDsSet.forEach(
+      (item) => void detail.hidden.push(item)
+    );
+    triggerEvent(eventTarget, Events.ANNOTATION_VISIBILITY_CHANGE, detail);
+  }
+}
+
+function shouldDefineIsVisibleProperty(annotation: Annotation): boolean {
+  const descriptor = Object.getOwnPropertyDescriptor(annotation, 'isVisible');
+  if (descriptor) {
+    return (
+      descriptor.configurable &&
+      (descriptor.set !== setIsVisible || descriptor.get !== getIsVisible)
+    );
+  }
+  return Object.isExtensible(annotation);
+}
+
+function setIsVisible(hidden: boolean) {
+  setAnnotationVisibility((this as Annotation).annotationUID, hidden);
+}
+
+function getIsVisible() {
+  return isAnnotationVisible((this as Annotation).annotationUID);
+}
+
+export {
+  setAnnotationVisibility,
+  showAllAnnotations,
+  isAnnotationVisible,
+  checkAndDefineIsVisibleProperty,
+};