@gyeonghokim/fisheye.js 1.1.0 → 2.0.0

package/README.md

@@ -1,10 +1,10 @@
 # fisheye.js
 
-DEMO: https://gyeonghokim.github.io/fisheye.js/
+DEMO: <https://gyeonghokim.github.io/fisheye.js/>
 
-> Modern fisheye dewarping library for the web using **WebGPU** (general-purpose GPU compute)
+> Modern fisheye undistortion 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 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.
+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).
 
 ## Learning Docs
 
@@ -12,7 +12,7 @@ See the full educational curriculum in `doc/index.md`.
 
 ## 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
+- **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 undistortion
 - **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"`
@@ -37,7 +37,7 @@ if you installed `@webgpu/types`,
 ```
 
 > Why should I install webgpu types?
-> This library does not render your binary, it just dewarp the VideoFrame.
+> This library does not render your binary, it just undistorts the VideoFrame.
 > You should make **your own YUV renderer**, or you can install `@gyeonghokim/yuv-player`.
 
 in your code,
@@ -45,72 +45,185 @@ in your code,
 ```ts
 import { Fisheye } from "@gyeonghokim/fisheye.js";
 
-const dewarper = new Fisheye({
+// Option 1: Flat style (simple)
+const fisheye = new Fisheye({
+  // OpenCV fisheye distortion coefficients D = [k1, k2, k3, k4]
   k1: 0.5,
   k2: 0.0,
   k3: 0.0,
   k4: 0.0,
+
+  // Output size
+  width: 1920,
+  height: 1080,
+
+  // Optional: Camera matrix K parameters
+  fx: 1000, // focal length x (pixels)
+  fy: 1000, // focal length y (pixels)
+  cx: 960, // principal point x (pixels)
+  cy: 540, // principal point y (pixels)
+
+  // Optional: New camera matrix P estimation parameters
+  balance: 0.0, // 0.0 = no black edges (zoom in), 1.0 = keep original FOV (may have black edges)
+  fovScale: 1.0, // >1.0 = widen FOV, <1.0 = narrow FOV
+
+  // Optional: Projection mode
+  projection: { kind: "rectilinear" }, // or "equirectangular", "cylindrical", "original"
+});
+
+// Option 2: Grouped style (OpenCV-like)
+const fisheyeGrouped = new Fisheye({
+  K: { fx: 1000, fy: 1000, cx: 960, cy: 540 },
+  D: { k1: 0.5, k2: 0, k3: 0, k4: 0 },
+  size: { width: 1920, height: 1080 },
+  balance: 0.0,
+  fovScale: 1.0,
+  projection: { kind: "rectilinear" },
+});
+
+// Option 3: Manual rectilinear with explicit P matrix
+const fisheyeManual = new Fisheye({
+  k1: 0.5, k2: 0, k3: 0, k4: 0,
   width: 1920,
   height: 1080,
-  fov: 180, // Field of view in degrees
-  centerX: 0, // X offset of lens center (-1.0 to 1.0)
-  centerY: 0, // Y offset of lens center (-1.0 to 1.0)
-  zoom: 1.0, // Zoom factor
+  projection: { kind: "rectilinear", mode: "manual", newFx: 800, newFy: 800 },
 });
 
-const renderLoop = (timestamp: DOMHighResTimestamp) => {
-  // your render logic
-  const dewarpedVideoFrame: VideoFrame = await dewarper.dewarp(yourVideoFrame);
-  yourYUVPlayer.draw(dewarpedVideoFrame);
+const renderLoop = async (timestamp: DOMHighResTimestamp) => {
+  const undistorted: VideoFrame = await fisheye.undistort(yourVideoFrame);
+  yourYUVPlayer.draw(undistorted);
   requestAnimationFrame(renderLoop);
 };
 ```
 
+## Architecture & Design
+
+### Distortion Model: OpenCV Fisheye (Kannala-Brandt)
+
+This library uses the **OpenCV fisheye model** (Kannala-Brandt, 2006) for undistortion:
+
+```
+# Normalized coordinates (a, b) where a = X/Z, b = Y/Z
+r = sqrt(a² + b²)
+θ = atan(r)                                           # incidence angle
+θ_d = θ × (1 + k₁θ² + k₂θ⁴ + k₃θ⁶ + k₄θ⁸)           # distorted angle
+x' = (θ_d / r) × a,  y' = (θ_d / r) × b              # distorted coords
+u = fx(x' + αy') + cx,  v = fy × y' + cy             # pixel coords
+```
+
+This is the same model as [OpenCV's fisheye module](https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html).
+
+**Important:** OpenCV's `fisheye.undistortImage()` always outputs **rectilinear (perspective) projection only**. It does not provide panoramic or other projection modes.
+
+### Projection Modes
+
+For **WebGPU efficiency**, projection transformation is applied in a **single GPU pass**:
+
+| Mode | Description |
+|------|-------------|
+| `rectilinear` | Standard perspective projection (same as OpenCV) |
+| `rectilinear` + `mode: "manual"` | Explicit P matrix with `newFx`, `newFy`, `newCx?`, `newCy?` |
+| `equirectangular` | Panoramic equirectangular projection |
+| `cylindrical` | Panoramic cylindrical projection |
+| `original` | Pass-through (no undistortion) |
+
+### Why Unified GPU Pipeline?
+
+Traditional OpenCV approach:
+
+```python
+# Step 1: Undistort (GPU/CPU)
+undistorted = cv2.fisheye.undistortImage(img, K, D, Knew)
+
+# Step 2: Projection transform (CPU) - if panoramic needed
+panorama = cv2.remap(undistorted, custom_map_x, custom_map_y, cv2.INTER_LINEAR)
+```
+
+**Our approach (single GPU compute shader):**
+
+```typescript
+// All in one GPU pass: undistortion + projection
+const undistorted = await fisheye.undistort(input);
+```
+
 ## API
 
 ### `new Fisheye(options?: FisheyeOptions)`
 
-Creates a new Fisheye dewarper instance.
+Creates a new Fisheye undistortion instance.
 
-**Options:**
+#### OpenCV Fisheye Model Parameters
 
-- `k1` (number, optional): Fisheye distortion coefficient k1. Typical range: -1.0 to 1.0. Default: `0`.
-- `k2` (number, optional): Fisheye distortion coefficient k2. Default: `0`.
-- `k3` (number, optional): Fisheye distortion coefficient k3. Default: `0`.
-- `k4` (number, optional): Fisheye distortion coefficient k4. Default: `0`.
-- `width` (number, optional): Output frame width. Default: `300`
-- `height` (number, optional): Output frame height. Default: `150`
-- `fov` (number, optional): Field of view in degrees. Default: `180`
-- `centerX` (number, optional): X offset of the lens center (normalized, -1.0 to 1.0). Default: `0`
-- `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`
+| Parameter  | Type      | Default    | Description                                              |
+| ---------- | --------- | ---------- | -------------------------------------------------------- |
+| `fx`       | `number?` | auto       | Camera matrix K: focal length in x-axis (pixels)         |
+| `fy`       | `number?` | auto       | Camera matrix K: focal length in y-axis (pixels)         |
+| `cx`       | `number?` | `width/2`  | Camera matrix K: principal point x-coordinate (pixels)   |
+| `cy`       | `number?` | `height/2` | Camera matrix K: principal point y-coordinate (pixels)   |
+| `k1`       | `number?` | `0`        | Distortion coefficient k1 (Kannala-Brandt)               |
+| `k2`       | `number?` | `0`        | Distortion coefficient k2 (Kannala-Brandt)               |
+| `k3`       | `number?` | `0`        | Distortion coefficient k3 (Kannala-Brandt)               |
+| `k4`       | `number?` | `0`        | Distortion coefficient k4 (Kannala-Brandt)               |
+| `width`    | `number?` | `300`      | Output image width (OpenCV `new_size.width`)             |
+| `height`   | `number?` | `150`      | Output image height (OpenCV `new_size.height`)           |
+| `balance`  | `number?` | `0.0`      | Balance (0.0 = no black edges/zoom in, 1.0 = keep original FOV) |
+| `fovScale` | `number?` | `1.0`      | FOV scale (>1.0 = widen FOV, <1.0 = narrow FOV)          |
 
-**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:
+**Note:** These parameters exactly match [OpenCV fisheye API](https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html). Use values from `cv2.fisheye.calibrate()` or `cv2.fisheye.estimateNewCameraMatrixForUndistortRectify()`.
 
-```
-theta = atan(r)
-theta_d = theta * (1 + k1*theta^2 + k2*theta^4 + k3*theta^6 + k4*theta^8)
-r_d = tan(theta_d)
+#### Projection Options
+
+| Parameter    | Type                 | Default                    | Description                                                    |
+| ------------ | -------------------- | -------------------------- | -------------------------------------------------------------- |
+| `projection` | `FisheyeProjection`  | `{ kind: "rectilinear" }`  | Output projection mode (see Projection Modes above)            |
+
+**FisheyeProjection types:**
+
+```typescript
+// Auto: P matrix computed from balance/fovScale
+{ kind: "rectilinear" }
+{ kind: "equirectangular" }
+{ kind: "cylindrical" }
+{ kind: "original" }
+
+// Manual: Explicit P matrix
+{ kind: "rectilinear", mode: "manual", newFx: number, newFy: number, newCx?: number, newCy?: number }
 ```
 
-### `dewarp(frame: VideoFrame): Promise<VideoFrame>`
+### `undistort(frame: VideoFrame): Promise<VideoFrame>`
 
-Dewarps a VideoFrame with fisheye distortion.
+Undistorts a VideoFrame with fisheye distortion.
 
 **Parameters:**
 
 - `frame`: Input VideoFrame with fisheye distortion
 
-**Returns:** Promise that resolves to a dewarped VideoFrame
+**Returns:** Promise that resolves to an undistorted VideoFrame
+
+**Differences from OpenCV:**
+
+Unlike OpenCV's `fisheye.undistortImage()` which only outputs rectilinear (perspective) projection, this method performs **all transformations in a single GPU pass** for WebGPU efficiency:
+
+1. **Undistortion** (OpenCV Kannala-Brandt fisheye model)
+2. **Projection** (rectilinear, equirectangular, cylindrical, or original)
+
+OpenCV equivalent for non-rectilinear projections would require 2 separate operations:
+```python
+# OpenCV: 2 CPU/GPU roundtrips for panoramic projection
+undistorted = cv2.fisheye.undistortImage(img, K, D, Knew)
+panorama = cv2.remap(undistorted, map_x, map_y, cv2.INTER_LINEAR)
+
+# fisheye.js: 1 GPU pass - undistortion + projection
+undistorted = await fisheye.undistort(img)
+```
 
 ### `updateConfig(options: Partial<FisheyeOptions>): void`
 
-Updates the dewarper configuration. You can update any subset of the original options.
+Updates the configuration. You can update any subset of the original options.
 
 ### `destroy(): void`
 
-Cleans up GPU resources. Call this when you're done using the dewarper.
+Cleans up GPU resources. Call this when you're done using the instance.
 
 ## Working with YUV Binary Data
 
@@ -119,21 +232,21 @@ If you receive raw YUV binary data from a camera or server, you can use the `cre
 ```ts
 import { Fisheye, createVideoFrameFromYUV } from "@gyeonghokim/fisheye.js";
 
-const dewarper = new Fisheye({ k1: 0.5, width: 1920, height: 1080 });
+const fisheye = new Fisheye({ k1: 0.5, width: 1920, height: 1080 });
 
 // Example: Receiving NV12 data from a server
 const response = await fetch("/api/camera/frame");
 const yuvBuffer = await response.arrayBuffer();
 
 const frame = createVideoFrameFromYUV(new Uint8Array(yuvBuffer), {
-  format: "NV12",  // YUV format
+  format: "NV12", // YUV format
   width: 1920,
   height: 1080,
-  timestamp: performance.now() * 1000,  // microseconds
+  timestamp: performance.now() * 1000, // microseconds
 });
 
-const dewarpedFrame = await dewarper.dewarp(frame);
-frame.close();  // Don't forget to close the original frame
+const undistorted = await fisheye.undistort(frame);
+frame.close(); // Don't forget to close the original frame
 ```
 
 ### `createVideoFrameFromYUV(data, options)`
@@ -156,13 +269,13 @@ Creates a VideoFrame from YUV binary data.
 
 **Supported YUV Formats:**
 
-| Format | Description | Data Size |
-|--------|-------------|-----------|
-| `I420` | YUV 4:2:0 planar (Y, U, V planes) | width × height × 1.5 |
-| `NV12` | YUV 4:2:0 semi-planar (Y plane, interleaved UV) | width × height × 1.5 |
-| `I420A` | YUV 4:2:0 planar with alpha | width × height × 2.5 |
-| `I422` | YUV 4:2:2 planar | width × height × 2 |
-| `I444` | YUV 4:4:4 planar | width × height × 3 |
+| Format  | Description                                     | Data Size            |
+| ------- | ----------------------------------------------- | -------------------- |
+| `I420`  | YUV 4:2:0 planar (Y, U, V planes)               | width × height × 1.5 |
+| `NV12`  | YUV 4:2:0 semi-planar (Y plane, interleaved UV) | width × height × 1.5 |
+| `I420A` | YUV 4:2:0 planar with alpha                     | width × height × 2.5 |
+| `I422`  | YUV 4:2:2 planar                                | width × height × 2   |
+| `I444`  | YUV 4:4:4 planar                                | width × height × 3   |
 
 ### `calculateYUVDataSize(format, width, height)`
 
@@ -171,7 +284,7 @@ Calculates the expected byte size for YUV data.
 ```ts
 import { calculateYUVDataSize } from "@gyeonghokim/fisheye.js";
 
-const size = calculateYUVDataSize("NV12", 1920, 1080);  // 3110400 bytes
+const size = calculateYUVDataSize("NV12", 1920, 1080); // 3110400 bytes
 ```
 
 ## Development

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+declare type AllOrNothing<T extends object> = T | {
+    [K in keyof T]?: undefined;
+};
+
 /**
  * Calculate the expected byte size for YUV data based on format and dimensions
  *
@@ -8,6 +12,9 @@
  */
 export declare function calculateYUVDataSize(format: YUVFormat, width: number, height: number): number;
 
+/** Flat K matrix input - fx/fy both required or both omitted */
+export declare type CameraIntrinsics = AllOrNothing<Pick<KMatrix, "fx" | "fy">> & Pick<KMatrix, "cx" | "cy" | "alpha">;
+
 /**
  * Convert RGBA image data to YUV format (I420 by default)
  *
@@ -120,20 +127,17 @@ export declare interface CreateVideoFrameOptions {
     transfer?: boolean;
 }
 
+/** D vector - distortion coefficients for `θ_d = θ(1 + k₁θ² + k₂θ⁴ + k₃θ⁶ + k₄θ⁸)` */
+export declare interface DVector {
+    k1: number;
+    k2: number;
+    k3: number;
+    k4: number;
+}
+
 /**
- * Fisheye dewarper using WebGPU via TypeGPU (Pure GPGPU)
- *
- * @example
- * ```ts
- * const dewarper = new Fisheye({
- *   width: 1920,
- *   height: 1080,
- *   fov: 180,
- *   projection: "rectilinear",
- * });
- *
- * const dewarpedFrame = await dewarper.dewarp(inputVideoFrame);
- * ```
+ * Fisheye undistortion using WebGPU via TypeGPU.
+ * @see {@link https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html}
  */
 export declare class Fisheye {
     private config;
@@ -142,7 +146,7 @@ export declare class Fisheye {
     private inputTexture;
     private outputTexture;
     private bindGroup;
-    private dewarpPipeline;
+    private pipeline;
     private readbackBuffers;
     private readbackIndex;
     private readbackHasData;
@@ -153,169 +157,115 @@ export declare class Fisheye {
     private outputTextureSize;
     private uniformInputWidth;
     private uniformInputHeight;
+    private cachedNewCameraMatrix;
     constructor(options?: FisheyeOptions);
-    /**
-     * Apply default values to options
-     */
     private applyDefaults;
-    /**
-     * Initialize TypeGPU root and resources
-     */
+    /** Undistort a point using Newton's method (OpenCV fisheye inverse). */
+    private undistortPointNormalized;
+    private undistortPixelToNormalized;
+    /** @see {@link https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html#ga384940fdf04c03e362e94b6eb9b673c9|estimateNewCameraMatrixForUndistortRectify} */
+    private computeNewCameraMatrix;
     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
-     */
+    /** Undistort a VideoFrame. */
+    undistort(frame: VideoFrame): Promise<VideoFrame>;
+    /** Update configuration. */
     updateConfig(options: Partial<FisheyeOptions>): void;
-    /**
-     * Clean up GPU resources
-     */
+    /** Clean up GPU resources. */
     destroy(): void;
 }
 
-/**
- * Internal configuration after applying defaults
- */
-export declare interface FisheyeConfig extends Required<FisheyeOptions> {
+/** Normalized configuration with grouped K, D, size. */
+export declare interface FisheyeConfig {
+    K?: KMatrix;
+    D: DVector;
+    size: ImageSize;
+    balance: number;
+    fovScale: number;
+    projection: FisheyeProjection;
 }
 
-/**
- * Camera mount position. Affects which view range is meaningful (e.g. ceiling → 360° azimuth).
- * Used for defaults or validation when combined with projection.
- */
-export declare type FisheyeMount = "ceiling" | "wall" | "desk";
+/** Flat D vector input - all required or all omitted */
+export declare type FisheyeDistortionCoeffs = AllOrNothing<DVector>;
 
-/**
- * **Presets for UI:** Combine `mount` + `projection` (+ `fov`) and expose them to end users
- * as preset names instead of raw options. Example mapping:
- *
- * | User-facing name        | mount   | projection     | fov                  |
- * |-------------------------|---------|----------------|----------------------|
- * | Panoramic 180           | any     | equirectangular| 180                  |
- * | 360° Panorama           | ceiling | equirectangular| 360                  |
- * | Normal / PTZ view       | any     | rectilinear    | e.g. 90              |
- * | Quad (4 panes)          | ceiling | rectilinear ×4 | 90 per pane (layout) |
- *
- * The library does not define preset names; the app chooses labels and maps them to
- * `FisheyeOptions` (and, for Quad, to multiple Fisheye instances or a layout pipeline).
- */
-/**
- * Options for configuring the Fisheye dewarper
- */
-export declare interface FisheyeOptions {
-    /**
-     * Fisheye distortion coefficient k1 (OpenCV fisheye / Kannala–Brandt).
-     * From calibration; omit or 0 for ideal equidistant.
-     * @default 0
-     */
-    k1?: number;
-    /**
-     * Fisheye distortion coefficient k2.
-     * @default 0
-     */
-    k2?: number;
-    /**
-     * Fisheye distortion coefficient k3.
-     * @default 0
-     */
-    k3?: number;
-    /**
-     * Fisheye distortion coefficient k4.
-     * @default 0
-     */
-    k4?: number;
-    /**
-     * Output image width in pixels.
-     * @default 300
-     */
-    width?: number;
-    /**
-     * Output image height in pixels.
-     * @default 150
-     */
-    height?: number;
-    /**
-     * Field of view in degrees.
-     * For rectilinear: angular diameter of the output. For equirectangular: horizontal span.
-     * @default 180
-     */
-    fov?: number;
-    /**
-     * Projection used to map corrected angles to output pixels.
-     * @default "rectilinear"
-     */
+/** Union of flat options and grouped config for API flexibility. */
+export declare type FisheyeOptions = FisheyeOptionsStrict | FisheyeConfig;
+
+/** Flat options for user-facing API */
+export declare type FisheyeOptionsStrict = CameraIntrinsics & FisheyeDistortionCoeffs & OutputSize & {
+    balance?: number;
+    fovScale?: number;
     projection?: FisheyeProjection;
-    /**
-     * Camera mount position. Optional; can affect default FOV or valid range when projection is equirectangular.
-     * @default "ceiling"
-     */
-    mount?: FisheyeMount;
-    /**
-     * 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 applied after distortion correction.
-     * @default 1.0
-     */
-    zoom?: number;
+};
+
+export declare type FisheyeProjection = RectilinearProjection | {
+    readonly kind: "equirectangular";
+} | {
+    readonly kind: "original";
+} | {
+    readonly kind: "cylindrical";
+};
+
+/** Output image size */
+export declare interface ImageSize {
+    width: number;
+    height: number;
 }
 
 /**
- * How the corrected ray directions are mapped to the output image.
+ * OpenCV Fisheye Camera Model (Kannala-Brandt) type definitions.
+ *
+ * **Distortion**: `θ_d = θ(1 + k₁θ² + k₂θ⁴ + k₃θ⁶ + k₄θ⁸)` where `θ = atan(r)`, `r² = a² + b²`
  *
- * - **rectilinear**: Standard perspective (like a normal camera). Straight lines in the
- *   scene stay straight; the center is natural, edges are compressed. With wide FOV (e.g.
- *   180°) the edges look very squished. One "window" view.
+ * **Pixel coords**: `u = fx(x' + αy') + cx`, `v = fy·y' + cy`
  *
- * - **equirectangular**: Horizontal axis = azimuth (longitude), vertical = elevation
- *   (latitude). The full horizontal span (e.g. 180°) maps linearly to the width, so you
- *   get a wide panoramic strip: left = one side, right = the other. Classic panorama look.
+ * **K matrix**: `[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]`
  *
- * Commercial equivalents:
- * - "Panoramic 180" / "180° Panorama" → equirectangular with 180° horizontal.
- * - "Panoramic" / "360° Panorama" → equirectangular with 360° horizontal (ceiling mount).
- * - "Normal" / "PTZ view" / single window → rectilinear (often with ~90° FOV per pane).
- * - "Panoramic with 4 panes" / "Quad" → layout of four rectilinear ~90° views, not one projection.
+ * **D vector**: `[k₁, k₂, k₃, k₄]`
+ *
+ * @see {@link https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html}
+ * @module
  */
-export declare type FisheyeProjection = "rectilinear" | "equirectangular";
+/** K matrix - camera intrinsics */
+export declare interface KMatrix {
+    fx: number;
+    fy: number;
+    cx?: number;
+    cy?: number;
+    alpha?: number;
+}
+
+/**
+ * New camera matrix P (Knew).
+ * @see {@link https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html#ga167df4b1c2e30f6c46a2af7fa6d4cfff|initUndistortRectifyMap}
+ */
+export declare interface NewCameraMatrix {
+    readonly newFx: number;
+    readonly newFy: number;
+    readonly newCx?: number;
+    readonly newCy?: number;
+}
+
+/** Flat size input - both required or both omitted */
+export declare type OutputSize = AllOrNothing<ImageSize>;
+
+declare interface RectilinearAuto {
+    readonly kind: "rectilinear";
+    readonly mode?: undefined;
+}
+
+declare interface RectilinearManual extends NewCameraMatrix {
+    readonly kind: "rectilinear";
+    readonly mode: "manual";
+}
+
+declare type RectilinearProjection = RectilinearAuto | RectilinearManual;
 
 /**
  * Supported YUV pixel formats for VideoFrame creation