@niivue/uikit 1.0.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { AnnotationGeometryOptions } from './annotationOverlay';
+export { buildAnnotationGeometry, UIKitAnnotationOverlay, } from './annotationOverlay';
+export type { CrosshairGeometry, CrosshairSpec } from './crosshair';
+export { buildCrosshair } from './crosshair';
+export type { CrosshairPlacement } from './crosshairOverlay';
+export { UIKitCrosshairOverlay } from './crosshairOverlay';
+export type { LineData, LineTerminators } from './line';
+export { buildLine, buildTerminatedLine, LineTerminator } from './line';
+export { UIKitLineOverlay } from './lineOverlay';
+export type { RulerGeometry, RulerSpec, Vec2 } from './ruler';
+export { buildRuler } from './ruler';
+export { UIKitRulerOverlay } from './rulerOverlay';
+export { loadDefaultFont } from './text/defaultFont';
+export type { RawFontFile, UIKitFont, UIKitFontMetrics, UIKitGlyph, } from './text/font';
+export { parseFont, screenPxRange } from './text/font';
+export type { RGBA, TextLayoutOptions } from './text/layout';
+export { autoOutlineColor, layoutText, measureWidth, readableAngle, } from './text/layout';
+export type { UIKitTextItem } from './textOverlay';
+export { UIKitTextOverlay } from './textOverlay';

package/dist/line.d.ts

@@ -0,0 +1,34 @@
+export type LineData = {
+    data: Float32Array;
+};
+export declare const FLOATS_PER_LINE = 12;
+export declare function buildLine(startX: number, startY: number, endX: number, endY: number, thickness?: number, color?: readonly number[]): LineData;
+/**
+ * Line-end decorations. Only NONE and ARROW are implemented; CIRCLE and RING are
+ * reserved so callers and the enum can grow to the old uikit terminator set (they
+ * need a filled-disc primitive that this line-segment builder does not provide).
+ */
+export declare enum LineTerminator {
+    NONE = 0,
+    ARROW = 1,
+    CIRCLE = 2,
+    RING = 3
+}
+export interface LineTerminators {
+    /** Decoration at the start point. Defaults to NONE. */
+    start?: LineTerminator;
+    /** Decoration at the end point. Defaults to NONE. */
+    end?: LineTerminator;
+}
+/**
+ * A line plus optional end/start terminators, returned as plain {@link LineData}
+ * segments (the shaft first, then any terminator barbs). Terminators are composed
+ * from short line segments, so a plain line renderer draws them unchanged and both
+ * backends render them identically. Mirrors the old uikit `drawLine({ terminator })`
+ * in this data-emitting model.
+ *
+ * ARROW shortens the shaft by half a barb length at the terminated end so it does
+ * not poke through the arrowhead. A zero-length line has no direction, so it is
+ * returned as the bare shaft with no terminators.
+ */
+export declare function buildTerminatedLine(startX: number, startY: number, endX: number, endY: number, thickness?: number, color?: readonly number[], terminators?: LineTerminators): LineData[];

package/dist/lineOverlay.d.ts

@@ -0,0 +1,13 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { LineData } from './line';
+export declare class UIKitLineOverlay implements UIKitOverlayRenderer {
+    private lines;
+    private readonly gl;
+    private readonly wgpu;
+    constructor(lines?: LineData[]);
+    /** Replace the lines drawn each frame. Trigger a redraw via the controller. */
+    setLines(lines: LineData[]): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}

package/dist/render/glLineRenderer.d.ts

@@ -0,0 +1,13 @@
+import { LineData } from '../line';
+export declare class GlLineRenderer {
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uCanvasSize;
+    private scratch;
+    private ensure;
+    /** Draw `lines` in screen-pixel space over a `width` x `height` bounds rect. */
+    draw(gl: WebGL2RenderingContext, lines: LineData[], width: number, height: number): void;
+    destroy(): void;
+}

package/dist/render/glTextRenderer.d.ts

@@ -0,0 +1,16 @@
+export declare class GlTextRenderer {
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private texture;
+    private textureImage;
+    private uCanvasSize;
+    private uScreenPxRange;
+    private uFontTexture;
+    private ensureProgram;
+    private ensureTexture;
+    /** Draw one already-laid-out glyph run (screen-pixel vertices). */
+    draw(gl: WebGL2RenderingContext, image: ImageBitmap, vertices: Float32Array, count: number, screenPxRange: number, width: number, height: number): void;
+    destroy(): void;
+}

package/dist/render/shaders.d.ts

@@ -0,0 +1,6 @@
+export declare const GL_LINE_VERT = "#version 300 es\nprecision highp float;\nuniform vec2 canvasSize;\nin vec2 lineStart;\nin vec2 lineEnd;\nin float lineThickness;\nin vec4 lineColor;\nout vec4 vColor;\n\nvoid main() {\n  int vIdx = gl_VertexID;\n  vec2 delta = lineEnd - lineStart;\n  vec2 dir = normalize(delta);\n  vec2 perp = vec2(-dir.y, dir.x);\n  float halfThickness = lineThickness * 0.5;\n  vec2 offset;\n  if (vIdx == 0) {\n    offset = -perp * halfThickness;\n  } else if (vIdx == 1) {\n    offset = perp * halfThickness;\n  } else if (vIdx == 2) {\n    offset = -perp * halfThickness + delta;\n  } else {\n    offset = perp * halfThickness + delta;\n  }\n  vec2 pixelPos = lineStart + offset;\n  vec2 ndc = (pixelPos / canvasSize) * 2.0 - 1.0;\n  gl_Position = vec4(ndc.x, -ndc.y, 0.0, 1.0);\n  vColor = lineColor;\n}\n";
+export declare const GL_LINE_FRAG = "#version 300 es\nprecision highp float;\nin vec4 vColor;\nout vec4 fragColor;\n\nvoid main() {\n  fragColor = vColor;\n}\n";
+export declare const WGSL_LINE = "\nstruct LineUniforms {\n    canvasSize: vec2f,\n};\n\nstruct Line {\n    start: vec2f,\n    end: vec2f,\n    thickness: f32,\n    _pad0: f32,\n    _pad1: f32,\n    _pad2: f32,\n    color: vec4f,\n};\n\n@group(0) @binding(0) var<uniform> u: LineUniforms;\n@group(0) @binding(1) var<storage, read> lines: array<Line>;\n\nstruct VertexOutput {\n    @builtin(position) position: vec4f,\n    @location(0) color: vec4f,\n};\n\n@vertex\nfn vertex_main(\n    @builtin(vertex_index) vIdx: u32,\n    @builtin(instance_index) iIdx: u32\n) -> VertexOutput {\n    let line = lines[iIdx];\n    let delta = line.end - line.start;\n    let dir = normalize(delta);\n    let perp = vec2f(-dir.y, dir.x);\n    let halfThickness = line.thickness * 0.5;\n    var offset = vec2f(0.0);\n    if (vIdx == 0u) {\n        offset = -perp * halfThickness;\n    } else if (vIdx == 1u) {\n        offset = perp * halfThickness;\n    } else if (vIdx == 2u) {\n        offset = -perp * halfThickness + delta;\n    } else {\n        offset = perp * halfThickness + delta;\n    }\n    let pixelPos = line.start + offset;\n    let ndc = (pixelPos / u.canvasSize) * 2.0 - 1.0;\n    var out: VertexOutput;\n    out.position = vec4f(ndc.x, -ndc.y, 0.0, 1.0);\n    out.color = line.color;\n    return out;\n}\n\n@fragment\nfn fragment_main(in: VertexOutput) -> @location(0) vec4f {\n    return in.color;\n}\n";
+export declare const GL_TEXT_VERT = "#version 300 es\nprecision highp float;\nuniform vec2 canvasSize;\nin vec2 pos;\nin vec2 uv;\nin vec4 color;\nout vec2 vUv;\nout vec4 vColor;\n\nvoid main() {\n  vec2 ndc = (pos / canvasSize) * 2.0 - 1.0;\n  gl_Position = vec4(ndc.x, -ndc.y, 0.0, 1.0);\n  vUv = uv;\n  vColor = color;\n}\n";
+export declare const GL_TEXT_FRAG = "#version 300 es\nprecision highp float;\nuniform highp sampler2D fontTexture;\nuniform float screenPxRange;\nin vec2 vUv;\nin vec4 vColor;\nout vec4 fragColor;\n\nfloat median(float r, float g, float b) {\n  return max(min(r, g), min(max(r, g), b));\n}\n\nvoid main() {\n  vec3 msd = texture(fontTexture, vUv).rgb;\n  float sd = median(msd.r, msd.g, msd.b);\n  float opacity = clamp(screenPxRange * (sd - 0.5) + 0.5, 0.0, 1.0);\n  if (opacity <= 0.0) discard;\n  fragColor = vec4(vColor.rgb, vColor.a * opacity);\n}\n";
+export declare const WGSL_TEXT = "\nstruct TextUniforms {\n    canvasSize: vec2f,\n    screenPxRange: f32,\n    _pad: f32,\n};\n\n@group(0) @binding(0) var<uniform> u: TextUniforms;\n@group(0) @binding(1) var fontTex: texture_2d<f32>;\n@group(0) @binding(2) var fontSampler: sampler;\n\nstruct VertexOutput {\n    @builtin(position) position: vec4f,\n    @location(0) uv: vec2f,\n    @location(1) color: vec4f,\n};\n\n@vertex\nfn vertex_main(\n    @location(0) pos: vec2f,\n    @location(1) uv: vec2f,\n    @location(2) color: vec4f\n) -> VertexOutput {\n    var out: VertexOutput;\n    let ndc = (pos / u.canvasSize) * 2.0 - 1.0;\n    out.position = vec4f(ndc.x, -ndc.y, 0.0, 1.0);\n    out.uv = uv;\n    out.color = color;\n    return out;\n}\n\nfn median(r: f32, g: f32, b: f32) -> f32 {\n    return max(min(r, g), min(max(r, g), b));\n}\n\n@fragment\nfn fragment_main(in: VertexOutput) -> @location(0) vec4f {\n    let msd = textureSample(fontTex, fontSampler, in.uv).rgb;\n    let sd = median(msd.r, msd.g, msd.b);\n    let opacity = clamp(u.screenPxRange * (sd - 0.5) + 0.5, 0.0, 1.0);\n    return vec4f(in.color.rgb, in.color.a * opacity);\n}\n";

package/dist/render/wgpuLineRenderer.d.ts

@@ -0,0 +1,16 @@
+import { LineData } from '../line';
+export declare class WgpuLineRenderer {
+    private device;
+    private pipeline;
+    private bindLayout;
+    private paramsBuffer;
+    private storageBuffer;
+    private bindGroup;
+    private capacity;
+    private key;
+    private ensurePipeline;
+    private ensureCapacity;
+    /** Append `lines` (screen-pixel space) to the open pass over a bounds rect. */
+    draw(device: GPUDevice, pass: GPURenderPassEncoder, colorFormat: GPUTextureFormat, sampleCount: number, depthFormat: GPUTextureFormat | undefined, lines: LineData[], width: number, height: number): void;
+    destroy(): void;
+}

package/dist/render/wgpuTextRenderer.d.ts

@@ -0,0 +1,34 @@
+/** One already-laid-out glyph run to draw: its vertices, vertex count and AA range. */
+export type TextRun = {
+    vertices: Float32Array;
+    count: number;
+    screenPxRange: number;
+};
+export declare class WgpuTextRenderer {
+    private device;
+    private pipeline;
+    private bindLayout;
+    private uniformBuffer;
+    private vertexBuffer;
+    private sampler;
+    private texture;
+    private textureImage;
+    private bindGroup;
+    private capacityBytes;
+    private uniformCapacity;
+    private key;
+    private ensurePipeline;
+    private ensureTexture;
+    private ensureUniformBuffer;
+    private ensureVertexBuffer;
+    private ensureBindGroup;
+    /**
+     * Draw all already-laid-out glyph runs into the open pass. Every run's
+     * vertices are packed into one vertex buffer and its (width, height,
+     * screenPxRange) uniform into its own 256-byte slot, so each draw reads its
+     * own data — writing every run into a single shared buffer would collapse to
+     * the last run before the deferred pass executes.
+     */
+    drawAll(device: GPUDevice, pass: GPURenderPassEncoder, colorFormat: GPUTextureFormat, sampleCount: number, depthFormat: GPUTextureFormat | undefined, image: ImageBitmap, runs: readonly TextRun[], width: number, height: number): void;
+    destroy(): void;
+}

package/dist/ruler.d.ts

@@ -0,0 +1,47 @@
+import { LineData } from './line';
+import { UIKitTextItem } from './textOverlay';
+export type Vec2 = readonly [number, number];
+export type RGBA = readonly [number, number, number, number];
+export interface RulerSpec {
+    /** Endpoints in screen pixels. */
+    a: Vec2;
+    b: Vec2;
+    /** Measured length to display (in `units`). */
+    length: number;
+    /** Unit suffix, e.g. 'mm'. */
+    units?: string;
+    /** Label text height in pixels. Default 36. */
+    sizePx?: number;
+    /** Decimals in the length label. Default 1. */
+    decimals?: number;
+    lineColor?: RGBA;
+    textColor?: RGBA;
+    /** Line thickness in pixels. Default 2. */
+    thickness?: number;
+    /** Half-length of a minor tick in pixels. Default 6. */
+    tickLength?: number;
+    /** Draw tick marks every unit (majors every 5). Default true. */
+    showTicks?: boolean;
+    /** Draw the number at every major tick. Default false. */
+    showTickNumbers?: boolean;
+    /**
+     * Draw long perpendicular end caps crossing the start and end points to mark
+     * the measurement's exact extent (longer than a major tick). Default true.
+     */
+    showEndCaps?: boolean;
+    /**
+     * Outline width (px) for the label + tick text, for readability over busy
+     * backgrounds. Default 2. The outline color auto-contrasts the text color
+     * (black on light text, white on dark). Set 0 to disable.
+     */
+    textOutlineWidthPx?: number;
+}
+export interface RulerGeometry {
+    lines: LineData[];
+    text: UIKitTextItem[];
+}
+/**
+ * Build the line + text draw data for a ruler. Pure geometry; font-independent
+ * (glyph widths are resolved when the text is laid out at draw time).
+ */
+export declare function buildRuler(spec: RulerSpec): RulerGeometry;

package/dist/rulerOverlay.d.ts

@@ -0,0 +1,16 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { RulerSpec } from './ruler';
+import { UIKitFont } from './text/font';
+export declare class UIKitRulerOverlay implements UIKitOverlayRenderer {
+    private readonly lines;
+    private readonly labels;
+    private hasRuler;
+    constructor(font: UIKitFont, spec?: RulerSpec);
+    /** Set (or update) the ruler. Trigger a redraw via the controller. */
+    setRuler(spec: RulerSpec): void;
+    /** Clear the ruler so nothing draws. */
+    clear(): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}

package/dist/text/defaultFont.d.ts

@@ -0,0 +1,3 @@
+import { UIKitFont } from './font';
+/** Fetch + decode the bundled Ubuntu atlas and parse its metrics. */
+export declare function loadDefaultFont(): Promise<UIKitFont>;

package/dist/text/font.d.ts

@@ -0,0 +1,55 @@
+export interface UIKitGlyph {
+    /** [left, bottom, width, height] in [0,1] atlas UV space. */
+    readonly uv: readonly [number, number, number, number];
+    /** [left, bottom, width, height] in em units (quad to place). */
+    readonly plane: readonly [number, number, number, number];
+    /** Horizontal advance in em units. */
+    readonly xadv: number;
+}
+export interface UIKitFontMetrics {
+    /** MSDF distance range in pixels (from atlas gen). */
+    readonly distanceRange: number;
+    /** Atlas glyph em size in pixels. */
+    readonly size: number;
+    /** Atlas texture dimensions in pixels. */
+    readonly textureSize: readonly [number, number];
+    readonly glyphs: ReadonlyMap<string, UIKitGlyph>;
+}
+/** A parsed font plus its uploaded-once atlas image, consumed by the renderers. */
+export interface UIKitFont {
+    readonly metrics: UIKitFontMetrics;
+    readonly image: ImageBitmap;
+}
+interface RawGlyph {
+    unicode: number;
+    advance: number;
+    atlasBounds?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    planeBounds?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+export interface RawFontFile {
+    atlas: {
+        width: number;
+        height: number;
+        distanceRange: number;
+        size: number;
+    };
+    glyphs: RawGlyph[];
+}
+/** Parse msdf-atlas-gen JSON into a UIKit font metrics table. */
+export declare function parseFont(raw: RawFontFile): UIKitFontMetrics;
+/**
+ * MSDF anti-aliasing range in screen pixels for a given text size, matching the
+ * old uikit: `max((size / atlasSize) * distanceRange, 1)`. Passed to the shader.
+ */
+export declare function screenPxRange(metrics: UIKitFontMetrics, sizePx: number): number;
+export {};

package/dist/text/layout.d.ts

@@ -0,0 +1,54 @@
+import { UIKitFontMetrics } from './font';
+export declare const FLOATS_PER_VERTEX = 8;
+export declare const VERTICES_PER_GLYPH = 6;
+export type RGBA = readonly [number, number, number, number];
+export interface TextLayoutOptions {
+    /** Anchor position in screen pixels (baseline reference before alignment). */
+    x: number;
+    y: number;
+    /** Text height in screen pixels (the em size; scales the atlas plane bounds). */
+    sizePx: number;
+    /** Rotation in radians, measured in screen space (0 = left-to-right, y-down). */
+    rotation?: number;
+    color?: RGBA;
+    /** Horizontal alignment along the (rotated) baseline: 0 left, 0.5 center, 1 right. */
+    align?: number;
+    /** Shift perpendicular to the text direction, in pixels (positive = above line). */
+    liftPx?: number;
+    /**
+     * Outline (halo) width in screen pixels; 0 (default) draws no outline. The
+     * effective width is bounded by the atlas SDF range, so a small value (1-2)
+     * reads best with the bundled MSDF atlas.
+     */
+    outlineWidthPx?: number;
+    /**
+     * Outline color. Omit to auto-pick black or white for contrast against the
+     * fill color (see {@link autoOutlineColor}).
+     */
+    outlineColor?: RGBA;
+}
+/**
+ * Pick a high-contrast outline color for a fill: black for light fills, white
+ * for dark ones, using perceptual (Rec. 601) luminance.
+ */
+export declare function autoOutlineColor(fill: RGBA): RGBA;
+/** Total advance width of `str` in pixels at `sizePx`. */
+export declare function measureWidth(metrics: UIKitFontMetrics, str: string, sizePx: number): number;
+/**
+ * Normalize a line direction angle so text drawn along it is never upside down.
+ * When the raw angle points leftward (cos < 0), the label would render mirrored;
+ * flip it by pi. Returns the readable angle and whether a flip occurred (the
+ * caller flips the perpendicular lift so the label stays on the same side).
+ */
+export declare function readableAngle(rotation: number): {
+    angle: number;
+    flipped: boolean;
+};
+/**
+ * Lay out `str` into screen-pixel triangle vertices. Returns the packed vertex
+ * buffer (8 floats/vertex) and the vertex count (6 per rendered glyph).
+ */
+export declare function layoutText(metrics: UIKitFontMetrics, str: string, opts: TextLayoutOptions): {
+    vertices: Float32Array;
+    count: number;
+};

package/dist/textOverlay.d.ts

@@ -0,0 +1,23 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { UIKitFont } from './text/font';
+import { TextLayoutOptions } from './text/layout';
+/** One piece of text to draw: the string plus its layout pose. */
+export type UIKitTextItem = TextLayoutOptions & {
+    str: string;
+};
+export declare class UIKitTextOverlay implements UIKitOverlayRenderer {
+    private font;
+    private items;
+    private readonly gl;
+    private readonly wgpu;
+    private runs;
+    constructor(font: UIKitFont, items?: UIKitTextItem[]);
+    /** Swap the font atlas (metrics + image). Trigger a redraw via the controller. */
+    setFont(font: UIKitFont): void;
+    /** Replace the text items drawn each frame. Trigger a redraw via the controller. */
+    setItems(items: UIKitTextItem[]): void;
+    private layoutRuns;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}