@gyeonghokim/fisheye.js 1.0.0 → 1.0.1

package/README.md

@@ -2,12 +2,12 @@
 
 > Modern fisheye dewarping library for the web using **WebGPU** (general-purpose GPU compute)
 
-fisheye.js processes [VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame)s with **WebGPU compute shaders**—no canvas 2D—and corrects fisheye lens distortion using the **OpenCV fisheye camera model** (polynomial in angle θ with coefficients k1–k4), not a simple radial model.
+fisheye.js processes [VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame)s with **WebGPU compute shaders**—no canvas 2D—and corrects fisheye lens distortion using the **OpenCV fisheye model** (Kannala–Brandt–style polynomial in angle θ with coefficients k1–k4). This is the same model as in [OpenCV’s fisheye module](https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html), not UCM (Unified Camera Model) or a simple radial model.
 
 ## Features
 
 - **WebGPU GPGPU**: Compute-shader pipeline via [TypeGPU](https://www.npmjs.com/package/typegpu); input/output as textures and readback to VideoFrame—no canvas element for dewarping
-- **OpenCV fisheye model**: Distortion model `θ_d = θ × (1 + k1·θ² + k2·θ⁴ + k3·θ⁶ + k4·θ⁸)` for accurate calibration
+- **OpenCV fisheye (Kannala–Brandt) model**: Distortion model `θ_d = θ × (1 + k1·θ² + k2·θ⁴ + k3·θ⁶ + k4·θ⁸)` for accurate calibration
 - **WebCodecs**: Built on the [VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame) API
 - **ESM**: `import { Fisheye } from "@gyeonghokim/fisheye.js"`
 - **npm**: Install via npm or other package managers
@@ -79,9 +79,8 @@ Creates a new Fisheye dewarper instance.
 - `centerY` (number, optional): Y offset of the lens center (normalized, -1.0 to 1.0). Default: `0`
 - `zoom` (number, optional): Zoom factor. Default: `1.0`
 
-**Fisheye model (OpenCV):**
-We follow the OpenCV fisheye camera model described here:
-https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html
+**Fisheye model (OpenCV fisheye / Kannala–Brandt):**
+We use the same model as OpenCV’s [fisheye module](https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html) (cited there as the “generic camera model” from Kannala & Brandt, 2006). It is a polynomial-in-θ model, not UCM:
 
 ```
 theta = atan(r)

package/dist/index.d.ts

@@ -1,266 +1,269 @@
-/**
- * Options for configuring the Fisheye dewarper
- */
-interface FisheyeOptions {
-    /**
-     * Fisheye distortion coefficient k1.
-     */
-    k1?: number;
-    /**
-     * Fisheye distortion coefficient k2.
-     */
-    k2?: number;
-    /**
-     * Fisheye distortion coefficient k3.
-     */
-    k3?: number;
-    /**
-     * Fisheye distortion coefficient k4.
-     */
-    k4?: number;
-    /**
-     * Canvas width for output
-     * @default 300
-     */
-    width?: number;
-    /**
-     * Canvas height for output
-     * @default 150
-     */
-    height?: number;
-    /**
-     * Field of view in degrees
-     * @default 180
-     */
-    fov?: number;
-    /**
-     * X offset of the lens center (normalized, -1.0 to 1.0)
-     * @default 0
-     */
-    centerX?: number;
-    /**
-     * Y offset of the lens center (normalized, -1.0 to 1.0)
-     * @default 0
-     */
-    centerY?: number;
-    /**
-     * Zoom factor
-     * @default 1.0
-     */
-    zoom?: number;
-}
-/**
- * Internal configuration after applying defaults
- */
-interface FisheyeConfig extends Required<FisheyeOptions> {
-}
-
-/**
- * Fisheye dewarper using WebGPU via TypeGPU (Pure GPGPU)
- *
- * @example
- * ```ts
- * const dewarper = new Fisheye({
- *   distortion: 0.5,
- *   width: 1920,
- *   height: 1080,
- * });
- *
- * const dewarpedFrame = await dewarper.dewarp(videoFrame);
- * ```
- */
-declare class Fisheye {
-    private config;
-    private root;
-    private uniformBuffer;
-    private inputTexture;
-    private outputTexture;
-    private inputView;
-    private outputView;
-    private bindGroup;
-    private dewarpPipeline;
-    private readbackBuffers;
-    private readbackIndex;
-    private readbackHasData;
-    private readbackBytesPerRow;
-    private readbackActualBytesPerRow;
-    private pixelBuffer;
-    private inputTextureSize;
-    private outputTextureSize;
-    private static createInputView;
-    private static createOutputView;
-    constructor(options?: FisheyeOptions);
-    /**
-     * Apply default values to options
-     */
-    private applyDefaults;
-    /**
-     * Initialize TypeGPU root and resources
-     */
-    private initialize;
-    /**
-     * Get uniform data from current configuration
-     */
-    private getUniformData;
-    /**
-     * Update uniform buffer with current configuration
-     */
-    private updateUniforms;
-    private readbackToVideoFrame;
-    /**
-     * Create input texture with proper typing
-     */
-    private createInputTexture;
-    /**
-     * Create output texture with proper typing (storage only, no render needed for GPGPU)
-     */
-    private createOutputTexture;
-    /**
-     * Calculate bytes per row with proper alignment (256-byte alignment for WebGPU)
-     */
-    private calculateBytesPerRow;
-    /**
-     * Create or recreate readback buffer for GPU to CPU data transfer
-     */
-    private createReadbackBuffer;
-    /**
-     * Dewarp a VideoFrame
-     *
-     * @param frame - Input VideoFrame with fisheye distortion
-     * @returns Dewarped VideoFrame
-     */
-    dewarp(frame: VideoFrame): Promise<VideoFrame>;
-    /**
-     * Update configuration
-     */
-    updateConfig(options: Partial<FisheyeOptions>): void;
-    /**
-     * Clean up GPU resources
-     */
-    destroy(): void;
-}
-
-/**
- * Supported YUV pixel formats for VideoFrame creation
- */
-type YUVFormat = "I420" | "I420A" | "I422" | "I444" | "NV12";
-/**
- * Options for creating a VideoFrame from YUV data
- */
-interface CreateVideoFrameOptions {
-    /**
-     * YUV pixel format
-     * - I420: YUV 4:2:0 planar (Y plane, U plane, V plane)
-     * - I420A: YUV 4:2:0 planar with alpha
-     * - I422: YUV 4:2:2 planar
-     * - I444: YUV 4:4:4 planar
-     * - NV12: YUV 4:2:0 semi-planar (Y plane, interleaved UV plane)
-     */
-    format: YUVFormat;
-    /**
-     * Width of the video frame in pixels
-     */
-    width: number;
-    /**
-     * Height of the video frame in pixels
-     */
-    height: number;
-    /**
-     * Timestamp in microseconds
-     */
-    timestamp: number;
-    /**
-     * Duration in microseconds (optional)
-     */
-    duration?: number;
-    /**
-     * Display width (optional, defaults to width)
-     */
-    displayWidth?: number;
-    /**
-     * Display height (optional, defaults to height)
-     */
-    displayHeight?: number;
-    /**
-     * Color space configuration (optional)
-     */
-    colorSpace?: VideoColorSpaceInit;
-    /**
-     * Transfer ownership of the buffer for zero-copy (optional)
-     * If true, the input buffer will be detached after VideoFrame creation
-     */
-    transfer?: boolean;
-}
-/**
- * Create a VideoFrame from YUV binary data
- *
- * @param data - YUV binary data (ArrayBuffer, TypedArray, or DataView)
- * @param options - Configuration options including format, dimensions, and timestamp
- * @returns A new VideoFrame object
- *
- * @example
- * ```ts
- * // Create VideoFrame from I420 (YUV 4:2:0) data
- * const yuvData = new Uint8Array(width * height * 1.5); // I420 size
- * const frame = createVideoFrameFromYUV(yuvData, {
- *   format: "I420",
- *   width: 1920,
- *   height: 1080,
- *   timestamp: 0,
- * });
- * ```
- *
- * @example
- * ```ts
- * // Create VideoFrame from NV12 data with zero-copy transfer
- * const nv12Data = new Uint8Array(width * height * 1.5);
- * const frame = createVideoFrameFromYUV(nv12Data, {
- *   format: "NV12",
- *   width: 1920,
- *   height: 1080,
- *   timestamp: 0,
- *   transfer: true, // Transfer buffer ownership for better performance
- * });
- * ```
- */
-declare function createVideoFrameFromYUV(data: BufferSource, options: CreateVideoFrameOptions): VideoFrame;
-/**
- * Convert RGBA image data to YUV format (I420 by default)
- *
- * Uses ITU-R BT.601 color space conversion:
- * - Y = 0.299*R + 0.587*G + 0.114*B
- * - U = -0.169*R - 0.331*G + 0.5*B + 128
- * - V = 0.5*R - 0.419*G - 0.081*B + 128
- *
- * For I420 format:
- * - Y plane: full resolution (width * height)
- * - U plane: quarter resolution ((width/2) * (height/2))
- * - V plane: quarter resolution ((width/2) * (height/2))
- *
- * @param rgbaData - RGBA pixel data (Uint8ClampedArray from ImageData)
- * @param width - Image width in pixels
- * @param height - Image height in pixels
- * @param format - YUV format to convert to (default: "I420")
- * @returns YUV data as Uint8Array
- *
- * @example
- * ```ts
- * const canvas = document.createElement('canvas');
- * const ctx = canvas.getContext('2d');
- * ctx.drawImage(image, 0, 0);
- * const imageData = ctx.getImageData(0, 0, width, height);
- * const yuvData = convertRGBAtoYUV(imageData.data, width, height);
- * ```
- */
-declare function convertRGBAtoYUV(rgbaData: Uint8ClampedArray, width: number, height: number, format?: YUVFormat): Uint8Array;
-/**
- * Calculate the expected byte size for YUV data based on format and dimensions
- *
- * @param format - YUV pixel format
- * @param width - Frame width in pixels
- * @param height - Frame height in pixels
- * @returns Expected byte size
- */
-declare function calculateYUVDataSize(format: YUVFormat, width: number, height: number): number;
-
-export { type CreateVideoFrameOptions, Fisheye, type FisheyeConfig, type FisheyeOptions, type YUVFormat, calculateYUVDataSize, convertRGBAtoYUV, createVideoFrameFromYUV };
+/**
+ * Calculate the expected byte size for YUV data based on format and dimensions
+ *
+ * @param format - YUV pixel format
+ * @param width - Frame width in pixels
+ * @param height - Frame height in pixels
+ * @returns Expected byte size
+ */
+export declare function calculateYUVDataSize(format: YUVFormat, width: number, height: number): number;
+
+/**
+ * Convert RGBA image data to YUV format (I420 by default)
+ *
+ * Uses ITU-R BT.601 color space conversion:
+ * - Y = 0.299*R + 0.587*G + 0.114*B
+ * - U = -0.169*R - 0.331*G + 0.5*B + 128
+ * - V = 0.5*R - 0.419*G - 0.081*B + 128
+ *
+ * For I420 format:
+ * - Y plane: full resolution (width * height)
+ * - U plane: quarter resolution ((width/2) * (height/2))
+ * - V plane: quarter resolution ((width/2) * (height/2))
+ *
+ * @param rgbaData - RGBA pixel data (Uint8ClampedArray from ImageData)
+ * @param width - Image width in pixels
+ * @param height - Image height in pixels
+ * @param format - YUV format to convert to (default: "I420")
+ * @returns YUV data as Uint8Array
+ *
+ * @example
+ * ```ts
+ * const canvas = document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ * ctx.drawImage(image, 0, 0);
+ * const imageData = ctx.getImageData(0, 0, width, height);
+ * const yuvData = convertRGBAtoYUV(imageData.data, width, height);
+ * ```
+ */
+export declare function convertRGBAtoYUV(rgbaData: Uint8ClampedArray, width: number, height: number, format?: YUVFormat): Uint8Array;
+
+/**
+ * Create a VideoFrame from YUV binary data
+ *
+ * @param data - YUV binary data (ArrayBuffer, TypedArray, or DataView)
+ * @param options - Configuration options including format, dimensions, and timestamp
+ * @returns A new VideoFrame object
+ *
+ * @example
+ * ```ts
+ * // Create VideoFrame from I420 (YUV 4:2:0) data
+ * const yuvData = new Uint8Array(width * height * 1.5); // I420 size
+ * const frame = createVideoFrameFromYUV(yuvData, {
+ *   format: "I420",
+ *   width: 1920,
+ *   height: 1080,
+ *   timestamp: 0,
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create VideoFrame from NV12 data with zero-copy transfer
+ * const nv12Data = new Uint8Array(width * height * 1.5);
+ * const frame = createVideoFrameFromYUV(nv12Data, {
+ *   format: "NV12",
+ *   width: 1920,
+ *   height: 1080,
+ *   timestamp: 0,
+ *   transfer: true, // Transfer buffer ownership for better performance
+ * });
+ * ```
+ */
+export declare function createVideoFrameFromYUV(data: BufferSource, options: CreateVideoFrameOptions): VideoFrame;
+
+/**
+ * Options for creating a VideoFrame from YUV data
+ */
+export declare interface CreateVideoFrameOptions {
+    /**
+     * YUV pixel format
+     * - I420: YUV 4:2:0 planar (Y plane, U plane, V plane)
+     * - I420A: YUV 4:2:0 planar with alpha
+     * - I422: YUV 4:2:2 planar
+     * - I444: YUV 4:4:4 planar
+     * - NV12: YUV 4:2:0 semi-planar (Y plane, interleaved UV plane)
+     */
+    format: YUVFormat;
+    /**
+     * Width of the video frame in pixels
+     */
+    width: number;
+    /**
+     * Height of the video frame in pixels
+     */
+    height: number;
+    /**
+     * Timestamp in microseconds
+     */
+    timestamp: number;
+    /**
+     * Duration in microseconds (optional)
+     */
+    duration?: number;
+    /**
+     * Display width (optional, defaults to width)
+     */
+    displayWidth?: number;
+    /**
+     * Display height (optional, defaults to height)
+     */
+    displayHeight?: number;
+    /**
+     * Color space configuration (optional)
+     */
+    colorSpace?: VideoColorSpaceInit;
+    /**
+     * Transfer ownership of the buffer for zero-copy (optional)
+     * If true, the input buffer will be detached after VideoFrame creation
+     */
+    transfer?: boolean;
+}
+
+/**
+ * Fisheye dewarper using WebGPU via TypeGPU (Pure GPGPU)
+ *
+ * @example
+ * ```ts
+ * const dewarper = new Fisheye({
+ *   distortion: 0.5,
+ *   width: 1920,
+ *   height: 1080,
+ * });
+ *
+ * const dewarpedFrame = await dewarper.dewarp(videoFrame);
+ * ```
+ */
+export declare class Fisheye {
+    private config;
+    private root;
+    private uniformBuffer;
+    private inputTexture;
+    private outputTexture;
+    private bindGroup;
+    private dewarpPipeline;
+    private readbackBuffers;
+    private readbackIndex;
+    private readbackHasData;
+    private readbackBytesPerRow;
+    private readbackActualBytesPerRow;
+    private pixelBuffer;
+    private inputTextureSize;
+    private outputTextureSize;
+    private uniformInputWidth;
+    private uniformInputHeight;
+    constructor(options?: FisheyeOptions);
+    /**
+     * Apply default values to options
+     */
+    private applyDefaults;
+    /**
+     * Initialize TypeGPU root and resources
+     */
+    private initialize;
+    /**
+     * Get uniform data from current configuration
+     */
+    private getUniformData;
+    /**
+     * Update uniform buffer with current configuration
+     */
+    private updateUniforms;
+    private readbackToVideoFrame;
+    /**
+     * Create input texture (TypeGPU; per official docs: sampled + render for .write(image/VideoFrame)).
+     */
+    private createInputTexture;
+    /**
+     * Create output storage texture (TypeGPU; type-safe with layout.$)
+     */
+    private createOutputTexture;
+    /**
+     * Calculate bytes per row with proper alignment (256-byte alignment for WebGPU)
+     */
+    private calculateBytesPerRow;
+    /**
+     * Create or recreate readback buffer for GPU to CPU data transfer
+     */
+    private createReadbackBuffer;
+    /**
+     * Dewarp a VideoFrame
+     *
+     * @param frame - Input VideoFrame with fisheye distortion
+     * @returns Dewarped VideoFrame
+     */
+    dewarp(frame: VideoFrame): Promise<VideoFrame>;
+    /**
+     * Update configuration
+     */
+    updateConfig(options: Partial<FisheyeOptions>): void;
+    /**
+     * Clean up GPU resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Internal configuration after applying defaults
+ */
+export declare interface FisheyeConfig extends Required<FisheyeOptions> {
+}
+
+/**
+ * Options for configuring the Fisheye dewarper
+ */
+export declare interface FisheyeOptions {
+    /**
+     * Fisheye distortion coefficient k1.
+     */
+    k1?: number;
+    /**
+     * Fisheye distortion coefficient k2.
+     */
+    k2?: number;
+    /**
+     * Fisheye distortion coefficient k3.
+     */
+    k3?: number;
+    /**
+     * Fisheye distortion coefficient k4.
+     */
+    k4?: number;
+    /**
+     * Canvas width for output
+     * @default 300
+     */
+    width?: number;
+    /**
+     * Canvas height for output
+     * @default 150
+     */
+    height?: number;
+    /**
+     * Field of view in degrees
+     * @default 180
+     */
+    fov?: number;
+    /**
+     * X offset of the lens center (normalized, -1.0 to 1.0)
+     * @default 0
+     */
+    centerX?: number;
+    /**
+     * Y offset of the lens center (normalized, -1.0 to 1.0)
+     * @default 0
+     */
+    centerY?: number;
+    /**
+     * Zoom factor
+     * @default 1.0
+     */
+    zoom?: number;
+}
+
+/**
+ * Supported YUV pixel formats for VideoFrame creation
+ */
+export declare type YUVFormat = "I420" | "I420A" | "I422" | "I444" | "NV12";
+
+export { }