Draw a control measure

draw(draft, options?) starts an interactive draw and resolves on commit with { graphic, render }. The graphic is a defensive copy, so you can safely add it to your application state.

Choose a control measure, select Draw, then select points on the map.

AmbushMain AttackFortified AreaBlockLoading map…

const { graphic } = await td.draw({
  kind: "block",
  style: { color: "#dc2626", strokeWidth: 3 },
  properties: { source: "toolbar" }, // your metadata, copied onto the committed measure
});

measures.push(graphic);
td.render(measures);

The draft

Only kind is required. You may also provide id, controlPoints, options, style, textAmplifiers, and properties; they are copied onto the committed measure. TacticalDraw generates a missing ID with the constructor's generateId. For variable-length kinds, controlPoints seeds the draw with existing points. The TypeScript type is DrawMeasureDraft<K>, so options is typed for the chosen kind.

Point symbols and Images use the same method with their own drafts:

// Point symbol: `kind` and `sidc` are required. Commits on one click.
await td.draw({ kind: "point-symbol", sidc: "130315003611010300000000000000" });

// Image: `kind`, `resourceId`, and `intrinsicSize` are required.
await td.draw({ kind: "image", resourceId, intrinsicSize: { width: 1600, height: 900 } });

Both need a capability configured on the constructor; see Optional point symbols and Host-backed Images.

Commit behavior

Fixed-length kinds commit as soon as the user places the final required point (minCoordinates === maxCoordinates). Examples include Block, Disrupt, Attack by Fire, Support by Fire, and Bypass.

Variable-length kinds commit after one of these actions:

• Call session.commit().
• Double-click the map.
• Select the last point again.

Double-click zoom is disabled during the draw and restored when it ends. Press Escape to cancel the draw; the promise rejects with reason "escape".

See Variable-length draw with Done / Cancel buttons for wiring a commit UI.

Modifiers and snapping

• Hold Shift while placing or dragging a point to constrain angles, for kinds whose draw rule supports it (such as Sector). Set another key with editModifiers.
• Enable snapping to place points exactly on existing control points or graphic edges.

The session

Use options.onSession to receive the DrawSession. It exposes controlPoints, canCommit, commit(), abort(), and the subscriptions below. You can also read the live session from td.activeSession. See the DrawSession reference for every member.

onCommit and onSettled

session.onCommit(handler) runs synchronously once when the draw commits, whether by session.commit(), double-click, selecting the last point again, or placing the final point of a fixed-length kind. It receives the same snapshot as the draw() promise and does not run after an abort.

session.onSettled(handler) runs once after either commit or abort, after onCommit and after td.activeSession becomes null. A late subscription runs asynchronously. EditSession follows the same timing.

onTransientChange

session.onTransientChange(listener) reports live geometry for every rubber-band pointer movement:

• points: the working control points, with the live point included.
• pointIndex: the index of the live point in points.
• phase: "start" on the first movement, "move" on later movements, and "end" once when the session settles.

Measurements are not precomputed. Derive them from points; for example, haversineDistance from @orbat-mapper/control-measures returns ground distance in meters. See Show a live radius for a full example.

DrawOptions

Field	What it does
signal	An AbortSignal to cancel the draw. Rejects with reason "signal".
onSession	Called once for each draw before pointer events flow. Use it to subscribe to session changes; the live session is also available as td.activeSession.
guide	Opt out of the rubber-band guide (default true). Auto-suppressed for point kinds, and for fixed-length kinds unless the kind's draw rule opts back in via showGuide.
interactionStyle	Per-call style override. Only the guide slot applies to draws; it merges over constructor defaults and built-ins.
sizeAnchor	Sets the anchor for geometry and label pixel sizes. The default "ground" value converts pixels to meters at commit. The "screen" value keeps a constant screen size and renders again after zoom. It has no effect on kinds that contain only meter sizes. TacticalDraw does not store this option.