[−][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.
Sorry :(
Notes
rust-3d
is still in really early stages, there might come breaking changes with each update.
The test coverage is far from perfect, so you might find some bugs (please report them).
Compiling with stable
.
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
The documentation is quite good already, come and take a look.
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 |
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 |
IsProjectionToPlane | IsProjectionToPlane is a trait used types which can be projected onto and from planes within 3D space |
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 |