@cornerstonejs/tools 0.56.2 → 0.56.4

package/src/stateManagement/annotation/config/ToolStyle.ts

@@ -0,0 +1,265 @@
+import {
+  StyleConfig,
+  ToolStyleConfig,
+  StyleSpecifier,
+  AnnotationStyle,
+} from '../../../types/AnnotationStyle';
+
+/**
+ * This class handles the configuration of the tool style. You can use it to set
+ * the style of a tool at various levels (annotation, viewport, toolGroup, global).
+ *
+ * The hierarchy of the configuration is as follows (each level falls back to the
+ * next level if not specified):
+ *
+ * 1) Annotation-level styles (with annotationUID)
+ *     2) Viewport-level tool styles
+ *         - Per-tool: Length on the viewport with viewportId
+ *         - Global: All tools on the viewport with viewportId
+ *             3) ToolGroup tool styles
+ *                 - Per-tool: Angle on toolGroupId in all viewports of the toolGroup
+ *                 - Global: All tools in the toolGroupId for all viewports
+ *                     4) Default level:
+ *                         - Per-tool: Length styles
+ *                         - Global: Opinionated styles by CornerstoneJS
+ */
+class ToolStyle {
+  config: StyleConfig;
+
+  constructor() {
+    const defaultConfig = {
+      color: 'rgb(255, 255, 0)',
+      colorHighlighted: 'rgb(0, 255, 0)',
+      colorSelected: 'rgb(0, 220, 0)',
+      colorLocked: 'rgb(255, 255, 0)',
+      lineWidth: '1',
+      lineDash: '',
+      shadow: true,
+      textBoxFontFamily: 'Helvetica Neue, Helvetica, Arial, sans-serif',
+      textBoxFontSize: '14px',
+      textBoxColor: 'rgb(255, 255, 0)',
+      textBoxColorHighlighted: 'rgb(0, 255, 0)',
+      textBoxColorSelected: 'rgb(0, 255, 0)',
+      textBoxColorLocked: 'rgb(255, 255, 0)',
+      textBoxBackground: '',
+      textBoxLinkLineWidth: '1',
+      textBoxLinkLineDash: '2,3',
+      textBoxShadow: true,
+    };
+
+    this._initializeConfig(defaultConfig);
+  }
+
+  /**
+   * It returns the annotation-specific tool styles for the annotation with the given UID
+   * @param annotationUID - The unique identifier of the annotation.
+   * @returns The annotation tool styles for the annotation with the given UID.
+   */
+  getAnnotationToolStyles(annotationUID: string): AnnotationStyle {
+    return this.config.annotations && this.config.annotations[annotationUID];
+  }
+
+  /**
+   * It returns the styles for a given viewport. It includes tool-specific and
+   * global styles (all tools in the viewport)
+   * @param viewportId - The id of the viewport
+   * @returns The viewport tool styles for the given viewport id.
+   */
+  getViewportToolStyles(viewportId: string): ToolStyleConfig {
+    return this.config.viewports && this.config.viewports[viewportId];
+  }
+
+  /**
+   * It returns the tool style for the given toolGroup. It includes tool-specific and
+   * global styles (all tools in the toolGroup)
+   * @param toolGroupId - The id of the toolGroup.
+   * @returns The tool styles for the tool group with the given id.
+   */
+  getToolGroupToolStyles(toolGroupId: string): ToolStyleConfig {
+    return this.config.toolGroups && this.config.toolGroups[toolGroupId];
+  }
+
+  /**
+   * It returns the default tool styles from the config file. It includes tool-specific and
+   * global styles (all tools in all tooLGroups)
+   * @returns The default tool styles.
+   */
+  getDefaultToolStyles(): ToolStyleConfig {
+    return this.config.default;
+  }
+
+  /**
+   * It takes an annotationUID and a style object and sets the styles at
+   * the annotationLevel (highest priority in the hierarchy). The styles is an
+   * object with key value pairs.
+   * @param annotationUID - string - The unique identifier for the annotation.
+   * @param styles - ToolStyles
+   */
+  setAnnotationStyles(annotationUID: string, styles: AnnotationStyle) {
+    let annotationSpecificStyles = this.config.annotations;
+
+    if (!annotationSpecificStyles) {
+      this.config = {
+        ...this.config,
+        annotations: {},
+      };
+
+      annotationSpecificStyles = this.config.annotations;
+    }
+
+    annotationSpecificStyles[annotationUID] = styles;
+  }
+
+  /**
+   * It takes a viewportId and a ToolStyles object, and adds the ToolStyles object
+   * at the viewport level (second highest priority in the hierarchy after the annotation level).
+   * @param viewportId - The id of the viewport
+   * @param styles - style object including tool-specific and/or global styles (All tools in the viewport)
+   */
+  setViewportToolStyles(viewportId: string, styles: ToolStyleConfig) {
+    let viewportSpecificStyles = this.config.viewports;
+
+    if (!viewportSpecificStyles) {
+      this.config = {
+        ...this.config,
+        viewports: {},
+      };
+
+      viewportSpecificStyles = this.config.viewports;
+    }
+
+    viewportSpecificStyles[viewportId] = styles;
+  }
+
+  /**
+   * It takes a toolGroupId and a ToolStyles object, and it adds the ToolStyles object
+   * at the toolGroup level (third highest priority in the hierarchy after the viewport level).
+   * @param toolGroupId - The id of the toolGroup
+   * @param styles - style object including tool-specific (in all viewports of the toolGroup) and/or
+   * global styles (All tools in the toolGroup for all viewports)
+   */
+  setToolGroupToolStyles(toolGroupId: string, styles: ToolStyleConfig) {
+    let toolGroupSpecificStyles = this.config.toolGroups;
+
+    if (!toolGroupSpecificStyles) {
+      this.config = {
+        ...this.config,
+        toolGroups: {},
+      };
+
+      toolGroupSpecificStyles = this.config.toolGroups;
+    }
+
+    toolGroupSpecificStyles[toolGroupId] = styles;
+  }
+
+  /**
+   * Sets the default tool styles for the editor. It overrides the default styles for all tools.
+   * @param styles - style object including tool-specific (a tool in all toolGroups) and/or
+   * global styles (All tools in all tooLGroups)
+   */
+  setDefaultToolStyles(styles: ToolStyleConfig) {
+    this.config.default = styles;
+  }
+
+  /**
+   * It returns the value for a given style key, based on the provided specifications.
+   * It starts by looking at the annotation-specific styles, then at the viewport-specific styles,
+   * then at the toolGroup-specific styles, and finally at the default styles.
+   * @param styleKey - The key of the style.
+   * @param styleSpecifier - An object containing the specifications such as viewportId,
+   * toolGroupId, toolName and annotationUID which are used to get the style if the level of specificity is
+   * met
+   * @returns The value for the given style key.
+   */
+  getStyleProperty(toolStyle: string, specifications: StyleSpecifier) {
+    const { annotationUID, viewportId, toolGroupId, toolName } = specifications;
+
+    return this._getToolStyle(
+      toolStyle,
+      annotationUID,
+      viewportId,
+      toolGroupId,
+      toolName
+    );
+  }
+
+  private _getToolStyle(
+    property: string,
+    annotationUID: string,
+    viewportId: string,
+    toolGroupId: string,
+    toolName: string
+  ) {
+    if (annotationUID) {
+      const styles = this.getAnnotationToolStyles(annotationUID);
+
+      if (styles) {
+        // check first in the toolSpecific styles
+        if (styles[property]) {
+          return styles[property];
+        }
+      }
+    }
+
+    if (viewportId) {
+      const styles = this.getViewportToolStyles(viewportId);
+
+      if (styles) {
+        // check if we have the viewportId specific style
+        // check first in the toolSpecific styles
+        if (styles[toolName] && styles[toolName][property]) {
+          return styles[toolName][property];
+        }
+
+        // check if we have the style in the viewport specific global viewportSpecificStyles
+        if (styles.global && styles.global[property]) {
+          return styles.global[property];
+        }
+      }
+    }
+
+    if (toolGroupId) {
+      const styles = this.getToolGroupToolStyles(toolGroupId);
+
+      if (styles) {
+        // check first in the toolSpecific styles
+        if (styles[toolName] && styles[toolName][property]) {
+          return styles[toolName][property];
+        }
+
+        // check if we have the style in the toolGroup specific global styles
+        if (styles.global && styles.global[property]) {
+          return styles.global[property];
+        }
+      }
+    }
+
+    const globalStyles = this.getDefaultToolStyles();
+
+    if (globalStyles[toolName] && globalStyles[toolName][property]) {
+      return globalStyles[toolName][property];
+    }
+
+    if (globalStyles.global && globalStyles.global[property]) {
+      return globalStyles.global[property];
+    }
+  }
+
+  private _initializeConfig(config) {
+    const toolStyles = {};
+    for (const name in config) {
+      toolStyles[name] = config[name];
+    }
+
+    this.config = {
+      default: {
+        global: toolStyles as AnnotationStyle,
+      },
+    };
+  }
+}
+
+const toolStyle = new ToolStyle();
+
+export default toolStyle;

package/src/stateManagement/annotation/config/getFont.ts

@@ -0,0 +1,36 @@
+import { ToolModes, AnnotationStyleStates } from '../../../enums';
+import { getStyleProperty } from './helpers';
+import { StyleSpecifier } from '../../../types/AnnotationStyle';
+
+/**
+ * getFont - Returns a font string of the form "{fontSize}px fontName" used by `canvas`.
+ * @param styleSpecifier - An object containing the specifications such as viewportId,
+ * toolGroupId, toolName and annotationUID which are used to get the style if the level of specificity is
+ * met (hierarchy is checked from most specific to least specific which is
+ * annotationLevel -> viewportLevel -> toolGroupLevel -> default.
+ * @param state - An optional state to determine the final property name
+ * @param mode - An optional mode to determine the final property name
+ * @returns The font string.
+ */
+function getFont(
+  styleSpecifier: StyleSpecifier,
+  state?: AnnotationStyleStates,
+  mode?: ToolModes
+): string {
+  const fontSize = getStyleProperty(
+    'textBoxFontSize',
+    styleSpecifier,
+    state,
+    mode
+  );
+  const fontFamily = getStyleProperty(
+    'textBoxFontFamily',
+    styleSpecifier,
+    state,
+    mode
+  );
+
+  return `${fontSize}px ${fontFamily}`;
+}
+
+export default getFont;

package/src/stateManagement/annotation/config/getState.ts

@@ -0,0 +1,26 @@
+import { Annotation } from '../../../types';
+import { isAnnotationLocked } from '../annotationLocking';
+import { isAnnotationSelected } from '../annotationSelection';
+import { AnnotationStyleStates } from '../../../enums';
+
+/**
+ * Given a Annotation object, return the annotationStyle State that it
+ * should be in based on its data
+ * @param annotation - The annotation that we want to style.
+ * @returns The state of the annotation whether it is Default, Highlighted, Locked, or Selected.
+ */
+function getState(annotation?: Annotation): AnnotationStyleStates {
+  if (annotation) {
+    if (annotation.data && annotation.highlighted)
+      return AnnotationStyleStates.Highlighted;
+    if (isAnnotationSelected(annotation.annotationUID))
+      return AnnotationStyleStates.Selected;
+
+    // Todo: make annotation lock api not to rely on the annotation itself
+    if (isAnnotationLocked(annotation)) return AnnotationStyleStates.Locked;
+  }
+
+  return AnnotationStyleStates.Default;
+}
+
+export default getState;

package/src/stateManagement/annotation/config/helpers.ts

@@ -0,0 +1,55 @@
+import { StyleSpecifier } from '../../../types/AnnotationStyle';
+import { ToolModes, AnnotationStyleStates } from '../../../enums';
+import toolStyle from './ToolStyle';
+
+/**
+ * Build a list of hierarchal property names in ascending order of priority
+ * @param property - The base property name -- e.g., 'color'
+ * @param state - An optional state to determine the final property name
+ * @param mode - An optional mode to determine the final property name
+ * @returns A list of property names
+ */
+function getHierarchalPropertyStyles(
+  property: string,
+  state?: AnnotationStyleStates,
+  mode?: ToolModes
+): string[] {
+  const list = [`${property}`];
+  if (state) list.push(`${list[0]}${state}`);
+  if (mode) list.push(`${list[list.length - 1]}${mode}`);
+  return list;
+}
+
+/**
+ * Get the value of a style property from the ToolStyle config
+ * @param property - The name of the property to get.
+ * @param styleSpecifier - An object containing the specifications such as viewportId,
+ * toolGroupId, toolName and annotationUID which are used to get the style if the level of specificity is
+ * met (hierarchy is checked from most specific to least specific which is
+ * annotationLevel -> viewportLevel -> toolGroupLevel -> default.
+ * @param state - The state of the tool (Default, Locked etc.)
+ * @param mode - The current tool mode. (Active, Passive etc.)
+ * @returns The value of the property.
+ */
+function getStyleProperty(
+  property: string,
+  styleSpecifier: StyleSpecifier,
+  state?: AnnotationStyleStates,
+  mode?: ToolModes
+): string {
+  // Hierarchal property styles is a list of property names with priority in ascending
+  // order like: ['color', 'colorSelected', 'colorSelectedActive'], if in the toolStyle
+  // config, the `colorSelectedActive` property is defined, it will be used, otherwise
+  // the `colorSelected` property will be used, and if that is not defined, the `color`
+  // property will be used. This is done to ensure that the most specific property is used.
+  // Thus, we attempt resolving property names in reverse order
+  const alternatives = getHierarchalPropertyStyles(property, state, mode);
+  for (let i = alternatives.length - 1; i >= 0; --i) {
+    const style = toolStyle.getStyleProperty(alternatives[i], styleSpecifier);
+    if (style !== undefined) {
+      return style;
+    }
+  }
+}
+
+export { getStyleProperty };

package/src/stateManagement/annotation/config/index.ts

@@ -0,0 +1,5 @@
+import getState from './getState';
+import getFont from './getFont';
+import style from './ToolStyle';
+
+export { getState, getFont, style };

package/src/stateManagement/annotation/helpers/state.ts

@@ -0,0 +1,83 @@
+import {
+  getEnabledElement,
+  triggerEvent,
+  eventTarget,
+  getEnabledElementByIds,
+} from '@cornerstonejs/core';
+import { Events } from '../../../enums';
+import { Annotation } from '../../../types/AnnotationTypes';
+import { getToolGroupsWithToolName } from '../../../store/ToolGroupManager';
+import { AnnotationAddedEventDetail } from '../../../types/EventTypes';
+
+/**
+ * It triggers an event for the element when an annotation is added
+ * @param annotation - Annotation - The annotation that was added.
+ * @param element - The element that the annotation was added to.
+ */
+function triggerAnnotationAddedForElement(
+  annotation: Annotation,
+  element: HTMLDivElement
+) {
+  const enabledElement = getEnabledElement(element);
+  const { renderingEngine, viewportId } = enabledElement;
+
+  const eventType = Events.ANNOTATION_ADDED;
+
+  const eventDetail: AnnotationAddedEventDetail = {
+    annotation,
+    viewportId,
+    renderingEngineId: renderingEngine.id,
+  };
+
+  triggerEvent(eventTarget, eventType, eventDetail);
+}
+
+/**
+ * If the annotation has a FrameOfReferenceUID, it triggers the ANNOTATION_ADDED
+ * event for all the viewports that has the same FrameOfReferenceUID.
+ * @param annotation -  Annotation - The annotation that was added
+ */
+function triggerAnnotationAddedForFOR(annotation: Annotation) {
+  const { toolName } = annotation.metadata;
+
+  const toolGroups = getToolGroupsWithToolName(toolName);
+
+  if (!toolGroups.length) {
+    return;
+  }
+
+  // Find the viewports in the toolGroups who has the same FrameOfReferenceUID
+  const viewportsToRender = [];
+
+  toolGroups.forEach((toolGroup) => {
+    toolGroup.viewportsInfo.forEach((viewportInfo) => {
+      const { renderingEngineId, viewportId } = viewportInfo;
+      const { FrameOfReferenceUID } = getEnabledElementByIds(
+        viewportId,
+        renderingEngineId
+      );
+
+      if (annotation.metadata.FrameOfReferenceUID === FrameOfReferenceUID) {
+        viewportsToRender.push(viewportInfo);
+      }
+    });
+  });
+
+  if (!viewportsToRender.length) {
+    return;
+  }
+
+  const eventType = Events.ANNOTATION_ADDED;
+
+  viewportsToRender.forEach(({ renderingEngineId, viewportId }) => {
+    const eventDetail: AnnotationAddedEventDetail = {
+      annotation,
+      viewportId,
+      renderingEngineId,
+    };
+
+    triggerEvent(eventTarget, eventType, eventDetail);
+  });
+}
+
+export { triggerAnnotationAddedForElement, triggerAnnotationAddedForFOR };

package/src/stateManagement/annotation/index.ts

@@ -0,0 +1,15 @@
+import * as config from './config';
+import * as locking from './annotationLocking';
+import * as selection from './annotationSelection';
+import * as state from './annotationState';
+import * as visibility from './annotationVisibility';
+import FrameOfReferenceSpecificAnnotationManager from './FrameOfReferenceSpecificAnnotationManager';
+
+export {
+  config,
+  locking,
+  selection,
+  state,
+  visibility,
+  FrameOfReferenceSpecificAnnotationManager,
+};

package/src/stateManagement/index.js

@@ -0,0 +1,40 @@
+import FrameOfReferenceSpecificAnnotationManager, {
+  defaultFrameOfReferenceSpecificAnnotationManager,
+} from './annotation/FrameOfReferenceSpecificAnnotationManager';
+import * as annotationLocking from './annotation/annotationLocking';
+import * as annotationSelection from './annotation/annotationSelection';
+
+import {
+  getAnnotations,
+  addAnnotation,
+  removeAnnotation,
+  getAnnotation,
+  getNumberOfAnnotations,
+  setAnnotationManager,
+  getAnnotationManager,
+  resetAnnotationManager,
+} from './annotation/annotationState';
+
+import {
+  addSegmentationRepresentations,
+  removeSegmentationsFromToolGroup,
+} from './segmentation';
+
+export {
+  // annotations
+  FrameOfReferenceSpecificAnnotationManager,
+  defaultFrameOfReferenceSpecificAnnotationManager,
+  annotationLocking,
+  annotationSelection,
+  getAnnotations,
+  addAnnotation,
+  getNumberOfAnnotations,
+  removeAnnotation,
+  getAnnotation,
+  setAnnotationManager,
+  getAnnotationManager,
+  resetAnnotationManager,
+  // segmentations
+  addSegmentationRepresentations,
+  removeSegmentationsFromToolGroup,
+};