tidy

README.md

@@ -10,33 +10,22 @@ Providing an easy to use, generics defined, point-wise iterator abstraction over
 To keep the crate a general purpose library for the problem and support ROS1 and ROS2, it uses its own type for the message `PointCloud2Msg`.
 
 ## Examples
-
-Using a `Vec<>`.
 ```rust
 use ros_pointcloud2::{
   pcl_utils::PointXYZ, reader::ReaderXYZ, writer::WriterXYZ, PointCloud2Msg,
 };
 
 // Your points (here using the predefined type PointXYZ).
 let cloud_points = vec![
-  PointXYZ {
-    x: 91.486,
-    y: -4.1,
-    z: 42.0001,
-  },
-
-  PointXYZ {
-    x: f32::MAX,
-    y: f32::MIN,
-    z: f32::MAX,
-  },
+  PointXYZ {x: 91.486, y: -4.1, z: 42.0001,},
+  PointXYZ {x: f32::MAX, y: f32::MIN, z: f32::MAX,},
 ];
 
 // For equality test later
 let cloud_copy = cloud_points.clone();
 
 // Vector -> Writer -> Message.
-// You can also just give the Vec or anything that implements `IntoIter`.
+// You can also just give the Vec or anything that implements `IntoIterator`.
 let internal_msg: PointCloud2Msg = WriterXYZ::from(cloud_points.into_iter())
   .try_into() // iterating points here O(n)
   .unwrap();
@@ -49,7 +38,7 @@ let internal_msg: PointCloud2Msg = WriterXYZ::from(cloud_points.into_iter())
 // ... now incoming from a topic.
 // let internal_msg: PointCloud2Msg = msg.into();
 
-// Message -> Reader. The Reader implements the Iterator trait.
+// Message -> Reader -> your pipeline. The Reader implements the Iterator trait.
 let reader = ReaderXYZ::try_from(internal_msg).unwrap();
 let new_cloud_points = reader
   .map(|point: PointXYZ| {

src/convert.rs

@@ -8,10 +8,8 @@ pub enum FieldDatatype {
     I32,
     U8,
     U16,
-
     #[default]
     U32,
-
     I8,
     I16,
 }
@@ -135,7 +133,50 @@ pub(crate) fn check_coord(
 }
 
 /// Matching field names from each meta data per point to the PointField name.
-/// Always make sure to use the same order as in your Into<> implementation to have a correct mapping.
+/// Always make sure to use the same order as in your conversion implementation to have a correct mapping.
+///
+/// This trait is needed to implement the `PointConvertible` trait.
+///
+/// # Example for full point conversion.
+/// ```
+/// use ros_pointcloud2::{Point, PointConvertible, MetaNames, size_of};
+///
+/// #[derive(Clone, Debug, PartialEq, Copy)]
+/// pub struct MyPointXYZI {
+///     pub x: f32,
+///     pub y: f32,
+///     pub z: f32,
+///     pub intensity: f32,
+/// }
+///
+/// impl From<MyPointXYZI> for Point<f32, 3, 1> {
+///     fn from(point: MyPointXYZI) -> Self {
+///         Point {
+///             coords: [point.x, point.y, point.z],
+///             meta: [point.intensity.into()],
+///         }
+///     }
+/// }
+///
+/// impl From<Point<f32, 3, 1>> for MyPointXYZI {
+///     fn from(point: Point<f32, 3, 1>) -> Self {
+///         Self {
+///             x: point.coords[0],
+///             y: point.coords[1],
+///             z: point.coords[2],
+///             intensity: point.meta[0].get(),
+///         }
+///     }
+/// }
+///
+/// impl MetaNames<1> for MyPointXYZI {
+///    fn meta_names() -> [&'static str; 1] {
+///       ["intensity"]
+///   }
+/// }
+///
+/// impl PointConvertible<f32, {size_of!(f32)}, 3, 1> for MyPointXYZI {}
+/// ```
 pub trait MetaNames<const METADIM: usize> {
     fn meta_names() -> [&'static str; METADIM];
 }

src/lib.rs

@@ -1,6 +1,6 @@
 //! A library to work with the PointCloud2 message type from ROS.
 //!
-//! ros_pointcloud2 mainly provides iterator-based [`ros_pointcloud2::Reader`] and [`ros_pointcloud2::Writer`] to interact
+//! ros_pointcloud2 mainly provides iterator-based [`ros_pointcloud2::reader`] and [`ros_pointcloud2::writer`] to interact
 //! with the internal message type [`ros_pointcloud2::PointCloud2Msg`] without forcing an iteration.
 //!
 //! For ROS interoperability, the message type generated by the respective crate must be converted to
@@ -23,25 +23,15 @@
 //!
 //! // Your points (here using the predefined type PointXYZ).
 //! let cloud_points = vec![
-//!   PointXYZ {
-//!     x: 9.0006,
-//!     y: 42.0,
-//!     z: -6.2,
-//!   },
-//!
-//!   PointXYZ {
-//!     x: f32::MAX,
-//!     y: f32::MIN,
-//!     z: f32::MAX,
-//!   },
+//!   PointXYZ {x: 9.0006, y: 42.0, z: -6.2,},
+//!   PointXYZ {x: f32::MAX, y: f32::MIN,z: f32::MAX,},
 //! ];
 //!
 //! // For equality test later
 //! let cloud_copy = cloud_points.clone();
 //!
 //! // Vector -> Writer -> Message.
-//! // Vector -> Writer -> Message.
-//! // You can also just give the Vec or anything that implements `IntoIter`.
+//! // You can also just give the Vec or anything that implements `IntoIterator`.
 //! let internal_msg: PointCloud2Msg = WriterXYZ::from(cloud_points.into_iter())
 //!     .try_into() // iterating points here O(n)
 //!     .unwrap();
@@ -54,7 +44,7 @@
 //! // ... now incoming from a topic.
 //! // let internal_msg: PointCloud2Msg = msg.into();
 //!
-//! // Message -> Reader. The Reader implements the Iterator trait.
+//! // Message -> Reader -> your pipeline. The Reader implements the Iterator trait.
 //! let reader = ReaderXYZ::try_from(internal_msg).unwrap();
 //! let new_cloud_points = reader
 //!     .map(|point: PointXYZ| {
@@ -91,6 +81,7 @@ macro_rules! size_of {
 pub mod reader;
 pub mod writer;
 
+pub use convert::MetaNames;
 pub use ros_types::PointCloud2Msg;
 
 use crate::convert::*;
@@ -119,6 +110,42 @@ pub enum ConversionError {
     DataLengthMismatch,
 }
 
+/// Internal point representation. It is used to store the coordinates and meta data of a point.
+/// In each iteration, the Reader will convert the internal representation to the desired point type.
+/// Implement the `From` traits for your point type to use the conversion as part of the PointConvertible trait.
+///
+/// # Example
+/// ```
+/// use ros_pointcloud2::Point;
+///
+/// #[derive(Clone, Debug, PartialEq, Copy)]
+/// pub struct MyPointXYZI {
+///     pub x: f32,
+///     pub y: f32,
+///     pub z: f32,
+///     pub intensity: f32,
+/// }
+///
+/// impl From<MyPointXYZI> for Point<f32, 3, 1> {
+///     fn from(point: MyPointXYZI) -> Self {
+///         Point {
+///             coords: [point.x, point.y, point.z],
+///             meta: [point.intensity.into()],
+///         }
+///     }
+/// }
+///
+/// impl From<Point<f32, 3, 1>> for MyPointXYZI {
+///     fn from(point: Point<f32, 3, 1>) -> Self {
+///         Self {
+///             x: point.coords[0],
+///             y: point.coords[1],
+///             z: point.coords[2],
+///             intensity: point.meta[0].get(),
+///         }
+///     }
+/// }
+/// ```
 pub struct Point<T, const DIM: usize, const METADIM: usize> {
     pub coords: [T; DIM],
     pub meta: [PointMeta; METADIM],
@@ -155,7 +182,7 @@ pub struct PointMeta {
 impl Default for PointMeta {
     fn default() -> Self {
         Self {
-            bytes: [0; std::mem::size_of::<f64>()],
+            bytes: [u8::default(); std::mem::size_of::<f64>()],
             datatype: FieldDatatype::F32,
         }
     }

src/reader.rs

@@ -124,7 +124,7 @@ pub type ReaderXYZL = ReaderF32<3, 1, PointXYZL>;
 /// ## Example
 /// ```
 /// use ros_pointcloud2::{
-///     reader::Reader, writer::Writer, PointConvertible, Point, size_of, convert::MetaNames, PointMeta,
+///     reader::Reader, writer::Writer, PointConvertible, Point, size_of, MetaNames, PointMeta,
 /// };
 ///
 /// type Xyz = f32; // coordinate type

src/writer.rs

@@ -105,7 +105,7 @@ pub type WriterXYZL = WriterF32<3, 1, PointXYZL>;
 /// ## Example
 /// ```
 /// use ros_pointcloud2::{
-///     reader::Reader, writer::Writer, PointConvertible, Point, size_of, convert::MetaNames, PointMeta,
+///     reader::Reader, writer::Writer, PointConvertible, Point, size_of, MetaNames, PointMeta,
 /// };
 ///
 /// type Xyz = f32; // coordinate type

tests/e2e_test.rs

@@ -65,7 +65,7 @@ fn custom_xyz_f32() {
         }
     }
 
-    impl convert::MetaNames<METADIM> for CustomPoint {
+    impl MetaNames<METADIM> for CustomPoint {
         fn meta_names() -> [&'static str; METADIM] {
             []
         }
@@ -130,7 +130,7 @@ fn custom_xyzi_f32() {
         }
     }
 
-    impl convert::MetaNames<METADIM> for CustomPoint {
+    impl MetaNames<METADIM> for CustomPoint {
         fn meta_names() -> [&'static str; METADIM] {
             ["intensity"]
         }
@@ -215,7 +215,7 @@ fn custom_rgba_f32() {
         }
     }
 
-    impl convert::MetaNames<METADIM> for CustomPoint {
+    impl MetaNames<METADIM> for CustomPoint {
         fn meta_names() -> [&'static str; METADIM] {
             ["r", "g", "b", "a"]
         }
@@ -741,7 +741,7 @@ fn write_less_than_available() {
         }
     }
 
-    impl convert::MetaNames<METADIM> for CustomPoint {
+    impl MetaNames<METADIM> for CustomPoint {
         fn meta_names() -> [&'static str; METADIM] {
             []
         }