playback
Classes
| Name | Type | Summary |
|---|---|---|
| AssetPlaybackDatasetLoader | AssetPlaybackDatasetLoader | |
| CachedPlayback | CachedPlayback | A scan in the playback cache. |
| PlaybackBackgroundView | PlaybackBackgroundView | A view that displays the current playback frame image as the background. Place this view behind your 3D/GL surface when in playback mode and call [setPlaybackFrame] whenever a new [PlaybackFrame] is delivered so the recorded camera image is shown. Orientation is corrected so that the image (which may be stored in sensor/landscape layout) is rotated to match the current device orientation using [ImageMath.displayTransform]. Use with [PlaybackSession] and a frame listener: when the session delivers a frame, build [FrameData] for NSDK and call [setPlaybackFrame] to update this view. |
| PlaybackCacheSession | PlaybackCacheSession | Opens scan recordings from the Niantic Spatial portal through one [com.nianticspatial.nsdk.NSDKSession], caching them on the device. The NSDK session creates it on its creating thread and holds one acquisition, so it is ready at nsdkSession.playbackCache from any thread. Closing the NSDK session ends it: an open inflight then fails, and every later call fails, with [PlaybackOpenError.SESSION_ENDED]. Thread-safe. Two locks guard the native calls: this session's own monitor, which [close] and [destroy] take, ends the cache cleanly; [NativeHandle]'s read lock keeps the NSDK instance alive underneath, so a call after the NSDK session is closed, even an [acquire], receives a null handle rather than a freed one. |
| PlaybackCamera | PlaybackCamera | Camera representation for playback, built from frame [metadata]. Exposes transform, intrinsics, resolution, tracking state, and orientation. Use [toArCorePose] to build a [Pose] for [FrameData.cameraPose]. Use [getViewMatrix] and [getProjectionMatrix] to drive a virtual camera for playback rendering. |
| PlaybackDataset | PlaybackDataset | A playback dataset loaded from a capture JSON file. Uses on-demand loading for frame images and depth: only the requested frame is loaded and cached (1-frame cache). Open with [open], which reads the dataset through native playback. The [loadFrom] path over a [PlaybackDatasetSource] is deprecated and will be removed in a future release. [close] releases native resources. Thread safety: This class is NOT thread-safe. All methods must be called from a single thread. The 1-frame cache ([cachedFrameIndex], [cachedImageBytes], [cachedDepthData], [cachedConfidenceData]) is not protected by a lock; concurrent reads and writes will produce inconsistent results. [PlaybackSession] satisfies this constraint by loading frames on one worker thread at a time. If you introduce additional callers, ensure they are serialized. Cache fields are marked [@Volatile][Volatile] so that a value written on a background thread is immediately visible to any thread that subsequently reads it (e.g. the main thread checking [cachedFrameIndex] before deciding to reload). This is a visibility guarantee only — it does not make compound check-then-act sequences atomic. |
| PlaybackDatasetError | PlaybackDatasetError | Errors that can occur when loading or accessing playback dataset data. |
| PlaybackDatasetInfo | PlaybackDatasetInfo | Capture-level facts about a playback dataset. Mirrors ARDK_PlaybackDataset_Info. |
| abstract PlaybackDatasetLoader | PlaybackDatasetLoader | Base class for loading playback dataset data from various sources. Subclasses override [loadCaptureJson], [loadImage], [loadDepthData], [loadDepthConfidence] to provide concrete implementations. Use [loadDataset] to parse the capture JSON and create a [PlaybackDataset] that uses this loader for on-demand frame loading. |
| PlaybackFileInfo | PlaybackFileInfo | The recording [PlaybackCacheSession.open] plays for a scan, as the portal lists it. For a chunked scan, every value is the first (playing) chunk's. |
| PlaybackFrameMetadata | PlaybackFrameMetadata | One frame's recorded data, without its image or depth buffers. Mirrors the frame native playback returns from ARDK_PlaybackDataset_GetFrameMetadata; [transform] is in the recorded (ARCore)convention. |
| PlaybackImageUtility.YuvImageHandler | YuvImageHandler | Holds a YUV [Image] and its [ImageReader]/[ImageWriter]; call [close] when done. |
| PlaybackOpenException | PlaybackOpenException | Thrown by [PlaybackDataset.open] with a scan ID when the open fails. |
| PlaybackSession | PlaybackSession | Runs a timed loop over a [PlaybackDataset], loading one frame per tick and notifying a listener. Use [play] to begin playback and [pause] to stop; the loop wraps to frame 0 at end, and each later pass has its timestamps moved one recording's length later so they keep increasing. Call [setOnFrameListener] before [play] to receive each [PlaybackFrame]; the listener is invoked on a background thread, one frame at a time (post to the main thread before touching UI). An exception thrown by the listener is logged and playback continues; an error loading a frame is logged and stops playback. |
Interfaces
| Name | Type | Summary |
|---|---|---|
| PlaybackDatasetSource | PlaybackDatasetSource | Abstraction for loading playback dataset data from a source (assets, file, etc.). Used for on-demand frame loading: [PlaybackDataset] calls these methods when frames are requested. |
Data Classes
| Name | Type | Summary |
|---|---|---|
| CaptureMetadata | CaptureMetadata | Optional capture-level metadata. |
| CaptureRoot | CaptureRoot | Root structure for the capture JSON file. Required fields per spec; optional may be null. |
| FrameMetadata | FrameMetadata | Per-frame metadata from the capture JSON. Required fields per spec; optional may be null. |
| LocationMetadata | LocationMetadata | Location metadata for a frame. All fields optional for varying capture formats. |
| PlaybackDatasetError.ImageLoadFailed | ImageLoadFailed | Frame image could not be loaded: missing image filename in metadata or loader could not read the file. |
| PlaybackDatasetError.IndexOutOfBounds | IndexOutOfBounds | Requested frame index is outside the dataset (e.g. negative or >= frame count). |
| PlaybackFrame | PlaybackFrame | One frame of playback: recorded data, camera representation, optional image and depth. Created when a frame is loaded (e.g. by [PlaybackSession]). Use [camera] for pose/intrinsics and [frameMetadata] for the frame's recorded data. |
| PlaybackGpsLocation | PlaybackGpsLocation | GPS location from playback metadata (no Android dependency). Use [toLocation] to obtain [android.location.Location] for [FrameData.location]. Testable without mocking Android. |
Enums
| Name | Type | Summary |
|---|---|---|
| CachedPlaybackState | CachedPlaybackState | How far a cached scan's recording got. |
| PlaybackOpenError | PlaybackOpenError | Why [PlaybackDataset.open] with a scan ID failed. |
Functions
| Name | Type | Summary |
|---|---|---|
| cameraImageHeight | Int | Image height in pixels (resolution[1]). |
| cameraImageWidth | Int | Image width in pixels (resolution[0]). |
| cameraIntrinsics | CameraIntrinsics | [CameraIntrinsics] from metadata (fx, fy, cx, cy) and resolution [width, height]. |
| cameraTimestampMs | Long | Timestamp in milliseconds (timestamp × 1000). |
| cameraTransformFloatArray | FloatArray | Column-major 4×4 transform (pose4x4) as FloatArray of 16 elements for use with ARCore and rendering. |
| compassData | Compass? | [Compass] from location metadata when heading is present; null otherwise. |
| gpsLocation | Location? | Android [Location] from frame location metadata when lat/long present; null otherwise. |
| orientation | Orientation | Screen orientation from metadata string; UNKNOWN if missing or unrecognized. |
| playbackGpsLocation | PlaybackGpsLocation? | Parsed GPS location from frame metadata when lat/long present; null otherwise. Use this in tests. |
| trackingState | TrackingState | Tracking: 0 → STOPPED, 1 → PAUSED, 2 (or other) → TRACKING. |
Use a subdirectory that contains a capture JSON file and the frame images (and optional depth files).
Example: place a dataset in
src/main/assets/playback/my_capture/withcapture.json,frame_00000000.jpg, etc. Then useAssetPlaybackDatasetLoader(context, "playback/my_capture").