Struct Voxels

pub struct Voxels { /* private fields */ }

A shape made of axis-aligned, uniformly sized, cubes (aka. voxels).

This shape is specialized to handle voxel worlds and voxelized obojects efficiently why ensuring that collision-detection isn’t affected by the so-called “internal edges problem” that can create artifacts when another objects rolls or slides against a flat voxelized surface.

The internal storage is compact (but not sparse at the moment), storing only one byte per voxel in the allowed domain. This has a generally smaller memory footprint than a mesh representation of the voxels.

Implementations

impl Voxels

pub fn aabb(&self, pos: &Isometry<f32>) -> Aabb

Computes the world-space Aabb of this set of voxels, transformed by pos.

pub fn local_aabb(&self) -> Aabb

Computes the local-space Aabb of this set of voxels.

impl Voxels

pub fn bounding_sphere(&self, pos: &Isometry<f32>) -> BoundingSphere

Computes the world-space bounding sphere of this set of voxels, transformed by pos.

pub fn local_bounding_sphere(&self) -> BoundingSphere

Computes the local-space bounding sphere of this set of voxels.

impl Voxels

pub fn new( primitive_geometry: VoxelPrimitiveGeometry, voxel_size: Vector<f32>, grid_coordinates: &[Point<i32>], ) -> Self

Initializes a voxel shapes from the voxels grid coordinates.

Each voxel will have its bottom-left-back corner located at grid_coordinates * voxel_size; and its center at (grid_coordinates + 0.5) * voxel_size.

pub fn from_points( primitive_geometry: VoxelPrimitiveGeometry, voxel_size: Vector<f32>, points: &[Point<f32>], ) -> Self

Computes a voxels shape from the set of points.

The points are mapped to a regular grid centered at the provided point with smallest coordinates, and with grid cell size equal to scale. It is OK if multiple points fall into the same grid cell.

pub fn total_memory_size(&self) -> usize

An approximation of the memory usage (in bytes) for this struct plus the memory it allocates dynamically.

pub fn heap_memory_size(&self) -> usize

An approximation of the memory dynamically-allocated by this struct.

pub fn extents(&self) -> Vector<f32>

The extents of the total axis-aligned volume covered by this Voxels shape.

This accounts for all the voxels reserved in the internal buffer of self, including empty ones.

pub fn domain_center(&self) -> Point<f32>

The center of this shape’s domain (accounting for both empty and filled voxels).

pub fn set_voxel_size(&mut self, size: Vector<f32>)

Sets the size of each voxel along each local coordinate axis.

If Self::primitive_geometry is VoxelPrimitiveGeometry::PseudoBall, then all voxels must be square, and only size.x is taken into account for setting the size.

pub fn domain(&self) -> [&Point<i32>; 2]

The valid semi-open range of voxel grid indices.

With let [mins, maxs] = voxels.domain(); the valid indices along the dimension i are all the indices in the range mins[i]..maxs[i] (i.e. maxs[i] is excluded).

pub fn dimensions(&self) -> Vector<u32>

The number of voxels along each coordinate axis.

pub fn voxel_size(&self) -> Vector<f32>

The size of each voxel part this Voxels shape.

pub fn primitive_geometry(&self) -> VoxelPrimitiveGeometry

The shape each voxel is assumed to have.

pub fn scaled(self, scale: &Vector<f32>) -> Option<Self>

Scale this shape.

pub fn try_set_voxel( &mut self, key: Point<i32>, is_filled: bool, ) -> Option<VoxelState>

Sets the voxel at the given grid coordinates, returning None if it lies outside Self::domain.

See Self::set_voxel for a method that automatically resizes the internal storage of self if the key is out of the valid bounds.

pub fn set_voxel( &mut self, key: Point<i32>, is_filled: bool, ) -> Option<VoxelState>

Inserts a voxel at the given key, even if it is out of the bounds of this shape.

If is_filed is true and the key lies out of the bounds on this shape, the internal voxels storage will be resized automatically. If a resize happens, the cost of the insertion is O(n) where n is the capacity of self. If no resize happens, then the cost of insertion is O(1).

Use Self::try_set_voxel instead for a version that will be a no-op if the provided coordinates are outside the Self::domain, avoiding potential internal reallocations.

pub fn resize_domain( &mut self, domain_mins: Point<i32>, domain_maxs: Point<i32>, )

Set the model domain.

The domain can be smaller or larger than the current one. Voxels in any overlap between the current and new domain will be preserved.

If for any index i, domain_maxs[i] <= domain_mins[i], then the new domain is invalid and this operation will result in a no-op.

pub fn with_resized_domain( &self, domain_mins: Point<i32>, domain_maxs: Point<i32>, ) -> Option<Self>

Clone this voxels shape with a new size.

The domain can be smaller or larger than the current one. Voxels in any overlap between the current and new domain will be preserved.

If for any index i, domain_maxs[i] <= domain_mins[i], then the new domain is invalid and this operation returns None.

pub fn is_voxel_in_bounds(&self, key: Point<i32>) -> bool

Checks if the given key is within Self::domain.

pub fn voxel_aabb(&self, key: Point<i32>) -> Aabb

The AABB of the voxel with the given quantized key.

pub fn voxel_state(&self, key: Point<i32>) -> VoxelState

Returns the state of a given voxel.

Panics if the key is out of the bounds defined by Self::domain.

pub fn voxel_at_point_unchecked(&self, point: Point<f32>) -> Point<i32>

Calculates the grid coordinates of the voxel containing the given point, regardless of Self::domain.

pub fn voxel_at_point(&self, pt: Point<f32>) -> Option<Point<i32>>

Gets the key of the voxel containing the given pt.

Note that the returned key might address a voxel that is empty. None is returned if the point is out of the domain of self.

pub fn clamp_voxel(&self, key: Point<i32>) -> Point<i32>

Clamps an arbitrary voxel into the valid domain of self.

pub fn voxel_range_intersecting_local_aabb( &self, aabb: &Aabb, ) -> [Point<i32>; 2]

The range of grid coordinates of voxels intersecting the given AABB.

The returned range covers both empty and non-empty voxels, and is not limited to the bounds defined by Self::domain. The range is semi, open, i.e., the range along each dimension i is understood as the semi-open interval: range[0][i]..range[1][i].

pub fn voxel_range_aabb(&self, mins: Point<i32>, maxs: Point<i32>) -> Aabb

The AABB of a given range of voxels.

The AABB is computed independently of Self::domain and independently of whether the voxels contained within are empty or not.

pub fn align_aabb_to_grid(&self, aabb: &Aabb) -> Aabb

Aligns the given AABB with the voxelized grid.

The aligned is calculated such that the returned AABB has corners lying at the grid intersections (i.e. matches voxel corners) and fully contains the input aabb.

pub fn voxels_intersecting_local_aabb( &self, aabb: &Aabb, ) -> impl Iterator<Item = VoxelData> + '_

Iterates through every voxel intersecting the given aabb.

Returns the voxel’s linearized id, center, and state.

pub fn voxels(&self) -> impl Iterator<Item = VoxelData> + '_

The center point of all the voxels in this shape (including empty ones).

The voxel data associated to each center is provided to determine what kind of voxel it is (and, in particular, if it is empty or full).

pub fn split_with_box(&self, aabb: &Aabb) -> (Option<Self>, Option<Self>)

Splits this voxels shape into two subshapes.

The first subshape contains all the voxels which centers are inside the aabb. The second subshape contains all the remaining voxels.

pub fn voxels_in_range( &self, mins: Point<i32>, maxs: Point<i32>, ) -> impl Iterator<Item = VoxelData> + '_

Iterate through the data of all the voxels within the given (semi-open) voxel grid indices.

Note that this yields both empty and non-empty voxels within the range. This does not include any voxel that falls outside Self::domain.

pub fn linear_index(&self, voxel_key: Point<i32>) -> u32

The linearized index associated to the given voxel key.

pub fn voxel_at_id(&self, linear_index: u32) -> Point<i32>

The key of the voxel at the given linearized index.

pub fn voxel_center(&self, key: Point<i32>) -> Point<f32>

The center of the voxel with the given key.

impl Voxels

pub fn to_outline(&self) -> (Vec<Point<f32>>, Vec<[u32; 2]>)

Outlines this voxels shape as a set of polylines.

The outline is such that only convex edges are output in the polyline.

pub fn iter_outline(&self, f: impl FnMut(Point<f32>, Point<f32>))

Outlines this voxels shape using segments.

The outline is such that only convex edges are output in the polyline.

impl Voxels

pub fn to_trimesh(&self) -> (Vec<Point<f32>>, Vec<[u32; 3]>)

Computes an unoptimized mesh representation of this shape.

Each free face of each voxel will result in two triangles. No effort is made to merge adjacent triangles on large flat areas.

Trait Implementations

impl Clone for Voxels

fn clone(&self) -> Voxels

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Voxels

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

Formats the value using the given formatter.

impl PointQuery for Voxels

fn project_local_point(&self, pt: &Point<f32>, solid: bool) -> PointProjection

Projects a point on self.

fn project_local_point_and_get_feature( &self, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self and returns the id of the feature the point was projected on.

fn project_local_point_with_max_dist( &self, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point on self, unless the projection lies further than the given max distance.

fn project_point_with_max_dist( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point on self transformed by m, unless the projection lies further than the given max distance.

fn distance_to_local_point(&self, pt: &Point<f32>, solid: bool) -> f32

Computes the minimal distance between a point and self.

fn contains_local_point(&self, pt: &Point<f32>) -> bool

Tests if the given point is inside of self.

fn project_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> PointProjection

Projects a point on self transformed by m.

fn distance_to_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> f32

Computes the minimal distance between a point and self transformed by m.

fn project_point_and_get_feature( &self, m: &Isometry<f32>, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self transformed by m and returns the id of the feature the point was projected on.

fn contains_point(&self, m: &Isometry<f32>, pt: &Point<f32>) -> bool

Tests if the given point is inside of self transformed by m.

impl RayCast for Voxels

fn cast_local_ray_and_get_normal( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn cast_local_ray( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn intersects_local_ray(&self, ray: &Ray, max_time_of_impact: f32) -> bool

Tests whether a ray intersects this transformed shape.

fn cast_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn cast_ray_and_get_normal( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn intersects_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, ) -> bool

Tests whether a ray intersects this transformed shape.

impl Shape for Voxels

fn compute_local_aabb(&self) -> Aabb

Computes the Aabb of this shape.

fn compute_local_bounding_sphere(&self) -> BoundingSphere

Computes the bounding-sphere of this shape.

fn clone_dyn(&self) -> Box<dyn Shape>

Clones this shape into a boxed trait-object.

fn scale_dyn( &self, _scale: &Vector<f32>, _num_subdivisions: u32, ) -> Option<Box<dyn Shape>>

Scales this shape by scale into a boxed trait-object.

fn mass_properties(&self, _density: f32) -> MassProperties

Compute the mass-properties of this shape given its uniform density.

fn shape_type(&self) -> ShapeType

Gets the type tag of this shape.

fn as_typed_shape(&self) -> TypedShape<'_>

Gets the underlying shape as an enum.

fn ccd_thickness(&self) -> f32

fn ccd_angular_thickness(&self) -> f32

fn clone_box(&self) -> Box<dyn Shape>

👎Deprecated: renamed to clone_dyn

Clones this shape into a boxed trait-object.

fn compute_aabb(&self, position: &Isometry<f32>) -> Aabb

Computes the Aabb of this shape with the given position.

fn compute_bounding_sphere(&self, position: &Isometry<f32>) -> BoundingSphere

Computes the bounding-sphere of this shape with the given position.

fn is_convex(&self) -> bool

Is this shape known to be convex?

fn as_support_map(&self) -> Option<&dyn SupportMap>

Converts this shape into its support mapping, if it has one.

fn as_composite_shape(&self) -> Option<&dyn SimdCompositeShape>

fn as_polygonal_feature_map(&self) -> Option<(&dyn PolygonalFeatureMap, f32)>

Converts this shape to a polygonal feature-map, if it is one.

fn feature_normal_at_point( &self, _feature: FeatureId, _point: &Point<f32>, ) -> Option<Unit<Vector<f32>>>

The shape’s normal at the given point located on a specific feature.

fn compute_swept_aabb( &self, start_pos: &Isometry<f32>, end_pos: &Isometry<f32>, ) -> Aabb

Computes the swept Aabb of this shape, i.e., the space it would occupy by moving from the given start position to the given end position.