ComPDFKit Web SDK
    Preparing search index...

    Class MeasurementManager

    Manages the scales of measurement annotations and measurement tools.

    Measurement items are grouped by their scale string (such as 1 in = 1 ft). Applying a scale to an annotation re-measures it; applying a scale to a tool affects the annotations it creates afterwards. The calibration tool and the annotations it draws are not measurement items.

    Get the instance with documentViewer.getMeasurementManager().

    const { documentViewer, Scale } = instance.Core;
    const measurementManager = documentViewer.getMeasurementManager();

    measurementManager.addEventListener('scaleUpdated', (scales) => {
    console.log(Object.keys(scales)); // ['1 in = 1 ft']
    });

    // Use 1 inch on the page for 1 foot in the world for every measurement tool.
    await measurementManager.createAndApplyScale({
    scale: new Scale([[1, 'in'], [1, 'ft']]),
    applyTo: [],
    });

    Hierarchy (View Summary)

    Index
    • Adds a listener for an event. Adding the same function twice for one event has no effect.

      Type Parameters

      • K extends keyof MeasurementManagerEvents

      Parameters

      • name: K

        Event name.

      • fn: (...args: MeasurementManagerEvents[K]) => void

        Listener, called with the event arguments.

      • Optionaloptions: { once?: boolean }

        Listener options.

        • Optionalonce?: boolean

          When true, the listener is removed after it runs once.

      Returns void

    • Applies a scale to measurement annotations and tools, and triggers scaleUpdated. When no scale exists yet, the scale is applied to every measurement tool and applyTo is ignored. When items already use the same scale, the scale takes their precision.

      Parameters

      Returns Promise<void>

      const [annotation] = annotationManager.getSelectedAnnotations();
      await measurementManager.createAndApplyScale({
      scale: new instance.Core.Scale([[1, 'cm'], [2, 'm']]),
      applyTo: [annotation],
      });
    • Deletes a scale and triggers scaleUpdated. Annotations using the scale are deleted; tools using it switch to the first remaining scale. The last remaining scale cannot be deleted: a warning is logged and nothing changes.

      Parameters

      • scale: Scale

        The scale to delete.

      Returns Promise<void>

    • Stops setStyles on a measurement tool from restyling existing annotations.

      Returns void

    • Makes setStyles on a measurement tool also restyle the annotations that use the same scale. Off by default.

      Returns void

    • Gets the precision used by the items that use a scale.

      Parameters

      • scale: Scale

        The scale to look up.

      Returns number | undefined

      The precision, such as 0.01, or undefined when no item uses the scale.

    • Gets every scale in use and the measurement items that use it. Measurement tools that have no scale yet are given the first scale.

      Returns Record<string, MeasurementItem[]>

      An object whose keys are scale strings (such as 1 in = 1 ft) and whose values are the annotations and tools using that scale.

      const scales = measurementManager.getScales();
      for (const [scale, items] of Object.entries(scales))
      console.log(scale, items.length);
    • Tells whether style syncing between measurement tools and annotations is on.

      Returns boolean

      true after enableAnnotationAndToolStyleSyncing, otherwise false.

    • Removes a listener, or every listener of the event when fn is omitted.

      Type Parameters

      • K extends keyof MeasurementManagerEvents

      Parameters

      • name: K

        Event name.

      • Optionalfn: (...args: MeasurementManagerEvents[K]) => void

        The function that was passed to addEventListener.

      Returns void

    • Replaces a scale with another one on every annotation and tool that uses it, and triggers scaleUpdated.

      Parameters

      • oldScale: Scale

        The scale to replace.

      • newScale: Scale

        The scale to use instead.

      Returns Promise<void>

      const { Scale } = instance.Core;
      await measurementManager.replaceScale(new Scale('1 in = 1 ft'), new Scale('1 in = 2 ft'));
    • Replaces several scales with one scale on every annotation and tool that uses them, and triggers scaleUpdated.

      Parameters

      • oldScales: Scale[]

        The scales to replace.

      • newScale: Scale

        The scale to use instead.

      Returns Promise<void>

    • Turns a distance measurement around its start point to the given angle, keeping its length; the end point is kept inside the page. ComPDFKit extension.

      Parameters

      • annotation: LineAnnotation

        A distance measurement line.

      • degrees: number

        The angle from the positive x axis, counter-clockwise as seen on the page.

      Returns Promise<void>

      // Point the line straight up from its start point.
      await measurementManager.setMeasuredAngle(line, 90);
    • Sets the measured length of a distance measurement, in the world unit of its scale. The left end of the line stays where it is and the other end moves along the line; the result is kept inside the page. The change is committed like annotationManager.updateAnnotation. ComPDFKit extension.

      Parameters

      • annotation: LineAnnotation

        A distance measurement line.

      • length: number

        The new length in the world unit of the annotation's scale (for 1 in = 1 ft, in feet).

      Returns Promise<void>

      const [line] = annotationManager.getSelectedAnnotations();
      if (line instanceof instance.Core.Annotations.LineAnnotation && line.Measure)
      await measurementManager.setMeasuredLength(line, 3);
    • Sets the measured width (horizontal side) and / or height (vertical side) of a rectangular area measurement, in the world unit of its scale. The top-left corner stays where it is; the result is kept inside the page. Polygons that are not axis-aligned rectangles are left unchanged. ComPDFKit extension.

      Parameters

      • annotation: PolygonAnnotation

        A rectangular area measurement (a polygon whose vertices are the corners of an axis-aligned rectangle).

      • size: { height?: number; width?: number }

        The new size in the world unit of the annotation's scale.

        • Optionalheight?: number

          The new vertical side; omit to keep it.

        • Optionalwidth?: number

          The new horizontal side; omit to keep it.

      Returns Promise<void>

      // Make the rectangle 5 units wide and keep its height.
      await measurementManager.setMeasuredSize(rectangle, { width: 5 });
    • A listener that throws does not affect the others; the error is reported through logger.error.

      Type Parameters

      • K extends keyof MeasurementManagerEvents

      Parameters

      • name: K
      • Optionalargs: MeasurementManagerEvents[K]

      Returns void

    • Like trigger, but awaits the Promise returned by each listener in turn; a failing listener does not affect the others.

      Type Parameters

      • K extends keyof MeasurementManagerEvents

      Parameters

      • name: K
      • Optionalargs: MeasurementManagerEvents[K]

      Returns Promise<void>

    Events: {
        CREATE_ANNOTATION_WITH_NO_SCALE: "createAnnotationWithNoScale";
        SCALE_UPDATED: "scaleUpdated";
    }

    Names of the events this class triggers.

    Type Declaration

    • ReadonlyCREATE_ANNOTATION_WITH_NO_SCALE: "createAnnotationWithNoScale"

      'createAnnotationWithNoScale': fired when a measurement tool cannot create an annotation because no scale is set.

    • ReadonlySCALE_UPDATED: "scaleUpdated"

      'scaleUpdated': fired when scales are created, changed or deleted.