@niivue/uikit 1.0.0-rc.1

package/README.md

@@ -0,0 +1,61 @@
+# @niivue/uikit
+
+UIKit: a collection of controls and widgets (rulers, crosshairs, annotations,
+and later buttons, sliders, panels) integrated into the
+[NiiVue](https://github.com/niivue/niivue) rendering lifecycle.
+
+> **Status: shipping widgets.** The rendering-lifecycle hook, UIKit's own
+> line/text renderers (WebGL2 + WebGPU, with a text transform), and the first
+> widgets (ruler, annotation, crosshair) are in. See `docs/ruler-port.md` in
+> `@niivue/niivue` for the design.
+
+## Design in one paragraph
+
+UIKit is a **separate module with privileged access to NiiVue's rendering
+lifecycle**. NiiVue core exposes a small hook (an overlay draw phase + a backend
+handle + a settled signal); UIKit registers into it and draws with **its own**
+line/text renderers on both backends. UIKit carries a duplicated copy of the line
+and text drawing so core stays untouched during a bake-in phase; once UIKit is
+proven, core's overlays cut over onto it and the duplicate in core is removed.
+
+## Widgets
+
+Each widget is a pure geometry builder (spec in, plain line + text draw data out,
+unit-testable without a GPU) paired with an overlay that owns the GPU resources
+and draws that data through the lifecycle hook.
+
+| Builder | Overlay | Draws |
+| --- | --- | --- |
+| `buildRuler` | `UIKitRulerOverlay` | A measuring ruler with graduated ticks and a distance label |
+| `buildCrosshair` | `UIKitCrosshairOverlay` | A screen-space cross marking a point, optionally graduated and numbered |
+| `buildAnnotationGeometry` | `UIKitAnnotationOverlay` | Free-form annotation lines |
+
+```ts
+import { loadDefaultFont, UIKitCrosshairOverlay } from '@niivue/uikit'
+
+// One font fetch, shared by every widget on the pane.
+const crosshair = new UIKitCrosshairOverlay(await loadDefaultFont())
+renderer.overlayDraw = (frame) => crosshair.drawOverlay(frame)
+
+crosshair.setCrosshair({
+  at: [x, y],
+  gapPx: 10, // leave the pixel being pointed at uncovered
+  showTicks: true,
+  showTickNumbers: true,
+  pxPerUnit: [devicePxPerUm, devicePxPerUm], // per axis: planes can be anisotropic
+  unitsPerTick: 100,
+  units: 'um',
+})
+```
+
+The builders are usable on their own if you want the geometry but not UIKit's
+renderers:
+
+```ts
+import { buildTerminatedLine, LineTerminator } from '@niivue/uikit'
+
+// A line with an arrowhead at the end, as plain LineData segments.
+const segments = buildTerminatedLine(0, 0, 100, 40, 2, [1, 0, 0, 1], {
+  end: LineTerminator.ARROW,
+})
+```

package/dist/annotationOverlay.d.ts

@@ -0,0 +1,31 @@
+import { AnnotationScreenShape, UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { LineData } from './line';
+import { UIKitFont } from './text/font';
+import { UIKitTextItem } from './textOverlay';
+export interface AnnotationGeometryOptions {
+    /** Device-pixel ratio; scales stroke width + label size for crisp output. */
+    dpr?: number;
+    /** Label em size in CSS pixels (multiplied by dpr). */
+    labelCssPx?: number;
+}
+/**
+ * Build the line + text geometry for a set of projected annotation shapes.
+ * Closed shapes (ellipse/rect/circle/freehand) draw as outline loops; line/arrow
+ * draw start->end (arrow gets an arrowhead). Pure, so it is unit-testable.
+ */
+export declare function buildAnnotationGeometry(shapes: readonly AnnotationScreenShape[], opts?: AnnotationGeometryOptions): {
+    lines: LineData[];
+    text: UIKitTextItem[];
+};
+export declare class UIKitAnnotationOverlay implements UIKitOverlayRenderer {
+    private readonly lines;
+    private readonly labels;
+    private shapes;
+    private options;
+    constructor(font: UIKitFont, options?: AnnotationGeometryOptions);
+    /** Set the shapes to draw next frame. Trigger a redraw via the controller. */
+    setShapes(shapes: readonly AnnotationScreenShape[], options?: AnnotationGeometryOptions): void;
+    clear(): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    destroy(): void;
+}

package/dist/crosshair.d.ts

@@ -0,0 +1,81 @@
+import { LineData } from './line';
+import { RGBA, Vec2 } from './ruler';
+import { UIKitTextItem } from './textOverlay';
+export interface CrosshairSpec {
+    /** Crosshair centre in screen pixels (the space the overlay draws in). */
+    at: Vec2;
+    /** Frame width in the same pixel space (the overlay frame's bounds). */
+    width: number;
+    /** Frame height in the same pixel space. */
+    height: number;
+    color?: RGBA;
+    /** Line thickness in pixels. Default 2. */
+    thickness?: number;
+    /**
+     * Radius of the hole left at the centre. Default 6. Set 0 for an unbroken
+     * cross.
+     */
+    gapPx?: number;
+    /**
+     * Arm length in pixels, measured outward from the edge of the gap. Omit for
+     * arms that run to the edge of the frame.
+     */
+    armPx?: number;
+    /**
+     * Draw graduation ticks along the arms, every unit outward from the centre,
+     * longer (and optionally numbered) every fifth. Needs `pxPerUnit`: without a
+     * scale there is nothing to graduate against and ticks are skipped. Default
+     * false.
+     */
+    showTicks?: boolean;
+    /**
+     * Screen pixels per graduation unit. Pass a pair to graduate the horizontal
+     * and vertical arms on their own scales -- these planes can be anisotropic
+     * (a slab that never downsamples one axis), and a single mean would read long
+     * on one arm and short on the other.
+     */
+    pxPerUnit?: number | readonly [number, number];
+    /**
+     * Units between minor ticks. Default 1. Set it when one unit is the wrong
+     * tick spacing at the current scale: a pane that zooms across three decades
+     * wants 100 um ticks at one end and half-micron ticks at the other, and the
+     * numbers then read the distance (`i * unitsPerTick`), not the tick count.
+     */
+    unitsPerTick?: number;
+    /** Half-length of a minor tick in pixels. Default 6 (majors are twice that). */
+    tickLength?: number;
+    /** Tick thickness in pixels. Default half the line thickness, minimum 1. */
+    tickThickness?: number;
+    /** Number the major ticks. Default false. Needs a font on the overlay. */
+    showTickNumbers?: boolean;
+    /**
+     * Unit suffix for the graduation numbers, e.g. 'um'. Omit for bare numbers.
+     * Worth setting on a pane whose scale changes with zoom, where a bare "10" is
+     * ambiguous.
+     */
+    units?: string;
+    /** Graduation number height in pixels. Default 18. */
+    sizePx?: number;
+    /** Number color. Defaults to the line color. */
+    textColor?: RGBA;
+    /**
+     * Outline width (px) for the numbers, for readability over busy backgrounds.
+     * Default 2; the outline color auto-contrasts the text color. Set 0 to
+     * disable.
+     */
+    textOutlineWidthPx?: number;
+}
+export interface CrosshairGeometry {
+    lines: LineData[];
+    text: UIKitTextItem[];
+}
+/**
+ * Build the cross as up to four clipped segments, plus graduation ticks and
+ * numbers when a scale is supplied.
+ *
+ * An axis is drawn only when the centre lies within the frame on the OTHER axis,
+ * so a crosshair panned off the left edge still shows its horizontal line (which
+ * says "the point is on this row, off to the left") but not a stray full-height
+ * vertical line at a column that is not on screen.
+ */
+export declare function buildCrosshair(spec: CrosshairSpec): CrosshairGeometry;

package/dist/crosshairOverlay.d.ts

@@ -0,0 +1,18 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { CrosshairSpec } from './crosshair';
+import { UIKitFont } from './text/font';
+export type CrosshairPlacement = Omit<CrosshairSpec, 'width' | 'height'>;
+export declare class UIKitCrosshairOverlay implements UIKitOverlayRenderer {
+    private readonly lines;
+    private readonly labels;
+    private placement;
+    private builtFor;
+    constructor(font?: UIKitFont, placement?: CrosshairPlacement);
+    /** Set (or move) the crosshair. Trigger a redraw via the host. */
+    setCrosshair(placement: CrosshairPlacement): void;
+    /** Clear the crosshair so nothing draws. */
+    clear(): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}