class · iOS 17.0+ · SDK 27.1
@MainActor class ObjectCaptureSessionA session object that monitors and controls image capture for photogrammetry. An ``ObjectCaptureSession`` is used together with an ``ObjectCaptureView`` to present a view that assists in capturing images of an object for reconstruction of a 3D model by using a ``RealityKit/PhotogrammetrySession``. A capture session contains functions for starting and advancing the capture session through a state machine that controls the image capture process. Your app can also observe several properties of the capture session to determine the current state of the capture process. Once a session enters the `.completed` state, your app can transfer the images to a Mac or use them locally on the iOS device for use in object reconstruction using ``PhotogrammetrySession``. Model reconstruction is a separate phase which this session does not directly monitor or control.
requestImageCapture(): Promise<void>@MainActor func requestImageCapture()Requests a manual image capture. If the session's state is `.capturing`, call this method to request an image be manually captured at the current location. This function has no effect if the session is in any other state, or if ``ObjectCaptureSession/canRequestImageCapture`` is `false`.
get canRequestImageCapture(): Promise<boolean>@MainActor var canRequestImageCapture: Bool { get }Will be `true` only when a call to ``ObjectCaptureSession/requestImageCapture()`` is expected to be successful. It will be `false` when not in the `.capturing` state or if the session is too busy to currently process a new request. There is a period of time after requesting an image capture where this property will be `false` and a new call to ``ObjectCaptureSession/requestImageCapture()`` will not produce a new image.
get canRequestImageCaptureUpdates(): Promise<ObjectCaptureSession_Updates<boolean>>@MainActor var canRequestImageCaptureUpdates: ObjectCaptureSession.Updates<Bool> { get }The `Updates` `AsyncSequence` for the `canRequestImagecapture` property.
get isAutoCaptureEnabled(): Promise<boolean>@MainActor var isAutoCaptureEnabled: Bool { get set }Enables/disables auto-capture system. If disabled, only manually triggered shots are taken.
setIsAutoCaptureEnabled(value: boolean): Promise<void>@MainActor var isAutoCaptureEnabled: Bool { get set }Enables/disables auto-capture system. If disabled, only manually triggered shots are taken.
static get isSupported(): Promise<boolean>@MainActor static var isSupported: Bool { get }A Boolean that indicates whether the current device supports object capture sessions. Before creating an object capture session, check this value to make sure the current device supports the feature. If `false`, attempting to create an `ObjectCaptureSession` will result in a runtime error.
get stateUpdates(): Promise<ObjectCaptureSession_Updates<ObjectCaptureSession_CaptureState>>@MainActor var stateUpdates: ObjectCaptureSession.Updates<ObjectCaptureSession.CaptureState> { get }The `Updates` `AsyncSequence` for the `state` property.
get configuration(): Promise<ObjectCaptureSession_Configuration>@MainActor var configuration: ObjectCaptureSession.Configuration { get }The read-only `Configuration` used to start the capture session. The configuration can be set by passing it to the `start()` call and it remains immutable after the session is started successfully.
get cameraTracking(): Promise<ObjectCaptureSession_Tracking>@MainActor var cameraTracking: ObjectCaptureSession.Tracking { get }The current state of ARKit camera tracking. The ARKit coaching overylay will be automatically show if this state moves away from `.normal` since the loss of ARKit tracking will cause many of the Object Capture algorithms to pause until the environmental tracking issue is resolved by the user. Also, the app may want to adjust its UI when this state is not `.normal` to allow proper visibility of the coaching overlay.
resetDetection(): Promise<boolean>@discardableResult @MainActor func resetDetection() -> BoolMoves the session state from `.detecting` back to `.ready` to reset the bounding box and prepare to select a new one with a new call to `startDetecting()`. If the session is not in `.detecting` state this will return false and have no effect. This call allows the object selection process to be restarted from scratch by the user if the wrong object is automatically selected or the user wants to discard manual bounding box edits and rerun the automatic selection process.
startCapturing(): Promise<void>@MainActor func startCapturing()Begins taking images for object capture. This call moves the session state from `.ready` or `.detecting` into `.capturing`. In object-centric scanning, this function is called after the user chooses the object selection bounding box and wishes to start the capture process. This call then moves the session state from `.detecting` into `.capturing`. In freeform scanning where the user skips the bounding box selection, this call moves the session state from `.ready` directly into `.capturing`.
startDetecting(): Promise<boolean>@MainActor func startDetecting() -> BoolRequests that the session should start detecting the object in the center of the camera. If success, the session state eventually transitions to ``CaptureState/detecting`` and switches to the bounding box selection mode UI. This method needs be called in `.ready` state or the call will return false and the state will not change. If there is no horizontal plane detected along the ray originating at the center of the screen it will also return false immediately and remain in `.ready`.
get feedbackUpdates(): Promise<ObjectCaptureSession_Updates<Array<ObjectCaptureSession_Feedback>>>@MainActor var feedbackUpdates: ObjectCaptureSession.Updates<Set<ObjectCaptureSession.Feedback>> { get }The `Updates` `AsyncSequence` for the `feedback` property.
get isPausedUpdates(): Promise<ObjectCaptureSession_Updates<boolean>>@MainActor var isPausedUpdates: ObjectCaptureSession.Updates<Bool> { get }The `Updates` `AsyncSequence` for the `isPaused` property.
beginNewScanPass(): Promise<void>@MainActor func beginNewScanPass()Resets the state of the capture dial such that the user will need to perform another complete scan pass to fill it and generate a new event in the published property ``ObjectCaptureSession/userCompletedScanPass``. This is intended to be used once the user has completed one scan pass and another scan pass at a different height is desired *without flipping the object*. The same object selection box chosen previously is used, so no new box is chosen. This call is particularly useful for the case where the object is not flippable but multiple passes at different heights are needed to fully capture the object. This call will throw if the session is not in `.capturing` state (or `.paused` from `.capturing` state). Note: If the object is flipped and a new scan pass is required, ``ObjectCaptureSession/beginNewScanPassAfterFlip()`` should be called. Calling this function is only valid in object-centric scanning.
get shouldPlayHaptics(): Promise<boolean>@MainActor var shouldPlayHaptics: Bool { get set }Enables/disables haptics on devices that support it.
setShouldPlayHaptics(value: boolean): Promise<void>@MainActor var shouldPlayHaptics: Bool { get set }Enables/disables haptics on devices that support it.
get numberOfShotsTaken(): Promise<number>@MainActor var numberOfShotsTaken: Int { get }The number of shots taken in the entire capture session so far, including both automatic capture and manual capture. This number includes shots from all scan passes, flipped or unflipped. It can be directly compared to the `maximumNumberOfInputImages` to keep track of the memory limits required for reconstruction of this session on-device and whether over-capture mode limits are reached for a given session.
get cameraTrackingUpdates(): Promise<ObjectCaptureSession_Updates<ObjectCaptureSession_Tracking>>@MainActor var cameraTrackingUpdates: ObjectCaptureSession.Updates<ObjectCaptureSession.Tracking> { get }The `Updates` `AsyncSequence` for the `cameraTracking` property.
get userCompletedScanPass(): Promise<boolean>@MainActor var userCompletedScanPass: Bool { get }This property starts out `false` at the start of a capture and will switch to `true` when the user has moved the device in a full circular scan pass around the bounding box of the target object and captured enough data to fill completely the capture dial. It is reset to `false` in a given capture session whenever either: 1) ``ObjectCaptureSession/beginNewScanPassAfterFlip()`` is called to start a new scan pass for a flipped object. or 2) ``ObjectCaptureSession/beginNewScanPass()`` is called to start a new scan pass on an unflipped object.
beginNewScanPassAfterFlip(): Promise<void>@MainActor func beginNewScanPassAfterFlip()Starts the capturing of a new side of the object, to be called after the object is scanned one side and flipped. After capturing one side of an object, the session can be paused and the user can be prompted to flip the object to a new side (e.g. the bottom showing) and then ``ObjectCaptureSession/beginNewScanPassAfterFlip()`` called. This will transition the session back to the `.ready` state waiting for a new bounding box selection phase to ensure the correct object is captured. Since the object has been flipped, the miniview capture display in the `ObjectCaptureView`will begin empty after this call. All captured images are written to the same output directories and the reconstruction process in ``RealityKit/PhotogrammetrySession`` will stitch these multiple captures together automatically. Note: ``ObjectCaptureSession/beginNewScanPassAfterFlip()`` should be called *after* the object flipped for best results. See also ``ObjectCaptureSession/beginNewScanPass()`` for the case where the object was not flipped but another capture circle at a different height will be performed on the same side instead. Calling this function is only valid in object-centric scanning.
get numberOfShotsTakenUpdates(): Promise<ObjectCaptureSession_Updates<number>>@MainActor var numberOfShotsTakenUpdates: ObjectCaptureSession.Updates<Int> { get }The `Updates` `AsyncSequence` for the `numberOfShotsTaken` property.
get maximumNumberOfInputImages(): Promise<number>@MainActor var maximumNumberOfInputImages: Int { get }The maximum number of images that can be used for on-device reconstruction. Note: the session will stop capturing images when this limit is reached unless ``ObjectCaptureSession/Configuration/isOverCaptureEnabled`` is true.
get userCompletedScanPassUpdates(): Promise<ObjectCaptureSession_Updates<boolean>>@MainActor var userCompletedScanPassUpdates: ObjectCaptureSession.Updates<Bool> { get }The `Updates` `AsyncSequence` for the `userCompletedScanPass` property.
pause(): Promise<void>@MainActor func pause()Pauses the automatic capture and other resource-intense algorithms. Call this when object capture view is not visible, such as when a help screen is shown.
start(imagesDirectory: string, configuration?: ObjectCaptureSession_Configuration): Promise<void>@MainActor func start(imagesDirectory: URL, configuration: ObjectCaptureSession.Configuration = Configuration())Starts the session with the provided output image directory and optional checkpoint directory. - Parameters: - imagesDirectory: A directory to save the images. - configuration: A configuration specifying session options. The directory that `imagesDirectory` points to needs to be an empty and writable directory or it is an error. Likewise, if `checkpointDirectory` is provided, it needs to be empty if it already exists. If the directory does not exist, it is created for you. If it cannot be, the session moves to `.failed` state. This call is only valid once on a newly created session.
get state(): Promise<ObjectCaptureSession_CaptureState>@MainActor var state: ObjectCaptureSession.CaptureState { get }The current state of the capture session.
cancel(): Promise<void>@MainActor func cancel()Requests that the capture session be canceled. Call this when the user indicates they want to cancel the scan. Calling this method eventually transitions the session to `.failed(Error)` Once the session enters the failed state it is safe to tear down the session and create a new one if desired.
finish(): Promise<void>@MainActor func finish()Requests that the capture session be stopped and all data saved. Call this method when the user has completed the scan successfully. The session switches to state `.finishing` while it saves all data and ultimately switches the state to `.completed`. The session ignores this method call if the current state is any value other than `.capturing`.
resume(): Promise<void>@MainActor func resume()Resumes object tracking algorithms after ``ObjectCaptureSession/pause()`` is called. Call this method when the object capture view first appears on the screen, or after `pause()` is called to show another view temporarily.
get feedback(): Promise<Array<ObjectCaptureSession_Feedback>>@MainActor var feedback: Set<ObjectCaptureSession.Feedback> { get }The current set of active `Feedback` states.
get isPaused(): Promise<boolean>@MainActor var isPaused: Bool { get }A Boolean value that indicates if the capture session is paused.
static init(): Promise<ObjectCaptureSession>@MainActor init()Creates a new object capture session. ``ObjectCaptureSession/isSupported`` needs to be true on the device in order to create a session.
No declarations were skipped in this snapshot.