Struct rerun::sdk::prelude::VideoFrameReference

pub struct VideoFrameReference {
    pub timestamp: Option<SerializedComponentBatch>,
    pub video_reference: Option<SerializedComponentBatch>,
}

Archetype: References a single video frame.

Used to display individual video frames from a archetypes::AssetVideo. To show an entire video, a video frame reference for each frame of the video should be logged.

See https://rerun.io/docs/reference/video for details of what is and isn’t supported.

Examples

Video with automatically determined frames

use rerun::external::anyhow;

fn main() -> anyhow::Result<()> {
    let args = _args;
    let Some(path) = args.get(1) else {
        // TODO(#7354): Only mp4 is supported for now.
        anyhow::bail!("Usage: {} <path_to_video.[mp4]>", args[0]);
    };

    let rec =
        rerun::RecordingStreamBuilder::new("rerun_example_asset_video_auto_frames").spawn()?;

    // Log video asset which is referred to by frame references.
    let video_asset = rerun::AssetVideo::from_file_path(path)?;
    rec.log_static("video", &video_asset)?;

    // Send automatically determined video frame timestamps.
    let frame_timestamps_ns = video_asset.read_frame_timestamps_ns()?;
    let video_timestamps_ns = frame_timestamps_ns
        .iter()
        .copied()
        .map(rerun::components::VideoTimestamp::from_nanoseconds)
        .collect::<Vec<_>>();
    let time_column = rerun::TimeColumn::new_nanos(
        "video_time",
        // Note timeline values don't have to be the same as the video timestamps.
        frame_timestamps_ns,
    );

    rec.send_columns(
        "video",
        [time_column],
        rerun::VideoFrameReference::update_fields()
            .with_many_timestamp(video_timestamps_ns)
            .columns_of_unit_batches()?,
    )?;

    Ok(())
}

Demonstrates manual use of video frame references

use rerun::external::anyhow;

fn main() -> anyhow::Result<()> {
    let args = _args;
    let Some(path) = args.get(1) else {
        // TODO(#7354): Only mp4 is supported for now.
        anyhow::bail!("Usage: {} <path_to_video.[mp4]>", args[0]);
    };

    let rec =
        rerun::RecordingStreamBuilder::new("rerun_example_asset_video_manual_frames").spawn()?;

    // Log video asset which is referred to by frame references.
    rec.log_static("video_asset", &rerun::AssetVideo::from_file_path(path)?)?;

    // Create two entities, showing the same video frozen at different times.
    rec.log(
        "frame_1s",
        &rerun::VideoFrameReference::new(rerun::components::VideoTimestamp::from_seconds(1.0))
            .with_video_reference("video_asset"),
    )?;
    rec.log(
        "frame_2s",
        &rerun::VideoFrameReference::new(rerun::components::VideoTimestamp::from_seconds(2.0))
            .with_video_reference("video_asset"),
    )?;

    // TODO(#5520): log blueprint once supported
    Ok(())
}

Fields

timestamp: Option<SerializedComponentBatch>

References the closest video frame to this timestamp.

Note that this uses the closest video frame instead of the latest at this timestamp in order to be more forgiving of rounding errors for inprecise timestamp types.

Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame. This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.

video_reference: Option<SerializedComponentBatch>

Optional reference to an entity with a archetypes::AssetVideo.

If none is specified, the video is assumed to be at the same entity. Note that blueprint overrides on the referenced video will be ignored regardless, as this is always interpreted as a reference to the data store.

For a series of video frame references, it is recommended to specify this path only once at the beginning of the series and then rely on latest-at query semantics to keep the video reference active.

Implementations

impl VideoFrameReference

pub fn descriptor_timestamp() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::timestamp.

pub fn descriptor_video_reference() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::video_reference.

pub fn descriptor_indicator() -> ComponentDescriptor

Returns the ComponentDescriptor for the associated indicator component.

impl VideoFrameReference

pub const NUM_COMPONENTS: usize = 3usize

The total number of components in the archetype: 1 required, 1 recommended, 1 optional

impl VideoFrameReference

pub fn new(timestamp: impl Into<VideoTimestamp>) -> VideoFrameReference

Create a new VideoFrameReference.

pub fn update_fields() -> VideoFrameReference

Update only some specific fields of a VideoFrameReference.

pub fn clear_fields() -> VideoFrameReference

Clear all the fields of a VideoFrameReference.

pub fn columns<I>( self, _lengths: I, ) -> Result<impl Iterator<Item = SerializedComponentColumn>, SerializationError>

where I: IntoIterator<Item = usize> + Clone,

Partitions the component data into multiple sub-batches.

Specifically, this transforms the existing SerializedComponentBatches data into SerializedComponentColumns instead, via SerializedComponentBatch::partitioned.

This makes it possible to use RecordingStream::send_columns to send columnar data directly into Rerun.

The specified lengths must sum to the total length of the component batch.

pub fn columns_of_unit_batches( self, ) -> Result<impl Iterator<Item = SerializedComponentColumn>, SerializationError>

Helper to partition the component data into unit-length sub-batches.

This is semantically similar to calling Self::columns with std::iter::take(1).repeat(n), where n is automatically guessed.

pub fn with_timestamp( self, timestamp: impl Into<VideoTimestamp>, ) -> VideoFrameReference

References the closest video frame to this timestamp.

Note that this uses the closest video frame instead of the latest at this timestamp in order to be more forgiving of rounding errors for inprecise timestamp types.

Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame. This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.

pub fn with_many_timestamp( self, timestamp: impl IntoIterator<Item = impl Into<VideoTimestamp>>, ) -> VideoFrameReference

This method makes it possible to pack multiple crate::components::VideoTimestamp in a single component batch.

This only makes sense when used in conjunction with Self::columns. Self::with_timestamp should be used when logging a single row’s worth of data.

pub fn with_video_reference( self, video_reference: impl Into<EntityPath>, ) -> VideoFrameReference

Optional reference to an entity with a archetypes::AssetVideo.

If none is specified, the video is assumed to be at the same entity. Note that blueprint overrides on the referenced video will be ignored regardless, as this is always interpreted as a reference to the data store.

For a series of video frame references, it is recommended to specify this path only once at the beginning of the series and then rely on latest-at query semantics to keep the video reference active.

pub fn with_many_video_reference( self, video_reference: impl IntoIterator<Item = impl Into<EntityPath>>, ) -> VideoFrameReference

This method makes it possible to pack multiple crate::components::EntityPath in a single component batch.

This only makes sense when used in conjunction with Self::columns. Self::with_video_reference should be used when logging a single row’s worth of data.

Trait Implementations

impl Archetype for VideoFrameReference

type Indicator = GenericIndicatorComponent<VideoFrameReference>

The associated indicator component, whose presence indicates that the high-level archetype-based APIs were used to log the data.

fn name() -> ArchetypeName

The fully-qualified name of this archetype, e.g. rerun.archetypes.Points2D.

fn display_name() -> &'static str

Readable name for displaying in UI.

fn indicator() -> SerializedComponentBatch

Creates a ComponentBatch out of the associated Self::Indicator component.

fn required_components() -> Cow<'static, [ComponentDescriptor]>

Returns all component descriptors that must be provided by the user when constructing this archetype.

fn recommended_components() -> Cow<'static, [ComponentDescriptor]>

Returns all component descriptors that should be provided by the user when constructing this archetype.

fn optional_components() -> Cow<'static, [ComponentDescriptor]>

Returns all component descriptors that may be provided by the user when constructing this archetype.

fn all_components() -> Cow<'static, [ComponentDescriptor]>

Returns all component descriptors that must, should and may be provided by the user when constructing this archetype.

fn from_arrow_components( arrow_data: impl IntoIterator<Item = (ComponentDescriptor, Arc<dyn Array>)>, ) -> Result<VideoFrameReference, DeserializationError>

Given an iterator of Arrow arrays and their respective ComponentNames, deserializes them into this archetype.

fn from_arrow( data: impl IntoIterator<Item = (Field, Arc<dyn Array>)>, ) -> Result<Self, DeserializationError>

where Self: Sized,

Given an iterator of Arrow arrays and their respective field metadata, deserializes them into this archetype.

impl AsComponents for VideoFrameReference

fn as_serialized_batches(&self) -> Vec<SerializedComponentBatch>

Exposes the object’s contents as a set of SerializedComponentBatches.

fn to_arrow(&self) -> Result<Vec<(Field, Arc<dyn Array>)>, SerializationError>

Serializes all non-null Components of this bundle into Arrow arrays.

impl Clone for VideoFrameReference

fn clone(&self) -> VideoFrameReference

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VideoFrameReference

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for VideoFrameReference

fn default() -> VideoFrameReference

Returns the “default value” for a type.

impl SizeBytes for VideoFrameReference

fn heap_size_bytes(&self) -> u64

Returns how many bytes self uses on the heap.

fn total_size_bytes(&self) -> u64

Returns the total size of self in bytes, accounting for both stack and heap space.

fn stack_size_bytes(&self) -> u64

Returns the total size of self on the stack, in bytes.

fn is_pod() -> bool

Is Self just plain old data?

impl ArchetypeReflectionMarker for VideoFrameReference