🐛 convertCameraPointToFramePoint ignores normalising extents on orientation swap (iOS) — square region maps to a 3.16:1 strip

[florianpreusner]

Prerequisites

• I have read and followed every applicable step in the Nitro Modules Troubleshooting guide.
• I have read the VisionCamera Troubleshooting guide.
• I have searched existing issues and found nothing matching (no hits for convertCameraPointToFramePoint).
• I am on the latest version, or have a specific reason I cannot upgrade — see "VisionCamera version" below.

Reproduction

#4113 — adds one failing Harness test, maps a square Frame region onto a square View region, to apps/simple-camera/__tests__/visioncamera.coordinates.harness.tsx.

Steps to reproduce

1. Check out the branch in test: Add failing Harness test — square Frame region maps to a 3.16:1 strip in View space on iOS #4113.
2. Run the coordinates harness on an iOS device: bun run test:harness:ios -- --testPathPatterns=coordinates.
3. Watch maps a square Frame region onto a square View region.
4. Run the same file on an Android device — it passes there.

What did you expect to happen?

Composing the two public coordinate conversions should preserve aspect. A square region in Frame space should map to a square region in View space:

PreviewView.convertViewPointToCameraPoint()  ->  Frame.convertCameraPointToFramePoint()

Every transform in between — sensor scale, orientation counter-rotation, the preview's aspect-preserving crop — preserves aspect. Camera space itself is allowed to be anisotropic (iOS normalises per-axis to [0, 1]), but converting out of it should undo the same per-axis scaling it applied.

What actually happened?

On iOS the square comes back as a wide, short strip. Measured on iPhone 15 Pro Max, frame 3840×2160, orientation: "left", using a square guide cell of identical ±19.7 dp in both view axes:

sensor Δx 0.0562  ->  frame Δy 121.4 px
sensor Δy 0.0999  ->  frame Δx 383.6 px

383.6 × 121.4 px — a ratio of 3.159, where a correct mapping measures 1.000. Pixel 8 (1280×720) composes correctly at 1.000.

convertViewPointToCameraPoint looks correct on its own: for the square patch it returns Δx/Δy = 0.5625 = exactly 9/16, consistent with per-axis normalisation over a 16:9 image.

Suspected cause. ios/Utils/FrameCoordinateSystemConverter.getFrameToCameraMatrix rotates within [0, 1]² in step 1, then normalises in step 3 with matrix.scaledBy(x: 1 / width, y: 1 / height). scaledBy post-concatenates, so the point is normalised by the buffer's own extents before the rotation swaps the axes — and the extents never swap with it. The numbers match that reading exactly: 0.0562 × 2160 = 121.4, 0.0999 × 3840 = 383.6. Predicted anisotropy for 16:9 at orientation: left is (16/9)² = 3.1605 against the measured 3.159.

The existing tests can't catch it: the Frame→Camera→Frame round-trip is self-inverse (getCameraToFrameMatrix is getFrameToCameraMatrix().inverted()), and the end-to-end center test uses the frame center, which maps to camera (0.5, 0.5) under both a correct and an anisotropic matrix. Only an off-center region exposes it. Full analysis in the PR.

Affected platforms

iOS (device)

Device(s) affected

iPhone 15 Pro Max (iOS 26.5.2) — reproduces. Pixel 8 — does not reproduce (exact Android build not recorded at measurement time).

VisionCamera version

5.0.11. Not on the latest (5.2.0) because 5.2.0 is nitrogen-0.36.3-generated and our app is still on react-native-nitro-modules 0.35.x — that upgrade is scheduled separately.

This is very unlikely to matter here: ios/Utils/FrameCoordinateSystemConverter.swift is byte-identical across v5.0.11, v5.1.0, v5.1.1 and v5.2.0 (md5 7e406d9d979e0490f06ca05f7e52ea70, 74 lines each), and no 5.x release note touches it. Happy to re-measure on 5.2.0 if you'd like it confirmed on the current release.

React Native version

0.86.0 at measurement time (since upgraded to 0.86.2).

React Native architecture

New Architecture (Fabric / bridgeless)

Context

Found while mapping a Rubik's cube scan guide onto sampled frames in a shipping app. Our workaround validates the composed mapping with an isotropy check and falls back to deriving the geometry from the frame dimensions when it fails — no platform branch, it's measured at runtime. Android accepts the library transform; iOS rejects it at 3.159 and falls back. Glad to test a fix on device.

[florianpreusner]

Correcting my own "suspected cause" above — it's wrong, and a patch to that line would not fix this.

The test merged in #4113 is now red on main (run 30639316971, iPhone 16 Pro, expected 1.7777777777777777 to be close to 1; Pixel 9 Pro green). The Android leg on the PR itself was only the fork/OIDC limitation, not the test — the post-merge run is the first real execution.

That CI number (16/9) didn't match my field number (3.159), so I instrumented both compositions in one session on one frame and re-measured.

Measured

iPhone 15 Pro Max, iOS 26.5.2, VisionCamera 5.0.11 — FrameCoordinateSystemConverter.swift and HybridPreviewView.swift are byte-identical to main, so this is comparable to the harness run.

frame 3840×2160, orientation=left, isMirrored=false, view 430×932 dp. Cover-fit scaled preview image: max(430/2160, 932/3840) = 0.2427 → 524.2 × 932.0.

A. view → camera → frame (107.5 dp square):

camera  TL(0.4423, 0.6025)  TR(0.4423, 0.3975)  BL(0.5577, 0.6025)
view x-edge -> camera Δy 0.2050 -> frame 787.0 px
view y-edge -> camera Δx 0.1154 -> frame 249.1 px      ratio 0.3166 = 1/3.159

B. frame → camera → view (540 px square, built exactly as the harness test builds it):

camera  TL(0.6250, 0.4297)  TR(0.6250, 0.5703)  BL(0.3750, 0.4297)
frame x-edge -> camera Δy 0.1406 (= 540/3840) -> view  73.77 dp
frame y-edge -> camera Δx 0.2500 (= 540/2160) -> view 233.00 dp   ratio 3.1587

Both directions measure 3.159, so the composition is a single anisotropy — my earlier reading that A and B disagreed was an artifact of comparing across devices.

What's actually wrong

Not step 3 of getFrameToCameraMatrix. Normalising each buffer axis by its own extent and then rotating inside the unit square is correct on its own — normalised coordinates live in [0,1]² regardless of aspect, so there is nothing for the extents to "swap" into. That function is self-consistent.

The defect is that the two iOS conversions do not share a Camera space.

• Frame↔Camera (FrameCoordinateSystemConverter) yields [0,1]² normalised over the counter-rotated, upright image. At orientation: left that puts buffer y (short axis, ÷2160) into camera x, and buffer x (long axis, ÷3840) into camera y.
• PreviewView↔Camera delegates to AVCaptureVideoPreviewLayer.layerPointConverted(fromCaptureDevicePoint:), whose space is [0,1]² normalised over the sensor in its native landscape orientation — x along the sensor's long axis.

The measured per-axis scales confirm AVFoundation's convention exactly: 233.00 / 0.2500 = 932.0 (= scaled image height) and 73.77 / 0.1406 = 524.7 (= scaled image width, 524.2). So camera x is scaled by the long axis, camera y by the short — the transpose of what the Frame side emitted.

Both spaces are [0,1]², so nothing throws; they're just different unit squares, and normalising over transposed extents is anisotropic by W/H per axis pair.

Had the Frame side emitted AVFoundation's convention — camera = (frameX/3840, frameY/2160) — the same frame square maps to 0.1406 × 932.0 = 131.0 and 0.2500 × 524.2 = 131.05 view px. Ratio 1.000.

Android is the contrast that shows the intent. Both its sides are anchored to one shared space:

// HybridFrame.kt
image.imageInfo.sensorToBufferTransformMatrix   // sensor <-> buffer pixels
// HybridPreviewView.kt
previewView.sensorToViewTransform               // sensor <-> view pixels

The sensor space cancels on composition, which is why Android measures 1.000.

On the differing magnitudes

The model is ratio = (W/H) × (scaledImageH / scaledImageW). Under a cover fit on a portrait view the second factor is itself W/H, giving (16/9)² = 3.1605 — against 3.1587 measured, 0.06% off. CI's 1.7778 implies a scaled preview image of different aspect. The harness test doesn't log frame dimensions, orientation or view size, so the CI magnitude can't be reconstructed from the run — it may be worth having the test print those, since the invariant is 1.000 everywhere but the failure magnitude is geometry-dependent.

The invariant and the platform split hold on both devices; only the magnitude varies.

Which side should move is your call on the documented semantics of Camera coordinates — the Preview side is Apple's API and can't be redefined, so making FrameCoordinateSystemConverter emit AVFoundation's sensor-landscape convention looks like the smaller change, but that changes what convertFramePointToCameraPoint means for anyone already compensating. Happy to test a fix on device and re-run both directions.