@zendir/ui 0.2.20 → 0.3.0

package/dist/react/core/widgets/Capture.d.ts

@@ -0,0 +1,140 @@
+import { default as React } from 'react';
+
+/** Camera capture arguments */
+export interface CaptureArgs {
+    monochromatic: boolean;
+    resolution: number;
+    coc: number;
+    pixel_pitch: number;
+    focusing_distance: number;
+    aperture: number;
+    focal_length: number;
+    fov: number;
+    sample: boolean;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    /**
+     * Output image format. Defaults to 'png' when omitted.
+     * - 'png'  → lossless, larger file (good for scientific/archival use)
+     * - 'jpeg' → lossy, smaller file (~3-5× smaller than PNG at q=0.92)
+     */
+    format?: 'png' | 'jpeg';
+    /**
+     * JPEG quality factor (0–1). Only used when format='jpeg'. Default: 0.92.
+     * Ignored for PNG (which is always lossless).
+     */
+    jpeg_quality?: number;
+}
+/** Incoming capture request */
+export interface CaptureRequest {
+    type: 'capture';
+    req_id: number;
+    args: CaptureArgs;
+}
+/** Imperative handle exposed via ref */
+export interface CaptureHandle {
+    /** Process a capture request, returns image bytes */
+    capture: (request: CaptureRequest) => Promise<Uint8Array>;
+    /** The server's unique ID */
+    serverId: string;
+}
+/** Captured image entry stored for gallery display */
+export interface CapturedImage {
+    reqId: number;
+    dataUrl: string;
+    timestamp: number;
+    /** Raw image byte count */
+    bytes: number;
+    /** The CaptureArgs used for this capture (camera settings, position, etc.) */
+    args?: CaptureArgs;
+}
+export interface CaptureProps {
+    /** Whether host transport is connected (drives status indicator) */
+    connected?: boolean;
+    /**
+     * Image source for capture responses. Three tiers:
+     * 1. `Uint8Array` -- static bytes returned for every request
+     * 2. `(args) => Promise<Uint8Array>` -- async renderer (e.g. CesiumCaptureSource)
+     * 3. `undefined` (default) -- auto-detects CesiumJS; falls back to placeholder image
+     */
+    imageSource?: Uint8Array | ((args: CaptureArgs) => Promise<Uint8Array>);
+    /**
+     * Pre-load the CesiumJS renderer on mount instead of waiting for the first
+     * capture request. Only applies when `imageSource` is not provided (auto-detect mode).
+     * @default true
+     */
+    preload?: boolean;
+    /**
+     * Explicit server ID. When provided the component uses this value instead
+     * of generating a new UUID. Useful for persisting across reloads via localStorage.
+     */
+    serverId?: string;
+    /** Fired after each capture is processed */
+    onCapture?: (request: CaptureRequest) => void;
+    /** Called once on mount with the server ID */
+    onReady?: (serverId: string) => void;
+    /**
+     * Start with the image gallery expanded. When true, the component renders
+     * in a flex-column layout designed to fill its container height.
+     * @default false
+     */
+    defaultGalleryExpanded?: boolean;
+    /** Custom style */
+    style?: React.CSSProperties;
+}
+/**
+ * Bundled astronaut placeholder PNG (or 1x1 fallback). Exported for
+ * `CesiumCaptureSource` when globe capture fails (e.g. missing Cesium assets, WebGL).
+ */
+export declare function loadCapturePlaceholderImage(): Promise<Uint8Array>;
+export interface UseCaptureOptions {
+    /** Image to return: static bytes or async function receiving capture args */
+    imageSource?: Uint8Array | ((args: CaptureArgs) => Promise<Uint8Array>);
+    /**
+     * Pre-load the CesiumJS renderer on mount (only when imageSource is undefined).
+     * Set to false for lazy init on first capture request.
+     * @default true
+     */
+    preload?: boolean;
+    /**
+     * Explicit server ID. When provided the hook uses this value instead of
+     * generating a new `crypto.randomUUID()`. Useful for persisting the ID
+     * across page reloads (e.g. from localStorage).
+     */
+    serverId?: string;
+}
+export interface UseCaptureResult {
+    /** Stable unique server ID */
+    serverId: string;
+    /** Process a capture request, returns image bytes (empty if paused) */
+    capture: (request: CaptureRequest) => Promise<Uint8Array>;
+    /** Whether capture processing is paused */
+    paused: boolean;
+    /** Toggle pause state */
+    setPaused: (paused: boolean) => void;
+    /** Number of successfully processed requests */
+    requestCount: number;
+    /** Most recent request */
+    lastRequest: CaptureRequest | null;
+    /** Gallery of captured images (newest first) */
+    capturedImages: CapturedImage[];
+}
+/**
+ * Hook for capture server logic. Generates a stable UUID, manages
+ * pause state, and processes capture requests into image bytes.
+ *
+ * @example
+ * ```tsx
+ * const { serverId, capture, paused, setPaused } = useCapture();
+ * // call capture(request) when external message arrives
+ * ```
+ */
+export declare function useCapture(options?: UseCaptureOptions): UseCaptureResult;
+/**
+ * Capture server UI component. Displays server status, pause/resume control,
+ * copy-ID button, and a collapsible gallery of captured images.
+ *
+ * Access `capture()` and `serverId` imperatively via the forwarded ref.
+ */
+export declare const Capture: React.MemoExoticComponent<React.ForwardRefExoticComponent<CaptureProps & React.RefAttributes<CaptureHandle>>>;
+export default Capture;