![logo](./assets/logo-crater.png)

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/)