react-native-image-stitcher 0.17.0 → 0.19.0

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -17,15 +17,144 @@
 import Foundation
 import React
 
+// v0.18.0 — `RNSARSessionBridge` is now an `RCTEventEmitter` (was a
+// plain `NSObject`) so it can deliver the `onArFrame` LIGHT-metadata
+// channel as the JS `RNImageStitcherARFrame` device event.  The JS side
+// subscribes via `new NativeEventEmitter(NativeModules.RNSARSession)` —
+// the same module name this bridge is remapped to (see ARSessionBridge.m).
+//
+// Pattern mirrors `IncrementalStitcherBridge`: observe a NotificationCenter
+// post from the framework-free `RNSARSession` engine, then re-emit on the
+// main queue via `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", …)`
+// rather than `RCTEventEmitter.sendEvent(…)`, because under RN bridgeless
+// interop `sendEvent` silently no-ops for some event-body shapes (see the
+// IncrementalStitcherBridge.handleStateUpdate docstring).
 @objc(RNSARSessionBridge)
-public final class RNSARSessionBridge: NSObject {
+public final class RNSARSessionBridge: RCTEventEmitter {
+
+    /// Whether at least one JS listener is attached to the AR-frame event.
+    /// RN's EventEmitter contract: don't emit when no listeners are
+    /// registered.  Toggled by `startObserving` / `stopObserving`.
+    private var hasListeners: Bool = false
+
+    private static let arFrameEvent = "RNImageStitcherARFrame"
+    // v0.19.0 — async AR-plugin result channel (RNISARPluginRegistry.emit).
+    private static let arPluginResultEvent = "RNImageStitcherARPluginResult"
 
-    @objc public static func requiresMainQueueSetup() -> Bool {
+    public override init() {
+        super.init()
+        // Defensively de-dupe the observer: under RN bridgeless interop a
+        // bridge's init() can run twice on the same instance.  Remove any
+        // prior registration for this notification before adding, so the
+        // observer fires at most once per post regardless.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleArFrameMeta(_:)),
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+        // v0.19.0 — observe the async AR-plugin result channel (posted by
+        // `RNISARPluginRegistry.emit`) and re-emit as a JS device event.
+        // Same de-dupe rationale as the onArFrame observer above.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensARPluginResult,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleArPluginResult(_:)),
+            name: .retailensARPluginResult,
+            object: nil
+        )
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    // MARK: - RCTEventEmitter protocol
+
+    public override static func requiresMainQueueSetup() -> Bool {
         // ARSession.start() must be called on the main thread —
         // ARKit needs to attach to the active CVDisplayLink.
         return true
     }
 
+    public override func supportedEvents() -> [String]! {
+        return [Self.arFrameEvent, Self.arPluginResultEvent]
+    }
+
+    public override func startObserving() {
+        hasListeners = true
+    }
+
+    public override func stopObserving() {
+        hasListeners = false
+    }
+
+    /// Forward a posted `ARFrameMeta` dictionary to JS as the
+    /// `RNImageStitcherARFrame` device event.  Dropped when no JS listener
+    /// is attached.  Emits via `enqueueJSCall` on the main queue (see the
+    /// class docstring for why not `sendEvent`).
+    @objc private func handleArFrameMeta(_ notification: Notification) {
+        guard hasListeners else { return }
+        guard let userInfo = notification.userInfo else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let bridge = self.bridge else { return }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.arFrameEvent, userInfo],
+                completion: nil
+            )
+        }
+    }
+
+    /// v0.19.0 — forward a posted async AR-plugin result
+    /// (`{ plugin, result }`, from `RNISARPluginRegistry.emit`) to JS as
+    /// the `RNImageStitcherARPluginResult` device event.  Dropped when no
+    /// JS listener is attached.  Emits via `enqueueJSCall` on the main
+    /// queue (same `sendEvent`-avoidance rationale as `handleArFrameMeta`).
+    @objc private func handleArPluginResult(_ notification: Notification) {
+        guard hasListeners else { return }
+        guard let userInfo = notification.userInfo else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let bridge = self.bridge else { return }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.arPluginResultEvent, userInfo],
+                completion: nil
+            )
+        }
+    }
+
+    // MARK: - Module methods
+
+    /// v0.18.0 — toggle the `onArFrame` LIGHT-metadata channel.  Called
+    /// from JS with `true` + the throttle interval (ms) when a host
+    /// supplies `<Camera onArFrame={...}>`, and `false` on
+    /// unmount / prop-removal.  Resolves with no value.
+    @objc(setArFrameMetaEnabled:intervalMs:resolver:rejecter:)
+    public func setArFrameMetaEnabled(
+        enabled: NSNumber,
+        intervalMs: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        RNSARSession.shared.setArFrameMetaEnabled(
+            enabled.boolValue,
+            intervalMs: intervalMs.doubleValue
+        )
+        resolver(nil)
+    }
+
     @objc(isSupported:rejecter:)
     public func isSupported(
         resolver: @escaping RCTPromiseResolveBlock,
@@ -68,6 +197,47 @@ public final class RNSARSessionBridge: NSObject {
         ])
     }
 
+    /// Toggle ARKit scene reconstruction (LiDAR mesh / `ARMeshAnchor`s).
+    /// Driven by the <Camera> `enableMesh` prop; gates the
+    /// StitcherFrame `meshGeometry` extraction at the SESSION level
+    /// (the per-frame `__stitcherProxy.setExtractionConfig(...mesh)`
+    /// gates the marshaling — both must be on for a host to receive
+    /// mesh).  Resolves with no value.
+    ///
+    /// Hops to the main queue: `setSceneReconstructionEnabled` may call
+    /// `arSession.run(config)` to reconfigure a live session, and
+    /// ARKit session lifecycle must run on the main thread (same
+    /// constraint as `start`).
+    @objc(setSceneReconstructionEnabled:resolver:rejecter:)
+    public func setSceneReconstructionEnabled(
+        enabled: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let on = enabled.boolValue
+        DispatchQueue.main.async {
+            RNSARSession.shared.setSceneReconstructionEnabled(on)
+            resolver(nil)
+        }
+    }
+
+    /// Hops to the main queue: `setPlaneDetection` may call
+    /// `arSession.run(config)` to reconfigure a live session, and ARKit
+    /// session lifecycle must run on the main thread (same constraint as
+    /// `start` / `setSceneReconstructionEnabled`).
+    @objc(setPlaneDetection:resolver:rejecter:)
+    public func setPlaneDetection(
+        mode: NSString,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let m = mode as String
+        DispatchQueue.main.async {
+            RNSARSession.shared.setPlaneDetection(m)
+            resolver(nil)
+        }
+    }
+
     @objc(snapshotPoseLog:rejecter:)
     public func snapshotPoseLog(
         resolver: @escaping RCTPromiseResolveBlock,

package/ios/Sources/RNImageStitcher/CameraFrameHostObject.h

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// CameraFrameHostObject.h — Obj-C facade for the v0.8.0
+// `StitcherFrame` JSI host object.  Header is intentionally
+// Obj-C-only (no `<jsi/jsi.h>` import) so this can land in the
+// public CocoaPods umbrella without breaking `use_frameworks!` hosts
+// (same rationale as `KeyframeGateBridge.h`).
+//
+// The C++ JSI host object class lives in the .mm; this facade
+// exposes only what cross-module callers need:
+//
+//   - Factory `+ fromARFrame:pose:` that the AR worklet runtime
+//     calls per ARFrame to construct a host object backed by the
+//     current AR session's frame.
+//   - Opaque accessor `- (void *)jsiHostObjectPtr` returning the
+//     `std::shared_ptr<facebook::jsi::HostObject> *` (boxed) that
+//     the worklet runtime hands to `jsi::Object::createFromHostObject`.
+//
+// Lifetime: the Obj-C wrapper holds the C++ shared_ptr; ARC frees
+// the wrapper when nothing references it.  Worklet runtime
+// invalidates the underlying ARFrame retain when the dispatch
+// returns; after invalidation, JSI access throws.
+
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <ARKit/ARKit.h>
+
+@class RNSARFramePose;
+
+NS_ASSUME_NONNULL_BEGIN
+
+NS_SWIFT_NAME(CameraFrameHostObject)
+@interface CameraFrameHostObject : NSObject
+
+/// Construct a host object backed by the supplied ARFrame + pose.
+/// Retains the ARFrame for the host object's lifetime — caller can
+/// safely release their reference.
+///
+/// Thread: safe to call from the ARSession delegate queue; the
+/// resulting host object's JSI access must happen on the worklet
+/// runtime's thread (separate queue).
++ (instancetype)fromARFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose;
+
+/// Mark the host object's underlying ARFrame as no longer accessible.
+/// Subsequent JSI property reads return `undefined` or throw,
+/// depending on the property.  Idempotent.
+- (void)invalidate;
+
+/// Opaque pointer to a `std::shared_ptr<facebook::jsi::HostObject>`.
+/// The worklet runtime (Obj-C++ context with JSI available) casts
+/// this back via `*reinterpret_cast<std::shared_ptr<facebook::jsi::HostObject>*>(ptr)`
+/// to hand to `jsi::Object::createFromHostObject`.
+///
+/// Returns `NULL` if the host object has been invalidated.
+- (nullable void *)jsiHostObjectPtr;
+
+/// Build the LIGHT per-frame AR metadata dictionary for the `onArFrame`
+/// callback (the `ARFrameMeta` TS shape).  Distinct from the full
+/// host-object factory above: this copies NO pixel / vertex / face bytes
+/// — only scalars, dimensions, anchor transforms, and mesh COUNTS — so
+/// it's cheap enough to run at the throttled `onArFrame` cadence.
+///
+/// Gating mirrors the full extraction path: `depth` only when the JS
+/// `enableDepth` flag is on (read from the shared C++ extraction config),
+/// `anchors` only when `enableAnchors`, `mesh` (counts) only when
+/// `enableMesh`.  `intrinsics` / `pose` / `trackingState` / `timestamp`
+/// are always populated.  `intrinsics` is `NSNull` only when the frame
+/// reported a degenerate (zero) resolution.
+///
+/// Returns a JSON-safe `NSDictionary` (NSNumber / NSString / NSArray /
+/// NSDictionary / NSNull leaves) ready to hand to
+/// `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", ...)`.
+///
+/// Thread: safe to call from the ARSession delegate queue (reads the
+/// frame synchronously; copies nothing that outlives the call).
++ (NSDictionary *)lightArFrameMetaFromARFrame:(ARFrame *)arFrame
+                                         pose:(RNSARFramePose *)pose
+    NS_SWIFT_NAME(lightArFrameMeta(from:pose:));
+
+/// Build the gated anchor-dictionary array for an ARFrame — the SAME
+/// `[{ id, type, alignment?, extent?, classification?, transform }]`
+/// shape the `onArFrame` LIGHT meta surfaces (mesh anchors excluded;
+/// they're summarised under `mesh`).  Returns an EMPTY array when the
+/// JS `enableAnchors` flag is off (read from the shared C++ extraction
+/// config) — matching the TS contract's `Array<...>` (never null).
+///
+/// Extracted so BOTH the `onArFrame` light-meta path AND the v0.19.0 AR
+/// plugin context (`RNISARFrameContext.anchors`) build anchors from one
+/// source of truth (DRY).
+///
+/// Thread: safe to call from the ARSession delegate queue (reads the
+/// frame synchronously; copies nothing that outlives the call).
++ (NSArray<NSDictionary *> *)arAnchorDictsFromFrame:(ARFrame *)arFrame
+    NS_SWIFT_NAME(arAnchorDicts(from:));
+
+/// Whether the shared C++ extraction config currently has `enableDepth`
+/// on (the `<Camera enableDepth>` prop, set via JS
+/// `__stitcherProxy.setExtractionConfig`).  The v0.19.0 AR plugin
+/// context uses this to decide whether to expose the raw
+/// `ARFrame.sceneDepth` depthBuffer to plugins — gating the config read
+/// (C++) in the .mm so Swift doesn't need the C++ header.
++ (BOOL)arExtractionDepthEnabled
+    NS_SWIFT_NAME(arExtractionDepthEnabled());
+
+@end
+
+NS_ASSUME_NONNULL_END