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
Is2Dare split into several versions:IsEditable2D,IsBuildable2D IsMeshis 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 viaFilterAND,FilterOR,FilterAny,FilterNegate… - Any
IsFilter<T>can be transformed to work for any collection ofTs (IsFilterRandomAccessible). IsDirectionField2Dmight be transformed to anIsFilter<Is2D>, which can then be transformed to anIsFilterRandomAccessible<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
§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§
- rust-3d trait implementations for the standard Box
- Containing IO functions / traits / types
- rust-3d trait implementations for the standard LinkedList
- Subdivision algorithms to e.g. refine meshes
- helper functions for testing (these functions unwrap and panic, only use for tests)
- rust-3d trait implementations for the standard Vec
- rust-3d trait implementations for the standard VecDeque
Macros§
Structs§
- BoundingBox2D, an axis aligned bounding box within 2D space
- BoundingBox3D, an axis aligned bounding box within 3D space
- Box2D, a box in 2D space
- Box3D, a box in 3D space
- Not axis aligned Box in 3D space
- Circle, a circle in 2D space
- Spatial clustering of data on the x/y plane
- CompressedPoint3D
- CompressedPointCloud3D
- 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
- Face3, a face defined by 3 indices (e.g. used for Mesh)
- FilterAND, a filter which combines two filters and is true if both of its filters are true
- FilterAll, a filter to chain multiple filters with the and condition => must pass all filters to pass this filter
- FilterAllRandomAccessible, a filter to chain multiple IsFilterRandomAccessible with the and condition => must pass all filters to pass this filter
- FilterAllow, a filter which always returns true
- FilterAny, a filter to chain multiple filters with the or condition => must pass any filter to pass this filter
- FilterAnyRandomAccessible, a filter to chain multiple IsFilterRandomAccessible with the or condition => must pass any filter to pass this filter
- FilterBox2D, a box filter within 2D space
- FilterBox3D, a box filter within 3D space
- FilterCircle, a circle filter within 2D space
- FilterDeny, a filter which always returns false
- FilterDirectionField2D, a filter which can transform any IsDirectionField2D into a filter for (Is2D, IsNormalized2D)
- FilterDirectionField3D, a filter which can transform any IsDirectionField3D into a filter for (Is3D, IsNormalized3D)
- FilterNegate, a filter which negates another filter
- FilterOR, a filter which combines two filters and is true if one of its filters is true
- 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, 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, a filter which can transform any IsFilter into an IsFilterRandomAccessible
- FilterSphere, a sphere filter within 3D space
- FilterXOR, a filter which combines two filters and is true iff one of its filters is true
- HalfEdge, the half edge data structure
- Wrapper helper to convert the Maybe type to the non-Maybe type
- Wrapper helper to convert the Maybe type to the non-Maybe type
- Iterator for IsIndexContainer
- KdTree https://en.wikipedia.org/wiki/K-d_tree
- Line2D, a line within 2D space
- Line3D, a line within 3D space
- LineSegment2D, a line segment within 2D space
- LineSegment3D, a line segment within 3D space
- Matrix3, a matrix with 3 rows and columns
- Matrix4, a matrix with 4 rows and columns
- Matrix3Pipe, which makes it easier to pipe different matrices in a defined order
- Matrix4Pipe, which makes it easier to pipe different matrices in a defined order
- Mesh3D, a mesh with tri-faces within 3D space
- NonNegative, a wrapper for a f64 value, ensuring it is always >= 0
- Norm2D, a normalized vector within 2D space
- Norm3D, a normalized vector within 3D space
- OcTree https://en.wikipedia.org/wiki/Octree
- Plane3D, a plane within 3D space
- Point2D, a point / position within 2D space
- Point3D, a point / position within 3D space
- PointCloud2D, a collection of positions within 2D space
- PointCloud3D, a collection of positions within 3D space
- PointCloud3Df32, a collection of positions within 3D space stored lossy as f32 vector for easier usage during rendering
- Polygon2D, a polygon within 2D space
- Polygon3D, a polygon within 3D space
- Positive, a wrapper for a f64 value, ensuring it is always > 0
- Ray2D, a ray within 2D space
- Ray3D, a ray within 3D space
- Rgb, a struct holding color information
- Helper to check for collisions between IsSATObject
- SearchableMesh, transforms IsMesh to IsSearchableMesh
- Iterator that skips empty elements
- Iterator that skips empty strings
- Sphere, a sphere in 3D space
- Face with 3 corners in 3D space
- U32IndexVec is a u32 container with a usize interface (make sure your use case doesn’t go out of bounds)
Enums§
- AABBTree2D, an axis aligned bounding box tree in 2D for fast collision detection
- AABBTree3D, an axis aligned bounding box tree in 3D for fast collision detection
- Collider enumeration for 3D space
- The Error Enum used by rust-3d
- Used to flag precision e.g. for IO operations (32 or 64 bit)
- View, which defines a restricted / full view onto any T. E.g. used when filtering collections of points.
Traits§
- HasBoundingBox2D is a trait for types which have a bounding box
- HasBoundingBox2DMaybe is a trait for types which might have a bounding box
- HasBoundingBox3D is a trait for types which have a bounding box
- HasBoundingBox3DMaybe is a trait for types which might have a bounding box
- HasCenterOfGravity2D is a trait for types which might have a center of gravity
- HasCenterOfGravity3D is a trait for types which might have a center of gravity
- Trait for types that have 3D colliders
- HasDistanceTo trait used for types which have a defined distance towards another T. Implementing HasDistanceTo
for U also implements HasDistanceTo for T - HasLength is a trait used for types which have a physical length
- Is2D is a trait used for types which are positioned within the 2D space
- Is3D is a trait used for types which are positioned within the 3D space
- 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 is a trait used for types which are positioned in 2D space and can be constructed
- IsBuildable3D is a trait used for types which are positioned in 3D space and can be constructed
- IsBuildableND is a trait used for types which are positioned in n-dimensional space and can be constructed
- Trait for containers with 3D colliders
- IsDataContainer trait used for data containers allowing for different storage types than using the abstracted type
- IsDirectionField2D is a trait used for fields of directions within 2D space
- IsDirectionField3D is a trait used for fields of directions within 3D space
- IsEditable2D is a trait used for types which are positioned in 2D space and their position can be changed
- IsEditable3D is a trait used for types which are positioned in 3D space and their position can be changed
- IsEditableND is a trait used for types which are positioned in n-dimensional space and their position can be changed
- IsEditablePolygon trait used for polygons which can be edited
- IsFaceEditableMesh trait used for meshes with editable face data
- IsFilter trait used for filters
- IsFilterRandomAccessible is a trait used for filters for random accessible collections
- IsIndexContainer trait for containers holding indices
- 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 trait used for types that can be transformed by a 3x3 Matrix
- IsMatrix4Transformable trait used for types that can be transformed by a 4x4 Matrix
- IsMergeable trait used for types which can be merged with their own type
- IsMesh is trait used for meshes
- IsMesh3D is trait used for meshes in 3D space
- IsMovable2D is a trait used for types within 2D space which can be moved
- IsMovable3D is a trait used for types within 3D space which can be moved
- IsND is a trait used for types which are positioned within the n-dimensional space
- IsNormalized2D is a trait used for types which are positioned within the 2D space and normalized
- IsNormalized3D is a trait used for types which are positioned within the 3D space and normalized
- IsOcTree is a trait used for OcTrees
- IsPlane3D is a trait used for planes within 3D space
- IsPolygon is a trait used for closed polygons
- IsPushable trait used for collections of elements which can be pushed / appended to
- IsRandomAccessible is a trait used for collections of elements which are random accessible
- IsRandomInsertible is a trait used for collections of elements which are random insertible
- IsSATObject is a trait used for objects that can be used for SAT collision checks
- IsScalable trait used for types that can have their size scaled by a factor
- IsSearchableMesh trait used for meshes which have extended search methods
- Utility trait to easily spawn the SkipEmpty iterator
- Utility trait to easily spawn the SkipEmptyString iterator
- IsSortable2D trait used for collections which can be sorted by x or y
- IsSortable3D trait used for collections which can be sorted by x,y or z
- IsSortableND trait used for collections which can be sorted by certain dimensions. E.g. x,y,z
- 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 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 is a trait used for any type which can be transformed 2D space
- IsTransFormableTo3D is a trait used for any type which can be transformed 3D space
- IsTree3D is a trait used for types which are any type of tree within 3D space
- IsVertexEditableMesh trait used for meshes with editable vertex data
- IsViewBuildable trait used for types which can be constructed from a view / have a view applied to them
- IsVoxelImage is a trait used for any type of voxel image
Functions§
- Adds two Is3D values
- Creates an arc with the given center, diameter, resolution and start and end angles in radians
- Positions the object in such a way that its center is at origin
- Returns the center of two IsBuildable2D
- Returns the center of two IsBuildable3D
- Returns the closest intersection with the ray
- Returns the closest intersection with the ray
- Algorithm to cluster nearby vertices within a mesh
- Collects all intersections between a ray and mesh
- Calculates the vector between two positions
- Checks whether haystack contains needle
- 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
- Returns the cross product between a Is3D and a IsBuildable3D
- Compares two IsBuildable3D at a given dimensions
- Calculates the distance within a given dimension between two IsBuildable3D
- Returns the distance between two Is2D
- Returns the distance between two Is3D
- Returns the distance between two IsND in case their number of dimensions match
- Douglas Peucker algorithm for 2D https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm
- Creates an ellipse with the given center, a, b and resolution
- Estimates the used delimiter within a string
- Extrudes a 2D point cloud into 3D space with a given center and direction
- Applies the function to each intersection candidate
- Generates the hash of an f64
- Algorithm to remove duplicate and degenerate faces from a mesh
- Returns the index of the closest intersection with the ray
- Returns the Bezier interpolation of the given base points
- Returns the Cosine interpolation of the given base points
- Returns the linear interpolation of the given base points
- The intersection between a line and BoundingBox if there is any
- Finds the intersection between a ray and triangle
- Creates a involut circle with the given center, diameter, resolution and start and end angles in radians
- Maximum of two f64 values
- Max of two f64 values
- Max of three f64 values
- Minimum of two f64 values
- Calculates the normal of a face given by three vertices
- Calculates the normals of a mesh
- Returns a container with duplicates removed and indices representing the original order
- Projects a point onto a plane
- Creates a 2D rectangle from given center width and height
- Scales the object to the required size
- Helper function to sort a Vec of Is2D by x
- Helper function to sort a Vec of Is2D by y
- Helper function to sort a Vec of Is3D by x
- Helper function to sort a Vec of Is3D by y
- Helper function to sort a Vec of Is3D by z
- Returns the squared distance between two Is2D
- Returns the squared distance between two Is3D
- Returns the squared distance between two IsND in case their number of dimensions match
- Splits an ASCII line into its words, skipping empty elements
- Algorithm to unifiy the face orientation within a mesh
- Returns all until delimiter
- Returns all until delimiter
Type Aliases§
- Result type used by rust-3d