Struct rerun::sdk::archetypes::Pinhole

pub struct Pinhole {
    pub image_from_camera: Option<SerializedComponentBatch>,
    pub resolution: Option<SerializedComponentBatch>,
    pub camera_xyz: Option<SerializedComponentBatch>,
    pub image_plane_distance: Option<SerializedComponentBatch>,
}

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

Examples

Simple pinhole camera

use ndarray::{Array, ShapeBuilder};

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());
    image.map_inplace(|x| *x = rand::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),
    )?;

    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.

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.

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.

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.

Implementations

impl Pinhole

pub fn descriptor_image_from_camera() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::image_from_camera.

pub fn descriptor_resolution() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::resolution.

pub fn descriptor_camera_xyz() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::camera_xyz.

pub fn descriptor_image_plane_distance() -> ComponentDescriptor

Returns the ComponentDescriptor for Self::image_plane_distance.

pub fn descriptor_indicator() -> ComponentDescriptor

Returns the ComponentDescriptor for the associated indicator component.

impl Pinhole

pub const NUM_COMPONENTS: usize = 5usize

The total number of components in the archetype: 1 required, 2 recommended, 2 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.

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.

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_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.

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 fov_y(&self) -> Option<f32>

👎Deprecated since 0.22.0: Use Pinhole::image_from_camera_from_arrow & Pinhole::resolution_from_arrow to deserialize the components back, or better use the components prior to passing it to the archetype, and then call PinholeProjection::fov_y

Field of View on the Y axis, i.e. the angle between top and bottom (in radians).

Only returns a result if both projection & resolution are set.

pub fn resolution(&self) -> Option<Vec2>

👎Deprecated since 0.22.0: Use Pinhole::resolution_from_arrow to deserialize back to a Resolution component, or better use the Resolution prior to passing it to the archetype, and then use Resolution::into for the conversion

The resolution of the camera sensor in pixels.

pub fn aspect_ratio(&self) -> Option<f32>

👎Deprecated since 0.22.0: Use Pinhole::resolution_from_arrow to deserialize back to a Resolution component, or better use the Resolution prior to passing it to the archetype, and then use Resolution::aspect_ratio

Width/height ratio of the camera sensor.

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.

pub fn focal_length_in_pixels(&self) -> Vec2D

👎Deprecated since 0.22.0: Use Pinhole::image_from_camera_from_arrow instead to deserialize back to a PinholeProjection component, or better use the PinholeProjection component prior to passing it to the archetype, and then call PinholeProjection::focal_length_in_pixels

X & Y focal length in pixels.

see definition of intrinsic matrix

pub fn principal_point(&self) -> Vec2

👎Deprecated since 0.22.0: Use Pinhole::image_from_camera_from_arrow instead to deserialize back to a PinholeProjection component, or better use the PinholeProjection component prior to passing it to the archetype, and then call PinholeProjection::principal_point

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

see definition of intrinsic matrix

pub fn project(&self, pixel: Vec3) -> Vec3

👎Deprecated since 0.22.0: Use Pinhole::image_from_camera_from_arrow instead to deserialize back to a PinholeProjection component, or better use the PinholeProjection component prior to passing it to the archetype, and then call PinholeProjection::project

Project camera-space coordinates into pixel coordinates, returning the same z/depth.

pub fn unproject(&self, pixel: Vec3) -> Vec3

👎Deprecated since 0.22.0: Use Pinhole::image_from_camera_from_arrow instead to deserialize back to a PinholeProjection component, or better use the PinholeProjection component prior to passing it to the archetype, and then call PinholeProjection::unproject

Given pixel coordinates and a world-space depth, return a position in the camera space.

The returned z is the same as the input z (depth).

Trait Implementations

impl Archetype for Pinhole

type Indicator = GenericIndicatorComponent<Pinhole>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method 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 ArchetypeReflectionMarker for Pinhole

impl StructuralPartialEq for Pinhole