Skip to main content
←API Reference ←com.nianticspatial.nsdk.playback

PlaybackDataset

↳ extends AutoCloseable

Declaration​

class PlaybackDataset

Summary​

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​

NameTypeSummary
captureRootCaptureRoot
The fully decoded capture.json for this dataset (capture-level metadata plus per-frame
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.
compassTimestampBaseClockBase
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.
frameCountInt
Number of frames in the dataset; [info]'s frame count.
frameIntervalDouble
Seconds between frames at the recorded rate.
infoPlaybackDatasetInfo
Capture-level facts about this dataset.

Functions​

NameTypeSummary
clearCachevoid
Deletes every cached scan recording through the active session's playback cache; see
[PlaybackCacheSession.clearCache].
closevoid
Releases the native dataset [open] created, after which [getPlaybackFrameAtIndex] throws
[PlaybackDatasetError.IndexOutOfBounds]. Does not close a source passed to [loadFrom].
deleteCachedvoid
Deletes a scan's cached recording through the active session's playback cache; see
[PlaybackCacheSession.deleteCached].
getDepthConfidenceAtIndexByteArray?
Loads depth confidence (UInt8 binary) at [index] on-demand. Returns null if not available.
getDepthDataAtIndexByteArray?
Loads depth data (Float32 binary) at [index] on-demand. Returns null if this frame has no depth.
getFrameImageAtIndexandroid.graphics.Bitmap?
Loads the frame image at [index] on-demand (and caches it). Returns decoded bitmap, or null if no image.
getFrameImageBytesAtIndexByteArray
Returns raw image bytes at [index] (on-demand, cached). Use when you need bytes instead of Bitmap.
getFrameMetadataAtIndexFrameMetadata
Returns frame metadata at [index].
getPlaybackFrameAtIndexPlaybackFrame
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.
getPlaybackFrameMetadataAtIndexPlaybackFrameMetadata
Returns frame [index]'s recorded data without loading its image or depth.
hasDepthBoolean
True if the dataset declares LiDAR depth in a supported format; [info]'s depth flag.
loadFromPlaybackDataset?
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.
openPlaybackDataset?
Opens the dataset at [datasetPath]: a filesystem directory, or asset://<directory> for a
directory in the application APK's assets, e.g. "asset://playback/my_capture" for
src/main/assets/playback/my_capture/.