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, ...

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 (see /src/traits).

• 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

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

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

LGPL (see LICENSE)

Modules

algorithms	Containing algorithms
distances_2d	Distances between objects in 2D space
distances_3d	Distances between objects in 3D space
distances_nd	Distances between objects in ND space
factory_2d	functions used for the creation of 2D shapes and geometries
filters	Containing filters
functions	utility functions
impls	rust-3d trait implementations for standard containers / structs
interpolation_2d	interpolations within 2D space. E.g. bezier, linear, cosine
io	Containing IO functions / traits / types
prelude	Exporting often used types / traits for convenience
strong_types	Containing strong type definitions for safer usage
test_helper	helper functions for testing (these functions unwrap and panic, only use for tests)
traits	Containing traits used by rust-3d

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
Circle	Circle, a circle in 2D space
CompressedPoint3D	CompressedPoint3D
CompressedPointCloud3D	CompressedPointCloud3D
Face3	Face3, a face defined by 3 indices (e.g. used for Mesh)
HalfEdge	HalfEdge, the half edge data structure
KdTree	KdTree https://en.wikipedia.org/wiki/K-d_tree
Line2D	Line2D, a line within 2D space
Line3D	Line2D, 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
Positive	Positive, a wrapper for a f64 value, ensuring it is always > 0
Ray2D	Ray2D, a ray within 2D space
Ray3D	Ray3D, a ray within 3D space
SearchableMesh	SearchableMesh, transforms IsMesh to IsSearchableMesh
Sphere	Sphere, a sphere in 3D space

Enums

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.

Type Definitions

Result

Result type used by rust-3d