Skip to main content


LengthTool let you draw annotations that measures the length of two drawing points on a slice. You can use the LengthTool in all imaging planes even in oblique reconstructed planes. Note: annotation tools in cornerstone3DTools exists in the exact location in the physical 3d space, as a result, by default, all annotations that are drawing in the same frameOfReference will get shared between viewports that are in the same frameOfReference.

The resulting annotation’s data (statistics) and metadata (the state of the viewport while drawing was happening) will get added to the ToolState manager and can be accessed from the ToolState by calling getAnnotations or similar methods.


const toolGroup = ToolGroupManager.createToolGroup('toolGroupId')


toolGroup.addViewport('viewportId', 'renderingEngineId')

toolGroup.setToolActive(LengthTool.toolName, {
bindings: [
mouseButton: MouseBindings.Primary, // Left Click

Read more in the Docs section of the website.





  • Parameters

    Returns LengthTool



_throttledCalculateCachedStats: any


configuration: Record<string, any>


editData: { annotation: any; handleIndex?: number; hasMoved?: boolean; movingTextBox?: boolean; newAnnotation?: boolean; viewportIdsToRender: string[] }

Type declaration

  • annotation: any
  • optionalhandleIndex?: number
  • optionalhasMoved?: boolean
  • optionalmovingTextBox?: boolean
  • optionalnewAnnotation?: boolean
  • viewportIdsToRender: string[]


isDrawing: boolean


isHandleOutsideImage: boolean


mode: ToolModes

Tool Mode - Active/Passive/Enabled/Disabled/


mouseDragCallback: any


supportedInteractionTypes: Mouse[]

Supported Interaction Types - currently only Mouse


toolGroupId: string

ToolGroup ID the tool instance belongs to


touchDragCallback: any


toolName: string = 'Length'



  • _activateDraw(element: HTMLDivElement): void
  • Parameters

    • element: HTMLDivElement

    Returns void


  • _activateModify(element: HTMLDivElement): void
  • Parameters

    • element: HTMLDivElement

    Returns void


  • _calculateCachedStats(annotation: any, renderingEngine: any, enabledElement: any): any
  • Parameters

    • annotation: any
    • renderingEngine: any
    • enabledElement: any

    Returns any


  • _calculateLength(pos1: any, pos2: any): number
  • Parameters

    • pos1: any
    • pos2: any

    Returns number


  • _deactivateDraw(element: HTMLDivElement): void
  • Parameters

    • element: HTMLDivElement

    Returns void


  • _deactivateModify(element: HTMLDivElement): void
  • Parameters

    • element: HTMLDivElement

    Returns void


  • _getTextLines(data: any, targetId: any): string[]
  • Parameters

    • data: any
    • targetId: any

    Returns string[]


  • _isInsideVolume(index1: any, index2: any, dimensions: any): boolean
  • Parameters

    • index1: any
    • index2: any
    • dimensions: any

    Returns boolean


  • _mouseDragCallback(evt: MouseMoveEventType | MouseDragEventType): void
  • Parameters

    • evt: MouseMoveEventType | MouseDragEventType

    Returns void


  • _mouseUpCallback(evt: MouseUpEventType | MouseClickEventType): void
  • Parameters

    • evt: MouseUpEventType | MouseClickEventType

    Returns void


  • addNewAnnotation(evt: MouseDownActivateEventType): LengthAnnotation
  • Based on the current position of the mouse and the current imageId to create a Length Annotation and stores it in the annotationManager


    • evt: MouseDownActivateEventType


    Returns LengthAnnotation

    The annotation object.


  • applyActiveStrategy(enabledElement: IEnabledElement, operationData: unknown): any
  • It applies the active strategy to the enabled element.


    • enabledElement: IEnabledElement

      The element that is being operated on.

    • operationData: unknown

      The data that needs to be passed to the strategy.

    Returns any

    The result of the strategy.


  • cancel(element: HTMLDivElement): any
  • Parameters

    • element: HTMLDivElement

    Returns any


  • @virtual

    Given the element and annotations which is an array of annotation, it filters the annotations array to only include the annotation based on the viewportType. If the viewport is StackViewport, it filters based on the current imageId of the viewport, if the viewport is volumeViewport, it only returns those that are within the same slice as the current rendered slice in the volume viewport. imageId as the enabledElement.


    • element: HTMLDivElement

      The HTML element

    • annotations: Annotations

      The annotations to filter (array of annotation)

    Returns Annotations

    The filtered annotations


  • It checks if the mouse click is near TextBoxHandle or AnnotationHandle itself, and return either it. It prioritize TextBoxHandle over AnnotationHandle. If the mouse click is not near any of the handles, it does not return anything.


    • element: HTMLDivElement

      The element that the tool is attached to.

    • annotation: Annotation

      The annotation object associated with the annotation

    • canvasCoords: Point2

      The coordinates of the mouse click on canvas

    • proximity: number

      The distance from the mouse cursor to the point that is considered “near”.

    Returns ToolHandle

    The handle that is closest to the cursor, or null if the cursor is not near any of the handles.


  • getLinkedTextBoxStyle(specifications: StyleSpecifier, annotation?: Annotation): Record<string, unknown>
  • It returns the style for the text box


    • specifications: StyleSpecifier
    • optionalannotation: Annotation

      The annotation for the tool that is currently active.

    Returns Record<string, unknown>

    An object of the style settings for the text box.


  • getStyle(property: string, specifications: StyleSpecifier, annotation?: Annotation): unknown
  • It takes the property (color, lineDash, etc.) and based on the state of the annotation (selected, highlighted etc.) it returns the appropriate value based on the central toolStyle settings for each level of specification.


    • property: string

      The name of the style property to get.

    • specifications: StyleSpecifier
    • optionalannotation: Annotation

      The annotation for the tool that is currently active.

    Returns unknown

    The value of the property.


  • getToolName(): string
  • Returns the name of the tool

    Returns string

    The name of the tool.


  • handleSelectedCallback(evt: MouseDownEventType, annotation: LengthAnnotation, handle: ToolHandle, interactionType?: string): void
  • handleSelectedCallback Custom callback for when a handle is selected.


    • evt: MouseDownEventType
    • annotation: LengthAnnotation
    • handle: ToolHandle
    • interactionType: string = 'mouse'

    Returns void


  • isPointNearTool(element: HTMLDivElement, annotation: LengthAnnotation, canvasCoords: Point2, proximity: number): boolean
  • It returns if the canvas point is near the provided length annotation in the provided element or not. A proximity is passed to the function to determine the proximity of the point to the annotation in number of pixels.


    • element: HTMLDivElement

      HTML Element

    • annotation: LengthAnnotation


    • canvasCoords: Point2

      Canvas coordinates

    • proximity: number

      Proximity to tool to consider

    Returns boolean

    Boolean, whether the canvas point is near tool


  • mouseMoveCallback(evt: MouseMoveEventType, filteredAnnotations?: Annotations): boolean
  • @virtual

    Event handler for Cornerstone MOUSE_MOVE event.


    • evt: MouseMoveEventType

      The normalized mouse event

    • optionalfilteredAnnotations: Annotations

      The annotations to check for hover interactions

    Returns boolean

    True if the annotation needs to be re-drawn by the annotationRenderingEngine.


  • onImageSpacingCalibrated(evt: ImageSpacingCalibratedEvent): void
  • On Image Calibration, take all the annotation from the AnnotationState manager, and invalidate them to force them to be re-rendered and their stats to be recalculated. Then use the old and new imageData (non-calibrated and calibrated) to calculate the new position for the annotations in the space of the new imageData.


    • evt: ImageSpacingCalibratedEvent

      The calibration event

    Returns void


  • it is used to draw the length annotation in each request animation frame. It calculates the updated cached statistics if data is invalidated and cache it.


    • enabledElement: IEnabledElement

      The Cornerstone’s enabledElement.

    • svgDrawingHelper: SVGDrawingHelper

      The svgDrawingHelper providing the context for drawing.

    Returns boolean


  • setActiveStrategy(strategyName: string): void
  • Sets the active strategy for a tool. Strategies are multiple implementations of tool behavior that can be switched by tool configuration.


    • strategyName: string

      name of the strategy to be set as active

    Returns void


  • setConfiguration(newConfiguration: Record<string, any>): void
  • merges the new configuration with the tool configuration


    • newConfiguration: Record<string, any>

    Returns void


  • toolSelectedCallback(evt: MouseDownEventType, annotation: LengthAnnotation, interactionType: Mouse): void
  • Custom callback for when an annotation is selected


    • evt: MouseDownEventType
    • annotation: LengthAnnotation
    • interactionType: Mouse

    Returns void