fitsjs-ng 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,607 @@
+/**
+ * FITS standard BITPIX values representing data types in image arrays.
+ * Positive values are integer types, negative values are floating point.
+ */
+type BitPix = 8 | 16 | 32 | -32 | -64;
+/**
+ * Extended BITPIX values used in compressed images (ZBITPIX).
+ */
+type ZBitPix = 8 | 16 | 32 | 64 | -32 | -64;
+/**
+ * Possible value types stored in a FITS header card.
+ */
+type CardValue = string | number | boolean | null;
+/**
+ * A single header card entry with its positional index, value, and optional comment.
+ */
+interface HeaderCard {
+    index: number;
+    value: CardValue;
+    comment: string;
+}
+/**
+ * Types of FITS data units.
+ */
+type DataUnitType = 'Image' | 'BinaryTable' | 'Table' | 'CompressedImage';
+/**
+ * FITS extension types as stored in the XTENSION keyword.
+ */
+type ExtensionType = 'IMAGE' | 'BINTABLE' | 'TABLE';
+/**
+ * Compression algorithms supported by the FITS tiled image convention.
+ */
+type CompressionType = 'GZIP_1' | 'RICE_1' | 'PLIO_1' | 'HCOMPRESS_1';
+/**
+ * Quantization methods for compressed images.
+ */
+type QuantizationType = 'LINEAR_SCALING' | 'SUBTRACTIVE_DITHER_1' | 'SUBTRACTIVE_DITHER_2';
+/**
+ * Binary table format type codes (single character descriptors).
+ */
+type BinaryTableTypeCode = 'L' | 'B' | 'I' | 'J' | 'K' | 'A' | 'E' | 'D' | 'C' | 'M' | 'X';
+/**
+ * ASCII table format type codes.
+ */
+type AsciiTableTypeCode = 'A' | 'I' | 'F' | 'E' | 'D';
+/**
+ * A binary table accessor function reads a value from a DataView at the given offset
+ * and returns the value plus the new offset.
+ */
+type BinaryAccessor = (view: DataView, offset: number) => [value: unknown, newOffset: number];
+/**
+ * An ASCII table accessor transforms a string value into the appropriate type.
+ */
+type AsciiAccessor = (value: string) => CardValue;
+type TypedArrayConstructor = Uint8ArrayConstructor | Int8ArrayConstructor | Uint16ArrayConstructor | Int16ArrayConstructor | Uint32ArrayConstructor | Int32ArrayConstructor | Float32ArrayConstructor | Float64ArrayConstructor;
+type TypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/**
+ * Warning callback type for non-fatal issues during parsing.
+ */
+type WarningCallback = (message: string) => void;
+/**
+ * Options for reading FITS data.
+ */
+interface ReadOptions {
+    /** Maximum number of header lines to parse (default: 600) */
+    maxHeaderLines?: number;
+    /** Callback for non-fatal warnings during parsing (default: console.warn) */
+    onWarning?: WarningCallback;
+}
+/**
+ * Options for fetching remote FITS files.
+ */
+interface FetchOptions extends ReadOptions {
+    /** Additional fetch options (headers, signal, etc.) */
+    requestInit?: RequestInit;
+}
+/**
+ * Row data from a table, keyed by column name.
+ */
+type TableRow = Record<string, unknown>;
+/**
+ * Compression algorithm parameters (e.g., BLOCKSIZE, BYTEPIX).
+ */
+type AlgorithmParameters = Record<string, number>;
+
+/**
+ * Context interface for verification functions — represents the header state
+ * during parsing so verification functions can access current parse state.
+ */
+interface VerifyContext {
+    cardIndex: number;
+    primary: boolean;
+    extension: boolean;
+    extensionType?: ExtensionType;
+    warn: WarningCallback;
+    get(key: string): CardValue;
+    isPrimary(): boolean;
+    isExtension(): boolean;
+}
+
+/**
+ * Represents a parsed FITS header.
+ *
+ * A FITS header consists of 80-character card images containing
+ * keyword = value / comment triplets.
+ */
+declare class Header implements VerifyContext {
+    private static readonly ARRAY_PATTERN;
+    /** Whether this is a primary header (contains SIMPLE keyword). */
+    primary: boolean;
+    /** Whether this is an extension header (contains XTENSION keyword). */
+    extension: boolean;
+    /** The extension type if this is an extension header. */
+    extensionType?: ExtensionType;
+    /** Storage for parsed header cards, keyed by keyword. */
+    private cards;
+    /** Storage for COMMENT cards. */
+    private comments;
+    /** Storage for HISTORY cards. */
+    private history;
+    /** Running index of the current card being parsed. */
+    cardIndex: number;
+    /** Warning callback for non-fatal issues during parsing. */
+    warn: WarningCallback;
+    /** Maximum number of header lines to parse. */
+    private maxLines;
+    /** The raw header block string, preserved for reference. */
+    readonly block: string;
+    constructor(block: string, maxLines?: number, onWarning?: WarningCallback);
+    /**
+     * Get the value for a header keyword.
+     * Returns `null` if the keyword is not present.
+     */
+    get(key: string): CardValue;
+    /**
+     * Get a numeric value for a header keyword.
+     * Returns the `fallback` (default `0`) if the keyword is missing.
+     * Throws `HeaderError` if the value is present but not a number.
+     */
+    getNumber(key: string, fallback?: number): number;
+    /**
+     * Get a string value for a header keyword.
+     * Returns the `fallback` (default `''`) if the keyword is missing.
+     * Throws `HeaderError` if the value is present but not a string.
+     */
+    getString(key: string, fallback?: string): string;
+    /**
+     * Get a boolean value for a header keyword.
+     * Returns the `fallback` (default `false`) if the keyword is missing.
+     * Throws `HeaderError` if the value is present but not a boolean.
+     */
+    getBoolean(key: string, fallback?: boolean): boolean;
+    /**
+     * Set a keyword with a value and optional comment.
+     */
+    set(key: string, value: CardValue, comment?: string): void;
+    /**
+     * Check if the header contains a specific keyword.
+     */
+    contains(key: string): boolean;
+    /**
+     * Get all COMMENT card values.
+     */
+    getComments(): string[];
+    /**
+     * Get all HISTORY card values.
+     */
+    getHistory(): string[];
+    /**
+     * Returns all keyword names in insertion order.
+     */
+    keys(): string[];
+    /**
+     * Determine if this header has an associated data unit based on NAXIS.
+     */
+    hasDataUnit(): boolean;
+    /**
+     * Calculate the byte length of the associated data unit.
+     */
+    getDataLength(): number;
+    /**
+     * Determine the data unit type from header keywords.
+     */
+    getDataType(): DataUnitType | null;
+    /** Check if this is a primary header. */
+    isPrimary(): boolean;
+    /** Check if this is an extension header. */
+    isExtension(): boolean;
+    private readBlock;
+    private readLine;
+    private validate;
+}
+
+/**
+ * Base class for FITS data units (Image, BinaryTable, Table, CompressedImage).
+ *
+ * FITS data is always stored in big-endian format. This base class provides
+ * shared infrastructure for endian swapping and buffer management.
+ */
+declare class DataUnit {
+    /** The ArrayBuffer containing raw data (available when loaded from buffer). */
+    buffer?: ArrayBuffer;
+    /** The Blob containing raw data (available when loaded from file). */
+    blob?: Blob;
+    /** Static endian swap functions keyed by type code or byte size. */
+    static readonly swapEndian: Record<string | number, (value: number) => number>;
+    constructor(data: ArrayBuffer | Blob);
+}
+
+/**
+ * Header Data Unit — the fundamental building block of a FITS file.
+ *
+ * Each HDU contains a header and an optional data unit. The header
+ * describes the structure and metadata of the data unit.
+ */
+declare class HDU {
+    readonly header: Header;
+    readonly data?: DataUnit;
+    constructor(header: Header, data?: DataUnit);
+    /**
+     * Check if this HDU has an associated data unit.
+     */
+    hasData(): boolean;
+}
+
+/**
+ * Main FITS class — the primary entry point for reading FITS files.
+ *
+ * Provides static factory methods for creating FITS instances from
+ * various data sources (ArrayBuffer, Blob/File, URL, Node.js Buffer).
+ *
+ * @example
+ * ```ts
+ * // From URL (browser)
+ * const fits = await FITS.fromURL('https://example.com/image.fits');
+ *
+ * // From ArrayBuffer
+ * const fits = FITS.fromArrayBuffer(buffer);
+ *
+ * // From File object (browser)
+ * const fits = await FITS.fromBlob(fileInput.files[0]);
+ *
+ * // Access data
+ * const header = fits.getHeader();
+ * const image = fits.getDataUnit();
+ * ```
+ */
+declare class FITS {
+    /** All Header Data Units in this FITS file. */
+    readonly hdus: HDU[];
+    private constructor();
+    /**
+     * Parse a FITS file from an ArrayBuffer (synchronous).
+     */
+    static fromArrayBuffer(buffer: ArrayBuffer, options?: ReadOptions): FITS;
+    /**
+     * Parse a FITS file from a Blob or File object (async).
+     */
+    static fromBlob(blob: Blob, options?: ReadOptions): Promise<FITS>;
+    /**
+     * Fetch a remote FITS file and parse it (async, browser or Node 18+).
+     *
+     * @param url - URL of the FITS file.
+     * @param init - Optional fetch RequestInit (headers, signal, etc.).
+     */
+    static fromURL(url: string, options?: FetchOptions): Promise<FITS>;
+    /**
+     * Parse a FITS file from a Node.js Buffer.
+     * The buffer is converted to an ArrayBuffer internally.
+     */
+    static fromNodeBuffer(nodeBuffer: {
+        buffer: ArrayBuffer;
+        byteOffset: number;
+        byteLength: number;
+    }, options?: ReadOptions): FITS;
+    /**
+     * Returns the first HDU containing a data unit.
+     * If `index` is provided, returns that specific HDU.
+     */
+    getHDU(index?: number): HDU | undefined;
+    /**
+     * Returns the header associated with the first HDU containing a data unit.
+     * If `index` is provided, returns the header of that specific HDU.
+     */
+    getHeader(index?: number): Header | undefined;
+    /**
+     * Returns the data unit associated with the first HDU containing a data unit.
+     * If `index` is provided, returns the data unit of that specific HDU.
+     */
+    getDataUnit(index?: number): DataUnit | undefined;
+}
+
+interface FrameOffset {
+    begin: number;
+    buffers?: ArrayBuffer[];
+}
+/**
+ * Represents a standard FITS image stored in the data unit of a FITS file.
+ * Supports BITPIX values: 8, 16, 32, -32, -64
+ * Supports data cubes (NAXIS > 2) with frame-by-frame reading.
+ */
+declare class Image extends DataUnit {
+    readonly bitpix: number;
+    readonly naxis: number[];
+    readonly width: number;
+    readonly height: number;
+    readonly depth: number;
+    readonly bzero: number;
+    readonly bscale: number;
+    readonly bytes: number;
+    readonly length: number;
+    readonly frameLength: number;
+    readonly frameOffsets: FrameOffset[];
+    constructor(header: Header, data: ArrayBuffer | Blob);
+    /**
+     * Convert raw buffer bytes into pixel values with endian handling and BZERO/BSCALE.
+     */
+    static computeFrame(buffer: ArrayBuffer, bitpix: number, bzero: number, bscale: number): TypedArray;
+    /**
+     * Read a single frame from the image. For 2D images, frame is always 0.
+     * For data cubes, frame selects the z-slice.
+     *
+     * @returns Promise resolving to pixel data as a typed array.
+     */
+    getFrame(frame?: number): Promise<TypedArray>;
+    /**
+     * Read multiple sequential frames from a data cube.
+     *
+     * @param startFrame - First frame index to read.
+     * @param count - Number of frames to read.
+     * @returns Promise resolving to an array of typed arrays, one per frame.
+     */
+    getFrames(startFrame: number, count: number): Promise<TypedArray[]>;
+    /** Check if the image is a data cube (more than 2 axes). */
+    isDataCube(): boolean;
+    /**
+     * Async iterator for frame-by-frame reading of data cubes.
+     * Yields each frame sequentially from index 0 to depth-1.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<TypedArray>;
+    /** Compute min/max pixel values of an array, ignoring NaN. */
+    getExtent(arr: TypedArray): [number, number];
+    /** Get a single pixel value at (x, y) from a pixel array. */
+    getPixel(arr: TypedArray, x: number, y: number): number;
+}
+
+/**
+ * Abstract base class for tabular FITS extensions (TABLE and BINTABLE).
+ *
+ * Handles shared logic for row/column access, buffer management,
+ * and accessor setup. Derived classes must implement `setAccessors` and `_getRows`.
+ */
+declare abstract class Tabular extends DataUnit {
+    /** Maximum memory (bytes) to hold when reading from blob. */
+    protected maxMemory: number;
+    readonly rowByteSize: number;
+    readonly rows: number;
+    readonly cols: number;
+    readonly length: number;
+    readonly heapLength: number;
+    readonly columns: string[] | null;
+    /** Accessor functions for each column. */
+    protected accessors: BinaryAccessor[];
+    /** Type descriptor for each column. */
+    protected descriptors: string[];
+    /** Byte length of each column element. */
+    protected elementByteLengths: number[];
+    /** TTYPE values for each column (used by subclasses to identify column roles). */
+    protected columnTypes: string[];
+    /** Heap data for variable-length arrays. */
+    heap?: ArrayBuffer;
+    /** Typed array constructor map (used by BinaryTable). */
+    protected typedArray: Record<string, new (length: number | ArrayBuffer) => TypedArray>;
+    private firstRowInBuffer;
+    private lastRowInBuffer;
+    private nRowsInBuffer;
+    private cachedBuffer?;
+    constructor(header: Header, data: ArrayBuffer | Blob);
+    /**
+     * Subclasses must call this at the end of their constructor.
+     */
+    protected initAccessors(header: Header): void;
+    /**
+     * Clear all accessor arrays before re-initialization.
+     */
+    private resetAccessors;
+    /**
+     * Derived classes must set up accessor functions for each column.
+     */
+    protected abstract setAccessors(header: Header): void;
+    /**
+     * Derived classes must implement row parsing from a buffer.
+     */
+    protected abstract _getRows(buffer: ArrayBuffer, nRows: number): TableRow[] | Float32Array;
+    /**
+     * Check if the specified row range is currently in memory.
+     */
+    private rowsInMemory;
+    /**
+     * Get column names from the header.
+     */
+    private getColumns;
+    /**
+     * Read a range of rows from the table.
+     *
+     * @param row - Starting row index (0-based).
+     * @param number_ - Number of rows to read.
+     */
+    getRows(row: number, number_: number): Promise<TableRow[] | Float32Array | ArrayLike<number>>;
+    /**
+     * Read a table buffer for a range of rows.
+     * Used internally for column-based reading from blob.
+     */
+    private getTableBuffer;
+    /**
+     * Read all values from a single column.
+     *
+     * @param name - Column name.
+     * @returns Array of column values.
+     */
+    getColumn(name: string): Promise<unknown[]>;
+}
+
+/**
+ * Reads ASCII tables from FITS files (XTENSION = 'TABLE').
+ *
+ * ASCII tables store data as fixed-width text fields where each row
+ * is a sequence of ASCII characters.
+ */
+declare class Table extends Tabular {
+    private asciiAccessors;
+    /** 0-based start positions for each column within a row. */
+    private colStarts;
+    /** Character widths for each column. */
+    private colWidths;
+    /** Whether TBCOL keywords were found in the header. */
+    private hasTBCOL;
+    constructor(header: Header, data: ArrayBuffer | Blob);
+    protected setAccessors(header: Header): void;
+    protected _getRows(buffer: ArrayBuffer, _nRows?: number): TableRow[];
+}
+
+/**
+ * Reads binary tables from FITS files (XTENSION = 'BINTABLE').
+ *
+ * Binary tables support a rich set of data types including logical,
+ * integer, float, complex, character, bit arrays, and variable-length
+ * array descriptors pointing to a heap area.
+ */
+declare class BinaryTable extends Tabular {
+    constructor(header: Header, data: ArrayBuffer | Blob);
+    protected setAccessors(header: Header): void;
+    /**
+     * Read data from the heap area following the main table data.
+     */
+    protected getFromHeap(view: DataView, offset: number, descriptor: string): [TypedArray, number];
+    private setupArrayAccessor;
+    private setupSingleAccessor;
+    private setupBitArrayAccessor;
+    private setupCharArrayAccessor;
+    private setupMultiAccessor;
+    protected _getRows(buffer: ArrayBuffer, nRows: number): TableRow[] | Float32Array;
+}
+
+/**
+ * Reads Rice-compressed FITS images stored as binary tables.
+ *
+ * Compressed images are stored in BINTABLE extensions with ZIMAGE=T.
+ * Each row in the table represents one tile of the image.
+ * This class decompresses tiles and reconstructs the full image,
+ * applying subtractive dithering when appropriate.
+ */
+declare class CompressedImage extends BinaryTable {
+    readonly zcmptype: string;
+    readonly zbitpix: number;
+    readonly znaxis: number;
+    readonly zblank: number | null;
+    readonly blank: number | null;
+    readonly zdither: number;
+    readonly ztile: number[];
+    readonly width: number;
+    readonly height: number;
+    readonly bzero: number;
+    readonly bscale: number;
+    readonly algorithmParameters: AlgorithmParameters;
+    readonly zquantiz: string;
+    constructor(header: Header, data: ArrayBuffer | Blob);
+    /**
+     * Override setAccessors to replace compressed data column accessors
+     * with decompression-aware versions. Delegates base TFORM parsing to BinaryTable.
+     */
+    protected setAccessors(header: Header): void;
+    /**
+     * Override _getRows to handle compressed image tile decompression
+     * and subtractive dithering.
+     */
+    protected _getRows(buffer: ArrayBuffer, nRows: number): Float32Array;
+    /**
+     * Read a frame from the compressed image.
+     * Exposes the same API as Image.getFrame() for consistency.
+     */
+    getFrame(_nFrame?: number): Promise<Float32Array>;
+    /** Compute min/max pixel values, ignoring NaN. */
+    getExtent(arr: Float32Array): [number, number];
+    /** Get a single pixel value at (x, y). */
+    getPixel(arr: Float32Array, x: number, y: number): number;
+}
+
+/**
+ * Compute the minimum and maximum pixel values in a typed array,
+ * ignoring NaN values.
+ *
+ * @returns A tuple [min, max], or [NaN, NaN] if all values are NaN.
+ */
+declare function getExtent(arr: TypedArray | Float32Array): [number, number];
+/**
+ * Get a single pixel value from a flat array given x, y coordinates and image width.
+ */
+declare function getPixel(arr: TypedArray | Float32Array, x: number, y: number, width: number): number;
+
+/**
+ * Setup functions for Rice decompression, keyed by bytepix (1, 2, or 4).
+ * Each returns [fsbits, fsmax, lastpix, pointer].
+ */
+declare const RiceSetup: Record<number, (array: Uint8Array) => [number, number, number, number]>;
+/**
+ * Rice decompression algorithm.
+ *
+ * Decompresses a byte array that was compressed using the Rice algorithm,
+ * as defined in the FITS tiled image compression convention.
+ *
+ * @param array - Compressed byte array.
+ * @param blocksize - Number of pixels encoded in a block.
+ * @param bytepix - Number of bytes per original pixel (1, 2, or 4).
+ * @param pixels - Output array to fill with decompressed values.
+ * @param nx - Number of output pixels (tile length).
+ * @param setup - Setup function map (default: RiceSetup).
+ * @returns The filled pixels array.
+ */
+declare function riceDecompress(array: Uint8Array, blocksize: number, bytepix: number, pixels: TypedArray, nx: number, setup?: Record<number, (array: Uint8Array) => [number, number, number, number]>): TypedArray;
+
+/**
+ * Parse a FITS file from an ArrayBuffer.
+ *
+ * Reads 2880-byte blocks sequentially, looking for the END keyword
+ * to delimit headers. After each header, the corresponding data unit
+ * is sliced from the buffer and an HDU is created.
+ *
+ * @param buffer - The complete FITS file as an ArrayBuffer.
+ * @returns Array of parsed HDUs.
+ */
+declare function parseBuffer(buffer: ArrayBuffer, options?: ReadOptions): HDU[];
+/**
+ * Parse a FITS file from a Blob (File object) using streaming block reads.
+ *
+ * Reads header blocks incrementally (2880 bytes at a time) without loading
+ * the entire file into memory. Data units are kept as Blob slices for
+ * lazy on-demand reading, significantly reducing memory usage for large files.
+ *
+ * @param blob - The FITS file as a Blob or File object.
+ * @returns Promise resolving to an array of parsed HDUs.
+ */
+declare function parseBlob(blob: Blob, options?: ReadOptions): Promise<HDU[]>;
+
+/** Width of a single FITS header card in bytes (characters). */
+declare const LINE_WIDTH = 80;
+/** Size of a FITS block in bytes. All FITS structures are padded to this boundary. */
+declare const BLOCK_LENGTH = 2880;
+/** Number of header card lines per FITS block. */
+declare const LINES_PER_BLOCK: number;
+/** Default maximum number of header lines to parse. */
+declare const DEFAULT_MAX_HEADER_LINES = 600;
+/** FITS special integer value representing a NULL pixel in compressed images. */
+declare const NULL_VALUE = -2147483647;
+/** FITS special integer value representing a 0.0 pixel in compressed images. */
+declare const ZERO_VALUE = -2147483646;
+/** Number of random values in the dithering sequence. */
+declare const N_RANDOM = 10000;
+/** Library version. */
+declare const VERSION: string;
+
+/**
+ * Base error class for all FITS-related errors.
+ */
+declare class FITSError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown during header parsing or validation.
+ */
+declare class HeaderError extends FITSError {
+    constructor(message: string);
+}
+/**
+ * Error thrown during data unit reading or interpretation.
+ */
+declare class DataError extends FITSError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when decompression fails.
+ */
+declare class DecompressionError extends FITSError {
+    constructor(message: string);
+}
+
+export { type AlgorithmParameters, type AsciiAccessor, type AsciiTableTypeCode, BLOCK_LENGTH, type BinaryAccessor, BinaryTable, type BinaryTableTypeCode, type BitPix, type CardValue, CompressedImage, type CompressionType, DEFAULT_MAX_HEADER_LINES, DataError, DataUnit, type DataUnitType, DecompressionError, type ExtensionType, FITS, FITSError, type FetchOptions, HDU, Header, type HeaderCard, HeaderError, Image, LINES_PER_BLOCK, LINE_WIDTH, NULL_VALUE, N_RANDOM, type QuantizationType, type ReadOptions, RiceSetup, Table, type TableRow, type TypedArray, type TypedArrayConstructor, VERSION, type WarningCallback, type ZBitPix, ZERO_VALUE, getExtent, getPixel, parseBlob, parseBuffer, riceDecompress };