react-native-image-stitcher 0.19.0 → 0.20.1

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -16,6 +16,8 @@
 
 import Foundation
 import React
+import ARKit
+import simd
 
 // v0.18.0 — `RNSARSessionBridge` is now an `RCTEventEmitter` (was a
 // plain `NSObject`) so it can deliver the `onArFrame` LIGHT-metadata
@@ -238,6 +240,85 @@ public final class RNSARSessionBridge: RCTEventEmitter {
         }
     }
 
+    // MARK: - v0.20.0 — AR overlay renderer
+
+    /// Replace the ENTIRE JS-set overlay collection.  The JS layer (the
+    /// shared `arOverlayController`) does the per-id diff and always sends
+    /// the FULL current array here on every mutation (declarative prop +
+    /// imperative ref methods both funnel through this one method).
+    ///
+    /// Native replaces its JS-overlay namespace in `RNISAROverlayStore`
+    /// wholesale; the per-frame draw view in the mounted `RNSARCameraView`
+    /// reprojects + strokes them every ARFrame.  Plugin-placed overlays
+    /// (a SEPARATE namespace, via `RNISARPluginRegistry.setOverlays`) are
+    /// untouched — the draw view renders the UNION.
+    ///
+    /// `overlays` is an array of dictionaries matching the JS `AROverlay`
+    /// shape (`id`, `worldPosition?`, `sizeMeters?`, `worldQuad?`, `shape?`,
+    /// `label?`, `color?`, `mode?`).  Entries missing an `id` or any
+    /// geometry are dropped.  Synchronous (no main-queue hop needed — it
+    /// only mutates the thread-safe store; the draw view reads it on the
+    /// next render pass).
+    @objc(setOverlays:resolver:rejecter:)
+    public func setOverlays(
+        overlays: NSArray,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        var parsed: [RNISAROverlay] = []
+        parsed.reserveCapacity(overlays.count)
+        for item in overlays {
+            guard let dict = item as? [String: Any],
+                  let o = RNISAROverlay.from(dictionary: dict) else { continue }
+            parsed.append(o)
+        }
+        RNISAROverlayStore.shared.setJSOverlays(parsed)
+        resolver(nil)
+    }
+
+    // MARK: - v0.20.0 — raycast (crosshair → real-world surface)
+
+    /// Raycast from the screen CENTER (the crosshair) along the camera's view
+    /// ray and resolve the first real-world surface hit as
+    /// `{ worldPosition: [x, y, z] }` (metres, ARKit world frame), or `null`
+    /// when nothing is hit (e.g. a featureless wall before any plane is
+    /// detected — the caller then falls back to a fixed distance ahead).
+    ///
+    /// Uses an `.estimatedPlane` target so it works before a plane is fully
+    /// detected.  No screen point arg is needed: the crosshair is the centre,
+    /// so the ray is exactly the camera's forward (−Z) axis from its position.
+    /// Pin the marker on THIS hit (then anchor it) and it sits on the real
+    /// surface at the real distance, instead of floating a guessed metre ahead.
+    @objc(raycast:rejecter:)
+    public func raycast(
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            let session = RNSARSession.shared.arSession
+            guard let frame = session.currentFrame else {
+                resolver(nil)
+                return
+            }
+            let t = frame.camera.transform
+            let origin = simd_float3(t.columns.3.x, t.columns.3.y, t.columns.3.z)
+            // ARKit camera looks down its local −Z.
+            let forward = -simd_float3(t.columns.2.x, t.columns.2.y, t.columns.2.z)
+            let query = ARRaycastQuery(
+                origin: origin,
+                direction: simd_normalize(forward),
+                allowing: .estimatedPlane,
+                alignment: .any
+            )
+            guard let hit = session.raycast(query).first else {
+                resolver(nil)
+                return
+            }
+            let p = hit.worldTransform.columns.3
+            resolver(["worldPosition": [p.x, p.y, p.z]])
+        }
+    }
+
     @objc(snapshotPoseLog:rejecter:)
     public func snapshotPoseLog(
         resolver: @escaping RCTPromiseResolveBlock,

package/ios/Sources/RNImageStitcher/RNISARFramePlugin.swift

@@ -244,4 +244,41 @@ public final class RNISARPluginRegistry: NSObject {
             ]
         )
     }
+
+    // MARK: - v0.20.0 — native-plugin overlay placement
+
+    // A native plugin can place AR overlays DIRECTLY (native→native, zero
+    // JS latency) via the methods below.  Plugin overlays live in their
+    // OWN namespace in `RNISAROverlayStore`, separate from JS-set overlays
+    // — the draw view renders the UNION, so a plugin placing overlays
+    // never clobbers `<Camera overlays={...}>` / the imperative ref, and
+    // vice-versa.  Safe to call from any thread (the store is internally
+    // locked); the per-frame draw view picks the change up on its next
+    // redraw.
+
+    /// Replace the ENTIRE plugin overlay set.  Pass the same dictionary
+    /// shape the JS `AROverlay` interface uses (`id`, `worldPosition`,
+    /// `sizeMeters`, `worldQuad`, `shape`, `label`, `color`, `mode`).
+    /// Entries missing an `id` or any geometry are dropped.
+    @objc public func setOverlays(_ overlays: [[String: Any]]) {
+        let parsed = overlays.compactMap { RNISAROverlay.from(dictionary: $0) }
+        RNISAROverlayStore.shared.setPluginOverlays(parsed)
+    }
+
+    /// Add or replace a single plugin overlay (same dictionary shape as
+    /// `setOverlays`).  No-op if the dict has no `id` / no geometry.
+    @objc public func addOverlay(_ overlay: [String: Any]) {
+        guard let parsed = RNISAROverlay.from(dictionary: overlay) else { return }
+        RNISAROverlayStore.shared.addPluginOverlay(parsed)
+    }
+
+    /// Remove a single plugin overlay by id.  No-op if absent.
+    @objc public func removeOverlay(_ id: String) {
+        RNISAROverlayStore.shared.removePluginOverlay(id)
+    }
+
+    /// Clear ALL plugin overlays.  JS-set overlays are untouched.
+    @objc public func clearOverlays() {
+        RNISAROverlayStore.shared.clearPluginOverlays()
+    }
 }

package/ios/Sources/RNImageStitcher/RNISAROverlay.swift

@@ -0,0 +1,409 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// RNISAROverlay — v0.20.0 AR overlay / annotation data model + store.
+//
+// An "overlay" is a 2D annotation (outline, box, or marker + label)
+// anchored to a WORLD position (or explicit world corners) and
+// reprojected to screen EVERY AR frame from the current camera
+// pose+intrinsics.  This file owns ONLY the data model + a process-wide
+// store; the actual drawing + per-frame reprojection lives in
+// `RNSARCameraView` (`AROverlayDrawView`).
+//
+// Mirrors the shared TS contract (`src/stitching/AROverlay.ts`):
+//
+//   interface AROverlay {
+//     id: string;
+//     worldPosition?: [number, number, number];   // world metres
+//     sizeMeters?: [number, number];               // box extent at worldPosition
+//     worldQuad?: Array<[number, number, number]>; // 3-4 explicit world corners
+//     shape?: 'box' | 'outline';                   // default 'outline'
+//     label?: string;
+//     color?: string;                              // hex; default theme color
+//     mode?: '2d' | '3d';                          // default '2d'; '3d' SCAFFOLD only
+//   }
+//
+// TWO overlay namespaces, rendered as a UNION (see `AROverlayStore`):
+//   1. JS-set overlays — declarative `overlays` prop / imperative ref
+//      methods, forwarded through the `RNSARCameraViewManager` view
+//      commands.
+//   2. Plugin-set overlays — native plugins place overlays directly via
+//      `RNISARPluginRegistry.shared.setOverlays(...)` (zero JS latency).
+// JS `setOverlays` never clobbers plugin overlays and vice-versa; the
+// draw view renders both sets every frame.
+
+import Foundation
+import UIKit
+import simd
+
+// MARK: - Overlay model
+
+/// One AR overlay annotation.  Value type (struct) so snapshots handed
+/// to the draw view are cheap, immutable copies — no shared mutable
+/// state across the AR thread / main thread boundary.
+public struct RNISAROverlay: Equatable {
+
+    /// Shape rendering style.
+    public enum Shape: String {
+        /// Stroked outline only (default) — a polygon connecting the
+        /// projected corners.
+        case outline
+        /// Stroked box (same as outline for a 4-corner quad; for a
+        /// `worldPosition` marker, a small square billboard).
+        case box
+    }
+
+    /// Render mode.  `.twoD` (default) is the only mode implemented in
+    /// v1.  `.threeD` is a SCAFFOLD this release — treated as `.twoD`
+    /// with a one-time log warning; the native 3D hook in
+    /// `AROverlayDrawView` is where a SceneKit renderer will plug in.
+    public enum Mode: String {
+        case twoD = "2d"
+        case threeD = "3d"
+    }
+
+    /// Stable identifier.  Diffed by id against the current set so a
+    /// declarative `overlays` prop / imperative update can replace one
+    /// overlay without disturbing the rest.
+    public let id: String
+
+    /// A single world point (metres, ARKit world frame).  When set (and
+    /// `worldQuad` is nil), the overlay is a billboard marker/box facing
+    /// the camera at this point, sized by `sizeMeters`.
+    public let worldPosition: simd_float3?
+
+    /// Box extent (width, height) in metres at `worldPosition`.  Only
+    /// meaningful with `worldPosition`.  Defaults to a small marker.
+    public let sizeMeters: CGSize?
+
+    /// Explicit world corners (3-4 points, metres).  When set, the
+    /// overlay is the polygon through these corners (e.g. a detected
+    /// quad).  Takes precedence over `worldPosition`.
+    public let worldQuad: [simd_float3]?
+
+    /// Shape style — `.outline` (default) or `.box`.
+    public let shape: Shape
+
+    /// Optional text label drawn near the overlay's centroid.
+    public let label: String?
+
+    /// Stroke / label color.  Defaults to a theme color when the JS hex
+    /// is absent / unparseable.
+    public let color: UIColor
+
+    /// Render mode (`.twoD` default; `.threeD` is scaffold-only — see
+    /// `Mode`).
+    public let mode: Mode
+
+    public init(
+        id: String,
+        worldPosition: simd_float3?,
+        sizeMeters: CGSize?,
+        worldQuad: [simd_float3]?,
+        shape: Shape,
+        label: String?,
+        color: UIColor,
+        mode: Mode
+    ) {
+        self.id = id
+        self.worldPosition = worldPosition
+        self.sizeMeters = sizeMeters
+        self.worldQuad = worldQuad
+        self.shape = shape
+        self.label = label
+        self.color = color
+        self.mode = mode
+    }
+
+    /// Default theme color when none / an unparseable hex is supplied.
+    /// Cyan matches the example overlay (`#00E5FF`).
+    public static let defaultColor = UIColor(
+        red: 0.0, green: 0.898, blue: 1.0, alpha: 1.0
+    )
+
+    /// Default marker extent (metres) for a bare `worldPosition` with no
+    /// `sizeMeters` — a ~6 cm square so a single anchor point is visible.
+    public static let defaultMarkerExtent: CGFloat = 0.06
+
+    /// Build from the JS bridge dictionary shape (the same keys the TS
+    /// `AROverlay` interface serialises to).  Returns `nil` when there's
+    /// no `id` (the only required field) or no geometry at all
+    /// (`worldPosition`/`worldQuad` both missing) — a geometryless
+    /// overlay can never be drawn.
+    public static func from(dictionary dict: [String: Any]) -> RNISAROverlay? {
+        guard let id = dict["id"] as? String, !id.isEmpty else { return nil }
+
+        let worldPosition = parseVec3(dict["worldPosition"])
+        let worldQuad = parseQuad(dict["worldQuad"])
+        // Need at least one geometry source.
+        guard worldPosition != nil || (worldQuad?.isEmpty == false) else {
+            return nil
+        }
+
+        let sizeMeters: CGSize? = {
+            guard let arr = dict["sizeMeters"] as? [Any], arr.count >= 2,
+                  let w = numeric(arr[0]), let h = numeric(arr[1]) else {
+                return nil
+            }
+            return CGSize(width: w, height: h)
+        }()
+
+        let shape: Shape = {
+            if let s = dict["shape"] as? String, let parsed = Shape(rawValue: s) {
+                return parsed
+            }
+            return .outline
+        }()
+
+        let mode: Mode = {
+            if let m = dict["mode"] as? String, let parsed = Mode(rawValue: m) {
+                return parsed
+            }
+            return .twoD
+        }()
+
+        let color: UIColor = {
+            if let hex = dict["color"] as? String,
+               let parsed = UIColor(hexString: hex) {
+                return parsed
+            }
+            return defaultColor
+        }()
+
+        let label = dict["label"] as? String
+
+        return RNISAROverlay(
+            id: id,
+            worldPosition: worldPosition,
+            sizeMeters: sizeMeters,
+            worldQuad: (worldQuad?.isEmpty == false) ? worldQuad : nil,
+            shape: shape,
+            label: label,
+            color: color,
+            mode: mode
+        )
+    }
+
+    // MARK: Dictionary parsing helpers
+
+    private static func numeric(_ v: Any?) -> CGFloat? {
+        if let n = v as? NSNumber { return CGFloat(n.doubleValue) }
+        if let d = v as? Double { return CGFloat(d) }
+        if let i = v as? Int { return CGFloat(i) }
+        return nil
+    }
+
+    private static func parseVec3(_ v: Any?) -> simd_float3? {
+        guard let arr = v as? [Any], arr.count >= 3,
+              let x = numeric(arr[0]), let y = numeric(arr[1]),
+              let z = numeric(arr[2]) else {
+            return nil
+        }
+        return simd_float3(Float(x), Float(y), Float(z))
+    }
+
+    private static func parseQuad(_ v: Any?) -> [simd_float3]? {
+        guard let arr = v as? [Any] else { return nil }
+        var pts: [simd_float3] = []
+        pts.reserveCapacity(arr.count)
+        for item in arr {
+            guard let p = parseVec3(item) else { continue }
+            pts.append(p)
+        }
+        // A polygon needs at least 3 corners; cap at 4 (the contract's
+        // "3-4 points").
+        guard pts.count >= 3 else { return nil }
+        return Array(pts.prefix(4))
+    }
+}
+
+
+// MARK: - UIColor hex parsing
+
+extension UIColor {
+    /// Parse a CSS-style hex string: `#RGB`, `#RGBA`, `#RRGGBB`, or
+    /// `#RRGGBBAA` (the leading `#` is optional).  Returns `nil` for
+    /// anything unparseable so the caller can fall back to a theme color.
+    public convenience init?(hexString raw: String) {
+        var s = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if s.hasPrefix("#") { s.removeFirst() }
+        // Expand shorthand #RGB / #RGBA to #RRGGBB / #RRGGBBAA.
+        if s.count == 3 || s.count == 4 {
+            s = s.map { "\($0)\($0)" }.joined()
+        }
+        guard s.count == 6 || s.count == 8,
+              let value = UInt64(s, radix: 16) else {
+            return nil
+        }
+        let r, g, b, a: CGFloat
+        if s.count == 8 {
+            r = CGFloat((value & 0xFF00_0000) >> 24) / 255.0
+            g = CGFloat((value & 0x00FF_0000) >> 16) / 255.0
+            b = CGFloat((value & 0x0000_FF00) >> 8) / 255.0
+            a = CGFloat(value & 0x0000_00FF) / 255.0
+        } else {
+            r = CGFloat((value & 0xFF0000) >> 16) / 255.0
+            g = CGFloat((value & 0x00FF00) >> 8) / 255.0
+            b = CGFloat(value & 0x0000FF) / 255.0
+            a = 1.0
+        }
+        self.init(red: r, green: g, blue: b, alpha: a)
+    }
+}
+
+
+// MARK: - Overlay store
+
+/// Process-wide store of active overlays, split into two namespaces:
+/// JS-set (declarative prop / imperative ref) and plugin-set (native
+/// plugins via `RNISARPluginRegistry`).  Mounted `RNSARCameraView`s
+/// subscribe (via `addObserver`) and re-read `snapshot()` to redraw.
+///
+/// THREAD SAFETY: mutations come from the bridge / main thread (JS
+/// commands) and arbitrary plugin queues (`setOverlays`); reads come from
+/// the main thread (the draw view).  All access is serialised by an
+/// internal lock; `snapshot()` returns a value-type array copy so the
+/// reader never holds the lock while drawing.
+@objc(RNISAROverlayStore)
+public final class RNISAROverlayStore: NSObject {
+
+    /// Shared instance — singleton because the overlay set is global to
+    /// the (single) AR session, matching `RNSARSession.shared`.
+    @objc public static let shared = RNISAROverlayStore()
+
+    /// Notification posted (on any thread) whenever either namespace
+    /// changes.  Mounted draw views observe it to mark themselves dirty.
+    /// (Used for the imperative / plugin paths; the per-frame redraw in
+    /// `RNSARCameraView` already refreshes geometry every frame, so this
+    /// is mainly to pick up SET changes between frames.)
+    public static let overlaysChanged =
+        Notification.Name("RNISAROverlaysChanged")
+
+    /// JS-set overlays, keyed by id (last-write-wins per id).  Ordered
+    /// list preserved separately for deterministic draw order.
+    private var jsById: [String: RNISAROverlay] = [:]
+    private var jsOrder: [String] = []
+
+    /// Plugin-set overlays, same structure, separate namespace.
+    private var pluginById: [String: RNISAROverlay] = [:]
+    private var pluginOrder: [String] = []
+
+    private let lock = NSLock()
+
+    private override init() { super.init() }
+
+    // MARK: JS namespace
+
+    /// Replace the ENTIRE JS overlay set (the declarative `overlays`
+    /// prop / imperative `setOverlays`).  Plugin overlays are untouched.
+    public func setJSOverlays(_ overlays: [RNISAROverlay]) {
+        lock.lock()
+        jsById.removeAll(keepingCapacity: true)
+        jsOrder.removeAll(keepingCapacity: true)
+        for o in overlays {
+            if jsById[o.id] == nil { jsOrder.append(o.id) }
+            jsById[o.id] = o
+        }
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Add or replace a single JS overlay (imperative `addOverlay`).
+    public func addJSOverlay(_ overlay: RNISAROverlay) {
+        lock.lock()
+        if jsById[overlay.id] == nil { jsOrder.append(overlay.id) }
+        jsById[overlay.id] = overlay
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Remove a single JS overlay by id (imperative `removeOverlay`).
+    /// No-op if absent.
+    public func removeJSOverlay(_ id: String) {
+        lock.lock()
+        jsById.removeValue(forKey: id)
+        jsOrder.removeAll { $0 == id }
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Clear ALL JS overlays (imperative `clearOverlays`).  Plugin
+    /// overlays are untouched.
+    public func clearJSOverlays() {
+        lock.lock()
+        jsById.removeAll(keepingCapacity: true)
+        jsOrder.removeAll(keepingCapacity: true)
+        lock.unlock()
+        postChanged()
+    }
+
+    // MARK: Plugin namespace
+
+    /// Replace the ENTIRE plugin overlay set.  JS overlays are untouched.
+    public func setPluginOverlays(_ overlays: [RNISAROverlay]) {
+        lock.lock()
+        pluginById.removeAll(keepingCapacity: true)
+        pluginOrder.removeAll(keepingCapacity: true)
+        for o in overlays {
+            if pluginById[o.id] == nil { pluginOrder.append(o.id) }
+            pluginById[o.id] = o
+        }
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Add or replace a single plugin overlay.
+    public func addPluginOverlay(_ overlay: RNISAROverlay) {
+        lock.lock()
+        if pluginById[overlay.id] == nil { pluginOrder.append(overlay.id) }
+        pluginById[overlay.id] = overlay
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Remove a single plugin overlay by id.  No-op if absent.
+    public func removePluginOverlay(_ id: String) {
+        lock.lock()
+        pluginById.removeValue(forKey: id)
+        pluginOrder.removeAll { $0 == id }
+        lock.unlock()
+        postChanged()
+    }
+
+    /// Clear ALL plugin overlays.  JS overlays are untouched.
+    public func clearPluginOverlays() {
+        lock.lock()
+        pluginById.removeAll(keepingCapacity: true)
+        pluginOrder.removeAll(keepingCapacity: true)
+        lock.unlock()
+        postChanged()
+    }
+
+    // MARK: Read
+
+    /// Snapshot of the UNION of both namespaces, in draw order (JS first,
+    /// then plugin).  Returns a value-type array copy so the caller can
+    /// iterate + draw without holding the lock.
+    public func snapshot() -> [RNISAROverlay] {
+        lock.lock()
+        defer { lock.unlock() }
+        var out: [RNISAROverlay] = []
+        out.reserveCapacity(jsOrder.count + pluginOrder.count)
+        for id in jsOrder { if let o = jsById[id] { out.append(o) } }
+        for id in pluginOrder { if let o = pluginById[id] { out.append(o) } }
+        return out
+    }
+
+    /// Whether there are no overlays in either namespace.  Cheap gate the
+    /// draw view can check to skip work.
+    public var isEmpty: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return jsOrder.isEmpty && pluginOrder.isEmpty
+    }
+
+    private func postChanged() {
+        NotificationCenter.default.post(
+            name: Self.overlaysChanged, object: nil
+        )
+    }
+}