feat: Add onUIRotationChanged(..) (#4147)

* feat: Add `onUIRotationChanged(..)`

* ok?

* fix logic

* animated ?

* fix: Get rotation working

* Add docs

* rename `getUIRotation`

* simplify to use `getUIRotation`

Author: mrousavy

apps/simple-camera/__tests__/README.md

@@ -28,6 +28,7 @@ Tests are split by domain. Each file tests one slice of the imperative `VisionCa
 | [visioncamera.constraints.harness.ts](visioncamera.constraints.harness.ts) | `VisionCamera.resolveConstraints` + `onSessionConfigSelected`, FPS / HDR / stabilization / binned / pixelFormat / resolutionBias constraints |
 | [visioncamera.controller.harness.ts](visioncamera.controller.harness.ts) | `CameraController` — zoom, torch, exposure bias, focus metering, low-light boost, subject area listener |
 | [visioncamera.hooks.harness.tsx](visioncamera.hooks.harness.tsx) | React hook reactivity for `useCameraDevice(...)` position and physical-device filter changes |
+| [visioncamera.utils.harness.ts](visioncamera.utils.harness.ts) | Pure public utilities such as `getUIRotation(...)` across every output/interface orientation pair |
 | [visioncamera.coordinates.harness.ts](visioncamera.coordinates.harness.ts) | `Frame.convertFramePointToCameraPoint` / `convertCameraPointToFramePoint`, `PreviewView.convertViewPointToCameraPoint` / `convertCameraPointToViewPoint`, `PreviewView.createMeteringPoint`, `convertScannedObjectCoordinatesToViewCoordinates`, end-to-end Frame → Camera → View round-trip |
 | [visioncamera.nativepreviewview.harness.tsx](visioncamera.nativepreviewview.harness.tsx) | Bare `NativePreviewView` lifecycle, layout-sensitive preview regression coverage, `resizeMode`, Android `implementationMode`, gesture controllers, multi-preview mounting, `PreviewView` ref methods, Android `takeSnapshot()` dimensions |
 | [visioncamera.camera-view.harness.tsx](visioncamera.camera-view.harness.tsx) | High-level `<Camera>` preview lifecycle, photo output integration, controller props, native gestures, `CameraRef` methods, `isActive`, mount / unmount / replacement behavior |

apps/simple-camera/__tests__/visioncamera.utils.harness.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'react-native-harness'
+import type { CameraOrientation } from 'react-native-vision-camera'
+import { getUIRotation } from 'react-native-vision-camera'
+
+describe('VisionCamera - Utils', () => {
+  it('calculates UI rotation for every output and interface orientation', () => {
+    const expectedRotations = [
+      { output: 'up', interface: 'up', rotation: 0 },
+      { output: 'up', interface: 'right', rotation: 90 },
+      { output: 'up', interface: 'down', rotation: 180 },
+      { output: 'up', interface: 'left', rotation: -90 },
+      { output: 'right', interface: 'up', rotation: -90 },
+      { output: 'right', interface: 'right', rotation: 0 },
+      { output: 'right', interface: 'down', rotation: 90 },
+      { output: 'right', interface: 'left', rotation: 180 },
+      { output: 'down', interface: 'up', rotation: 180 },
+      { output: 'down', interface: 'right', rotation: -90 },
+      { output: 'down', interface: 'down', rotation: 0 },
+      { output: 'down', interface: 'left', rotation: 90 },
+      { output: 'left', interface: 'up', rotation: 90 },
+      { output: 'left', interface: 'right', rotation: 180 },
+      { output: 'left', interface: 'down', rotation: -90 },
+      { output: 'left', interface: 'left', rotation: 0 },
+    ] satisfies {
+      output: CameraOrientation
+      interface: CameraOrientation
+      rotation: number
+    }[]
+
+    const reportedRotations = expectedRotations.map(
+      ({ output, interface: interfaceOrientation }) => ({
+        output,
+        interface: interfaceOrientation,
+        rotation: getUIRotation(output, interfaceOrientation),
+      }),
+    )
+
+    expect(reportedRotations).toEqual(expectedRotations)
+  })
+})

apps/simple-camera/src/components/CameraSelectorButton.tsx

@@ -5,17 +5,20 @@ import {
 } from '@react-native-menu/menu'
 import type React from 'react'
 import { useCallback, useMemo } from 'react'
+import { Animated } from 'react-native'
 import type { CameraDevice, CameraPosition } from 'react-native-vision-camera'
 import { IconButton } from './IconButton'
 
 interface Props {
   devices: CameraDevice[]
   setDevice: (device: CameraDevice) => void
+  uiRotation: Animated.Value
 }
 
 export function CameraSelectorButton({
   devices,
   setDevice,
+  uiRotation,
 }: Props): React.ReactElement {
   const menuActions = useMemo<MenuAction[]>(() => {
     const positions = ['back', 'front', 'external'].filter<CameraPosition>(
@@ -49,9 +52,24 @@ export function CameraSelectorButton({
     [devices, setDevice],
   )
 
+  const rotate = uiRotation.interpolate({
+    inputRange: [0, 360],
+    outputRange: ['0deg', '360deg'],
+  })
+
   return (
     <MenuView actions={menuActions} onPressAction={onMenuItemPressed}>
-      <IconButton iconName="camera" onPress={() => {}} />
+      <Animated.View
+        style={{
+          transform: [
+            {
+              rotate: rotate,
+            },
+          ],
+        }}
+      >
+        <IconButton iconName="camera" onPress={() => {}} />
+      </Animated.View>
     </MenuView>
   )
 }

apps/simple-camera/src/screens/CameraScreen.tsx

@@ -1,6 +1,13 @@
 import { useIsFocused, useNavigation } from '@react-navigation/native'
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { StatusBar, StyleSheet, Text, View } from 'react-native'
+import {
+  Animated,
+  StatusBar,
+  StyleSheet,
+  Text,
+  useAnimatedValue,
+  View,
+} from 'react-native'
 import {
   type Recorder,
   useCameraDeviceExtensions,
@@ -30,6 +37,7 @@ export function CameraScreen() {
   const [enableVideo, setEnableVideo] = useState(false)
   const [enableFrameStream, setEnableFrameStream] = useState(false)
   const [enableDepthStream, setEnableDepthStream] = useState(false)
+  const uiRotation = useAnimatedValue(0, { useNativeDriver: true })
 
   const devices = useCameraDevices()
   const defaultDevice = devices[0]
@@ -234,6 +242,13 @@ export function CameraScreen() {
         device={device}
         outputs={[photoOutput]}
         mirrorMode={device.position === 'front' ? 'on' : 'off'}
+        orientationSource="device"
+        onUIRotationChanged={(rotation) => {
+          Animated.spring(uiRotation, {
+            toValue: rotation,
+            useNativeDriver: true,
+          }).start()
+        }}
         constraints={
           [
             // Session Constraints
@@ -250,6 +265,7 @@ export function CameraScreen() {
         <Row>
           <View style={styles.flex} />
           <CameraSelectorButton
+            uiRotation={uiRotation}
             devices={devices}
             setDevice={(d) => {
               setDevice(d)

docs/content/docs/orientation.mdx

@@ -8,11 +8,13 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 A Camera has a fixed sensor orientation in which Frames are streamed in.
 If you rotate your phone, the Camera doesn't physically rotate alongside with it, so rotation has to be applied to the Frames dynamically - and each [`CameraOutput`](/api/react-native-vision-camera/hybrid-objects/CameraOutput) applies orientation differently.
 
-### Automatically set Orientation
+### Set Orientation
+
+#### Automatically set Orientation
 
 In most cases, your [`Orientation`](/api/react-native-vision-camera/type-aliases/CameraOrientation) should be automatically set to either the App's Interface Orientation, or your Phone's Device Orientation:
 
-- App Interface Orientation ([`'interface'`](/api/react-native-vision-camera/type-aliases/OrientationSource)): Changes output orientation only when the UI rotates. If the UI is locked to `portrait` and the phone is held sideways, the output orientation will still stick to `portrait` ([`'up'`](/api/react-native-vision-camera/type-aliases/CameraOrientation)). This is how apps like Snapchat or Instagram work.
+- App Interface Orientation ([`'interface'`](/api/react-native-vision-camera/type-aliases/OrientationSource)): Changes output orientation only when the UI rotates. If the UI is locked to `portrait` and the phone is held sideways, the output orientation will still stick to `portrait` ([`'up'`](/api/react-native-vision-camera/type-aliases/CameraOrientation)). This is how apps like Snapchat or Instagram work - they are effectively locked to `portrait`.
 - Phone Device Orientation ([`'device'`](/api/react-native-vision-camera/type-aliases/OrientationSource)): Changes output orientation when the phone physically rotates. If the UI is locked to `portrait` and the phone is held sideways, the output orientation will change to be sideways - even if the UI doesn't rotate to `landscape`. This is how most photography apps (including the stock iOS Camera app) work.
 
 VisionCamera exposes two [`OrientationManager`](/api/react-native-vision-camera/hybrid-objects/OrientationManager)s - one for monitoring [`'interface'`](/api/react-native-vision-camera/type-aliases/OrientationSource) orientation, and one for monitoring [`'device'`](/api/react-native-vision-camera/type-aliases/OrientationSource) orientation:
@@ -61,10 +63,54 @@ output.outputOrientation = orientationManager.currentOrientation
 </Tab>
 </Tabs>
 
-### Manually set Orientation
+#### Manually set Orientation
 
 For full manual control over orientation, set [`orientationSource`](/api/react-native-vision-camera/interfaces/CameraProps#orientationsource) to [`'custom'`](/api/react-native-vision-camera/type-aliases/OrientationSource) (if you are using `<Camera />` or `useCamera(...)`), and set a custom [`CameraOutput.outputOrientation`](/api/react-native-vision-camera/hybrid-objects/CameraOutput#outputorientation) for your outputs.
 
+#### Rotate UI Elements based on Camera Orientation
+
+If your Camera's [`orientationSource`](/api/react-native-vision-camera/interfaces/CameraProps#orientationsource) is set to [`'device'`](/api/react-native-vision-camera/type-aliases/OrientationSource) (or [`'custom'`](/api/react-native-vision-camera/type-aliases/OrientationSource)), your UI will not rotate alongside with the Camera pipeline.
+To then visually rotate individual Camera controls (such as the Flip Camera button, a Flash button, or other controls), listen to the [`onUIRotationChanged`](/api/react-native-vision-camera/interfaces/CameraProps#onuirotationchanged) callback and rotate accordingly:
+
+```tsx
+function App() {
+  const device = useCameraDevice('back')
+  // [!code ++]
+  const uiRotation = useAnimatedValue(0)
+  // [!code ++:4]
+  const rotate = uiRotation.interpolate({
+    inputRange: [0, 360],
+    outputRange: ['0deg', '360deg'],
+  })
+
+  return (
+    <View>
+      <Camera
+        style={StyleSheet.absoluteFill}
+        isActive={true}
+        device={device}
+        orientationSource="device"
+        // [!code ++:6]
+        onUIRotationChanged={(rotation) => {
+          Animated.spring(uiRotation, {
+            toValue: rotation,
+            useNativeDriver: true,
+          }).start()
+        }}
+      />
+      // [!code ++]
+      <Animated.View style={{ transform: [{ rotate: rotate }] }}>
+        <FlashButton />
+      // [!code ++]
+      </Animated.View>
+    </View>
+  )
+}
+```
+
+> [!TIP]
+> Use [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/) for more control over animations.
+
 ### How Orientation is handled
 
 Since Camera sensors have fixed orientations, rotation has to be applied to Frames dynamically. The Camera pipeline does not physically rotate buffers, as this is computationally expensive and would introduce latency.

packages/react-native-vision-camera/src/hooks/useCamera.ts

@@ -22,12 +22,14 @@ import type {
 import type { CameraSessionConfig } from '../specs/session/CameraSessionConfig.nitro'
 import type { CameraSessionConfiguration } from '../specs/session/CameraSessionConfiguration'
 import type { CameraSessionConnection } from '../specs/session/CameraSessionConnection'
+import { getUIRotation } from '../utils/getUIRotation'
 import { useCameraController } from './internal/useCameraController'
 import { useCameraControllerConfiguration } from './internal/useCameraControllerConfiguration'
 import { useCameraSession } from './internal/useCameraSession'
 import { useCameraSessionIsRunning } from './internal/useCameraSessionIsRunning'
 import { useExposureUpdater } from './internal/useExposureUpdater'
 import { useListenerSubscription } from './internal/useListenerSubscription'
+import { useStableCallback } from './internal/useStableCallback'
 import { useTorchModeUpdater } from './internal/useTorchModeUpdater'
 import { useZoomUpdater } from './internal/useZoomUpdater'
 import { useOrientation } from './useOrientation'
@@ -86,6 +88,16 @@ export interface CameraProps
    * @see {@linkcode CameraOutput.outputOrientation}
    */
   orientationSource?: OrientationSource | 'custom'
+  /**
+   * Called when the Camera Output orientation (driven
+   * by {@linkcode orientationSource}) or the interface
+   * orientation changes with a {@linkcode rotation} value
+   * that specifies the degrees needed to rotate UI elements
+   * such as Camera controls (flash button, Camera flip button)
+   * so they appear upright.
+   * @param rotation The degrees that UI elements need to be rotated by to appear up-right.
+   */
+  onUIRotationChanged?: (rotation: number) => void
   /**
    * Sets whether the {@linkcode CameraOutput}s are mirrored along
    * the vertical axis. {@linkcode MirrorMode | 'auto'} mirrors
@@ -252,6 +264,7 @@ export function useCamera({
   onInterruptionStarted,
   onInterruptionEnded,
   onSubjectAreaChanged,
+  onUIRotationChanged,
   enableDistortionCorrection,
   enableLowLightBoost,
   enableSmoothAutoFocus,
@@ -265,6 +278,12 @@ export function useCamera({
     onError: onError,
   })
 
+  // TODO: Refactor our orientation logic here because it is problematic for multiple reasons;
+  //       1. Avoid going through re-renders/React state to change orientation (2x useOrientation(..)) (slow)
+  //       2. Avoid going through multiple setter calls here in a useEffect to set output orientation (possible race condition)
+  //       3. Avoid having a static useOrientation(...) hook - instead, have a UI element (`<NativePreviewView />`) fire interface orientation listeners (multi-display support)
+  //       4. orientationSource="custom" currently resorts back to 'up', which is not true - not sure if we just skip the callback or ignore instead?
+  //       Instead, have orientation source be native/declarative so we can use `AVCaptureDevice.RotationCoordinator` and drive orientation from a preview without re-renders.
   // 2. Update output orientations
   const orientationSourceOrUndefined =
     orientationSource === 'custom' ? undefined : orientationSource
@@ -276,6 +295,20 @@ export function useCamera({
     }
   }, [orientation, outputs])
 
+  // 2.1. Call onUIRotationChanged listener
+  const interfaceOrientation = useOrientation(
+    onUIRotationChanged != null ? 'interface' : undefined,
+  )
+  const uiRotation = getUIRotation(
+    orientation ?? 'up',
+    interfaceOrientation ?? 'up',
+  )
+  const stableOnUIRotationChanged = useStableCallback(onUIRotationChanged)
+  useEffect(() => {
+    if (stableOnUIRotationChanged == null) return
+    stableOnUIRotationChanged(uiRotation)
+  }, [stableOnUIRotationChanged, uiRotation])
+
   // 4. Configure the session with the input + outputs to create a `CameraController`
   const controller = useCameraController(session, device, outputs, {
     mirrorMode: mirrorMode,

packages/react-native-vision-camera/src/index.ts

@@ -93,6 +93,7 @@ export * from './threading/RuntimeThreadProvider'
 export * from './utils/CommonDynamicRanges'
 export * from './utils/CommonResolutions'
 export * from './utils/FrameConverter'
+export * from './utils/getUIRotation'
 // Main factory
 export * from './VisionCamera'
 // Views

packages/react-native-vision-camera/src/utils/getUIRotation.ts

@@ -0,0 +1,43 @@
+import type { CameraOrientation } from '../specs/common-types/CameraOrientation'
+
+function cameraOrientationToDegrees(
+  orientation: CameraOrientation,
+): 0 | 90 | 180 | 270 {
+  switch (orientation) {
+    case 'up':
+      return 0
+    case 'right':
+      return 90
+    case 'down':
+      return 180
+    case 'left':
+      return 270
+  }
+}
+
+/**
+ * Gets the signed rotation needed to keep UI elements upright relative to the
+ * Camera output orientation.
+ *
+ * The result is normalized to the shortest cardinal rotation, with opposite
+ * orientations represented as `180`.
+ */
+export function getUIRotation(
+  outputOrientation: CameraOrientation,
+  interfaceOrientation: CameraOrientation,
+): number {
+  // Convert to degrees
+  const outputOrientationDegrees = cameraOrientationToDegrees(outputOrientation)
+  const interfaceOrientationDegrees =
+    cameraOrientationToDegrees(interfaceOrientation)
+  // Calculate difference, not overshooting 360°
+  const rotation =
+    (interfaceOrientationDegrees - outputOrientationDegrees + 360) % 360
+  const normalizedRotation = rotation % 360
+  if (normalizedRotation > 180) {
+    // Converts 270° to -90°
+    return normalizedRotation - 360
+  } else {
+    return normalizedRotation
+  }
+}