Struct BufferLayoutConverter 

pub struct BufferLayoutConverter<'a> { /* private fields */ }

A converter that can convert a point buffer from one PointLayout into another. This works by defining mappings between attributes from the source buffer and attributes in the target buffer. All mappings together define the way the source PointLayout transforms into the target PointLayout. Here is an example:

Source layout: [POSITION_3D(Vector3<i32>), CLASSIFICATION(u8), COLOR_RGB(Vector3<u16>)]
Target layout: [COLOR_RGB(Vector3<u8>), POSITION_3D(Vector3<f64>)]

Mappings:
POSITION_3D(Vector3<i32>) to POSITION_3D(Vector3<f64>)
COLOR_RGB(Vector3<u16>) to COLOR_RGB(Vector3<u8>)

This means that every position from the source buffer is converted into a position in the target buffer, with a type conversion from Vector3<i32> to Vector3<f64>, and every color from the source buffer is converted into a color in the target buffer, also with a type conversion from Vector3<u16> to Vector3<u8>. Type conversions follow the rules of the attribute converters as explained in get_converter_for_attributes.

Default mappings

By default, if BufferLayoutConverter::for_layouts is called, all attributes in the source layout are mapped to attributes in the target layout that have the same name. All other attributes are ignored. If the attributes have different datatypes, a default type converter is used. If there are attributes in the target layout that do not have a matching attribute in the source layout, this will raise an error, unless [BufferLayoutConverter::for_layouts_with_default] is called, in which case the target attribute(s) will be filled with default values.

Custom mappings

It is also possible to define custom mappings, which allow more flexibility than the default mappings. In particular:

• Multiple mappings may refer the same source attribute (but there can only be at most one mapping per target attribute)
• Custom mappings support attribute transformations using an arbitrary transformation function T -> T

Overriding existing mappings can be done by calling [set_custom_mapping] and [set_custom_mapping_with_transformation]. Here are some examples for what can be done with custom mappings:

• Extract bitfield attributes into multiple distinct attributes by creating multiple mappings from the bitfield attribute to the target attributes with different transformation functions that extract the relevant bits
• Offsetting and scaling values during transformation (such as going from local coordinates to world-space coordinates in an LAS file)

On performance

Buffer layout conversion works with buffers with arbitrary memory layouts, but since the mappings are defined per attribute, the best possible performance can be achieved if both the source and target buffer are in columnar memory layout.

Implementations

impl<'a> BufferLayoutConverter<'a>

pub fn for_layouts( from_layout: &'a PointLayout, to_layout: &'a PointLayout, ) -> Self

Creates a new BufferLayoutConverter from from_layout into to_layout. This generates default mappings for each attribute in to_layout following the rules of crate::layout::conversion::get_converter_for_attributes

Panics

If any PointAttributeMember in to_layout is not present (by name) in from_layout. If you want to allow missing attributes in from_layout and fill their values with default values, use Self::for_layouts_with_default instead!

pub fn for_layouts_with_default( from_layout: &'a PointLayout, to_layout: &'a PointLayout, ) -> Self

Like Self::for_layouts, but if an attribute from to_layout is not present in from_layout, the conversion still happens and will fill the target buffer with default values for this attribute instead!

pub fn set_custom_mapping( &mut self, from_attribute: &PointAttributeDefinition, to_attribute: &PointAttributeDefinition, )

Sets a custom mapping from from_attribute to to_attribute. This overrides the default mapping function for to_attribute. It allows mapping attributes with different names to each other and in particular allows the conversion to be surjective: Multiple attributes in to_attribute can be converted from the same attribute in from_attribute. An example where this is useful are bit-flag attributes, such as in the LAS file format, which semantically represent multiple attributes, but are represented as a single attribute in pasture.

Panics

If from_attribute is not part of the source PointLayout. If to_attribute is not part of the target PointLayout.

pub fn set_custom_mapping_with_transformation<T: PrimitiveType, F: Fn(T) -> T + 'static>( &mut self, from_attribute: &PointAttributeDefinition, to_attribute: &PointAttributeDefinition, transform_fn: F, apply_to_source_attribute: bool, )

Like Self::set_custom_mapping, but transforms the attribute value using the transform_fn. If apply_to_source_attribute is true, the transformation will be applied to the source attribute value prior to any potential conversion, otherwise it is applied after conversion

Panics

If from_attribute is not part of the source PointLayout. If to_attribute is not part of the target PointLayout. If T::data_type() does not match to_attribute.datatype().

pub fn convert<'b, 'c, 'd, OutBuffer: OwningBuffer<'c> + MakeBufferFromLayout<'c> + 'c, InBuffer: BorrowedBuffer<'b>>( &self, source_buffer: &'d InBuffer, ) -> OutBuffer

where 'b: 'd,

Convert the source_buffer into the target PointLayout and return its data as a new buffer of type OutBuffer

Panics

If source_buffer.point_layout() does not match the source PointLayout used to construct this BufferLayoutConverter

pub fn convert_into<'b, 'c, 'd, 'e>( &self, source_buffer: &'c impl BorrowedBuffer<'b>, target_buffer: &'e mut impl BorrowedMutBuffer<'d>, )

where 'b: 'c, 'd: 'e,

Like [convert], but converts into an existing buffer instead of allocating a new buffer

Panics

If source_buffer.point_layout() does not match the source PointLayout used to construct this BufferLayoutConverter If target_buffer.point_layout() does not match the target PointLayout used to construct this BufferLayoutConverter If target_buffer.len() is not equal to source_buffer.len()

pub fn convert_into_range<'b, 'c, 'd, 'e>( &self, source_buffer: &'c impl BorrowedBuffer<'b>, source_range: Range<usize>, target_buffer: &'e mut impl BorrowedMutBuffer<'d>, target_range: Range<usize>, )

where 'b: 'c, 'd: 'e,

Like [convert_into], but converts the points from source_range in source_buffer into the target_range in target_buffer

Panics

If source_buffer.point_layout() does not match the source PointLayout used to construct this BufferLayoutConverter If target_buffer.point_layout() does not match the target PointLayout used to construct this BufferLayoutConverter If target_buffer.len() is less than source_buffer.len()