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):
  • 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 TriangleMesh type. Use this to export to common rendering formats (e.g., .stl)
  • Invoke the (parallelized) Marching Cubes algorithm to convert CSGs to triangular meshes

Coming soon!

• CSG reconstruction from point-cloud geometry representations (i.e., the inverse of Marching Cubes - see [3])
• "GIF"-like .stl animations for time-dependent geometries (e.g., 4-D constructions of (x, y, z, t) that are common in relativistic geometries)
• Functional analysis of N-D CSG geometries (e.g., tangent spaces, normals, volume calculations, etc.)
• 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).

Here's a simple input

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

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! There are numerous examples and explanations written inline.

Citations

1. A. Ricci. "A constructive geometry for computer graphics" (1973)
2. Vadim Shapiro. "Theory of R-Functions: A Primer" (1988)
3. P.A. Fayolle and A. Pasko "An Evolutionary Approach to the Extraction of Object Construction Trees from 3D Point Clouds"
4. A. Pasko, et. al. "Function Representation in Geometric Modeling: Concepts, Implementation and Applications"
5. P. Bourke. "Polygonising a scalar field" (1994)
6. N. Matsakis "Rayon Data Parallelism in Rust"