@playcanvas/splat-transform/dist/lib/writers/write-image.d.ts

Library and CLI tool for 3D Gaussian splat format conversion and transformation

import { DataTable } from '../data-table';
import { type FileSystem } from '../io/write';
import { type Projection } from '../render/camera';
import type { DeviceCreator } from '../types';
/**
 * Options for writing a rendered splat image.
 */
type WriteImageOptions = {
    /** Output filename ending in `.webp`. */
    filename: string;
    /** Gaussian splat data to render. */
    dataTable: DataTable;
    /**
     * Camera projection mode. Default: `'pinhole'`.
     *
     * - `'pinhole'` — perspective camera using `fov`.
     * - `'equirect'` — full 360° × 180° equirectangular panorama from
     *   `cameraPosition`. Ignores `fov`. Requires `width === 2 × height`;
     *   default resolution is 2048 × 1024.
     */
    projection?: Projection;
    /** Camera position in world space. Default: (2, 1, -2). */
    cameraPosition?: {
        x: number;
        y: number;
        z: number;
    };
    /** Point the camera looks at, in world space. Default: (0, 0, 0). */
    lookAt?: {
        x: number;
        y: number;
        z: number;
    };
    /** World-space up vector. Default: (0, 1, 0). */
    up?: {
        x: number;
        y: number;
        z: number;
    };
    /** Vertical field of view in degrees. Default: 60 for `pinhole`. Must be omitted for `equirect` (throws if supplied). */
    fov?: number;
    /** Output image width in pixels. Default: 1280 (pinhole) or 2048 (equirect). */
    width?: number;
    /** Output image height in pixels. Default: 720 (pinhole) or 1024 (equirect). */
    height?: number;
    /** Near clip distance in world units. Splats with camera-space depth <= near are culled. Default: 0.2 (matches the reference 3DGS rasterizer). */
    near?: number;
    /** RGBA background, each channel in [0, 1]. Default: (0, 0, 0, 1). */
    background?: {
        r: number;
        g: number;
        b: number;
        a: number;
    };
    /**
     * Aperture as a photographic f-stop (e.g. 2.8, 5.6, 11). Enables
     * defocus blur / depth-of-field: smaller numbers = stronger blur.
     * Defaults to disabled. Pinhole only — passing this with
     * `projection: 'equirect'` is an error.
     */
    fStop?: number;
    /**
     * Camera-space Z of the focus plane in world units. Defaults to the
     * distance from `cameraPosition` to `lookAt` along the forward axis
     * (i.e. focus on the look-at point) when `fStop` is set. Has no
     * effect without `fStop`. Pinhole only — passing this with
     * `projection: 'equirect'` is an error.
     */
    focusDistance?: number;
    /**
     * Vertical sensor height in world units, used to give `fStop` a
     * defined physical meaning. Default `0.024` matches a 35mm
     * full-frame sensor when world units are meters. Scale this with
     * your scene's units (e.g. world unit = decimeter → 0.24, world
     * unit = millimeter → 24). Has no effect without `fStop`.
     */
    sensorSize?: number;
    /**
     * End camera position for motion blur. When set, enables camera
     * motion blur: the renderer averages `motionSamples` sub-frames
     * with the camera interpolated from (`cameraPosition`, `lookAt`,
     * `up`) at shutter-open to (`cameraEndPosition`, `lookAtEnd`,
     * `upEnd`) at shutter-close.
     */
    cameraEndPosition?: {
        x: number;
        y: number;
        z: number;
    };
    /**
     * End look-at target for motion blur. Defaults to `lookAt` when
     * motion blur is enabled.
     */
    lookAtEnd?: {
        x: number;
        y: number;
        z: number;
    };
    /**
     * End up vector for motion blur. Defaults to `up` when motion blur
     * is enabled.
     */
    upEnd?: {
        x: number;
        y: number;
        z: number;
    };
    /**
     * Shutter fraction in `[0, 1]`. Portion of the start→end segment
     * actually integrated, centered on the midpoint (standard
     * shutter-angle convention: 1.0 = full motion, 0.5 = 180° shutter).
     * Default: `1`. Only meaningful with `cameraEndPosition`.
     */
    shutter?: number;
    /**
     * Number of sub-frames to accumulate for motion blur. Cost is N×
     * a single render. Default: `16`. Only meaningful with
     * `cameraEndPosition`.
     */
    motionSamples?: number;
    /** Function returning a GraphicsDevice. Required — rasterization runs on GPU. */
    createDevice?: DeviceCreator;
};
/**
 * Renders the splat scene to a lossless WebP image written via `fs`.
 *
 * @param options - Render parameters and target filename.
 * @param fs - File system abstraction for writing the output.
 *
 * @example
 * ```ts
 * await writeImage({
 *     filename: 'view.webp',
 *     dataTable,
 *     cameraPosition: { x: 0, y: 0, z: 5 },
 *     fov: 60,
 *     width: 1920, height: 1080,
 *     createDevice: async () => myDevice
 * }, fs);
 * ```
 */
declare const writeImage: (options: WriteImageOptions, fs: FileSystem) => Promise<void>;
export { writeImage, type WriteImageOptions };