PlaybackDataset
Declaration
class PlaybackDatasetSummary
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.
Properties
| Name | Type | Summary |
|---|---|---|
| captureRoot | CaptureRoot | |
| compassTimestampBase | ClockBase | Clock this dataset's compass headingTimestamp values are on. Uses the explicit compassTimestampBase field when present, otherwise classifies by the first heading timestamp's magnitude. Zero timestamps mean "not captured" and are skipped. |
| frameCount | Int | Number of frames in the dataset; [info]'s frame count. |
| frameInterval | Double | Seconds between frames at the recorded rate. |
| info | PlaybackDatasetInfo | Capture-level facts about this dataset. |
Functions
| Name | Type | Summary |
|---|---|---|
| clearCache | void | Deletes every cached scan recording through the active session's playback cache; see [PlaybackCacheSession.clearCache]. |
| close | void | Releases the native dataset [open] created, after which [getPlaybackFrameAtIndex] throws [PlaybackDatasetError.IndexOutOfBounds]. Does not close a source passed to [loadFrom]. |
| deleteCached | void | Deletes a scan's cached recording through the active session's playback cache; see [PlaybackCacheSession.deleteCached]. |
| getDepthConfidenceAtIndex | ByteArray? | Loads depth confidence (UInt8 binary) at [index] on-demand. Returns null if not available. |
| getDepthDataAtIndex | ByteArray? | Loads depth data (Float32 binary) at [index] on-demand. Returns null if this frame has no depth. |
| getFrameImageAtIndex | android.graphics.Bitmap? | Loads the frame image at [index] on-demand (and caches it). Returns decoded bitmap, or null if no image. |
| getFrameImageBytesAtIndex | ByteArray | Returns raw image bytes at [index] (on-demand, cached). Use when you need bytes instead of Bitmap. |
| getFrameMetadataAtIndex | FrameMetadata | Returns frame metadata at [index]. |
| getPlaybackFrameAtIndex | PlaybackFrame | Loads a single frame at [index] as a [PlaybackFrame] (metadata, camera, optional image and depth). Image load failure yields a frame with [PlaybackFrame.image] null; depth is null when not available. |
| getPlaybackFrameMetadataAtIndex | PlaybackFrameMetadata | Returns frame [index]'s recorded data without loading its image or depth. |
| hasDepth | Boolean | True if the dataset declares LiDAR depth in a supported format; [info]'s depth flag. |
| loadFrom | PlaybackDataset? | Loads a dataset from [source]: reads capture JSON, decodes it in one pass with [kotlinx.serialization], and returns a [PlaybackDataset] that uses [source] for on-demand frame loading. |
| open | PlaybackDataset? | Opens the dataset at [datasetPath]: a filesystem directory, or asset://<directory> for adirectory in the application APK's assets, e.g. "asset://playback/my_capture" forsrc/main/assets/playback/my_capture/. |
metadata, including each frame's recorded GPS [location][LocationMetadata]). Exposed so
callers can read the recording's metadata — e.g. its location — without running playback.