[−][src]Crate rust_3d
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 viaFilterAND
,FilterOR
,FilterAny
,FilterNegate
... - Any
IsFilter<T>
can be transformed to work for any collection ofT
s (IsFilterRandomAccessible
). IsDirectionField2D
might 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
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 |
Matrix3Pipe | Matrix3Pipe, which makes it easier to pipe different matrices in a defined order |
Matrix4 | Matrix4, a matrix with 4 rows and columns |
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 |
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 Definitions
Result | Result type used by rust-3d |