Crate pcd_rs

Read and write PCD file format.

This crate provides data serializer and deserializer for PCD (Point Cloud Data) file format. The DynReader and DynWriter can read and write PCD files with any valid schemas. It also supports deserializing to static types if the derive feature is enabled.

Supported Format Versions

• 0.7
• Older versions are not supported yet.

Any Schema Example

In the case of any schema, the points are represented by an array or a slice of DynRecords, where is record wraps a sequence of data Fields.

Reader

The reader is created by DynReader::open(), returning an iterator, which generates a sequence of Result<DynRecord>.

use pcd_rs::DynReader;

// Declare the reader
let reader = DynReader::open("test_files/binary.pcd")?;

// The reader itself is an iterator of records
let points: Result<Vec<_>> = reader.collect();
println!("There are {} points found.", points?.len());

Writer

The writer is first configured by WriterInit, and then call WriterInit::create() to construct the DynWriter. The .push() is used to append the data to the writer. The writer must be finished by .finish() in the end.

use pcd_rs::{DataKind, DynRecord, DynWriter, Field, Schema, ValueKind, WriterInit};

// Declare point data
let points = [
    DynRecord(vec![
        Field::F32(vec![3.14159]),
        Field::U8(vec![2, 1, 7]),
        Field::I32(vec![-5]),
    ]),
    DynRecord(vec![
        Field::F32(vec![-0.0]),
        Field::U8(vec![254, 6, 98]),
        Field::I32(vec![7]),
    ]),
    DynRecord(vec![
        Field::F32(vec![5.6]),
        Field::U8(vec![4, 0, 111]),
        Field::I32(vec![-100000]),
    ]),
];

// Declare the schema
let schema = vec![
    ("x", ValueKind::F32, 1),
    ("y", ValueKind::U8, 3),
    ("z", ValueKind::I32, 1),
];

// Build a writer
let mut writer: DynWriter<_> = WriterInit {
    width: 300,
    height: 1,
    viewpoint: Default::default(),
    data_kind: DataKind::Ascii,
    schema: Some(Schema::from_iter(schema)),
}
.create("test_files/dump_ascii_untyped.pcd")?;

// Send the points to the writer
for point in points {
    writer.push(&point)?;
}

// Finalize the writer
writer.finish()?;

Static Schema Example

The serde-like derives PcdSerialize and PcdDeserialize allows the Reader and Writer to read from to write to the annotated types. Both are available if the derive feature is enabled. The type must be a struct with named fields, where each field type is either a primitive type, an array or a Vec.

Reader

The reader is constructed by Reader::open(), which itself is an iterator. The .push() is used to append the data to the writer. The writer must be finished by .finish() in the end.

use pcd_rs::{PcdDeserialize, Reader};

#[derive(PcdDeserialize)]
pub struct Point {
    pub x: f32,
    pub y: f32,
    pub z: f32,
    pub rgb: f32,
}

let reader = Reader::open("test_files/ascii.pcd")?;
let points: Result<Vec<Point>> = reader.collect();
println!("{} points found", points?.len());

Writer

The writer is configured by WriterInit and then created by WriterInit::create().

use pcd_rs::{DataKind, PcdDeserialize, PcdSerialize, WriterInit};

#[derive(PcdSerialize)]
pub struct Point {
    #[pcd(rename = "new_x")]
    x: f32,
    y: [u8; 3],
    z: i32,
}

// point data
let points = [
    Point {
        x: 3.14159,
        y: [2, 1, 7],
        z: -5,
    },
    Point {
        x: -0.0,
        y: [254, 6, 98],
        z: 7,
    },
    Point {
        x: 5.6,
        y: [4, 0, 111],
        z: -100000,
    },
];

// serialize points
let mut writer = WriterInit {
    width: 300,
    height: 1,
    viewpoint: Default::default(),
    data_kind: DataKind::Ascii,
    schema: None,
}
.create("test_files/dump_ascii_static.pcd")?;

for point in points {
    writer.push(&point)?;
}

writer.finish()?;

Derives

Both PcdSerialize and PcdDeserialize supports the following field attributes.

• #[pcd(rename = "NEW_NAME")] sets the field name on the written PCD data.
• #[pcd(ignore)] instructs the de/serializer to ignore the field.

Re-exports

• pub use error::Error;
• pub use metas::DataKind;
• pub use metas::FieldDef;
• pub use metas::PcdMeta;
• pub use metas::Schema;
• pub use metas::TypeKind;
• pub use metas::ValueKind;
• pub use metas::ViewPoint;
• pub use reader::DynReader;
• pub use reader::Reader;
• pub use record::DynRecord;
• pub use record::Field;
• pub use record::PcdDeserialize;
• pub use record::PcdSerialize;
• pub use traits::Value;
• pub use writer::DynWriter;
• pub use writer::Writer;
• pub use writer::WriterInit;

Modules

• error
  The module defines most error type used by this crate.
• metas
  Types for PCD metadata.
• prelude
  The Prelude for pcd-rs, including commonly used traits.
• reader
  Types for reading PCD data.
• record
  Defines serializing and deserializing traits and common record types.
• traits
  Traits definitions.
• writer
  Types for writing PCD data.

Derive Macros

• PcdDeserialize
  Derives PcdDeserialize trait on normal struct or tuple struct.
• PcdSerialize
  Derives PcdSerialize trait on normal struct or tuple struct.