Struct Pinhole 

pub struct Pinhole {
    pub image_from_camera: Option<SerializedComponentBatch>,
    pub resolution: Option<SerializedComponentBatch>,
    pub camera_xyz: Option<SerializedComponentBatch>,
    pub child_frame: Option<SerializedComponentBatch>,
    pub parent_frame: Option<SerializedComponentBatch>,
    pub image_plane_distance: Option<SerializedComponentBatch>,
    pub color: Option<SerializedComponentBatch>,
    pub line_width: Option<SerializedComponentBatch>,
}

Archetype: Camera perspective projection (a.k.a. intrinsics).

If archetypes::Transform3D is logged for the same child/parent relationship (e.g. for the camera extrinsics), it takes precedence over archetypes::Pinhole.

If you use named transform frames via the child_frame and parent_frame fields, you don’t have to use archetypes::CoordinateFrame as it is the case with other visualizations: for any entity with an archetypes::Pinhole the viewer will always visualize it directly without needing a archetypes::CoordinateFrame to refer to the pinhole’s child/parent frame.

Examples

Simple pinhole camera

use ndarray::{Array, ShapeBuilder as _};
use rand::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rec = rerun::RecordingStreamBuilder::new("rerun_example_pinhole").spawn()?;

    let mut image = Array::<u8, _>::default((3, 3, 3).f());
    let mut rng = rand::rngs::SmallRng::seed_from_u64(42);
    image.map_inplace(|x| *x = rng.random());

    rec.log(
        "world/image",
        &rerun::Pinhole::from_focal_length_and_resolution([3., 3.], [3., 3.]),
    )?;
    rec.log(
        "world/image",
        &rerun::Image::from_color_model_and_tensor(rerun::ColorModel::RGB, image)?,
    )?;

    Ok(())
}

Perspective pinhole camera

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rec = rerun::RecordingStreamBuilder::new("rerun_example_pinhole_perspective").spawn()?;

    let fov_y = std::f32::consts::FRAC_PI_4;
    let aspect_ratio = 1.7777778;
    rec.log(
        "world/cam",
        &rerun::Pinhole::from_fov_and_aspect_ratio(fov_y, aspect_ratio)
            .with_camera_xyz(rerun::components::ViewCoordinates::RUB)
            .with_image_plane_distance(0.1)
            .with_color(rerun::Color::from_rgb(255, 128, 0))
            .with_line_width(0.003),
    )?;

    rec.log(
        "world/points",
        &rerun::Points3D::new([(0.0, 0.0, -0.5), (0.1, 0.1, -0.5), (-0.1, -0.1, -0.5)])
            .with_radii([0.025]),
    )?;

    Ok(())
}

Fields

image_from_camera: Option<SerializedComponentBatch>

Camera projection, from image coordinates to view coordinates.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

resolution: Option<SerializedComponentBatch>

Pixel resolution (usually integers) of child image space. Width and height.

Example:

[1920.0, 1440.0]

image_from_camera project onto the space spanned by (0,0) and resolution - 1.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

camera_xyz: Option<SerializedComponentBatch>

Sets the view coordinates for the camera.

All common values are available as constants on the components::ViewCoordinates class.

The default is ViewCoordinates::RDF, i.e. X=Right, Y=Down, Z=Forward, and this is also the recommended setting. This means that the camera frustum will point along the positive Z axis of the parent space, and the cameras “up” direction will be along the negative Y axis of the parent space.

The camera frustum will point whichever axis is set to F (or the opposite of B). When logging a depth image under this entity, this is the direction the point cloud will be projected. With RDF, the default forward is +Z.

The frustum’s “up” direction will be whichever axis is set to U (or the opposite of D). This will match the negative Y direction of pixel space (all images are assumed to have xyz=RDF). With RDF, the default is up is -Y.

The frustum’s “right” direction will be whichever axis is set to R (or the opposite of L). This will match the positive X direction of pixel space (all images are assumed to have xyz=RDF). With RDF, the default right is +x.

Other common formats are RUB (X=Right, Y=Up, Z=Back) and FLU (X=Forward, Y=Left, Z=Up).

NOTE: setting this to something else than RDF (the default) will change the orientation of the camera frustum, and make the pinhole matrix not match up with the coordinate system of the pinhole entity.

The pinhole matrix (the image_from_camera argument) always project along the third (Z) axis, but will be re-oriented to project along the forward axis of the camera_xyz argument.

child_frame: Option<SerializedComponentBatch>

The child frame this transform transforms from.

The entity at which the transform relationship of any given child frame is specified mustn’t change over time, but is allowed to be different for static time. E.g. if you specified the child frame "robot_arm" on an entity named "my_transforms", you may not log transforms with the child frame "robot_arm" on any other entity than "my_transforms" unless one of them was logged with static time.

If not specified, this is set to the implicit transform frame of the current entity path. This means that if a archetypes::Transform3D is set on an entity called /my/entity/path then this will default to tf#/my/entity/path.

To set the frame an entity is part of see archetypes::CoordinateFrame.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

parent_frame: Option<SerializedComponentBatch>

The parent frame this transform transforms into.

If not specified, this is set to the implicit transform frame of the current entity path’s parent. This means that if a archetypes::Transform3D is set on an entity called /my/entity/path then this will default to tf#/my/entity.

To set the frame an entity is part of see archetypes::CoordinateFrame.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

image_plane_distance: Option<SerializedComponentBatch>

The distance from the camera origin to the image plane when the projection is shown in a 3D viewer.

This is only used for visualization purposes, and does not affect the projection itself.

color: Option<SerializedComponentBatch>

Color of the camera wireframe.

line_width: Option<SerializedComponentBatch>

Width of the camera wireframe lines.

Implementations

impl Pinhole

pub fn descriptor_image_from_camera() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::image_from_camera.

The corresponding component is crate::components::PinholeProjection.

pub fn descriptor_resolution() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::resolution.

The corresponding component is crate::components::Resolution.

pub fn descriptor_camera_xyz() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::camera_xyz.

The corresponding component is crate::components::ViewCoordinates.

pub fn descriptor_child_frame() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::child_frame.

The corresponding component is crate::components::TransformFrameId.

pub fn descriptor_parent_frame() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::parent_frame.

The corresponding component is crate::components::TransformFrameId.

pub fn descriptor_image_plane_distance() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::image_plane_distance.

The corresponding component is crate::components::ImagePlaneDistance.

pub fn descriptor_color() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::color.

The corresponding component is crate::components::Color.

pub fn descriptor_line_width() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::line_width.

The corresponding component is crate::components::Radius.

impl Pinhole

pub const NUM_COMPONENTS: usize = 8usize

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

impl Pinhole

pub fn new(image_from_camera: impl Into<PinholeProjection>) -> Pinhole

Create a new Pinhole.

pub fn update_fields() -> Pinhole

Update only some specific fields of a Pinhole.

pub fn clear_fields() -> Pinhole

Clear all the fields of a Pinhole.

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_image_from_camera( self, image_from_camera: impl Into<PinholeProjection>, ) -> Pinhole

Camera projection, from image coordinates to view coordinates.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

pub fn with_many_image_from_camera( self, image_from_camera: impl IntoIterator<Item = impl Into<PinholeProjection>>, ) -> Pinhole

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

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

pub fn with_resolution(self, resolution: impl Into<Resolution>) -> Pinhole

Pixel resolution (usually integers) of child image space. Width and height.

Example:

[1920.0, 1440.0]

image_from_camera project onto the space spanned by (0,0) and resolution - 1.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

pub fn with_many_resolution( self, resolution: impl IntoIterator<Item = impl Into<Resolution>>, ) -> Pinhole

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

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

pub fn with_camera_xyz(self, camera_xyz: impl Into<ViewCoordinates>) -> Pinhole

Sets the view coordinates for the camera.

All common values are available as constants on the components::ViewCoordinates class.

The default is ViewCoordinates::RDF, i.e. X=Right, Y=Down, Z=Forward, and this is also the recommended setting. This means that the camera frustum will point along the positive Z axis of the parent space, and the cameras “up” direction will be along the negative Y axis of the parent space.

The camera frustum will point whichever axis is set to F (or the opposite of B). When logging a depth image under this entity, this is the direction the point cloud will be projected. With RDF, the default forward is +Z.

The frustum’s “up” direction will be whichever axis is set to U (or the opposite of D). This will match the negative Y direction of pixel space (all images are assumed to have xyz=RDF). With RDF, the default is up is -Y.

The frustum’s “right” direction will be whichever axis is set to R (or the opposite of L). This will match the positive X direction of pixel space (all images are assumed to have xyz=RDF). With RDF, the default right is +x.

Other common formats are RUB (X=Right, Y=Up, Z=Back) and FLU (X=Forward, Y=Left, Z=Up).

NOTE: setting this to something else than RDF (the default) will change the orientation of the camera frustum, and make the pinhole matrix not match up with the coordinate system of the pinhole entity.

The pinhole matrix (the image_from_camera argument) always project along the third (Z) axis, but will be re-oriented to project along the forward axis of the camera_xyz argument.

pub fn with_many_camera_xyz( self, camera_xyz: impl IntoIterator<Item = impl Into<ViewCoordinates>>, ) -> Pinhole

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

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

pub fn with_child_frame( self, child_frame: impl Into<TransformFrameId>, ) -> Pinhole

The child frame this transform transforms from.

The entity at which the transform relationship of any given child frame is specified mustn’t change over time, but is allowed to be different for static time. E.g. if you specified the child frame "robot_arm" on an entity named "my_transforms", you may not log transforms with the child frame "robot_arm" on any other entity than "my_transforms" unless one of them was logged with static time.

If not specified, this is set to the implicit transform frame of the current entity path. This means that if a archetypes::Transform3D is set on an entity called /my/entity/path then this will default to tf#/my/entity/path.

To set the frame an entity is part of see archetypes::CoordinateFrame.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

pub fn with_many_child_frame( self, child_frame: impl IntoIterator<Item = impl Into<TransformFrameId>>, ) -> Pinhole

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

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

pub fn with_parent_frame( self, parent_frame: impl Into<TransformFrameId>, ) -> Pinhole

The parent frame this transform transforms into.

If not specified, this is set to the implicit transform frame of the current entity path’s parent. This means that if a archetypes::Transform3D is set on an entity called /my/entity/path then this will default to tf#/my/entity.

To set the frame an entity is part of see archetypes::CoordinateFrame.

Any update to this field will reset all other transform properties that aren’t changed in the same log call or send_columns row.

pub fn with_many_parent_frame( self, parent_frame: impl IntoIterator<Item = impl Into<TransformFrameId>>, ) -> Pinhole

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

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

pub fn with_image_plane_distance( self, image_plane_distance: impl Into<ImagePlaneDistance>, ) -> Pinhole

The distance from the camera origin to the image plane when the projection is shown in a 3D viewer.

This is only used for visualization purposes, and does not affect the projection itself.

pub fn with_many_image_plane_distance( self, image_plane_distance: impl IntoIterator<Item = impl Into<ImagePlaneDistance>>, ) -> Pinhole

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

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

pub fn with_color(self, color: impl Into<Color>) -> Pinhole

Color of the camera wireframe.

pub fn with_many_color( self, color: impl IntoIterator<Item = impl Into<Color>>, ) -> Pinhole

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

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

pub fn with_line_width(self, line_width: impl Into<Radius>) -> Pinhole

Width of the camera wireframe lines.

pub fn with_many_line_width( self, line_width: impl IntoIterator<Item = impl Into<Radius>>, ) -> Pinhole

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

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

impl Pinhole

pub const DEFAULT_CAMERA_XYZ: ViewCoordinates = ViewCoordinates::RDF

Camera orientation used when there’s no camera orientation explicitly logged.

• x pointing right
• y pointing down
• z pointing into the image plane (this is convenient for reading out a depth image which has typically positive z values)

pub fn from_focal_length_and_resolution( focal_length: impl Into<Vec2D>, resolution: impl Into<Vec2D>, ) -> Pinhole

Creates a pinhole from the camera focal length and resolution, both specified in pixels.

The focal length is the diagonal of the projection matrix. Set the same value for x & y value for symmetric cameras, or two values for anamorphic cameras.

Assumes the principal point to be in the middle of the sensor.

pub fn from_fov_and_aspect_ratio(fov_y: f32, aspect_ratio: f32) -> Pinhole

Creates a pinhole from the camera vertical field of view (in radians) and aspect ratio (width/height).

Assumes the principal point to be in the middle of the sensor.

pub fn with_principal_point(self, principal_point: impl Into<Vec2D>) -> Pinhole

Principal point of the pinhole camera, i.e. the intersection of the optical axis and the image plane.

see definition of intrinsic matrix

This method can be relatively costly since it has to deserialize & reserialize the [`PinholeProjection`] component from/to its arrow representation. On performance critical paths, prefer first setting up the [`PinholeProjection`] component fully before passing it to the archetype.

pub fn image_from_camera_from_arrow( &self, ) -> Result<PinholeProjection, DeserializationError>

Deserializes the pinhole projection from the image_from_camera field.

Returns re_types_core::DeserializationError::MissingData if the component is not present.

pub fn resolution_from_arrow(&self) -> Result<Resolution, DeserializationError>

Deserializes the resolution from the resolution field.

Returns re_types_core::DeserializationError::MissingData if the component is not present.

Trait Implementations

impl Archetype for Pinhole

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 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<Pinhole, DeserializationError>

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

fn all_component_identifiers() -> impl Iterator<Item = ComponentIdentifier>

Utility method based on Self::all_components to return all component identifiers.

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 Pinhole

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 Pinhole

fn clone(&self) -> Pinhole

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Pinhole

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

Formats the value using the given formatter.

impl Default for Pinhole

fn default() -> Pinhole

Returns the “default value” for a type.

impl PartialEq for Pinhole

fn eq(&self, other: &Pinhole) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SizeBytes for Pinhole

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 VisualizableArchetype for Pinhole

fn visualizer(&self) -> Visualizer

Create a visualizer for this archetype, using all currently set values as overrides.

impl ArchetypeReflectionMarker for Pinhole

impl StructuralPartialEq for Pinhole