@niivue/uikit 1.0.0-rc.13 → 1.0.0-rc.15

package/dist/index.d.ts

@@ -35,6 +35,10 @@ export type { NumberInputLayout, NumberInputSpec, NumberInputStyle, NumberInputV
 export { DEFAULT_NUMBER_INPUT_STYLE } from './numberInput';
 export type { UIKitNumberInputOverlayOptions } from './numberInputOverlay';
 export { UIKitNumberInputOverlay } from './numberInputOverlay';
+export type { PointLabelBounds, PointLabelGeometry, PointLabelSpec, } from './pointLabel';
+export { buildPointLabel } from './pointLabel';
+export type { MMPoint, MMProjector, PointLabelPlacement, } from './pointLabelOverlay';
+export { UIKitPointLabelOverlay } from './pointLabelOverlay';
 export type { RectData, RectSpec } from './rect';
 export { buildRect } from './rect';
 export { UIKitRectOverlay } from './rectOverlay';

package/dist/pointLabel.d.ts

@@ -0,0 +1,68 @@
+import { LineData } from './line';
+import { RGBA, Vec2 } from './ruler';
+import { UIKitFontMetrics } from './text/font';
+import { UIKitTextItem } from './textOverlay';
+export interface PointLabelBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PointLabelSpec {
+    /** The labelled point in screen pixels. */
+    target: Vec2;
+    text: string;
+    /**
+     * Where the leader ends and the text starts, in screen pixels. Omit to place
+     * it `leaderLength` from the target, pointing away from the centre of
+     * `bounds` (or up and to the right without bounds).
+     */
+    anchor?: Vec2;
+    /**
+     * The drawable area. Used to choose the automatic anchor direction and to
+     * keep the text inside the frame: the text flips to the other side of the
+     * anchor when it would run off an edge.
+     */
+    bounds?: PointLabelBounds;
+    /**
+     * The eight projected corners of a box to outline around the target (a
+     * volume brick, say), in screen pixels. Corner `c` sits at the box's
+     * minimum on each axis whose bit of `c` is clear and at its maximum where
+     * it is set, so the twelve edges join corners whose indices differ in one
+     * bit. Omit for no box.
+     */
+    box?: readonly Vec2[];
+    /** Colour of the box edges. Defaults to `lineColor`. */
+    boxColor?: RGBA;
+    /** Thickness of the box edges in pixels. Defaults to `thickness`. */
+    boxThickness?: number;
+    /** Leader length for the automatic anchor, in pixels. Default 110. */
+    leaderLength?: number;
+    /** Text height in pixels. Default 28. */
+    sizePx?: number;
+    lineColor?: RGBA;
+    textColor?: RGBA;
+    /** Line thickness in pixels. Default 3. */
+    thickness?: number;
+    /** Half-size of the diamond marking the target, in pixels. Default 6. */
+    markerSize?: number;
+    /** Text outline width in pixels, 0 for none. Default 2. */
+    textOutlineWidthPx?: number;
+    /**
+     * Multiplies every pixel size above (given or default), so one spec reads
+     * the same on a 1x and a 2x display. The overlay passes the frame's device
+     * pixel ratio. Default 1.
+     */
+    scale?: number;
+}
+export interface PointLabelGeometry {
+    lines: LineData[];
+    text: UIKitTextItem[];
+    /** The resolved anchor (useful for tests and for chaining labels). */
+    anchor: Vec2;
+}
+/**
+ * Build the line + text draw data for a point label. Pure geometry; the font
+ * metrics are only used to measure the text so it can be kept in frame.
+ */
+export declare function buildPointLabel(metrics: UIKitFontMetrics, spec: PointLabelSpec): PointLabelGeometry;

package/dist/pointLabelOverlay.d.ts

@@ -0,0 +1,39 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { PointLabelSpec } from './pointLabel';
+import { UIKitFont } from './text/font';
+export type MMPoint = readonly [number, number, number];
+/** Maps a world-mm point to canvas backing-store pixels, or null if off screen. */
+export type MMProjector = (mm: MMPoint) => [number, number] | null;
+/**
+ * A label pinned to a world-mm point; the rest styles the callout. Pixel
+ * sizes are in CSS pixels: the overlay scales them by the frame's device
+ * pixel ratio (times any `scale` given here).
+ */
+export type PointLabelPlacement = Omit<PointLabelSpec, 'target' | 'bounds' | 'box'> & {
+    mm: MMPoint;
+    /**
+     * The eight world-mm corners of a box to outline around the point (the
+     * volume brick holding it, say), in the corner order `PointLabelSpec.box`
+     * describes. The overlay projects them each frame.
+     */
+    boxMM?: readonly MMPoint[];
+};
+export declare class UIKitPointLabelOverlay implements UIKitOverlayRenderer {
+    private project;
+    private readonly lines;
+    private readonly labels;
+    private readonly font;
+    private placements;
+    constructor(font: UIKitFont, project: MMProjector, labels?: PointLabelPlacement[]);
+    /** Replace the labels. Trigger a redraw via the host. */
+    setLabels(labels: PointLabelPlacement[]): void;
+    /** Swap the projection (after a view change, say). */
+    setProjector(project: MMProjector): void;
+    /** Remove every label so nothing draws. */
+    clear(): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** The box's corners on the canvas, or undefined when any is off screen. */
+    private projectBox;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}