Skip to content

Getting Started

To get started with Plexus, add a dependency to Cargo.toml.

1
2
[dependencies]
plexus = "0.0.11" # Unstable. Require exact version.

Warning

Plexus is still in its initial development phase. At this time, it is best to take strict dependencies on a specific version. Using carets, tildes, or Kleene stars in dependency requirements will likely cause spurious build failures between releases.

Plexus interacts with other crates in the Rust ecosystem. Most importantly, it uses theon to abstract Euclidean geometry atop various mathematics crates. nalgebra is highly recommended for geometric types, but other crates like cgmath and mint are also supported via theon.

The decorum crate is also supported by Plexus and is useful for floating-point values that support Hash and various numeric traits. Consider also taking dependencies on these crates as needed.

1
2
3
4
5
[dependencies]
decorum = "^0.1.1"
nalgebra = "^0.17.0"
plexus = "0.0.11" # Unstable. Require exact version.
theon = "0.0.1" # Unstable. Require exact version.

Cargo Features

Plexus exposes two kinds of Cargo features: geometry features and encoding features. To configure features, specify a dependency on Plexus in Cargo.toml as seen below.

1
2
3
4
5
6
7
[dependencies.plexus]
default-features = false
features = [
    "encoding-ply"
    "geometry-nalgebra",
]
version = "0.0.11" # Unstable. Require exact version.

Geometry features integrate with mathematics crates and optionally implement geometric traits from theon for types in those crates. It is highly recommended to enable the corresponding geometry feature if a supported crate is used for geometric types.

Feature Default Crate Support
geometry-cgmath No cgmath Complete
geometry-mint No mint Partial
geometry-nalgebra Yes nalgebra Complete

Encoding features expose sub-modules in the encoding module for mesh formats that can be used to serialize and deserialize polygonal mesh data. For example, the encoding-ply feature enables the encoding::ply module with support for the PLY format.

Feature Default Encoding Read Write
encoding-ply No PLY Yes No

Prelude Module

Plexus exposes functionality via traits with blanket implementations. It can sometimes be cumbersome to import these traits, so it is recommended to import the contents of the prelude module whenever Plexus is used.

1
use plexus::prelude::*;

The prelude module re-exports commonly used traits. In particular, it re-exports traits used by iterator expressions that process streams of topological and geometric data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
use decorum::N64;
use nalgebra::Point3;
use plexus::index::{Flat3, HashIndexer};
use plexus::prelude::*;
use plexus::primitive::cube::Cube;
use plexus::primitive::generate::Position;

// These functions are all imported from `prelude` via traits.
let (indices, vertices) = Cube::new()
    .polygons::<Position<Point3<N64>>>()
    .triangulate()
    .index_vertices::<Flat3, _>(HashIndexer::default());

Note

Most code examples in the user guide do not include imports.