Weave.js

WeaveBrushLabPlugin

Opt-in plugin to measure and compare brush settings on real pen devices

Overview

WeaveBrushLabPlugin helps tune the brush tool on real hardware. It listens to the brush tool, reports what the device sends, draws overlays of the captured samples and measures every stroke.

The plugin is opt in. It lives in its own entry point, @inditextech/weave-sdk/lab, so applications that do not import it carry none of its code.

The lab keeps everything it records in memory only. It never stores, uploads or downloads recordings, and it adds no node to the document. Ghosts and metrics are gone when the page is reloaded.

Import

import { WeaveBrushLabPlugin } from "@inditextech/weave-sdk/lab";

const lab = new WeaveBrushLabPlugin({ maxGhosts: 5 });

Register it with the other plugins. The brush tool finds it by the name brushLab. While the plugin is enabled, strokes also save an inputMeta attribute that says which profile, preset and scenario drew them.

Methods

Method Description

enable() / disable()

Turns the lab on or off. Off hides its layer and stops listening.

getDeviceReport()

Pointer type, resolved profile, sample rate, samples per event, pressure range, tilt, predicted-event support, zoom, frames per second and warnings.

setOverlay(name

Switches an overlay: raw, stabilized, final or pressure.

getLastMetrics()

Metrics of the last stroke.

compareLast(scenarioId)

Draws the last stroke as it was drawn (black) and again through the chosen brush (scenario id, red), labelled. Choosing another brush replaces the first.

clearGhosts()

Forgets the kept strokes and removes the comparison.

setMaxGhosts(n)

Number of strokes kept for ghosts, 5 by default. The oldest are dropped.

Device report

The report is built from pointer events. A penReportsAsMouse warning appears when a pointer that says it is a mouse sends pressure or tilt, as a pen does when the driver does not use the pointer API (for example Windows Ink off).

Overlays

Overlays are drawn on a layer of the lab, not in the document.

  • raw one dot per sample the device reported, where it landed.

  • stabilized one dot per sample after stabilizing.

  • final the points kept after the stroke is finished.

  • pressure the pressure along the stroke.

Metrics

After each stroke the plugin emits onBrushLabMetrics with:

Field Meaning

samples

Samples reported by the device, predicted ones left out.

points

Points kept after finishing.

droppedDuplicates

Consecutive samples at the same position.

effectiveRateHz

Samples per second.

jitter

Mean distance of a raw sample from the line through its neighbours.

lag

Mean distance between raw and stabilized samples.

movedOnFinish

Largest distance a point moved when the stroke was finished.

widthRoughness

Mean change of width between neighbouring points.

drawMs

Time spent processing and finishing the stroke.

Comparing brushes

While enabled, the lab records the pointer events of every gesture itself, whatever brush is active: every coalesced sample of every event, with its time, in drawing coordinates. compareLast() replays the last gesture through the chosen brush: the capture it uses (all coalesced samples, or the last sample of each event), its minimum move, its stabilizer and its finishing step, and draws the resulting line. Each coalesced sample keeps its own time, as the brush reads it, and a stabilized stroke is completed where the pen was lifted when its stabilizer.catchUpOnEnd is on, as the brush does. Predicted samples are not replayed.

Only positions are replayed. Width, pressure smoothing and the outline are not, so a comparison shows how each brush places and simplifies the line, not how it looks when drawn.

The last maxGhosts recordings (5 by default) are kept in memory, the oldest are dropped, and the comparison is removed when the next stroke starts.