Overview
The WeaveBrushToolAction has many settings that decide how pen, finger and mouse input becomes a stroke. The SDK publishes them as plain data, so an application can build controls for them, validate values and save configurations without knowing each setting in advance. The SDK itself has no user interface.
Settings come in two kinds:
-
capture settings belong to an input profile and change which points are saved for new strokes.
-
draw settings belong to a look. A look is saved with each stroke, so every user and every export draws that stroke the same way. Strokes saved without a look are drawn exactly as in earlier releases.
Every default below is the value of the legacy preset, which reproduces the behaviour of earlier releases. Nothing changes until an application selects another preset.
| Some modes are introduced progressively. A setting whose mode is not implemented yet behaves as the legacy mode. |
Import
import {
BRUSH_TUNABLES,
BRUSH_PROFILE_TUNABLES,
BRUSH_LOOK_TUNABLES,
BRUSH_PROFILE_PRESETS,
BRUSH_LOOK_PRESETS,
BRUSH_SCENARIOS,
WeaveBrushPresetRegistry,
validateBrushTunablePatch,
} from "@inditextech/weave-sdk";
The list of settings
Each entry of BRUSH_TUNABLES has this shape:
type WeaveBrushTunable = {
key: string; // dotted path of the setting, unique inside its scope
scope: "profile" | "look";
path: string[];
stage: "capture" | "pressure" | "stabilizer" | "finalize" | "touch" | "outline" | "curve" | "width" | "ends" | "detail";
group: string; // heading a control is shown under
kind: "capture" | "draw";
type: "number" | "boolean" | "enum";
default: number | boolean | string | null; // value of the legacy preset
min?: number; max?: number; step?: number; integer?: boolean;
options?: string[];
nullable?: boolean;
unit?: "px" | "ms" | "Hz" | "fraction" | "canvas units" | "count";
help: string;
advanced?: boolean; // show in an "advanced" section
};
A value outside a setting’s range or option list is invalid. validateBrushTunablePatch(scope, patch) returns the problems
found in a partial profile or look; an empty list means the patch is valid.
Input profile settings (capture)
These settings live in an input profile, see Input profiles.
| Setting | Values | Default | Unit | Applied | Description |
|---|---|---|---|---|---|
|
legacy | coalesced |
|
capture |
legacy keeps one position per event; coalesced keeps every batched pen sample with its own position. |
|
|
now | event |
|
capture |
Time base of time-dependent filters: processing time or the time reported by each sample. |
|
|
0 to 3 |
|
px |
capture |
Samples closer than this to the last recorded one are skipped. |
|
off | tail |
|
capture |
Draw the browser-predicted tail ahead of the pen to hide latency. |
|
|
pointermove | pointerrawupdate |
|
capture |
Event that delivers samples. pointerrawupdate lowers latency where supported. (advanced) |
|
|
legacy | keep | holdLast |
|
capture |
How a pen pressure of 0 is treated: legacy replaces it with 0.5, keep records it, holdLast repeats the last non-zero value. |
|
|
legacy | timeEma | oneEuro | none |
|
capture |
Pressure smoothing: the legacy velocity-adaptive filter, a time-based one, the One Euro filter, or none. |
|
|
1 to 500 |
|
ms |
capture |
Time constant of the timeEma filter; larger is smoother and slower. |
|
0.01 to 10 |
|
Hz |
capture |
One Euro minimum cutoff: lower removes more jitter at slow speed. (advanced) |
|
0 to 1 |
|
capture |
One Euro speed coefficient: higher removes more lag at high speed. (advanced) |
|
|
0 to 0.5 |
|
fraction |
capture |
Lowest pressure that is recorded; prevents invisible strokes. |
|
backfill | average | none |
|
capture |
First point: backfill takes the next real sample, average takes the mean of the first movement readings, none keeps the contact reading. |
|
|
1 to 10 (whole) |
|
count |
capture |
Number of readings averaged by the average start policy. (advanced) |
|
backfill | none |
|
capture |
Last point: backfill takes the second-to-last pressure, none keeps the lift-off reading. |
|
|
none | oneEuro | pulledString | streamline |
|
capture |
Smooths the pen position while drawing. |
|
|
0.1 to 20 |
|
Hz |
capture |
One Euro minimum cutoff: lower removes more jitter at slow speed. |
|
0 to 1 |
|
capture |
One Euro speed coefficient: higher removes more lag at high speed. |
|
|
0 to 40 |
|
px |
capture |
Pulled string leash length: the pen must move this far before the line follows. |
|
0 to 1 |
|
fraction |
capture |
Streamline strength: 0 follows the pen exactly, 1 is the strongest smoothing. |
|
true | false |
|
capture |
Interpret the distances in screen pixels, so the effect on screen is the same at every zoom level. Off: canvas units. |
|
|
true | false |
|
capture |
Complete the stroke at the position where the pen was lifted. |
|
|
dp | dpPressure | bezierFit | none |
|
capture |
How points are reduced when the stroke ends: simplification, simplification keeping pressure detail, curve fitting, or nothing. |
|
|
0 to 20 |
|
capture |
Tolerance of the finishing step. Empty uses the tool-level tolerance. |
|
|
canvas | screen |
|
capture |
canvas: tolerance in canvas units. screen: in pixels, converted with the zoom when the stroke ends. |
|
|
0 to 200 |
|
capture |
Distance units per pressure unit when simplification keeps pressure detail. (advanced) |
|
|
0.5 to 20 |
|
px |
capture |
Spacing of the points a fitted curve is resampled to. (advanced) |
|
0 to 500 |
|
ms |
capture |
Wait before a finger stroke is committed, so a second finger can cancel it. |
|
0 to 40 |
|
px |
capture |
Movement that commits the stroke before the wait ends. |
|
true | false |
|
capture |
Cancel the stroke when a second finger lands during the wait. |
|
|
true | false |
|
capture |
Finger input does not draw once a pen has been used. |
Look settings (draw)
These settings live in the look saved with each stroke.
| Setting | Values | Default | Unit | Applied | Description |
|---|---|---|---|---|---|
|
legacy | round | freehand |
|
draw |
Shape of the stroke: legacy ribbon, round (discs and segments, no spikes) or freehand. |
|
|
uniform | centripetal | none |
|
draw |
Curve through the points. centripetal does not overshoot when points are unevenly spaced. |
|
|
catmullRom | linear |
|
draw |
How pressure is interpolated between points. linear never bulges. |
|
|
true | false |
|
draw |
Choose spacing and subdivision in screen pixels so smoothness does not depend on zoom. |
|
|
0.5 to 10 |
|
px |
draw |
Minimum spacing between control points. (advanced) |
|
0.25 to 5 |
|
px |
draw |
Detail of the curve. The centripetal curve keeps every edge within a tenth of this of the true curve; the uniform curve uses it as the target length of an edge. (advanced) |
|
separate | merged |
|
draw |
merged draws the round ends inside the same fill, so translucent colours stay uniform. |
|
|
0 to 1 |
|
fraction |
draw |
Width at pressure 0, as a fraction of the stroke width. |
|
0 to 1 |
|
fraction |
draw |
Width at pressure 1, as a fraction of the stroke width. |
|
0.2 to 3 |
|
draw |
Response curve: below 1 reacts faster to light pressure, above 1 needs a firmer press. |
|
|
0 to 200 |
|
px |
draw |
Distance over which the start narrows; 0 for none. |
|
0 to 200 |
|
px |
draw |
Distance over which the end narrows; 0 for none. |
Factory presets
A preset is a set of changes relative to the legacy profile or look. The factory presets are read-only. The values are starting points to be tuned on real hardware.
Profile mouse
| Preset | Id | Description |
|---|---|---|
Legacy |
|
Behaviour of earlier releases, point for point. |
Fixed |
|
Keeps every pen sample, uses event time, keeps zero pressure. |
Stabilized |
|
Fixed, plus One Euro position smoothing that follows the zoom and a Bézier-fitted finish. |
Pulled string |
|
Fixed, plus a pulled-string stabilizer. |
Profile touch
| Preset | Id | Description |
|---|---|---|
Legacy |
|
Behaviour of earlier releases, point for point. |
Fixed |
|
Keeps every pen sample, uses event time, keeps zero pressure. |
Guarded |
|
Fixed, plus a short wait that a second finger can cancel. |
Smooth |
|
Guarded, plus One Euro position smoothing and a Bézier-fitted finish. |
Profile pen.applePencil
| Preset | Id | Description |
|---|---|---|
Legacy |
|
Behaviour of earlier releases, point for point. |
Fixed |
|
Keeps every pen sample, uses event time, keeps zero pressure. |
Smooth |
|
Fixed, plus One Euro smoothing of pressure and position and a Bézier-fitted finish. |
Illustrator-like |
|
Fixed, plus streamline stabilizing and a Bézier-fitted finish in screen pixels. |
Profile pen.desktop
| Preset | Id | Description |
|---|---|---|
Legacy |
|
Behaviour of earlier releases, point for point. |
Fixed |
|
Keeps every pen sample, uses event time, keeps zero pressure. |
Smooth |
|
Fixed, plus One Euro smoothing of pressure and position and a Bézier-fitted finish. |
Illustrator-like |
|
Fixed, plus streamline stabilizing and a Bézier-fitted finish in screen pixels. |
Look
| Preset | Id | Description |
|---|---|---|
Legacy |
|
No look is stored: strokes are drawn as in earlier releases. |
Width curve |
|
Legacy outline with a minimum width and a pressure curve. |
Round |
|
Round outline: no spikes at turns, uniform translucent colour. |
Freehand |
|
Freehand outline. |
Illustrator-like |
|
Round outline with a Size ± Variation style width range. |
Scenarios
A scenario selects one preset for each profile and one look preset.
| Scenario | mouse |
touch |
pen.applePencil |
pen.desktop |
Look | Description |
|---|---|---|---|---|---|---|
A: legacy |
legacy |
legacy |
legacy |
legacy |
legacy |
Today’s behaviour, identical point for point. |
B: fixes |
fixed |
fixed |
fixed |
fixed |
legacy |
Every pen sample, event time and zero pressure kept. |
C: smooth |
stabilized |
smooth |
smooth |
smooth |
widthCurve |
B plus smoothing and a pressure curve. |
D: round |
stabilized |
smooth |
smooth |
smooth |
round |
C plus the round outline. |
E: freehand |
fixed |
fixed |
fixed |
fixed |
freehand |
B plus the freehand outline. |
F: Illustrator-like |
stabilized |
smooth |
illustrator |
illustrator |
illustrator |
Bézier-fitted finish, streamline stabilizing and a Size ± Variation width. |
Applying scenario A leaves every profile on its legacy preset and stores no look, so strokes are recorded and drawn exactly as in earlier releases.
const brush = weave.getActionHandler<WeaveBrushToolAction>("brushTool");
brush.applyScenario("B");
Custom presets
WeaveBrushPresetRegistry holds the factory presets and any custom ones. A factory preset cannot be changed or removed; copy
it under a new id and change the copy. Custom presets live in memory: the application decides whether to save them.
const registry = new WeaveBrushPresetRegistry();
registry.copyProfilePreset("pen.desktop", "smooth", "my-wacom", "My Wacom");
registry.setProfilePreset("pen.desktop", "my-wacom", { pressure: { floor: 0.1 } });
brush.applyScenario(
{ ...BRUSH_SCENARIOS[1], id: "mine", profiles: { ...BRUSH_SCENARIOS[1].profiles, "pen.desktop": "my-wacom" } },
registry
);
Saving and restoring a configuration
| Method | Description |
|---|---|
|
The four profiles and the look as a document with a |
|
The same document as JSON text. |
|
Restores a configuration. A document with an unsupported version or invalid values is rejected as a whole and nothing changes. |
|
The look saved on new strokes. |
|
Applies a scenario. Returns |