[][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.

This example is not tested
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.

This example is not tested
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.

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

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 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 Definitions

Result

Result type used by rust-3d