# Adding Depth to Your Project Source: https://www.nianticspatial.com/docs/nsdk/how-to/ar/depth/adding_depth/?platform=kotlin The `DepthSession` class provides access to depth estimation capabilities in the Niantic Spatial SDK (NSDK) for Kotlin/Android. It enables your application to retrieve real-time depth data from the camera feed, which can be used for occlusion, spatial understanding, and AR effects. ## Creating and Configuring a Depth Session To use depth in your application, you first need to acquire a `DepthSession` from your `NSDKSession`: ```kotlin val depthSession = nsdkSessionManager.session.depthSession.acquire() ``` Once you have a `DepthSession`, configure it with a `DepthConfig` before starting: ```kotlin depthSession.configure( DepthConfig( framerate = 30, featureMode = AwarenessFeatureMode.UNSPECIFIED ) ) ``` ### Configuration Options The `DepthConfig` class allows you to customize depth estimation behavior: - **`framerate`** -- Controls the target frame rate for depth estimation. Higher frame rates provide smoother depth updates but may consume more processing resources. - **`featureMode`** -- Specifies the awareness feature mode to use. ## Starting and Stopping the Session After configuration, start the depth session to begin receiving depth data: ```kotlin depthSession.start() ``` The `start()` method throws an `NsdkStatusException` if the session cannot be started. Once started, the session will begin processing camera frames and generating depth estimates. To stop the session: ```kotlin depthSession.stop() ``` Always stop the session when you no longer need depth data to free up system resources. ## Retrieving Depth Data Collect `depthSession.depthUpdates` to receive each new depth buffer. The flow polls the session on its own schedule while it has a collector and emits a buffer once, so a collector never sees the same frame twice: ```kotlin val depthJob = coroutineScope.launch { depthSession.depthUpdates.collect { result -> when (result) { is NSDKResult.Success -> { val depthBuffer = result.value // Use depthBuffer here } is NSDKResult.Error -> { // Emitted once per distinct error, for example NOT_READY while depth initializes Log.w("DepthSession", "Depth not available: ${result.code}") } } } } ``` Cancel the job when you no longer need updates; polling stops once the flow has no collectors. ### Reading the Latest Depth Buffer on Demand To read the current depth buffer at a moment of your choosing, for example from a frame callback, call `latestDepth()`: ```kotlin when (val result = depthSession.latestDepth()) { is NSDKResult.Success -> { val depthBuffer = result.value // Use depthBuffer here } is NSDKResult.Error -> { // Handle error - may indicate depth is not ready yet Log.w("DepthSession", "Depth not available: ${result.code}") } } ``` Every call copies the depth image into a new `FloatArray`, so call `latestDepth()` at most once per frame and never in a loop. Both `depthUpdates` and `latestDepth()` deliver an `NSDKResult`. The result may be an error if: - The session hasn't started yet - Depth estimation is still initializing - The camera feed is unavailable ### DepthBuffer Properties The `DepthBuffer` object contains the depth data and metadata: - **`timestampMs`** -- Timestamp of the depth frame in milliseconds - **`imageWidth`** -- Width of the depth image in pixels - **`imageHeight`** -- Height of the depth image in pixels - **`image`** -- `FloatArray` containing depth values. Each value represents the distance in meters from the camera to the corresponding pixel in the scene. ## More Information The [NSDK sample project](https://www.nianticspatial.com/docs/nsdk/sample_projects/) includes an example of running depth.