NSDKScanningSession

A session for 3D scanning and visualization with Combine publisher support....

Declaration

final class NSDKScanningSession

Summary

A session for 3D scanning and visualization with Combine publisher support. The scanning feature provides capabilities for capturing, processing, and exporting 3D scan data from AR sessions. Scans of a location can be processed by the Visual Positioning System's (VPS's) cloud services to enable VPS localization.

Overview

Use $latestRaycastBuffer and $latestVoxelBuffer to reactively update your UI or visualization in response to new scan data, rather than polling each frame manually.

Usage Pattern

let scanSession = nsdkSession.acquireScanningSession()
let config = NSDKScanningSession.Configuration(
    enableRaycastVisualization: true,
    enableVoxelVisualization: true
)
try scanSession.configure(with: config)
scanSession.start()
// Subscribe to raycast buffer updates
scanSession.$latestRaycastBuffer
    .compactMap { $0 }
    .sink { buffer in
        // Update raycast visualization
    }
    .store(in: &cancellables)
// Trigger voxel computation and subscribe to results
scanSession.computeVoxels()
scanSession.$latestVoxelBuffer
    .compactMap { $0 }
    .sink { buffer in
        // Update voxel visualization
    }
    .store(in: &cancellables)

$latestRaycastBuffer is updated automatically each frame by NSDKSession.update() while the session is active and raycast visualization is enabled. $latestVoxelBuffer is updated each frame when new voxel data is available after computeVoxels() has been called.

Properties

Name	Type	Summary
@Published var latestRaycastBuffer	RaycastBuffer	The most recently computed raycast buffer. Updated each frame by `NSDKSession` while active. `nil` until the first buffer arrives after `start()`. Requires `enableRaycastVisualization` to be set in the configuration.
@Published var latestVoxelBuffer	VoxelBuffer	The most recently computed voxel buffer. Updated each frame when new voxel data is ready. `nil` until `computeVoxels()` has been called and results become available. Requires `enableVoxelVisualization` to be set in the configuration.

Methods

Name	Type	Summary
computeVoxels	void	Triggers asynchronous voxel computation. Subscribe to `$latestVoxelBuffer` to receive the result once processing completes. - Precondition: Voxel visualization must have been enabled in the configuration.
configure	void	Configures the session with the specified settings. - Attention: This method must be called while the session is stopped, or else configuration will fail. In that case, while this function returns without throwing, configuration will still fail asynchronously. Use `featureStatus()` to check that configuration has not failed. - Parameter config: An object that defines this session's behavior. Only settings that differ from the defaults will be applied. - Throws: `NSDKError.invalidArgument` if the configuration is invalid. Check NSDK's C logs for more information.
exportArchive	String?	Exports the scan data as an archive file. This method processes the saved scan data and exports it to a standard archive format that can be used with external 3D processing tools or Niantic's VPS map. - Note: This function is blocking and may take a while to execute. See `NSDKRecordingExporter` for a non-blocking alternative. - Precondition: Argument `metadata` must be a valid JSON object string. - Parameter metadata: Metadata dictionary to include with the export. Can be left empty. - Parameter exportAsVideo: If true, the RGB frames in the scan will be exported as an .mp4 video. If false, they will be individual image files. - Returns: The path of the archive file, if the export was successful, `nil` if otherwise. Export failure indicates something was wrong with the saved scan. - Throws: - `NSDKError.invalidOperation` if the scanning session did not have a saved scan to export.
exportSplitArchive	[String]?	Exports the scan data as multiple archive files. This method processes the saved scan data and exports it to multiple archive files based on the maxFramesPerArchive parameter. Each archive will contain at most maxFramesPerArchive frames. - Note: This function is blocking and may take a while to execute. See `NSDKRecordingExporter` for a non-blocking alternative. - Precondition: Argument `metadata` must be a valid JSON object string. - Parameter metadata: Metadata dictionary to include with the export. Can be left empty. - Parameter maxFramesPerArchive: Maximum number of frames per archive file. - Parameter exportAsVideo: If true, the RGB frames in the scan will be exported as an .mp4 video. If false, they will be individual image files. - Returns: An array of paths to the archive files, if the export was successful, `nil` if otherwise. Export failure indicates something was wrong with the saved scan. - Throws: - `NSDKError.invalidOperation` if the scanning session did not have a saved scan to export.
featureStatus	NSDKFeatureStatus	Reports errors that have occurred within processes running inside this feature. Check this periodically to see if any errors have occurred with processes running inside this feature. Once an error has been flagged, it will remain flagged until the culprit process has been run again and completed successfully. - Returns: Feature status flags for any issues that have occurred
recordingInfo	NSDKScanningSession.RecordingInfo	Returns information about the current recording. Call this method before `saveCurrentScan()` to ensure that the recording contains frames to save. Otherwise, the save operation may fail. - Returns: A `RecordingInfo` object containing details about the current recording. - Note: Make sure to call this method before `saveCurrentScan()` if you plan to save the current scan; otherwise, the save may fail.
saveCurrentScan	NSDKScanningSession.SaveInfo	Stops recording and asynchronously saves the recording to the configured path. Calling this function will stop the active recording, but `stop` must still be called afterward to completely shut down this session. - Parameters: - timeout: The maximum duration in seconds to wait for the save operation (default is 10 seconds). - pollingInterval: The interval in seconds to wait between progress checks (default is 0.1 seconds) - Returns: Information about the saved scan, including it's id and file location. - Throws: - `CancellationError` if the Task running this function was cancelled. - `TimeoutError` if the function timed out before it could complete execution. - `NSDKScanningSession.SaveError` if there was an error specific to the save operation. - SeeAlso: - `stop` - `configure(with:)`
start	void	Starts scanning. "Scanning" here may include up to three processes — recording input AR data, raycasting, and voxelization — depending on how the feature is configured. Raycasting and voxelization are useful for visualizing scanned areas and providing feedback to the user about their scan. - SeeAlso: `stop()` - SeeAlso: `configure(_:)`
stop	void	Stops scanning and discards any unsaved scan data. Halts any active scanning while keeping the scanner instance alive. You can restart scanning later by calling `start()`. - SeeAlso: `start()`

Nested Types

Structs

Name	Type	Summary
Configuration	Configuration	Configuration structure for the scanning session.
RecordingInfo	RecordingInfo	Information about the recording generated during scanning.
SaveInfo	SaveInfo	Information about a save operation for a scan.

Enums

Name	Type	Summary
SaveError	SaveError	Errors that can occur during a save operation.

Relationships

conforms to: NSDKFeatureSession

Class NSDKScanningSession NSDKScanningSession

Declaration​

Summary​

Overview​

Usage Pattern​

Properties​

Methods​

Nested Types​

Structs​

Enums​

Relationships​