react-native-image-stitcher 0.1.0

package/dist/camera/ARCameraView.js

@@ -0,0 +1,170 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ARCameraView — AR-backed alternative to ``<CameraView>`` for
+ * audits that need pose-aware capture (panorama mode, packet
+ * detection).  Renders the ARKit camera feed via the native
+ * `RNSARCameraView` UIView; the underlying ARSession is the
+ * SDK singleton (`RNSARSession.shared`), shared between the
+ * preview and the pose log that feeds Phase 5 stitching + Phase 6
+ * measurement.
+ *
+ * Why a separate component (vs. a polymorphic CameraView)?
+ *   1. **Different imperative API.** The vision-camera-backed
+ *      CameraView exposes `takePhoto / startRecording` via its ref
+ *      (Phase 5 will add equivalents to this component, but they
+ *      route through ARFrame.capturedImage + AVAssetWriter rather
+ *      than vision-camera's APIs).
+ *   2. **Camera-access conflict.** ARKit and AVCaptureSession
+ *      can't share the camera.  Forcing the host to pick one
+ *      component over the other (instead of toggling a prop on a
+ *      shared component) makes the conflict impossible to misuse —
+ *      you can't accidentally mount both at the same time.
+ *   3. **Lifecycle clarity.** The native side starts the AR
+ *      session in `didMoveToWindow`.  Mount = start, unmount =
+ *      stop.  No flag-twiddling.
+ *
+ * This component is preview-only in Phase 4.4.  Photo + video
+ * capture come in Phase 5 (Step 5 of the AR design plan).  Until
+ * then, the host's panorama capture flow continues to use
+ * vision-camera; ARCameraView is opt-in via a settings flag for
+ * developer verification.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARCameraView = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+// React Native looks up the component by its NATIVE name.
+//   iOS: comes from `ARCameraViewManager.m`'s
+//        `RCT_EXTERN_MODULE(RNSARCameraViewManager, RCTViewManager)`.
+//   Android: comes from `RNSARCameraViewManager.kt`'s
+//        `getName() = "RNSARCameraView"`.
+// Both expose the same name; same JS lookup works on both platforms.
+const NativeARCameraView = react_native_1.Platform.OS === 'ios' || react_native_1.Platform.OS === 'android'
+    ? (0, react_native_1.requireNativeComponent)('RNSARCameraView')
+    : null;
+exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance }, ref) {
+    // Held across the start→stop lifecycle so stopRecording's
+    // resolved VideoFile can be delivered via the same callback
+    // pair vision-camera uses.
+    const recordingCallbacksRef = (0, react_1.useRef)(null);
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        takePhoto: async (options = {}) => {
+            const native = react_native_1.NativeModules.RNSARSession;
+            if (!native?.takePhoto) {
+                throw new Error('ARCameraView.takePhoto: native RNSARSession module not registered');
+            }
+            return native.takePhoto({
+                path: '',
+                quality: options.quality ?? 90,
+            });
+        },
+        startRecording: (options) => {
+            const native = react_native_1.NativeModules.RNSARSession;
+            if (!native?.startRecording) {
+                options.onRecordingError?.(new Error('ARCameraView.startRecording: native RNSARSession module not registered'));
+                return;
+            }
+            if (recordingCallbacksRef.current !== null) {
+                options.onRecordingError?.(new Error('ARCameraView.startRecording: a recording is already in progress'));
+                return;
+            }
+            recordingCallbacksRef.current = options;
+            native.startRecording({ path: '' })
+                .catch((err) => {
+                recordingCallbacksRef.current = null;
+                options.onRecordingError?.(err);
+            });
+        },
+        stopRecording: async () => {
+            const native = react_native_1.NativeModules.RNSARSession;
+            const callbacks = recordingCallbacksRef.current;
+            recordingCallbacksRef.current = null;
+            if (!native?.stopRecording || !callbacks) {
+                return;
+            }
+            try {
+                const video = await native.stopRecording();
+                callbacks.onRecordingFinished?.(video);
+            }
+            catch (err) {
+                callbacks.onRecordingError?.(err);
+            }
+        },
+    }), []);
+    if (!NativeARCameraView
+        || (react_native_1.Platform.OS !== 'ios' && react_native_1.Platform.OS !== 'android')) {
+        // Web / unsupported platforms get a clear "not available here"
+        // placeholder instead of a silent black rectangle.  iOS +
+        // Android both ship the native component now.
+        return (react_1.default.createElement(react_native_1.View, { style: [styles.placeholder, style], accessibilityLabel: "AR camera unavailable" },
+            react_1.default.createElement(react_native_1.Text, { style: styles.placeholderText }, "AR camera is not available on this platform.")));
+    }
+    return (react_1.default.createElement(react_native_1.View, { style: [styles.root, style] },
+        react_1.default.createElement(NativeARCameraView, { style: react_native_1.StyleSheet.absoluteFill }),
+        guidance ? (react_1.default.createElement(react_native_1.View, { style: styles.guidance, pointerEvents: "none", accessible: true, accessibilityRole: "text" },
+            react_1.default.createElement(react_native_1.Text, { style: styles.guidanceText, numberOfLines: 2 }, guidance))) : null));
+});
+const styles = react_native_1.StyleSheet.create({
+    root: {
+        flex: 1,
+        overflow: 'hidden',
+    },
+    placeholder: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#000',
+    },
+    placeholderText: {
+        color: '#ffffff',
+        fontSize: 14,
+    },
+    guidance: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        paddingHorizontal: 16,
+        paddingVertical: 10,
+        backgroundColor: 'rgba(0, 0, 0, 0.55)',
+    },
+    guidanceText: {
+        color: '#ffffff',
+        fontSize: 13,
+    },
+});
+//# sourceMappingURL=ARCameraView.js.map

package/dist/camera/Camera.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Camera — the public, props-based camera component for the
+ * `react-native-image-stitcher` library (publication target per the
+ * 2026-05-15 design doc).
+ *
+ * One component, both modes:
+ *   - **Tap shutter** → single photo via vision-camera's takePhoto
+ *     (non-AR) or ARFrame.capturedImage (AR).
+ *   - **Hold shutter** → panorama capture; pan-and-release produces
+ *     a stitched panorama JPEG via the incremental stitcher.
+ *
+ * One component, both capture sources:
+ *   - **AR mode** (ARKit / ARCore) — used for pose-aware stitching
+ *     when the device supports it.
+ *   - **Non-AR mode** (vision-camera + IMU) — fallback path,
+ *     forced when the 0.5× ultra-wide lens is selected (AR sessions
+ *     are tied to a single physical lens; can't switch mid-session).
+ *
+ * The Camera component owns its runtime state (arPreference, lens,
+ * settings).  Parent props are read as INITIAL VALUES at mount; the
+ * parent listens for state changes via the callback props.  This
+ * "uncontrolled" model matches React's `<input>` convention and
+ * matches the design doc's intent (NF — component owns runtime state,
+ * parent persists via callbacks if desired).
+ *
+ * Scope note (step 2 of the SDK extract plan):
+ *   - Props-driven API for both photo + panorama modes — DONE here.
+ *   - Lens chip + AR toggle UI (U1) — DONE here.
+ *   - `showSettingsButton` gates the existing PanoramaSettingsModal — DONE.
+ *   - Imperative ref methods (`takePhoto()`, `startPanorama()`,
+ *     `stopPanorama()`) — deferred; the built-in shutter button is the
+ *     primary affordance for v0.1.0.
+ *   - Forward-looking props (`defaultCompositingResolMP`,
+ *     `defaultRegistrationResolMP`, `defaultSeamEstimationResolMP`)
+ *     are accepted but currently no-ops — those fields don't exist on
+ *     PanoramaSettings yet.  They're declared so the public API is
+ *     stable before they wire through; the wiring is a follow-up.
+ *
+ * See: docs/site-content/design/2026-05-15-react-native-image-stitcher-publication.md
+ */
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export type CaptureSource = 'ar' | 'non-ar';
+export type CameraLens = '1x' | '0.5x';
+export type StitchMode = 'auto' | 'panorama' | 'scans';
+export type Blender = 'multiband' | 'feather';
+export type SeamFinder = 'graphcut' | 'skip';
+export type Warper = 'plane' | 'cylindrical' | 'spherical';
+/**
+ * Result emitted via `onCapture`.  Discriminated union keyed on
+ * `type` so consumers handle both photo and panorama outputs through
+ * one callback path.
+ *
+ * Identifier `CameraCaptureResult` (vs. the SDK's existing
+ * `CaptureResult` from `../types`) is intentional — the existing
+ * CaptureResult shape has SDK-specific fields (deviceMetadata,
+ * qualityReport, deviceUuid) that don't belong in the public RN
+ * library's surface.  Step 3 (symbol rename) will retire the
+ * historical SDK-specific names; for now we keep both types
+ * side-by-side so the existing host code continues to work.
+ */
+export type CameraCaptureResult = {
+    type: 'photo';
+    uri: string;
+    width: number;
+    height: number;
+} | {
+    type: 'panorama';
+    uri: string;
+    width: number;
+    height: number;
+    framesRequested: number;
+    framesIncluded: number;
+    framesDropped: number;
+    finalConfidenceThresh: number;
+    durationMs: number;
+};
+/**
+ * Errors surfaced via `onError`.  Classified codes so consumers can
+ * branch on the kind of failure (toast vs retry vs report).
+ */
+export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'UNKNOWN';
+export declare class CameraError extends Error {
+    readonly code: CameraErrorCode;
+    readonly cause?: unknown;
+    constructor(code: CameraErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Frames-dropped info delivered via `onFramesDropped`.  Fires once
+ * per panorama capture if the C+D progressive-confidence retry loop
+ * inside cv::Stitcher dropped one or more input frames.
+ */
+export interface FramesDroppedInfo {
+    requested: number;
+    included: number;
+}
+/**
+ * Camera component props.  See the design doc's "Component API"
+ * section for the full rationale per field.
+ */
+export interface CameraProps {
+    defaultCaptureSource?: CaptureSource;
+    defaultLens?: CameraLens;
+    defaultStitchMode?: StitchMode;
+    defaultBlender?: Blender;
+    defaultSeamFinder?: SeamFinder;
+    defaultWarper?: Warper;
+    defaultFlowNoveltyPercentile?: number;
+    defaultFlowEvalEveryNFrames?: number;
+    defaultFlowMaxTranslationCm?: number;
+    defaultKeyframeMaxCount?: number;
+    defaultKeyframeOverlapThreshold?: number;
+    /** Forward-looking — wires through to cv::Stitcher's compositingResol
+     *  once PanoramaSettings exposes the field (currently a no-op). */
+    defaultCompositingResolMP?: number;
+    /** Forward-looking — see above. */
+    defaultRegistrationResolMP?: number;
+    /** Forward-looking — see above. */
+    defaultSeamEstimationResolMP?: number;
+    enablePhotoMode?: boolean;
+    enablePanoramaMode?: boolean;
+    showSettingsButton?: boolean;
+    style?: StyleProp<ViewStyle>;
+    onCapture?: (result: CameraCaptureResult) => void;
+    onCaptureSourceChange?: (source: CaptureSource) => void;
+    onLensChange?: (lens: CameraLens) => void;
+    onFramesDropped?: (info: FramesDroppedInfo) => void;
+    onError?: (err: CameraError) => void;
+}
+/**
+ * The public `<Camera>` component.
+ */
+export declare function Camera(props: CameraProps): React.JSX.Element;
+//# sourceMappingURL=Camera.d.ts.map