Crate symbios_shape 

Symbios Shape

A Sovereign Derivation Engine for CGA Shape Grammars.

Symbios Shape is a pure-Rust engine for generating procedural geometry using Computer-Generated Architecture (CGA) Shape Grammars, as popularised by Esri CityEngine. It is designed for embedding in game engines (Bevy, Godot) and offline procedural pipelines where reliability and determinism are paramount.

Key Features

• Lightweight: Depends on glam (math), nom (parsing), rand (stochastic rules), thiserror, serde, and symbios-genetics — no engine or runtime required.
• CGA-Compatible Operations: Extrude, Split (snap-aware, with { … }* rhythm groups), SplitArea, Fit, Repeat, Comp(Faces|Edges), Taper, Scale, Size, Center, Translate, Rotate, Align, Mirror, Offset (inset/outset), ShapeL/ShapeU, Roof, Attach, Scatter, Polygon, RegSnap, Label, IfClear/IfOccluded/IfInside/IfTouches, Pick, I, Mat, and the reserved NIL vanish rule.
• Expression Language: every numeric argument accepts arithmetic, comparisons, logicals, rand(min, max) and friends, plus scope.x/y/z, split.i, split.n, depth, rule parameters, and attr/const names.
• Rules with Parameters and Guards: Spire(n) --> when(n == 0): … | else: … alongside weighted stochastic variants (70% A | else: B).
• Per-Shape Seed Streams: derivations are pure functions of (grammar, root scope, seed) — queue-order independent, and editing one subtree re-rolls only that subtree.
• Grammar Statements: attr / const declarations and style … extends … override sets; hosts steer with Interpreter::set_attr / Interpreter::set_style.
• 15 Roof Types: Pyramid, Shed, Gable, Hip, Flat, OpenGable, BoxGable, PyramidHip, Butterfly, MShaped, Gambrel, Mansard, Saltbox, Jerkinhead, DutchGable — with height=, ridge=, fascia bands, and Shed’s Back northlight face.
• Rich Face Profiles: FaceProfile describes each terminal’s cross-section (Rectangle, Taper, Triangle, Trapezoid, Polygon).
• Mass Model: Material { id, density } + MassProperties { mass, centroid, inertia } computed on Terminal for physics / LOD / IK consumers.
• Snap-Lines + Occlusion Queries: RegSnap records face planes; Split(snap=...) aligns to them. The occlusion conditionals gate sub-rules on (optionally labelled) OBB relations with already-emitted terminals; the same overlap test is exposed at runtime via ShapeModel::query → TerminalQuery and the free function obb_overlap.
• Genetic Evolution: genetics::ShapeGenotype wraps the rule table for symbios-genetics algorithms (literal-leaf Gaussian mutation, BLX-α crossover).
• Bevy-Ready Output: ShapeModel containing Terminal nodes with scope, mesh_id, face_profile, material, mass_properties, and occlusion label.

Example

use symbios_shape::{Interpreter, Scope, Vec3, Quat};
use symbios_shape::grammar::parse_ops;

let mut interp = Interpreter::new();

// A simple 3-storey building
interp.add_rule("Lot", parse_ops("Extrude(12) Split(Y) { 3: Ground | ~1: Upper | 2: Roof }").unwrap());
interp.add_rule("Ground", parse_ops(r#"I("GroundFloor")"#).unwrap());
interp.add_rule("Upper",  parse_ops(r#"I("Floor")"#).unwrap());
interp.add_rule("Roof",   parse_ops(r#"Taper(0.8) I("Roof")"#).unwrap());

let footprint = Scope::new(Vec3::ZERO, Quat::IDENTITY, Vec3::new(10.0, 0.0, 10.0));
let model = interp.derive(footprint, "Lot").unwrap();

assert_eq!(model.len(), 3);
assert_eq!(model.terminals[0].mesh_id, "GroundFloor");
assert_eq!(model.terminals[2].mesh_id, "Roof");
assert!(matches!(model.terminals[2].face_profile, symbios_shape::FaceProfile::Taper(t) if (t - 0.8).abs() < 1e-9));

Re-exports

pub use error::ShapeError;

pub use interpreter::Interpreter;

pub use model::FaceProfile;

pub use model::MassProperties;

pub use model::Material;

pub use model::ShapeModel;

pub use model::SnapPlane;

pub use model::Terminal;

pub use ops::AttachCase;

pub use ops::AttachSelector;

pub use ops::Axis;

pub use ops::CompTarget;

pub use ops::FaceSelector;

pub use ops::OffsetCase;

pub use ops::OffsetSelector;

pub use ops::RoofCase;

pub use ops::RoofConfig;

pub use ops::RoofFaceSelector;

pub use ops::RoofType;

pub use ops::ShapeOp;

pub use ops::SnapBinding;

pub use ops::SplitSize;

pub use ops::SplitSlot;

pub use query::TerminalQuery;

pub use query::obb_overlap;

pub use scope::Scope;

Modules

error

Error type returned by the parser and the interpreter.

expr

Arithmetic / logical expression language for grammar arguments.

genetics

Genetic evolution wrapper for CGA Shape Grammar interpreters.

grammar

interpreter

model

ops

query

Spatial query primitives over an in-progress or completed ShapeModel.

scope

Structs

Quat

A double-precision unit quaternion. Re-exported from glam. A quaternion representing an orientation.

Vec3

A 3-component double-precision vector. Re-exported from glam. A 3-dimensional vector.