 This is Crater, the official mascot of `crater.rs`! > âš ï¸ **WARNING** âš ï¸ > > `crater.rs` is still in early development. Until version `1.0.0`, consider the public API mutable! I appreciate your patience as `crater.rs` matures 😅 # Purpose `crater.rs` is a library for `N-D` geometric modeling and analysis. It is distributed in both library and binary form to suit your needs. ## Features - `N-D` [Constructive Solid Geometry (CSG)](https://en.wikipedia.org/wiki/Constructive_solid_geometry): - Define your geometry entirely in terms of an `N`-variant closure, `f(x1, x2, ..., xN) <= 0`. - Compose primitive closures together using differentiable, set-theoretic operations (e.g., `f1(x1, x2, ..., xN) <= 0 OR f2(x1, x2, ..., xN) <= 0`) - Arbitrarily transform regions through covariant operations on the `N-D` basis (e.g., `f(x1, x2, ..., xN) -> f(g_1(x1), g_2(x2), ... g_N(xN))` for some transformation `g_i(xi)`). - For `N=3`: - Interact with `crater.rs`'s `MeshCollection` and `TriangleMesh` types. Use this to export to common rendering formats (e.g., `.stl`, `.vtk`) - Invoke the (parallelized) [Marching Cubes](https://en.wikipedia.org/wiki/Marching_cubes) algorithm to convert CSGs to triangular meshes - `N-D` Region analysis: - Surface normals, gradients, curvature, etc. - Closed and open region volume calculations - Refer to the [`examples`](https://gitlab.com/games1122013/crater.rs/-/tree/main/examples?ref_type=heads) for various implemented use cases of `crater.rs` ## Coming soon! - CSG reconstruction from point-cloud geometry representations (i.e., the inverse of Marching Cubes - see [3]) - Serialization to other common geometry filetypes (e.g., `.obj`, `.3ds`) - Formal support for `N=2` serialization (i.e., drawing simple plots) # Quick Start ## As a command-line binary ### Install ``` > cargo install crater-rs ... Installs `crater` binary ``` Verify installation ``` > crater --version ... whatever the current version is ... ``` ### Marching Cubes At time of writing, the Marching Cubes algorithm is `crater`'s only command-line feature. It takes a `.yml` input file and emits `.stl` files. (For a few example input files, see [`crater_examples`](https://gitlab.com/games1122013/crater.rs/-/tree/main/crater_examples?ref_type=heads)). Here's a simple input ```yaml region: "-[(x^2 + y^2 + z^2 + 2.0^2 - 1.0^2)^2 - 4 * 2.0^2 * (x^2 + y^2)]" # A z-oriented torus bounds: [[-5, -5, -5], [5, 5, 5]] # Render from [-5, 5] in each of the 3 dimensions resolution: [50, 50, 50] # Evaluate 50 cubes in each of the 3 dimensions ``` ``` > crater marching-cubes -i ./path/to/torus.yml -o torus.stl ``` which outputs a `.stl` file. `crater.rs`'s CI/CD jobs run this exact example [see (`torus.stl`)](https://gitlab.com/games1122013/crater.rs/-/jobs/artifacts/main/browse?job=release). ## As a library `crater.rs` is distributed as a Rust library crate for use as a dependency in your project(s). ### Install ``` > cargo add crater-rs ... adds `crater-rs` as a dependency of your crate ``` # Theory `crater.rs` leverages a wealth of abstract mathematical and computing techniques. Rather than detail all aspects of the underlying theory in the `README.md`, check out the [API documentation](https://docs.rs/crater-rs/)! There are numerous examples and explanations written inline. # Citations 1. A. Ricci. ["A constructive geometry for computer graphics"](https://academic.oup.com/comjnl/article/16/2/157/372746) (1973) 2. Vadim Shapiro. ["Theory of R-Functions: A Primer"](https://ecommons.cornell.edu/server/api/core/bitstreams/deda5a32-8d13-4e10-abef-8b0030337a7b/content) (1988) 3. P.A. Fayolle and A. Pasko ["An Evolutionary Approach to the Extraction of Object Construction Trees from 3D Point Clouds"](https://eprints.bournemouth.ac.uk/23373/1/tree_recovery.pdf) 4. A. Pasko, et. al. ["Function Representation in Geometric Modeling: Concepts, Implementation and Applications"](https://papers.cumincad.org/data/works/att/d935.content.pdf) 5. P. Bourke. ["Polygonising a scalar field"](https://paulbourke.net/geometry/polygonise/) (1994) 6. N. Matsakis ["Rayon Data Parallelism in Rust"](https://smallcultfollowing.com/babysteps/blog/2015/12/18/rayon-data-parallelism-in-rust/)