The Honeycomb User Guide

Current Version GitHub commits since latest release Build Status Rust Tests codecov

Honeycomb

Honeycomb aims to provide a safe, efficient and scalable implementation of combinatorial maps for meshing applications. More specifically, the goal is to converge towards a (or multiple) structure(s) adapted to algorithms exploiting GPUs and many-core architectures.

The current objective is to

  • write a first implementation in Rust
  • improve the structure without having to deal with data races and similar issues, thanks to the Rust's guarantees
  • implement basic meshing algorithms to evaluate the viability of the implementation & improve our structure using Rust's framework to streamline the refactoring and parallelization process

Core Requirements

  • Rust stable release - Development started on 1.75, but we might use newer features as the project progresses

Quickstart

Rust

The core and render crates are being published on crates.io. You can add those to your project by adding the following lines to the manifest of the project:

# Cargo.toml
# ...

[dependencies]
# Other dependencies...
honeycomb-core = "0.2.0"
honeycomb-render = "0.2.0"

Note that if you want to access the latest changes and documentation, you may have to specify a commit instead of a version, and use the GitHub Pages documentation instead of the one hosted on docs.rs.

Documentation

You can generate this documentation locally using mdbook and cargo doc:

# Serve the doc on a local server
mdbook serve --open -d ../target/doc/ user-guide/ &
cargo doc --all --no-deps

Documentation

References

Contributing

Contributions are welcome and accepted as pull requests on GitHub. Feel free to use issues to report bugs, missing documentation or suggest improvements of the project.

Note that a most of the code possess documentation, including private modules / items / sections. You can generate the complete documentation by using the instructions above and passing the option --document-private-items to cargo doc.

License

Licensed under either of

  • Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your preference.

The SPDX license identifier for this project is MIT OR Apache-2.0.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

References

Combinatorial Maps

  • Damiand, Guillaume, and Pascal Lienhardt. Combinatorial Maps: Efficient Data Structures for Computer Graphics and Image Processing. Chapman&Hall/CRC, 2015.
    • Provides an in-depth presentation of the structure and its variants
    • Link
  • The CGAL Project. CGAL User and Reference Manual. CGAL Editorial Board, 5.6.1 edition, 2024.
    • Provides concrete examples as well as code snippets of the CGAL implementation of the structure. The CGAL implementation uses a different approach than ours, & support N-dimensionnal map.
    • Link

Integration

  • The repository structure and workspace system is heavily inspired by the wgpu repository