Crate rust_3d

Expand description

§rust-3d

3D/2D library written in Rust. Offering useful containers, structures and algorithms for 2D and 3D space. Meant as basis for numeric algorithms, viewers, game engines, …

§Migration 0.29.0 -> 0.30.0

Note that the module structure changed. There’s now only submodules for io and impls.
Also prelude was removed.
If you were using the prelude via rust_3d::prelude::*; you should now be able to just switch to rust_3d::*;.
If you were using explicit paths such as rust_3d::filters::combinators::FilterAll you should now use rust_3d::FilterAll.
Note that io and impls are still part of the module path.
This should make future usage easier, but might be painful for existing users.

§Tour

Here’s a little overview of some of rust-3d’s features. The snippets / names might not be up-to-date, so please check tests/ for compiling examples.

§Proper error handling

No .unwrap() where it’s not 100% safe.

§Strong / Smart Types

There’s strong types for everything that might get mixed up easily.
This way e.g. ids of faces can’t be mistaken for ids of vertices.

fn edges_of_face(&self, faceid: FId) -> Result<(EId, EId, EId)>;

There’s also smart types which restrict the values they can hold.
This way distances can never be < 0.0, sizes can be enfored to be > 0.0 etc.

Positive  
NonNegative

§Generic Code Base

I try and keep all algorithms and types as generic as possible.

Even rather basic types like Is2D are split into several versions: IsEditable2D, IsBuildable2D
IsMesh is defined for any vertex type and any number of vertices / face
There’s traits for collections (no need to use Vec)

This makes it possible to require as little implementation work as possible if you want to use your own types.

§Combinators / Transformers

Any IsFilter<T> can be combined via FilterAND, FilterOR, FilterAny, FilterNegate…
Any IsFilter<T> can be transformed to work for any collection of Ts (IsFilterRandomAccessible).
IsDirectionField2D might be transformed to an IsFilter<Is2D>, which can then be transformed to an IsFilterRandomAccessible<Is2D>.

§IO

Any IO method is defined on traits, so if you implement these, you’ll get read/write of different file formats for free.

§Documentation

You can find the documentation here.

§Examples

Please take a look at the tests in tests/. These will be up-to-date and compiling.
I might add extensive tutorials / examples / demo projects in the future.

§Links

crates.io
github.com
docs.rs

§Contribute

Feel free to open an issue in case you’re missing something or found a bug. Please avoid directly contributing since I might be working on breaking changes or the feature you want to implement. Open an issue or email me beforehand.

§License

MIT (see LICENSE)

Modules§

boxx: rust-3d trait implementations for the standard Box
io: Containing IO functions / traits / types
linked_list: rust-3d trait implementations for the standard LinkedList
subdivide: Subdivision algorithms to e.g. refine meshes
test_helper: helper functions for testing (these functions unwrap and panic, only use for tests)
vec: rust-3d trait implementations for the standard Vec
vec_deque: rust-3d trait implementations for the standard VecDeque

Macros§

array_from_bytes_be
array_from_bytes_le

Structs§

BoundingBox2D: BoundingBox2D, an axis aligned bounding box within 2D space
BoundingBox3D: BoundingBox3D, an axis aligned bounding box within 3D space
Box2D: Box2D, a box in 2D space
Box3D: Box3D, a box in 3D space
BoxUnaligned3D: Not axis aligned Box in 3D space
Circle: Circle, a circle in 2D space
Cluster: Spatial clustering of data on the x/y plane
CompressedPoint3D: CompressedPoint3D
CompressedPointCloud3D: CompressedPointCloud3D
Deg
DynamicPrecisionIndexVec: DynamicPrecisionIndexVec is a memory efficient container with a usize interface. It uses u8 -> u16 -> u32 -> usize for storage depending on the largest index’s size
EId
FId
Face3: Face3, a face defined by 3 indices (e.g. used for Mesh)
FilterAND: FilterAND, a filter which combines two filters and is true if both of its filters are true
FilterAll: FilterAll, a filter to chain multiple filters with the and condition => must pass all filters to pass this filter
FilterAllRandomAccessible: FilterAllRandomAccessible, a filter to chain multiple IsFilterRandomAccessible with the and condition => must pass all filters to pass this filter
FilterAllow: FilterAllow, a filter which always returns true
FilterAny: FilterAny, a filter to chain multiple filters with the or condition => must pass any filter to pass this filter
FilterAnyRandomAccessible: FilterAnyRandomAccessible, a filter to chain multiple IsFilterRandomAccessible with the or condition => must pass any filter to pass this filter
FilterBox2D: FilterBox2D, a box filter within 2D space
FilterBox3D: FilterBox3D, a box filter within 3D space
FilterCircle: FilterCircle, a circle filter within 2D space
FilterDeny: FilterDeny, a filter which always returns false
FilterDirectionField2D: FilterDirectionField2D, a filter which can transform any IsDirectionField2D into a filter for (Is2D, IsNormalized2D)
FilterDirectionField3D: FilterDirectionField3D, a filter which can transform any IsDirectionField3D into a filter for (Is3D, IsNormalized3D)
FilterNegate: FilterNegate, a filter which negates another filter
FilterOR: FilterOR, a filter which combines two filters and is true if one of its filters is true
FilterOuterInner: FilterOuterInner, a filter which combines an inner and an outer filter. Where the inner is negated while the outer is allowed. This is useful to create hollow filter shapes
FilterOutlier3D: FilterOutlier3D, a filter which removes outliers by counting their neighbours in a search radius This can be used to compare two sets of points by removing those in A which aren’t close enough to B Or to remove outliers within a single set For this use the same input to build this filter as to filter against Points will find themselves, so increase the required count by 1
FilterRandomAccessible: FilterRandomAccessible, a filter which can transform any IsFilter into an IsFilterRandomAccessible
FilterSphere: FilterSphere, a sphere filter within 3D space
FilterXOR: FilterXOR, a filter which combines two filters and is true iff one of its filters is true
HalfEdge: HalfEdge, the half edge data structure
HasBoundingBox2DConverted: Wrapper helper to convert the Maybe type to the non-Maybe type
HasBoundingBox3DConverted: Wrapper helper to convert the Maybe type to the non-Maybe type
IsIndexContainerIterator: Iterator for IsIndexContainer
KdTree: KdTree https://en.wikipedia.org/wiki/K-d_tree
Line2D: Line2D, a line within 2D space
Line3D: Line3D, a line within 3D space
LineSegment2D: LineSegment2D, a line segment within 2D space
LineSegment3D: LineSegment3D, a line segment within 3D space
Matrix3: Matrix3, a matrix with 3 rows and columns
Matrix4: Matrix4, a matrix with 4 rows and columns
Matrix3Pipe: Matrix3Pipe, which makes it easier to pipe different matrices in a defined order
Matrix4Pipe: Matrix4Pipe, which makes it easier to pipe different matrices in a defined order
Mesh3D: Mesh3D, a mesh with tri-faces within 3D space
NonNegative: NonNegative, a wrapper for a f64 value, ensuring it is always >= 0
Norm2D: Norm2D, a normalized vector within 2D space
Norm3D: Norm3D, a normalized vector within 3D space
OcTree: OcTree https://en.wikipedia.org/wiki/Octree
Plane3D: Plane3D, a plane within 3D space
Point2D: Point2D, a point / position within 2D space
Point3D: Point3D, a point / position within 3D space
PointCloud2D: PointCloud2D, a collection of positions within 2D space
PointCloud3D: PointCloud3D, a collection of positions within 3D space
PointCloud3Df32: PointCloud3Df32, a collection of positions within 3D space stored lossy as f32 vector for easier usage during rendering
Polygon2D: Polygon2D, a polygon within 2D space
Polygon3D: Polygon3D, a polygon within 3D space
Positive: Positive, a wrapper for a f64 value, ensuring it is always > 0
Rad
Ray2D: Ray2D, a ray within 2D space
Ray3D: Ray3D, a ray within 3D space
Rgb: Rgb, a struct holding color information
SATCollider: Helper to check for collisions between IsSATObject
SId
SearchableMesh: SearchableMesh, transforms IsMesh to IsSearchableMesh
SkipEmpty: Iterator that skips empty elements
SkipEmptyString: Iterator that skips empty strings
Sphere: Sphere, a sphere in 3D space
TriFace3D: Face with 3 corners in 3D space
U32IndexVec: U32IndexVec is a u32 container with a usize interface (make sure your use case doesn’t go out of bounds)
VId

Enums§

AABBTree2D: AABBTree2D, an axis aligned bounding box tree in 2D for fast collision detection
AABBTree3D: AABBTree3D, an axis aligned bounding box tree in 3D for fast collision detection
Collider3D: Collider enumeration for 3D space
ErrorKind: The Error Enum used by rust-3d
Precision: Used to flag precision e.g. for IO operations (32 or 64 bit)
View: View, which defines a restricted / full view onto any T. E.g. used when filtering collections of points.

Traits§

HasBoundingBox2D: HasBoundingBox2D is a trait for types which have a bounding box
HasBoundingBox2DMaybe: HasBoundingBox2DMaybe is a trait for types which might have a bounding box
HasBoundingBox3D: HasBoundingBox3D is a trait for types which have a bounding box
HasBoundingBox3DMaybe: HasBoundingBox3DMaybe is a trait for types which might have a bounding box
HasCenterOfGravity2D: HasCenterOfGravity2D is a trait for types which might have a center of gravity
HasCenterOfGravity3D: HasCenterOfGravity3D is a trait for types which might have a center of gravity
HasColliders3D: Trait for types that have 3D colliders
HasDistanceTo: HasDistanceTo trait used for types which have a defined distance towards another T. Implementing HasDistanceTo for U also implements HasDistanceTo for T
HasLength: HasLength is a trait used for types which have a physical length
Is2D: Is2D is a trait used for types which are positioned within the 2D space
Is3D: Is3D is a trait used for types which are positioned within the 3D space
IsBox3DSearchable: IsBox3DSearchable trait used for search structures which can be queried for elements within a 3D box You should only implement this, if your solution is rather efficient
IsBuildable2D: IsBuildable2D is a trait used for types which are positioned in 2D space and can be constructed
IsBuildable3D: IsBuildable3D is a trait used for types which are positioned in 3D space and can be constructed
IsBuildableND: IsBuildableND is a trait used for types which are positioned in n-dimensional space and can be constructed
IsColliderContainer3D: Trait for containers with 3D colliders
IsDataContainer: IsDataContainer trait used for data containers allowing for different storage types than using the abstracted type
IsDirectionField2D: IsDirectionField2D is a trait used for fields of directions within 2D space
IsDirectionField3D: IsDirectionField3D is a trait used for fields of directions within 3D space
IsEditable2D: IsEditable2D is a trait used for types which are positioned in 2D space and their position can be changed
IsEditable3D: IsEditable3D is a trait used for types which are positioned in 3D space and their position can be changed
IsEditableND: IsEditableND is a trait used for types which are positioned in n-dimensional space and their position can be changed
IsEditablePolygon: IsEditablePolygon trait used for polygons which can be edited
IsFaceEditableMesh: IsFaceEditableMesh trait used for meshes with editable face data
IsFilter: IsFilter trait used for filters
IsFilterRandomAccessible: IsFilterRandomAccessible is a trait used for filters for random accessible collections
IsIndexContainer: IsIndexContainer trait for containers holding indices
IsKNearestSearchable: IsKNearestSearchable trait used for search structures which can be queried for nearest neighbours. You should only implement this, if your solution is rather efficient
IsMatrix3Transformable: IsMatrix3Transformable trait used for types that can be transformed by a 3x3 Matrix
IsMatrix4Transformable: IsMatrix4Transformable trait used for types that can be transformed by a 4x4 Matrix
IsMergeable: IsMergeable trait used for types which can be merged with their own type
IsMesh: IsMesh is trait used for meshes
IsMesh3D: IsMesh3D is trait used for meshes in 3D space
IsMovable2D: IsMovable2D is a trait used for types within 2D space which can be moved
IsMovable3D: IsMovable3D is a trait used for types within 3D space which can be moved
IsND: IsND is a trait used for types which are positioned within the n-dimensional space
IsNormalized2D: IsNormalized2D is a trait used for types which are positioned within the 2D space and normalized
IsNormalized3D: IsNormalized3D is a trait used for types which are positioned within the 3D space and normalized
IsOcTree: IsOcTree is a trait used for OcTrees
IsPlane3D: IsPlane3D is a trait used for planes within 3D space
IsPolygon: IsPolygon is a trait used for closed polygons
IsPushable: IsPushable trait used for collections of elements which can be pushed / appended to
IsRandomAccessible: IsRandomAccessible is a trait used for collections of elements which are random accessible
IsRandomInsertible: IsRandomInsertible is a trait used for collections of elements which are random insertible
IsSATObject: IsSATObject is a trait used for objects that can be used for SAT collision checks
IsScalable: IsScalable trait used for types that can have their size scaled by a factor
IsSearchableMesh: IsSearchableMesh trait used for meshes which have extended search methods
IsSkipEmptyProducer: Utility trait to easily spawn the SkipEmpty iterator
IsSkipEmptyStringProducer: Utility trait to easily spawn the SkipEmptyString iterator
IsSortable2D: IsSortable2D trait used for collections which can be sorted by x or y
IsSortable3D: IsSortable3D trait used for collections which can be sorted by x,y or z
IsSortableND: IsSortableND trait used for collections which can be sorted by certain dimensions. E.g. x,y,z
IsSphereSearchable: IsSphereSearchable trait used for search structures which can be queried for elements within a sphere You should only implement this, if your solution is rather efficient
IsTopologyUnit: IsTopologyUnit trait used for single units of a topology. E.g. size 1 for paths, size 3 for tri meshes, size 4 for quad meshes
IsTransFormableTo2D: IsTransFormableTo2D is a trait used for any type which can be transformed 2D space
IsTransFormableTo3D: IsTransFormableTo3D is a trait used for any type which can be transformed 3D space
IsTree3D: IsTree3D is a trait used for types which are any type of tree within 3D space
IsVertexEditableMesh: IsVertexEditableMesh trait used for meshes with editable vertex data
IsViewBuildable: IsViewBuildable trait used for types which can be constructed from a view / have a view applied to them
IsVoxelImage: IsVoxelImage is a trait used for any type of voxel image

Functions§

add: Adds two Is3D values
arc: Creates an arc with the given center, diameter, resolution and start and end angles in radians
center: Positions the object in such a way that its center is at origin
center_2d: Returns the center of two IsBuildable2D
center_3d: Returns the center of two IsBuildable3D
closest_intersecting: Returns the closest intersection with the ray
closest_intersecting_mut: Returns the closest intersection with the ray
cluster_vertices: Algorithm to cluster nearby vertices within a mesh
collect_intersections_ray_mesh: Collects all intersections between a ray and mesh
conn: Calculates the vector between two positions
contains: Checks whether haystack contains needle
convex_hull_2d: Convex hull algorithm returning a Vec of the hull where the points are ordered according to the hull Using Andrew’s monotone chain convex hull algorithm https://en.wikibooks.org/wiki/Algorithm_Implementation/Geometry/Convex_hull/Monotone_chain
cross: Returns the cross product between a Is3D and a IsBuildable3D
dimension_compare: Compares two IsBuildable3D at a given dimensions
dimension_dist: Calculates the distance within a given dimension between two IsBuildable3D
dist_2d: Returns the distance between two Is2D
dist_3d: Returns the distance between two Is3D
dist_nd: Returns the distance between two IsND in case their number of dimensions match
douglas_peucker_2d: Douglas Peucker algorithm for 2D https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm
ellipse: Creates an ellipse with the given center, a, b and resolution
estimate_delimiter: Estimates the used delimiter within a string
extrude: Extrudes a 2D point cloud into 3D space with a given center and direction
for_each_intersecting: Applies the function to each intersection candidate
hash_f64: Generates the hash of an f64
heal_mesh: Algorithm to remove duplicate and degenerate faces from a mesh
index_closest_intersecting: Returns the index of the closest intersection with the ray
interpolate_bezier: Returns the Bezier interpolation of the given base points
interpolate_cosine: Returns the Cosine interpolation of the given base points
interpolation_linear: Returns the linear interpolation of the given base points
intersection: The intersection between a line and BoundingBox if there is any
intersection_ray_triangle: Finds the intersection between a ray and triangle
involut_circle: Creates a involut circle with the given center, diameter, resolution and start and end angles in radians
max64: Maximum of two f64 values
max_f64: Max of two f64 values
max_f64_3: Max of three f64 values
min64: Minimum of two f64 values
normal_of_face: Calculates the normal of a face given by three vertices
normals_of_mesh: Calculates the normals of a mesh
pack_dupes_indexed: Returns a container with duplicates removed and indices representing the original order
project_point_on_plane: Projects a point onto a plane
rectangle: Creates a 2D rectangle from given center width and height
set_size: Scales the object to the required size
sort_vec_2d_x: Helper function to sort a Vec of Is2D by x
sort_vec_2d_y: Helper function to sort a Vec of Is2D by y
sort_vec_3d_x: Helper function to sort a Vec of Is3D by x
sort_vec_3d_y: Helper function to sort a Vec of Is3D by y
sort_vec_3d_z: Helper function to sort a Vec of Is3D by z
sqr_dist_2d: Returns the squared distance between two Is2D
sqr_dist_3d: Returns the squared distance between two Is3D
sqr_dist_nd: Returns the squared distance between two IsND in case their number of dimensions match
to_words_skip_empty: Splits an ASCII line into its words, skipping empty elements
unify_faces: Algorithm to unifiy the face orientation within a mesh
until: Returns all until delimiter
until_bytes: Returns all until delimiter

Type Aliases§

Result: Result type used by rust-3d

Crate rust_3dCopy item path