Global

Members

(constant) ANNOTATION_TOOLBAR_PERSIST_ID_FILE :string

Persist id for the annotation save/load toolbar row.
Type:
  • string
Source:

(constant) ANNOTATION_TOOLBAR_PERSIST_ID_PENCIL :string

Persist id for the annotation pencil toolbar row (ConfigurationWidget custom section).
Type:
  • string
Source:

(constant) ANNOTATION_UI_SCOPE_CLASS

CSS scope class for annotation UI styles (see docs/css-scoping.md).
Source:

(constant) COMPOUND_PATH_CONTRACT_MESSAGE

Pure paper-item shape contract (no Paper.js dependency) for unit tests and shared messaging.
Source:

(constant) CONFIG_TOOLBAR_PERSIST_VERSION

Schema version for ConfigurationWidget toolbar visibility JSON in localStorage.
Source:

(constant) FOV_DROP_UNDER_STROKE

Dropped ring: same visual weights, in image space with rescale (see applyRescale).
Source:

(constant) FOV_HIT_FILL_ALPHA

Nearly invisible fill so hitTest / selection see the disk interior (Paper.js null fill skips fill hits).
Source:
See:

(constant) FOV_PREVIEW_OVER_STROKE

Black dashed stroke on top of halo (px).
Source:

(constant) FOV_PREVIEW_UNDER_STROKE

White halo stroke (px, logical; no rescale on toolLayer preview).
Source:

_paper

OpenSeadragon paperjs overlay plugin based on paper.js
Version:
  • 0.7.2 Includes additional open source libraries which are subject to copyright notices as indicated accompanying those segments of code. Original code: Copyright (c) 2022-2026, Thomas Pearce All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of osd-paperjs-annotation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Source:

(constant) iconDefs

OpenSeadragon paperjs overlay plugin based on paper.js
Version:
  • 0.7.2 Includes additional open source libraries which are subject to copyright notices as indicated accompanying those segments of code. Original code: Copyright (c) 2022-2026, Thomas Pearce All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of osd-paperjs-annotation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Source:

(constant) localImportsCompleted

OpenSeadragon paperjs overlay plugin based on paper.js
Version:
  • 0.7.2 Includes additional open source libraries which are subject to copyright notices as indicated accompanying those segments of code. Original code: Copyright (c) 2022-2026, Thomas Pearce All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of osd-paperjs-annotation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Source:

osd

OpenSeadragon paperjs overlay plugin based on paper.js
Version:
  • 0.7.2 Includes additional open source libraries which are subject to copyright notices as indicated accompanying those segments of code. Original code: Copyright (c) 2022-2026, Thomas Pearce All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of osd-paperjs-annotation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Source:

(constant) toolConstructors :Object.<string, function()>

Map of tool names to constructors.
Type:
  • Object.<string, function()>
Source:

Methods

_makeOverlayStyleRow(p)

Parameters:
Name Type Description
p Object
Properties
Name Type Description
labelText string
faIconClass string
osdButton Object
configurationWidget OSDPaperjsAnnotation.ConfigurationWidget
kind 'pencil' | 'file'
ui Object AnnotationUI instance
Source:

adaptiveOffsetCurve(curve, offset)

Adaptive offset a curve by repeatly apply the approximation proposed by Tiller and Hanson.
Parameters:
Name Type Description
curve curve to offset
offset offset value
Source:

annotationToolPrimaryButtonActiveDrag(ev) → {boolean}

Parameters:
Name Type Description
ev Object Paper ToolEvent or compatible; may include `event` (MouseEvent).
Source:
Returns:
True while the primary mouse button is still held during move/drag (`buttons & 1`).
Type
boolean

annotationToolPrimaryButtonDownOrUp(ev) → {boolean}

Paper.js tool/mouse events expose the native DOM event as `event`. Use for gating so only the primary button drives annotation tools (right/middle clicks do not draw).
Parameters:
Name Type Description
ev Object Paper ToolEvent or compatible; may include `event` (MouseEvent).
Source:
Returns:
True if this is a primary-button mousedown or mouseup (`button === 0`).
Type
boolean

applyRulerPhysicalScaleFromMpp(toolkit, mpp, optionsopt) → {boolean}

Parameters:
Name Type Attributes Description
toolkit OSDPaperjsAnnotation.AnnotationToolkit
mpp Object | null Microns per source pixel `{ x, y }` (isotropic +X uses `mpp.x`)
options Object <optional>
Properties
Name Type Attributes Description
unit string <optional>
 Display unit: `'mm'` (default) or `'um'`
Source:
Returns:
true if ruler toolbar was updated
Type
boolean

areaMm2FromDiameterPhysical(diameterPhysical, unit) → {number|null}

Circle area in mm² from diameter in physical units (mm or µm).
Parameters:
Name Type Description
diameterPhysical number
unit 'mm' | 'um'
Source:
Returns:
Type
number | null

attachAnnotationToolkitConfigurationWidget(annotationToolkit, configurationWidget) → {HTMLElement|null}

Attach the "Annotations" block to a ConfigurationWidget (calls addSection). Does not register with AnnotationToolkit.destroy(); use AnnotationToolkit#registerWithConfigurationWidget for that.
Parameters:
Name Type Description
annotationToolkit OSDPaperjsAnnotation.AnnotationToolkit
configurationWidget OSDPaperjsAnnotation.ConfigurationWidget
Source:
Returns:
Root element passed to addSection, or null if nothing was attached
Type
HTMLElement | null

buildDownsampleOptions()

Build preset power-of-two downsample options plus an "Other..." sentinel.
Source:

buildScreenshotDialogCSS() → {string}

Returns the CSS string for the screenshot dialog. All selectors are scoped to .screenshot-dialog to avoid global leaks.
Source:
Returns:
Type
string

buildScreenshotDialogHTML() → {string}

Returns the HTML string for the screenshot dialog.
Source:
Returns:
Type
string

buildSegmentGroupFromPath(path, parentGroup, props, index) → {paper.Group}

Build one 3-child segment group from a path and saved measurement properties. Label group counter-rotates with view (upright like PointText). Used when loading from GeoJSON.
Parameters:
Name Type Description
path paper.Path existing path (two segments)
parentGroup paper.Group parent that will receive the segment (must be in project so labelGroup.view exists)
props Object geometry.properties (lengths, units, strokeWidthPixels, haloExtraPixels, labelFontSize, etc.)
index number segment index
Source:
Returns:
Type
paper.Group

circlePreviewGeometryFromProjectPoint() → {Object|null}

Preview circle in project space; committed drop uses centerImg + diameterPx on the tile layer.
Source:
Returns:
Type
Object | null

composeScreenshotWithScalebar(params) → {Promise.<Blob>}

Composes a scalebar onto a base screenshot blob.
Parameters:
Name Type Description
params object
Properties
Name Type Description
baseBlob Blob The base screenshot blob
pixelRatio number Device pixel ratio used during base render
scaleFactor number Output scale factor (output pixels / base pixels)
scalebar object Scalebar configuration
Properties
Name Type Attributes Description
include boolean Whether to draw a scalebar
widthMm number Scalebar physical length in mm
heightPx number Scalebar bar height in pixels
mppX number Microns per pixel along X axis
label object <optional>
 Label fit info from _scalebarLabelFit
Source:
Returns:
Type
Promise.<Blob>

computeLabelPlacementCenter(label, p1, p2, midpoint, gapPixels) → {paper.Point}

Compute placement center for label offset above segment (constant pixel gap, zoom-aware). Same math as ruler tool's _computeLabelPlacementCenter; used only by the item.
Parameters:
Name Type Description
label paper.PointText label with bounds set (after applyRescale)
p1 paper.Point segment start point
p2 paper.Point segment end point
midpoint paper.Point segment midpoint
gapPixels number gap in screen pixels (e.g. RULER_LABEL_GAP_PX)
Source:
Returns:
placement center (midpoint if segment too short, otherwise offset above)
Type
paper.Point

computeOutputSize()

Shared helpers for screenshot output sizing from a base (full-res) region size.
Source:

computeRenderSignature(params) → {string}

Builds a JSON signature string that uniquely identifies a render request, used for cache invalidation.
Parameters:
Name Type Description
params object
Properties
Name Type Description
w number Output width in device pixels
h number Output height in device pixels
viewportRect OpenSeadragon.Rect Viewport-space rectangle
rotation number Viewport rotation
tileSource object The OSD tile source object
Source:
Returns:
Type
string

connectAdjacentBezier()

Connect two adjacent bezier curve, each curve is represented by two segments, create different types of joins or simply removal redundant segment.
Source:

connectBeziers()

Connect all the segments together.
Source:

convertFaIcons(element, faClassesToReplaceopt, faClassesToRemoveopt)

Find descendants of a parent element and convert font awesome classes into svg icons. See iconDefs for the list of supported class names.
Parameters:
Name Type Attributes Description
element HTMLElement the parent to search within
faClassesToReplace Array <optional>
 an optional array of strings of fontawesome class names to convert. Defaults to all classes in iconDefs above.
faClassesToRemove Array <optional>
 an optional array of strings to remove from the class list. Default: ['fa', 'fa-solid']
Source:

coordinatesMatchGeometryType(type, coordinates) → {boolean}

Returns whether `coordinates` matches the RFC 7946 array shape for `type`.
Parameters:
Name Type Description
type string | null | undefined GeoJSON geometry type
coordinates unknown
Source:
Returns:
Type
boolean

createAnnotationUIScopeRoot() → {HTMLDivElement}

Outermost node for official toolbar/layer UI roots. PostCSS rules are descendants of `.osd-paperjs-annotation`, not the same element.
Source:
Returns:
Type
HTMLDivElement

createDroppedRingGroup(radiusImg) → {Object}

Parameters:
Name Type Description
radiusImg number
Source:
Returns:
Type
Object

createPreviewRingGroup() → {Object}

Source:
Returns:
Type
Object

createScreenshotDialogElement() → {HTMLElement}

Injects the screenshot dialog CSS into the document head (once) and creates the dialog DOM element.
Source:
Returns:
The dialog element
Type
HTMLElement

diameterPhysicalFromAreaMm2(areaMm2, unit) → {number|null}

Diameter in physical `unit` (mm or µm) for a circle of the given area in mm².
Parameters:
Name Type Description
areaMm2 number
unit 'mm' | 'um'
Source:
Returns:
Type
number | null

diameterPhysicalToBasePixels(mpp, diameterPhysical, unit)

Isotropic diameter along image +X (mpp.x), v1 policy per overlay spec.
Parameters:
Name Type Description
mpp Object
diameterPhysical number
unit 'mm' | 'um'
Source:

ensureAnnotationUIStyles()

Idempotent. Injects scoped UI styles (link tags for ESM; webpack uses importcss).
Source:

ensureNamedToolLayer(paperScope)

Parameters:
Name Type Description
paperScope paper.PaperScope
Source:

evaluatePaperItemShapeContract(contractKey, isCompoundPath) → {Object|Object}

Parameters:
Name Type Description
contractKey 'compoundPath' | null | undefined from `AnnotationItem.constructor.paperItemShapeContract`
isCompoundPath boolean whether `paperItem instanceof paper.CompoundPath`
Source:
Returns:
Type
Object | Object

fovGeometryLog(…args)

Parameters:
Name Type Attributes Description
args unknown <repeatable>
Source:

fovOverlayLog(…args)

Parameters:
Name Type Attributes Description
args unknown <repeatable>
Source:

getPointLineIntersections()

Get the intersection point of point based lines
Source:

imagePointToProjectPoint(viewer, paperScope, imagePoint) → {paper.Point}

Parameters:
Name Type Description
viewer OpenSeadragon.Viewer
paperScope paper.PaperScope
imagePoint OpenSeadragon.Point
Source:
Returns:
Type
paper.Point

isLineStringCoordinates(coords) → {boolean}

Parameters:
Name Type Description
coords unknown
Source:
Returns:
Type
boolean

isLinearRing(ring) → {boolean}

Linear ring: closed loop; RFC requires >= 4 positions.
Parameters:
Name Type Description
ring unknown
Source:
Returns:
Type
boolean

isMultiLineStringCoordinates(coords) → {boolean}

Parameters:
Name Type Description
coords unknown
Source:
Returns:
Type
boolean

isMultiPointCoordinates(coords) → {boolean}

Parameters:
Name Type Description
coords unknown
Source:
Returns:
Type
boolean

isMultiPolygonCoordinates(coords) → {boolean}

Parameters:
Name Type Description
coords unknown
Source:
Returns:
Type
boolean

isPolygonCoordinates(coords) → {boolean}

Parameters:
Name Type Description
coords unknown
Source:
Returns:
Type
boolean

isPosition(pos) → {boolean}

Parameters:
Name Type Description
pos unknown
Source:
Returns:
Type
boolean

makeFaIcon(classname, currentColoropt)

Create an SVG icon from a font-awesome class name. See iconDefs for the list of supported class names.
Parameters:
Name Type Attributes Description
classname String
currentColor boolean <optional>
 Whether to use the currentColor property for the fill color
Source:
Returns:
the newly created svg element with class 'icon'

makeRoundJoin()

Create a round join segment between two adjacent segments.
Source:

mppFromActiveViewerImage(viewer) → {Object|null}

mpp from the sole world item when the viewer has exactly one tiled image. Multi-slide hosts should use mppFromTiledImage on the chosen image instead.
Parameters:
Name Type Description
viewer OpenSeadragon.Viewer
Source:
Returns:
Type
Object | null

mppFromTiledImage(tiledImage) → {Object|null}

Read and validate mpp from a tiled image source.
Parameters:
Name Type Description
tiledImage OpenSeadragon.TiledImage
Source:
Returns:
Type
Object | null

normalize()

Normalize a path, always clockwise, non-self-intersection, ignore really small components, and no one-component compound path.
Source:

offsetSegment(segment, curve, handleNormal, offset)

Offset the start/terminal segment of a bezier curve
Parameters:
Name Type Description
segment segment to offset
curve curve to offset
handleNormal the normal of the the line formed of two handles
offset offset value
Source:

projectPointToImagePoint(viewer, paperScope, projectPoint) → {OpenSeadragon.Point}

Parameters:
Name Type Description
viewer OpenSeadragon.Viewer
paperScope paper.PaperScope
projectPoint paper.Point
Source:
Returns:
Type
OpenSeadragon.Point

removeIntersection()

Remove self intersection when offset is negative by point direction dectection.
Source:

removeOutsiders()

Remove impossible segments in negative offset condition.
Source:

renderBaseScreenshot(params) → {Promise.<{blob: Blob, pixelRatio: number, signature: string}>}

Creates an off-screen OpenSeadragon viewer, renders the specified viewport region at the given pixel dimensions, and returns the result as a Blob.
Parameters:
Name Type Description
params object
Properties
Name Type Attributes Description
w number Output width in device pixels
h number Output height in device pixels
viewportRect OpenSeadragon.Rect Viewport-space rectangle to render
viewer object The main OSD viewer (for config like crossOriginPolicy)
tiledImage object The active tiled image
onProgress function <optional>
 Optional progress callback(loaded, total)
Source:
Returns:
Type
Promise.<{blob: Blob, pixelRatio: number, signature: string}>

styleDroppedOver(over)

Parameters:
Name Type Description
over paper.Path.Circle
Source:

styleDroppedUnder(under)

Parameters:
Name Type Description
under paper.Path.Circle
Source:

stylePreviewRing(group, under, over)

Parameters:
Name Type Description
group paper.Group
under paper.Shape.Circle
over paper.Shape.Circle
Source:

updateFillOpacity()

Item.updateFillOpacity (paper extension) Update the fill opacity of a paper item and its descendants.
Source:

updateStrokeOpacity()

Item.updateStrokeOpacity (paper extension) Update the stroke opacity of a paper item and its descendants.
Source:

validateGeoJSONGeometry(geom) → {Object}

Structural check only: `coordinates` array depth vs `type`. Skips `GeometryCollection` and missing/empty coordinates.
Parameters:
Name Type Description
geom Object GeoJSON-like object with optional `type`, `coordinates`, `geometries`
Source:
Returns:
`{ ok: boolean }` and optional `message` (string) when `ok` is false
Type
Object

validatePaperItemShapeContract(annotationItem, paperItem) → {Object|Object}

Parameters:
Name Type Description
annotationItem *
paperItem paper.Item
Source:
Returns:
Type
Object | Object

waitForNextPaintFrames(n) → {Promise.<void>}

Waits for `n` requestAnimationFrame ticks (falls back to setTimeout). Useful to ensure painted state after OSD viewport operations.
Parameters:
Name Type Description
n number Number of frames to wait
Source:
Returns:
Type
Promise.<void>