Struct polyhedron_ops::Polyhedron

pub struct Polyhedron { /* private fields */ }

Implementations

impl Polyhedron

Base Shapes

Start shape creation methods.

pub fn tetrahedron() -> Self

pub fn hexahedron() -> Self

pub fn cube() -> Self

Alias for hexahedron().

pub fn octahedron() -> Self

pub fn dodecahedron() -> Self

pub fn icosahedron() -> Self

pub fn prism(n: Option<usize>) -> Self

pub fn antiprism(n: Option<usize>) -> Self

impl Polyhedron

pub fn write_obj( &self, destination: &Path, reverse_winding: bool ) -> Result<PathBuf, Box<dyn Error>>

Write the polyhedron to a Wavefront OBJ file.

The name of the polyhedron is appended to the given destination and postfixed with the extension .obj.

Depending on the target coordinate system (left- or right handed) the mesh’s winding order can be reversed with the reverse_face_winding flag.

The return value, on success, is the final, complete path of the OBJ file.

pub fn read_obj(source: &Path, reverse_winding: bool) -> Result<Self, LoadError>

impl Polyhedron

Conversion to ɴsɪ.

pub fn to_nsi( &self, ctx: &Context<'_>, handle: Option<&str>, crease_hardness: Option<f32>, corner_hardness: Option<f32>, smooth_corners: Option<bool> ) -> String

Sends the polyhedron to the specified ɴsɪ context.

Arguments

• handle – Handle of the node being created. If omitted, the name of the polyhedron will be used as a handle.

• crease_hardness - The hardness of edges (default: 10).

• corner_hardness - The hardness of vertices (default: 0).

• smooth_corners - Whether to keep corners smooth where more than two edges meet. When set to false these automatically form a hard corner with the same hardness as crease_hardness.

impl Polyhedron

Mesh Buffer (GPU/realtime) Helpers

pub fn to_triangle_mesh_buffers(&self) -> (Vec<u32>, Points, Normals)

Returns a flat u32 triangle index buffer and two matching point and normal buffers.

This is mostly useful for realtime rendering, e.g. sending data to a GPU.

All the faces are disconnected. I.e. positions & normals are duplicated for each shared vertex.

impl Polyhedron

Operators

pub fn ambo(&mut self, ratio: Option<Float>, change_name: bool) -> &mut Self

Creates vertices with valence (aka degree) four.

It is also called rectification, or the medial graph in graph theory.

pub fn bevel( &mut self, ratio: Option<Float>, height: Option<Float>, face_arity_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Adds faces at the center, original vertices, and along the edges.

Arguments

• ratio - The ratio of the new vertices to the original vertices.
• height - The height (depth) of the bevel.
• face_arity_mask - Only faces matching the given arities will be affected.
• regular_faces_only - Only regular faces will be affected.

pub fn catmull_clark_subdivide(&mut self, change_name: bool) -> &mut Self

Performs Catmull-Clark subdivision.

Each face is replaced with n quadralaterals based on edge midpositions vertices and centroid edge midpositions are average of edge endpositions and adjacent centroids original vertices replaced by weighted average of original vertex, face centroids and edge midpositions.

pub fn chamfer(&mut self, ratio: Option<Float>, change_name: bool) -> &mut Self

Chamfers edges. I.e. adds a new hexagonal face in place of each original edge.

Arguments

• ratio - The ratio of the new faces to the old faces.

pub fn dual(&mut self, change_name: bool) -> &mut Self

Creates the dual. Replaces each face with a vertex, and each vertex with a face.

pub fn expand(&mut self, ratio: Option<Float>, change_name: bool) -> &mut Self

Cantellates. I.e. creates a new facet in place of each edge and of each vertex.

Arguments

• ratio - The ratio of the new faces to the old faces.

pub fn extrude( &mut self, height: Option<Float>, offset: Option<Float>, face_arity: Option<&[usize]>, change_name: bool ) -> &mut Self

Extrudes faces by height and shrinks the extruded faces by distance from the original edges.

Arguments

• height – The distance to extrude the faces. Default value is 0.3.
• offset – The distance to inset the extruded faces. Default value is 0.0.
• face_arity_mask – Only faces matching the given arities will be affected.

pub fn gyro( &mut self, ratio: Option<f32>, height: Option<f32>, change_name: bool ) -> &mut Self

Splits each edge and connects new edges at the split point to the face centroid. Existing positions are retained.

Arguments

• ratio – The ratio at which the adjacent edges get split.
• height – An offset to add to the face centroid point along the face normal.
• change_name – Whether to change the name of the mesh.

pub fn inset( &mut self, offset: Option<Float>, face_arity_mask: Option<&[usize]>, change_name: bool ) -> &mut Self

Inset faces by offset from the original edges.

Arguments

• offset – The distance to inset the faces. Default value is 0.3.
• face_arity_mask – Only faces matching the given arities will be affected.

pub fn join(&mut self, ratio: Option<Float>, change_name: bool) -> &mut Self

Creates quadrilateral faces around each original edge. Original edges are discarded.

Arguments

• ratio – The ratio at which the adjacent edges get split. Will be clamped to [0, 1]. Default value is 0.5.

pub fn kis( &mut self, height: Option<Float>, face_arity_mask: Option<&[usize]>, face_index_mask: Option<&[FaceKey]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Creates a kleetrope from the input. Splits each face into triangles, one for each edge, which extend to the face centroid. Existing positions are retained.

Arguments

• height - An offset to add to the face centroid point along the face normal.
• face_arity_mask - Only faces matching the given arities will be affected.
• face_index_mask - Only faces matching the given indices will be affected.
• regular_faces_only - Only faces whose edges are 90% the same length, within the same face, are affected.

pub fn medial( &mut self, ratio: Option<Float>, height: Option<Float>, vertex_valence_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Adds edges from the center to each original vertex.

Arguments

• ratio – The ratio of the new vertices to the original vertices.
• height – The height of the new vertices.
• vertex_valence_mask – Only vertices matching the given valences will be affected.
• regular_faces_only – Only regular faces will be affected.

pub fn meta( &mut self, ratio: Option<Float>, height: Option<Float>, vertex_valence_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Adds vertices at the center and along the edges.

Arguments

• ratio – The ratio of the new vertices to the original vertices.
• height – The height of the new vertices.
• vertex_valence_mask – Only vertices matching the given valences will be affected.
• regular_faces_only – Only regular faces will be affected.

pub fn needle( &mut self, height: Option<Float>, vertex_valence_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Like kis but also splits each edge in the middle.

Arguments

• height – The offset of the new face centers.
• vertex_valence_mask – Only vertices matching the given valences will be affected.
• regular_faces_only – Only regular faces will be affected.

pub fn ortho(&mut self, ratio: Option<Float>, change_name: bool) -> &mut Self

Connects the center of each face to the center of each edge.

Arguments

• ratio – The ratio of the new two parts each original edge is split into.

pub fn planarize(&mut self, iterations: Option<usize>, change_name: bool)

Applies quick and dirty canonicalization.

Arguments

• iterations – The number of iterations to perform. Typical number of iterations are 100+. The default is 100`.

pub fn propellor( &mut self, ratio: Option<Float>, change_name: bool ) -> &mut Self

Splits each edge into three parts and creates edges on each face connecting the new vertices.

Arguments

• ratio – The ratio of the edge splits.

pub fn quinto(&mut self, height: Option<Float>, change_name: bool) -> &mut Self

Splits each edge in the middle and creates new faces in the middle of each face then connects those.

Arguments

• height – The offset of the new faces from the original face.

pub fn reflect(&mut self, change_name: bool) -> &mut Self

Reflects the shape.

pub fn snub( &mut self, ratio: Option<Float>, height: Option<Float>, change_name: bool ) -> &mut Self

Applies a snub to the shape.

Arguments

• ratio – The ratio at which the adjacent edges get split.
• height – The height of the newly created centers.

pub fn spherize( &mut self, strength: Option<Float>, change_name: bool ) -> &mut Self

Projects all positions on the unit sphere (at strength 1.0).

Arguments

• strength – The strength of the spherization. If strength is zero this is a no-op and will neither change the geometry nor the name. Even if change_name is true.

pub fn truncate( &mut self, height: Option<Float>, face_arity_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Cuts off the shape at its vertices but leaves a portion of the original edges.

Arguments

• height – The height of the newly created centers.
• face_arity_mask - Only faces matching the given arities will be affected.
• regular_faces_only – Only regular faces will be affected.

pub fn whirl( &mut self, ratio: Option<Float>, height: Option<Float>, change_name: bool ) -> &mut Self

Splits each edge into three parts and connexts the new vertices. But also splits the newly formed connections and connects those.

Arguments

• ratio – The ratio at which the adjacent edges get split.
• height – The height offset of the newly created vertices.

pub fn zip( &mut self, height: Option<Float>, face_arity_mask: Option<&[usize]>, regular_faces_only: Option<bool>, change_name: bool ) -> &mut Self

Bitruncates the shape.

Arguments

• height – The height offset of the newly created vertices.
• face_arity_mask – Only faces with the given arity will be affected.
• regular_faces_only – Only regular faces will be affected.

impl Polyhedron

Triangulation

pub fn triangulate(&mut self, shortest: Option<bool>) -> &mut Self

Bitriangulates quadrilateral faces.

N-gon trinagulation is naive and may yield inferor results.

Arguments

• shortest - If true, use shortest diagonal so triangles are most nearly equilateral. On by default.

impl Polyhedron

Selection methods.

pub fn select_faces_above_plane( &self, origin: Point, normal: Vector ) -> Vec<FaceKey>

Selects all faces within a half space defined by a plane through origin and the the give plane normal.

impl Polyhedron

pub fn new() -> Self

pub fn from( name: &str, positions: Points, face_index: Faces, face_set_index: Option<Vec<FaceSet>> ) -> Self

pub fn bounding_box(&self) -> [f64; 6]

Returns the axis-aligned bounding box of the polyhedron in the format [x_min, y_min, z_min, x_max, y_max, z_max].

pub fn reverse(&mut self) -> &mut Self

Reverses the winding order of faces.

Clockwise(default) becomes counter-clockwise and vice versa.

pub fn name(&self) -> &String

Returns the name of this polyhedron. This can be used to reconstruct the polyhedron using Polyhedron::from<&str>().

pub fn positions(&self) -> &Points

pub fn faces(&self) -> &Faces

pub fn normalize(&mut self) -> &mut Self

pub fn to_edges(&self) -> Edges

Compute the edges of the polyhedron.

pub fn finalize(&self) -> Self

Turns the builder into a final object.

Trait Implementations

impl Clone for Polyhedron

fn clone(&self) -> Polyhedron

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Polyhedron

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Polyhedron

fn default() -> Self

Returns the “default value” for a type.

impl TryFrom<&str> for Polyhedron

fn try_from(s: &str) -> Result<Self, Self::Error>

Tries to create a polyhedron from a Conway Polyedron Notation string.

E.g. the string aD creates a dodecahedron with an ambo operation applied to it. Also known as an icosidodecahedron. One of the Archimedian solids.

Overview

• All parameters are optional (i.e. have defaults, if absent).

• Any (number of) parameter(s) can be skipped by using commata (,).

• Whitespace is ignored. This includes tabs, newlines and carriage returns.

Tokens

Integers are written as decimal numbers.

Floats are written as decimal numbers with an optional decimal point and an optional exponent.

Booleans are written as {t} (true) or {f} (false).

Parameter names in the operator list below are prefixed with the expected type:

• b_ – boolean
• f_ – float
• uf_ – unsigned float
• i_ – integer
• ui_ – unsigned integer
• [ui_, ...] – array of unsigned integers or single unsigned integer

Platonic Solids

• T – Tetrahedron
• C – Hexahedron (cube)
• O – Octahedron
• D – Dodecahedron
• I – Icosahedron

Operators

• a uf_ratio – ambo
• b f_ratio, f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – bevel (equiv. to ta)
• c uf_ratio – chamfer
• d – dual
• e uf_ratio – expand (a.k.a. explode, equiv. to aa)
• g uf_ratio, f_height – gyro
• i f_offset – inset/loft (equiv. to x,N)
• j uf_ratio – join (equiv. to dad)
• K ui_iterations – planarize (quick & dirty canonicalization)
• k f_height, [ui_face_arity_mask, ...], ui_face_index_mask, b_regular_faces_only – kis
• M uf_ratio, f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – medial (equiv. to dta)
• m uf_ratio, f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – meta (equiv. to k,,3j)
• n f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – needle (equiv. to dt)
• o uf_ratio – ortho (equiv. to jj)
• p uf_ratio – propellor
• q f_height – quinto
• r – reflect
• S uf_strength – spherize
• s uf_ratio, f_height – snub (equiv. to dgd)
• t f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – truncate (equiv. to dkd)
• v – subdivide (Catmull-Clark)
• w uf_ratio, f_height – whirl
• x f_height, f_offset, [ui_face_arity_mask, ...] – extrude
• z f_height, [ui_vertex_valence_mask, ...], b_regular_faces_only – zip (equiv. to dk)

Examples

let polyhedron_from_str =
    Polyhedron::try_from("g0.2k0.1,[3,4],,{t}b,2T").unwrap();

let polyhedron_from_builder = Polyhedron::tetrahedron()
    .bevel(None, Some(2.0), None, None, true)
    .kis(Some(0.1), Some(&[3, 4]), None, Some(true), true)
    .gyro(Some(0.2), None, true)
    .finalize();

assert_eq!(polyhedron_from_str.name(), polyhedron_from_builder.name());

type Error = Error<Rule>

The type returned in the event of a conversion error.