CameraController

interface CameraController extends HybridObject

A CameraController allows controlling an opened Camera.

You obtain one CameraController per configured connection via CameraSession.configure(...), or via the useCamera(...) hook.

After a CameraSession is reconfigured (e.g. when binding new inputs, outputs, or connection settings), you receive a new CameraController.

Examples

Via the useCamera(...) hook:

const device = useCameraDevice('back')
const camera = useCamera({
  isActive: true,
  device: device,
  outputs: []
})
useEffect(() => {
  camera?.setZoom(device.maxZoom)
}, [camera, device])

Via the imperative CameraSession APIs:

const devicesFactory = await VisionCamera.createDeviceFactory()
const device = devicesFactory.getDefaultCamera('back')
const cameraSession = await VisionCamera.createCameraSession(false)
const controller = await cameraSession.configure([
  {
    input: device,
    outputs: [],
    constraints: []
  }
])
await cameraSession.start()
controller.setZoom(device.maxZoom)

Properties

device

readonly device: CameraDevice

Gets the CameraDevice this CameraController is bound to.

You can use the device to query support for available features.

Example

Querying if the device supports focus metering:

const controller = ...
if (controller.supportsFocusMetering) {
  const meteringPoint = ...
  controller.focusTo(meteringPoint, {
    modes: ['AF']
  })
}

displayableZoomFactor

readonly displayableZoomFactor: number

A user-displayable zoom factor.

Example

const controller = ...           // Triple-Camera
controller.zoom                  // 1
controller.displayableZoomFactor // 0.5

exposureBias

readonly exposureBias: number

Get the current exposure compensation bias, or 0 if the device does not support exposure bias compensation - see CameraDevice.supportsExposureBias.

A positive value (like 1) means over-exposed ("brighter"), whereas a negative value (like -1) means under-exposed ("darker"). The default exposure bias is 0.

You can set exposure bias to a supported value via setExposureBias(...).

exposureDuration

readonly exposureDuration: number

Represents the current exposure duration, in seconds, or 0 if the device does not support manual exposure control - see CameraDevice.supportsExposureLocking..

The exposureDuration value changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific duration/ISO value (via setExposureLocked(...)).

exposureMode

readonly exposureMode: ExposureMode

Represents the current ExposureMode.

• 'continuous-auto-exposure': The session is continuously adjusting AE as the scene changes. (the default)
• 'auto-exposure': The session is currently metering to a specific exposure value via focusTo(...).
• 'locked': The session is currently locked at a specific exposureDuration/iso via setExposureLocked(...).

focusMode

readonly focusMode: FocusMode

Represents the current FocusMode.

• 'continuous-auto-focus': The session is continuously adjusting AF as the scene changes. (the default)
• 'auto-focus': The session is currently metering to a specific focus length position via focusTo(...).
• 'locked': The session is currently locked at a specific lensPosition via setFocusLocked(...).

isConnected

readonly isConnected: boolean

Gets whether this CameraController is currently connected to the session.

isDistortionCorrectionEnabled

readonly isDistortionCorrectionEnabled: boolean

Gets whether geometric distortion correction is currently enabled.

You can enable or disable distortion correction via configure(...) if the CameraDevice supports distortion correction (see CameraDevice.supportsDistortionCorrection).

isLowLightBoostEnabled

readonly isLowLightBoostEnabled: boolean

Gets whether low light boost is currently enabled.

You can enable low light boost via configure(...).

Example

Enabling low light boost:

const controller = ...
if (controller.device.supportsLowLightBoost) {
  await controller.configure({ enableLowLightBoost: true })
}

iso

readonly iso: number

Represents the current ISO value, or 0 if the device does not support manual exposure control - see CameraDevice.supportsExposureLocking..

The iso value changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific duration/ISO value (via setExposureLocked(...)).

isSmoothAutoFocusEnabled

readonly isSmoothAutoFocusEnabled: boolean

Gets whether smooth auto-focus is currently enabled.

You can enable or disable smooth auto-focus via configure(...) if the CameraDevice supports smooth auto-focus (see CameraDevice.supportsSmoothAutoFocus).

isSuspended

readonly isSuspended: boolean

Gets whether this CameraController is currently suspended.

A CameraController may be suspended when the system receives an interruption, such as thermal pressure.

isUsedByAnotherApp

readonly isUsedByAnotherApp: boolean

Gets whether this CameraController is currently used by another app with higher priority Camera access, for example when multi-tasking on iPad.

lensPosition

readonly lensPosition: number

Represents the current focus length, from 0.0 (closest) to 1.0 (furthest), or 0 if the device does not support manual focus control - see CameraDevice.supportsFocusLocking.

The lensPosition changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific lens-position value (via setFocusLocked(...)).

maxExposureDuration

readonly maxExposureDuration: number

Represents the maximum value for the duration parameter in setExposureLocked(...), or 0 if CameraDevice.supportsExposureLocking is false.

maxISO

readonly maxISO: number

Represents the maximum value for the iso parameter in setExposureLocked(...), or 0 if CameraDevice.supportsExposureLocking is false.

maxZoom

readonly maxZoom: number

Represents the maximum value for the zoom parameter in setZoom(...).

minExposureDuration

readonly minExposureDuration: number

Represents the minimum value for the duration parameter in setExposureLocked(...), or 0 if CameraDevice.supportsExposureLocking is false.

minISO

readonly minISO: number

Represents the minimum value for the iso parameter in setExposureLocked(...), or 0 if CameraDevice.supportsExposureLocking is false.

minZoom

readonly minZoom: number

Represents the minimum value for the zoom parameter in setZoom(...).

torchMode

readonly torchMode: TorchMode

Get the current TorchMode.

The torch can be enabled or disabled via setTorchMode(...).

torchStrength

readonly torchStrength: number

Get the current Torch's strength, which is a value from 0.0 (weakest) to 1.0 (brightest).

The torch's strength can be configured via setTorchMode('on', ...).

whiteBalanceGains

readonly whiteBalanceGains: WhiteBalanceGains

Represents the current white balance gains, or { 0, 0, 0 } if the device does not support manual white-balance control - see CameraDevice.supportsWhiteBalanceLocking..

The whiteBalanceGains change over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to specific WhiteBalanceGains (via setWhiteBalanceLocked(...)).

whiteBalanceMode

readonly whiteBalanceMode: WhiteBalanceMode

Represents the current WhiteBalanceMode.

• 'continuous-auto-white-balance': The session is continuously adjusting AWB as the scene changes. (the default)
• 'auto-white-balance': The session is currently metering to a specific white-balance value via focusTo(...).
• 'locked': The session is currently locked at a specific whiteBalanceGains value via setWhiteBalanceLocked(...).

zoom

readonly zoom: number

Represents the current zoom value. Zoom can be set via setZoom(...).

Methods

addSubjectAreaChangedListener()

addSubjectAreaChangedListener(onSubjectAreaChanged: () => void): ListenerSubscription

Adds a listener to be fired everytime the subject area substantially changes - e.g. when the user pans away from a scene previously in focus.

Returns a ListenerSubscription - call remove() on it to stop receiving subject-area-change events. Multiple subscriptions can coexist; the device stops monitoring subject-area changes only once the last subscription is removed.

Discussion

When manually locking focus (e.g. via focusTo(...) with adaptiveness set to 'locked', setFocusLocked(...) (or similar), or lockCurrentFocus() (or similar)), it is useful to listen for subject area changes, to reset focus again via resetFocus().

Example

const controller = ...
// Lock AE/AF/AWB
await Promise.all([
  controller.lockCurrentExposure(),
  controller.lockCurrentFocus(),
  controller.lockCurrentWhiteBalance(),
])
const subscription = controller.addSubjectAreaChangedListener(() => {
  // When user moves Camera away, reset AE/AF/AWB again
  controller.resetFocus()
})
// Later, to stop listening:
subscription.remove()

cancelZoomAnimation()

cancelZoomAnimation(): Promise<void>

Cancels any zoom animations previously started with startZoomAnimation(...).

configure()

configure(config: CameraControllerConfiguration): Promise<void>

Configures this CameraController with the given CameraControllerConfiguration.

Like a diff-map, setting a value inside the config object to undefined, causes the prop to be left at whatever its current value is.

convertWhiteBalanceTemperatureAndTintValues()

convertWhiteBalanceTemperatureAndTintValues(whiteBalanceTemperatureAndTint: WhiteBalanceTemperatureAndTint): WhiteBalanceGains

Converts the given whiteBalanceTemperatureAndTint values to WhiteBalanceGains.

focusTo()

focusTo(point: MeteringPoint, options: FocusOptions): Promise<void>

Focuses the Camera pipeline to the specified MeteringPoint, using the specified MeteringModes.

By default, all metering modes that are supported on this device are enabled - ideally that's AE, AF and AWB - also known as 3A.

The returned Promise resolves once focusing has been fully settled, or rejects if the focusing operation timed out or was canceled. A focus operation can be canceled by calling focusTo(...) again, or by calling resetFocus().

After the metering operation has settled, the Camera pipeline either keeps the specified MeteringPoint continuously focused even if the scene at the specific point changes ('continuous'), or locks the focus/exposure/white-balance values in-place ('locked'). You can adjust this behaviour via FocusOptions.adaptiveness.

Parameters

point

The MeteringPoint to focus to.

options

Options for this focus operation.

Examples

Focus center:

const point = VisionCamera.createNormalizedMeteringPoint(0.5, 0.5)
await controller.focusTo(point, { responsiveness: 'steady' })

Focus on tap

const onViewTapped = (tapX: number, tapY: number) => {
  const point = previewViewRef.createMeteringPoint(tapX, tapY)
  await controller.focusTo(point, { responsiveness: 'snappy' })
}

Lock focus until controller.resetFocus() is called:

const point = previewViewRef.createMeteringPoint(tapX, tapY)
await controller.focusTo(point, {
  responsiveness: 'snappy',
  adaptiveness: 'locked',
  autoResetAfter: null
})

lockCurrentExposure()

lockCurrentExposure(): Promise<void>

Locks the current exposure values.

You can read the current exposure values via exposureDuration and iso.

Example

const controller = ...
if (controller.device.supportsExposureLocking) {
  await controller.lockCurrentExposure()
}

lockCurrentFocus()

lockCurrentFocus(): Promise<void>

Locks the current focus values.

You can read the current focus values via lensPosition.

Example

const controller = ...
if (controller.device.supportsFocusLocking) {
  await controller.lockCurrentFocus()
}

lockCurrentWhiteBalance()

lockCurrentWhiteBalance(): Promise<void>

Locks the current white-balance values.

You can read the current white-balance values via whiteBalanceGains.

Example

const controller = ...
if (controller.device.supportsWhiteBalanceLocking) {
  await controller.lockCurrentWhiteBalance()
}

resetFocus()

resetFocus(): Promise<void>

Cancels any current focus operations from focusTo(...), resets back all 3A focus modes to continuously auto-focus if they have been previously locked (e.g. via setFocusLocked(...) or lockCurrentFocus(), and similar), and resets the focus point of interest to be in the center.

Example

await controller.resetFocus()

setExposureBias()

setExposureBias(exposure: number): Promise<void>

Sets the exposureBias to the given exposure bias value.

A positive value (like 1) means over-exposed ("brighter"), whereas a negative value (like -1) means under-exposed ("darker"). The default exposure bias is 0.

Example

Set Camera to maximum exposure:

const controller = ...
if (controller.device.supportsExposureBias) {
  const maxExposure = controller.device.maxExposureBias
  await controller.setExposureBias(maxExposure)
}

setExposureLocked()

setExposureLocked(duration: number, iso: number): Promise<void>

Locks the exposure at the specified duration and iso value.

Parameters

duration

The duration in seconds a single shutter is timed at. It must be a value between minExposureDuration and maxExposureDuration.

iso

The ISO value for the Camera. It must be a value between minISO and maxISO.

setFocusLocked()

setFocusLocked(lensPosition: number): Promise<void>

Locks the focus at the specified lensPosition.

Parameters

lensPosition

The position of the Camera lens, from 0.0 (closest) to 1.0 (furthest).

setTorchMode()

setTorchMode(mode: TorchMode, strength?: number): Promise<void>

Sets the torch to the specified mode.

• When mode == 'on', you can pass strength to configure the Torch's strength, from 0.0 to 1.0.
• When mode != 'on', the strength parameter is ignored.

setWhiteBalanceLocked()

setWhiteBalanceLocked(whiteBalanceGains: WhiteBalanceGains): Promise<void>

Locks the white-balance at the specified whiteBalanceGains value.

Parameters

whiteBalanceGains

The WhiteBalanceGains values. Each channel's value must be within 1 and the current device's maxWhiteBalanceGain value.

setZoom()

setZoom(zoom: number): Promise<void>

Sets the Camera's zoom to the specified zoom value.

Example

Zoom to the maximum:

const controller = ...
const maxZoom = controller.device.maxZoom
await controller.setZoom(maxZoom)

startZoomAnimation()

startZoomAnimation(zoom: number, rate: number): Promise<void>

Starts animating the Camera's zoom to the specified zoom value, at the specified rate.

Example

Zoom to the maximum:

const controller = ...
const maxZoom = controller.device.maxZoom
await controller.startZoomAnimation(maxZoom, 2)