brilliant-msg 2.0.0

package/dist/tx/capture-settings.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options for configuring camera capture settings.
+ */
+export interface TxCaptureSettingsOptions {
+    /** Optional image resolution (256-720, must be even). Defaults to 512. */
+    resolution?: number;
+    /** Optional index into JPEG quality array [VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH] (0-4). Defaults to 4 (VERY_HIGH). */
+    qualityIndex?: number;
+    /** Optional image pan value (-140 to 140). Defaults to 0. */
+    pan?: number;
+    /** Optional flag whether to capture in RAW (headerless JPEG) format. Defaults to false. */
+    raw?: boolean;
+}
+/**
+ * Message for camera capture settings.
+ */
+export declare class TxCaptureSettings {
+    /**
+     * Image resolution (256-720, must be even)
+     */
+    resolution: number;
+    /**
+     * Index into [VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH]
+     */
+    qualityIndex: number;
+    /**
+     * Image pan value (-140 to 140)
+     */
+    pan: number;
+    /**
+     * Whether to capture in RAW format
+     */
+    raw: boolean;
+    /**
+     * Constructs an instance of TxCaptureSettings.
+     * @param options Configuration options for the capture settings.
+     */
+    constructor(options?: TxCaptureSettingsOptions);
+    /**
+     * Packs the settings into 6 bytes.
+     * @returns Uint8Array Binary representation of the message (6 bytes)
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/code.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for configuring a TxCode message.
+ */
+export interface TxCodeOptions {
+    /** Optional byte value to be transmitted (0-255). Defaults to 0. */
+    value?: number;
+}
+/**
+ * A simple message containing only an optional byte value.
+ * Used for signaling the frameside app to take some action.
+ */
+export declare class TxCode {
+    value: number;
+    /**
+     * Constructs an instance of TxCode.
+     * @param options Configuration options for the code message.
+     */
+    constructor(options?: TxCodeOptions);
+    /**
+     * Packs the message into a single byte.
+     * @returns Uint8Array Binary representation of the message (a single byte)
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/image-sprite-block.d.ts

@@ -0,0 +1,62 @@
+import { TxSprite } from './sprite';
+/**
+ * Options for configuring an image sprite block.
+ */
+export interface TxImageSpriteBlockOptions {
+    /** The source {@link TxSprite} to be split into strips. */
+    image: TxSprite;
+    /**
+     * Optional height of each sprite strip. Defaults to 16.
+     * If the source `image` is compressed (`image.compress` is true),
+     * this value is dynamically calculated to respect a 4kB packed size limit per strip
+     * and any provided value here is ignored.
+     */
+    spriteLineHeight?: number;
+    /** Optional flag whether to render lines as they arrive. Defaults to true. */
+    progressiveRender?: boolean;
+    /** Optional flag whether lines can be updated after initial render. Defaults to true. */
+    updatable?: boolean;
+}
+/**
+ * An image split into horizontal sprite strips.
+ */
+export declare class TxImageSpriteBlock {
+    /**
+     * Source sprite to split.
+     */
+    image: TxSprite;
+    /**
+     * Height of each sprite strip. If the TxSprite is compressed, the strip has a packed size limit of 4kB and this value is dynamically calculated.
+     */
+    spriteLineHeight: number;
+    /**
+     * Whether to render lines as they arrive.
+     */
+    progressiveRender: boolean;
+    /**
+     * Whether lines can be updated after initial render.
+     */
+    updatable: boolean;
+    /**
+     * List of sprite strips.
+     */
+    spriteLines: TxSprite[];
+    /**
+     * Constructs an instance of TxImageSpriteBlock.
+     * @param options Configuration options for the image sprite block.
+     */
+    constructor(options: TxImageSpriteBlockOptions);
+    /**
+     * Splits the source image into horizontal strips.
+     * This method needs careful implementation based on how pixelData is structured
+     * and how BPP affects its layout if it's not 1 byte per pixel index.
+     * The current TxSprite.pixelData is Uint8Array of palette indices.
+     */
+    private _splitIntoLines;
+    /**
+     * Packs the image block header into a binary format.
+     * @returns Uint8Array Binary representation of the header
+     * @throws Error if there are no sprite lines to pack (though _splitIntoLines should always create at least one if height > 0 and spriteLineHeight > 0)
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/manual-exp-settings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Options for configuring manual exposure and gain settings.
+ */
+export interface TxManualExpSettingsOptions {
+    /** Optional shutter value (4-16383). Defaults to 3072. */
+    manualShutter?: number;
+    /** Optional analog gain value (1-248). Defaults to 16. */
+    manualAnalogGain?: number;
+    /** Optional red gain value (0-1023). Defaults to 121. */
+    manualRedGain?: number;
+    /** Optional green gain value (0-1023). Defaults to 64. */
+    manualGreenGain?: number;
+    /** Optional blue gain value (0-1023). Defaults to 140. */
+    manualBlueGain?: number;
+}
+/**
+ * Message for manual exposure and gain settings.
+ */
+export declare class TxManualExpSettings {
+    /**
+     * Shutter value (4-16383)
+     */
+    manualShutter: number;
+    /**
+     * Analog gain value (1-248)
+     */
+    manualAnalogGain: number;
+    /**
+     * Red gain value (0-1023)
+     */
+    manualRedGain: number;
+    /**
+     * Green gain value (0-1023)
+     */
+    manualGreenGain: number;
+    /**
+     * Blue gain value (0-1023)
+     */
+    manualBlueGain: number;
+    /**
+     * Constructs an instance of TxManualExpSettings.
+     * @param options Configuration options for manual exposure and gain settings.
+     */
+    constructor(options?: TxManualExpSettingsOptions);
+    /**
+     * Packs the settings into 9 bytes.
+     * @returns Uint8Array Binary representation of the message (9 bytes)
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/plain-text.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for configuring a plain text message.
+ */
+export interface TxPlainTextOptions {
+    /** The plain text content to be transmitted. */
+    text: string;
+    /** Optional X-coordinate for text position (1-640, Lua/1-based indexing). Defaults to 1. */
+    x?: number;
+    /** Optional Y-coordinate for text position (1-400, Lua/1-based indexing). Defaults to 1. */
+    y?: number;
+    /** Optional color palette offset (1-15, 0/'VOID' is invalid). Defaults to 1. */
+    paletteOffset?: number;
+    /** Optional character spacing value. Defaults to 4. */
+    spacing?: number;
+}
+/**
+ * A message containing plain text with positioning and formatting information.
+ */
+export declare class TxPlainText {
+    text: string;
+    x: number;
+    y: number;
+    paletteOffset: number;
+    spacing: number;
+    /**
+     * Constructs an instance of TxPlainText.
+     * @param options Configuration options for the plain text message.
+     */
+    constructor(options: TxPlainTextOptions);
+    /**
+     * Packs the message into a binary format.
+     * @returns Uint8Array Binary representation of the message
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/sprite-coords.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Options for configuring sprite coordinates.
+ */
+export interface TxSpriteCoordsOptions {
+    /** Unsigned byte identifying the sprite code. */
+    code: number;
+    /** X-coordinate for sprite position (1-640). */
+    x: number;
+    /** Y-coordinate for sprite position (1-400). */
+    y: number;
+    /** Optional palette offset value for the sprite (0-15). Defaults to 0. */
+    offset?: number;
+}
+/**
+ * A message containing sprite coordinates information for display.
+ */
+export declare class TxSpriteCoords {
+    /**
+     * Unsigned byte identifying the sprite code
+     */
+    code: number;
+    /**
+     * X-coordinate for sprite position (1..640)
+     */
+    x: number;
+    /**
+     * Y-coordinate for sprite position (1..400)
+     */
+    y: number;
+    /**
+     * Palette offset value for the sprite (0..15)
+     */
+    offset: number;
+    /**
+     * Constructs an instance of TxSpriteCoords.
+     * @param options Configuration options for the sprite coordinates.
+     */
+    constructor(options: TxSpriteCoordsOptions);
+    /**
+     * Packs the message into a binary format.
+     * @returns Uint8Array Binary representation of the message in the format:
+     * [code, x_msb, x_lsb, y_msb, y_lsb, offset]
+     * (6 bytes)
+     */
+    pack(): Uint8Array;
+}

package/dist/tx/sprite.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Options for creating a TxSprite instance.
+ */
+export interface TxSpriteOptions {
+    /** The width of the sprite in pixels. */
+    width: number;
+    /** The height of the sprite in pixels. */
+    height: number;
+    /** The number of colors in the sprite's palette. */
+    numColors: number;
+    /** The palette data as a flat Uint8Array of RGB values. */
+    paletteData: Uint8Array;
+    /** The pixel data as a Uint8Array of palette indices. */
+    pixelData: Uint8Array;
+    /** Optional flag whether to compress the pixel data using LZ4. Defaults to false. */
+    compress?: boolean;
+}
+/**
+ * A sprite message containing image data with a custom palette.
+ */
+export declare class TxSprite {
+    /** The width of the sprite in pixels. */
+    width: number;
+    /** The height of the sprite in pixels. */
+    height: number;
+    /** The number of colors in the sprite's palette. */
+    numColors: number;
+    /** The palette data as a flat Uint8Array of RGB values. */
+    paletteData: Uint8Array;
+    /** The pixel data as a Uint8Array of palette indices. */
+    pixelData: Uint8Array;
+    /** Whether the pixel data is compressed using LZ4. */
+    compress: boolean;
+    /**
+     * Creates an instance of TxSprite.
+     * @param options Configuration options for the sprite.
+     */
+    constructor(options: TxSpriteOptions);
+    /**
+     * Creates a TxSprite from an indexed PNG image.
+     * @param imageBytes The ArrayBuffer containing the PNG image data.
+     * @param compress Whether to compress the pixel data using LZ4.
+     * @returns A TxSprite instance.
+     */
+    static fromIndexedPngBytes(imageBytes: ArrayBuffer, compress?: boolean): Promise<TxSprite>;
+    /**
+     * Creates a TxSprite from an image file, resizing and quantizing it to a maximum of 16 colors.
+     * @param imageBytes The ArrayBuffer containing the image data.
+     * @param maxPixels The maximum number of pixels allowed in the sprite.
+     * @param compress Whether to compress the pixel data using LZ4.
+     * @returns A TxSprite instance.
+     */
+    static fromImageBytes(imageBytes: ArrayBuffer, maxPixels?: number, compress?: boolean): Promise<TxSprite>;
+    /**
+     * The number of bits per pixel, derived from the number of colors.
+     */
+    get bpp(): number;
+    /**
+     * Packs the sprite data into a compact binary format.
+     * The format includes a header, palette data, and packed pixel data.
+     * Pixel data can be optionally compressed using LZ4.
+     * @returns A Uint8Array containing the packed sprite data.
+     */
+    pack(): Uint8Array;
+    /**
+     * Packs pixel data into 1-bit per pixel format.
+     */
+    private static _pack_1bit;
+    /**
+     * Packs pixel data into 2-bits per pixel format.
+     */
+    private static _pack_2bit;
+    /**
+     * Packs pixel data into 4-bits per pixel format.
+     */
+    private static _pack_4bit;
+    /**
+     * Converts the TxSprite to a PNG image as an ArrayBuffer.
+     * Intended for debugging and visualization purposes.
+     * @returns The PNG image data as an ArrayBuffer.
+     */
+    toPngBytes(): ArrayBuffer;
+    /**
+     * Create a true-color PNG from an indexed palette and pixel data.
+     * @param width Image width in pixels
+     * @param height Image height in pixels
+     * @param paletteRGB Flat RGB Uint8Array of colors: [r0,g0,b0, r1,g1,b1, ..., rN,gN,bN]
+     * @param pixelIndices Uint8Array of palette indices (length = width * height)
+     * @returns PNG as ArrayBuffer
+     */
+    private static _makeRGBAPngFromIndexed;
+}

package/dist/tx/text-page.d.ts

@@ -0,0 +1,184 @@
+import { TxSprite } from './sprite';
+/**
+ * Abstract interface for defining the geometry of a text layout area.
+ * This allows for different shapes like rectangles and circles.
+ */
+export interface TextLayout {
+    /** The width of the layout in pixels. */
+    width: number;
+    /** The height of the layout in pixels. */
+    height: number;
+    /** The font size in pixels. */
+    fontSize: number;
+    /** Optional font family name. */
+    fontFamily?: string;
+    /** Text alignment within each line. */
+    textAlign: CanvasTextAlign;
+    /** The starting Y coordinate for laying out text. */
+    readonly startY: number;
+    /**
+     * Gets the layout parameters (width and x-offset) for a line at a specific Y position.
+     * Returns null if the line is outside the displayable area.
+     */
+    getLineLayout(lineY: number, lineHeight: number): {
+        width: number;
+        xOffset: number;
+    } | null;
+}
+/**
+ * A standard rectangular text layout.
+ */
+export declare class RectangularTextLayout implements TextLayout {
+    width: number;
+    height: number;
+    fontSize: number;
+    fontFamily?: string;
+    textAlign: CanvasTextAlign;
+    /**
+     * Constructs a RectangularTextLayout.
+     * @param options Configuration options.
+     */
+    constructor(options: {
+        width: number;
+        height: number;
+        fontSize: number;
+        fontFamily?: string;
+        textAlign?: CanvasTextAlign;
+    });
+    /** The starting Y coordinate for text layout (always 0 for rectangular). */
+    get startY(): number;
+    /**
+     * Returns the full width at xOffset 0 if the line fits vertically, null otherwise.
+     */
+    getLineLayout(lineY: number, lineHeight: number): {
+        width: number;
+        xOffset: number;
+    } | null;
+}
+/**
+ * A circular text layout, ideal for the Halo device.
+ * Text is constrained within a circle inscribed in the defined width/height.
+ */
+export declare class CircularTextLayout implements TextLayout {
+    width: number;
+    height: number;
+    fontSize: number;
+    fontFamily?: string;
+    textAlign: CanvasTextAlign;
+    circleMargin: number;
+    readonly radius: number;
+    readonly centerX: number;
+    readonly centerY: number;
+    /**
+     * Constructs a CircularTextLayout.
+     * @param options Configuration options.
+     */
+    constructor(options: {
+        width: number;
+        height: number;
+        fontSize: number;
+        circleMargin?: number;
+        fontFamily?: string;
+        textAlign?: CanvasTextAlign;
+    });
+    /** The starting Y coordinate for text layout (top of the inscribed circle). */
+    get startY(): number;
+    /**
+     * Returns the chord width and x-offset for a line at the given Y position within the circle.
+     * Returns null if the line is outside the circle or too narrow to render text.
+     */
+    getLineLayout(lineY: number, lineHeight: number): {
+        width: number;
+        xOffset: number;
+    } | null;
+}
+/**
+ * Options for TxTextPage constructor.
+ */
+export interface TxTextPageOptions {
+    /** The layout to use for text rendering. */
+    layout: TextLayout;
+    /** The text to render. */
+    text: string;
+}
+/** Internal data class for a measured line of text. */
+interface LineData {
+    text: string;
+    width: number;
+    xOffset: number;
+    yOffset: number;
+    lineHeight: number;
+}
+/**
+ * Represents a single, measured page of text that is ready to be rasterized into sprites.
+ */
+export declare class PageData {
+    private _lines;
+    private _layout;
+    private _sprites;
+    private _isRasterizing;
+    /** @internal */
+    constructor(lines: LineData[], layout: TextLayout);
+    /** Returns true if the page contains no lines. */
+    get isEmpty(): boolean;
+    /** Returns true if the page has been rasterized into sprites. */
+    get isRasterized(): boolean;
+    /** The rasterized sprites, one per line. Only valid after rasterize() has been called. */
+    get rasterizedSprites(): TxSprite[];
+    /** The text for each measured line. */
+    get lineTexts(): string[];
+    /**
+     * Rasterizes the measured lines into TxSprite objects (one per line) using
+     * 1-bit monochrome rendering via the Canvas 2D API.
+     */
+    rasterize(): Promise<void>;
+    /**
+     * Composes all rasterized sprites into a single layout.width × layout.height canvas
+     * and returns a PNG as a Uint8Array.
+     * Calls rasterize() first if not already done.
+     */
+    toPngBytes(): Promise<Uint8Array>;
+    /**
+     * Packs the page layout data for transmission to the device.
+     * Must be called after rasterize().
+     * Format:
+     *   0xFF (1 byte)
+     *   layout.width  (2 bytes, big-endian)
+     *   layout.height (2 bytes, big-endian)
+     *   numSprites    (1 byte)
+     *   [xOffset_h, xOffset_l, yOffset_h, yOffset_l] * numSprites
+     */
+    pack(): Uint8Array;
+}
+/**
+ * Manages the process of laying out and rasterizing text into pages.
+ * It works with any TextLayout to support different display shapes.
+ */
+export declare class TxTextPage {
+    /** The layout used for text rendering. */
+    readonly layout: TextLayout;
+    /** The full original text. */
+    readonly text: string;
+    private _remainingText;
+    /**
+     * Constructs an instance of TxTextPage.
+     * @param options Configuration options.
+     */
+    constructor(options: TxTextPageOptions);
+    /** The portion of the text that has not yet been processed into a page. */
+    get remainingText(): string;
+    /** Returns true if there is more text to be laid out. */
+    get hasMoreText(): boolean;
+    /**
+     * Measures the next page of text using the Canvas 2D API and returns a PageData
+     * without rasterizing any sprites.
+     * Returns null if there is no remaining text or if no text fits on the page.
+     */
+    measureNextPage(): Promise<PageData | null>;
+    /**
+     * Measures and rasterizes the next page in one call.
+     * Returns null if there is no remaining text or nothing fit on the page.
+     */
+    rasterizeNextPage(): Promise<PageData | null>;
+}
+export {};

package/dist/tx/text-sprite-block.d.ts

@@ -0,0 +1,50 @@
+import { TxSprite } from './sprite';
+/**
+ * Interface for TxTextSpriteBlock constructor options.
+ */
+export interface TxTextSpriteBlockOptions {
+    /** Width constraint for text layout */
+    width: number;
+    /** Font size in pixels */
+    fontSize: number;
+    /** Line height in pixels (fixed height for each sprite) */
+    lineHeight: number;
+    /** Maximum number of lines to display */
+    maxDisplayLines: number;
+    /** Optional font family name. Defaults to 'sans-serif'. */
+    fontFamily?: string;
+}
+/**
+ * A block of text rendered as sprites, for use in a browser environment.
+ */
+export declare class TxTextSpriteBlock {
+    /** The width constraint for the text layout, in pixels. */
+    width: number;
+    /** The font size used for rendering the text, in pixels. */
+    fontSize: number;
+    /** The fixed line height for each sprite, in pixels. */
+    lineHeight: number;
+    /** The maximum number of lines of text to be displayed. */
+    maxDisplayLines: number;
+    /** The font family used for rendering the text. */
+    fontFamily: string;
+    /**
+     * @param options Configuration options for the text sprite block.
+     */
+    constructor(options: TxTextSpriteBlockOptions);
+    /**
+     * Creates sprites from the rendered text using the browser's Canvas API.
+     * Returns an array of TxSprite instances, one per line of text.
+     * Each sprite has exactly lineHeight pixels in height and width pixels in width,
+     * except blank lines which are 1×lineHeight.
+     * @param text The text to render. Lines are split on '\n'.
+     * @returns Array of TxSprite instances.
+     */
+    createTextSprites(text: string): TxSprite[];
+    /**
+     * Packs the text block header into a 6-byte binary format.
+     * Format: 0xFF (1 byte) | width (uint16 BE) | lineHeight (uint16 BE) | maxDisplayLines (uint8)
+     * @returns Uint8Array Binary representation of the text block header.
+     */
+    pack(): Uint8Array;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "brilliant-msg",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "dist/brilliant-msg.umd.js",
+  "module": "dist/brilliant-msg.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/brilliant-msg.es.js",
+      "require": "./dist/brilliant-msg.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:example": "vite build --config example/vite.config.ts",
+    "preview": "vite preview",
+    "dev:demo": "vite --config example/vite.config.ts",
+    "docs:api": "typedoc --out example/dist/api src",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "luke-brilliant",
+  "license": "BSD-3-Clause",
+  "description": "A high-level library for interacting with Brilliant Labs Frame by passing structured messages between a Frameside app and a hostside app",
+  "devDependencies": {
+    "@types/node": "^22.15.17",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "dependencies": {
+    "@pdf-lib/upng": "^1.0.1",
+    "@types/lz4js": "^0.2.1",
+    "brilliant-ble": "^1.0.0",
+    "image-js": "^0.37.0",
+    "image-q": "^4.0.0",
+    "lz4js": "^0.2.0"
+  },
+  "optionalDependencies": {
+    "@rollup/rollup-linux-x64-gnu": "4.41.1"
+  },
+  "overrides": {
+    "vite": {
+      "rollup": "npm:@rollup/wasm-node"
+    }
+  }
+}