Crystal Geometry

3D crystal geometry engine for crystallographic visualization. Computes polyhedra from Crystal Description Language (CDL) strings using half-space intersection with point group symmetry.

Part of the Gemmology Project.

Installation

pip install crystal-geometry

Quick Start

from crystal_geometry import cdl_string_to_geometry, create_octahedron

# Create geometry from CDL string
geom = cdl_string_to_geometry("cubic[m3m]:{111}@1.0 + {100}@1.3")
print(f"Vertices: {len(geom.vertices)}, Faces: {len(geom.faces)}")

# Use convenience constructors
octahedron = create_octahedron()
print(f"Octahedron has {len(octahedron.faces)} faces")

Features

• CDL Integration: Parse Crystal Description Language strings to 3D geometry
• Point Group Symmetry: All 32 crystallographic point groups supported
• Half-Space Intersection: Robust geometry computation using scipy
• 7 Crystal Systems: Cubic, tetragonal, orthorhombic, hexagonal, trigonal, monoclinic, triclinic
• Miller Indices: Full support for 3-index (hkl) and 4-index (hkil) notation
• Amorphous Geometry (v2.0): 7 parametric shape generators for non-crystalline materials (massive, botryoidal, reniform, stalactitic, mammillary, nodular, conchoidal)
• Aggregate Layouts (v2.0): 6 spatial arrangement algorithms for crystal aggregates (parallel, random, radial, epitaxial, druse, cluster)
• Nested Growth (v2.0): Geometry support for overgrowth relationships via the > operator

Core API

Geometry Generation

from cdl_parser import parse_cdl
from crystal_geometry import cdl_to_geometry, cdl_string_to_geometry

# From CDL string directly
geom = cdl_string_to_geometry("cubic[m3m]:{111}")

# From parsed description (more control)
desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
geom = cdl_to_geometry(desc, c_ratio=1.0)

Convenience Constructors

from crystal_geometry import (
    create_octahedron,
    create_cube,
    create_dodecahedron,
    create_truncated_octahedron,
)

# Regular polyhedra
octahedron = create_octahedron(scale=1.0)
cube = create_cube(scale=1.0)
dodecahedron = create_dodecahedron(scale=1.0)
truncated = create_truncated_octahedron(octahedron_scale=1.0, cube_scale=1.3)

CrystalGeometry Class

from crystal_geometry import CrystalGeometry

geom = cdl_string_to_geometry("cubic[m3m]:{111}")

# Properties
geom.vertices      # Nx3 numpy array of vertex positions
geom.faces         # List of face vertex indices
geom.face_normals  # List of unit normal vectors
geom.face_forms    # Form index for each face
geom.face_millers  # Miller indices for each face
geom.is_amorphous  # True for amorphous geometry (v2.0)
geom.aggregate_metadata  # AggregateMetadata or None (v2.0)
geom.component_ids       # Per-face component ID for aggregates/twins

# Methods
geom.get_edges()           # Get unique edges as vertex pairs
geom.center()              # Compute centroid
geom.scale_to_unit()       # Scale to fit unit sphere
geom.translate(offset)     # Translate by vector
geom.euler_characteristic()  # V - E + F (should be 2)
geom.is_valid()            # Verify geometry integrity
geom.to_dict()             # Export to dictionary

AggregateMetadata (v2.0)

from crystal_geometry import AggregateMetadata

# Attached to CrystalGeometry.aggregate_metadata for aggregate geometry
# Properties:
#   arrangement: str     - Layout algorithm ('parallel', 'random', etc.)
#   n_instances: int     - Number of crystal instances
#   spacing: float|None  - Spacing between instances
#   orientation: str|None - Orientation mode

Symmetry Operations

from crystal_geometry import (
    get_point_group_operations,
    generate_equivalent_faces,
    miller_to_normal,
    LatticeParams,
)

# Get symmetry operations for a point group
ops = get_point_group_operations('m3m')  # 48 operations
ops = get_point_group_operations('6/mmm')  # 24 operations

# Generate equivalent faces from one Miller index
faces = generate_equivalent_faces(1, 1, 1, 'm3m')  # 8 faces for {111}
faces = generate_equivalent_faces(1, 0, 0, 'm3m')  # 6 faces for {100}

# Convert Miller indices to normal vector
lattice = LatticeParams.cubic()
normal = miller_to_normal(1, 1, 1, lattice)

# Create lattice parameters
cubic = LatticeParams.cubic()
tetragonal = LatticeParams.tetragonal(c_ratio=1.5)
hexagonal = LatticeParams.hexagonal(c_ratio=1.2)

Crystal Systems and Point Groups

Examples

Diamond-like Crystal

# Octahedron truncated by cube
geom = cdl_string_to_geometry("cubic[m3m]:{111}@1.0 + {100}@1.3")
assert len(geom.faces) == 14  # 8 octahedron + 6 cube

Garnet-like Crystal

# Dodecahedron with trapezohedron
geom = cdl_string_to_geometry("cubic[m3m]:{110}@1.0 + {211}@0.6")

Hexagonal Prism

# Prism with pinacoid termination
geom = cdl_string_to_geometry("hexagonal[6/mmm]:{10-10}@1.0 + {0001}@0.5")

Quartz-like Crystal

# Prism with rhombohedron
geom = cdl_string_to_geometry("trigonal[-3m]:{10-10}@1.0 + {10-11}@0.8")

Amorphous Shape (v2.0)

from crystal_geometry import generate_amorphous_shape

# Generate parametric mesh for an amorphous material
geom = generate_amorphous_shape("botryoidal", radius=1.0, seed=42)
print(geom.is_amorphous)  # True

Available shapes: massive, botryoidal, reniform, stalactitic, mammillary, nodular, conchoidal.

Crystal Aggregate (v2.0)

from crystal_geometry import generate_aggregate, cdl_string_to_geometry

# Generate base geometry, then arrange as aggregate
base = cdl_string_to_geometry("trigonal[32]:{10-10}@1.0 + {10-11}@0.8")
aggregate = generate_aggregate(base, arrangement="cluster", count=12, seed=42)
print(aggregate.aggregate_metadata.n_instances)  # 12

Available arrangements: parallel, random, radial, epitaxial, druse, cluster. Instance count is capped at 200 for performance.

Source Modules

Requirements

• Python >= 3.10
• numpy >= 1.20.0
• scipy >= 1.7.0
• cdl-parser >= 2.0.0

Documentation

See crystal-geometry.gemmology.dev for full documentation.

License

MIT License - see LICENSE for details.

Related Packages

• cdl-parser - Crystal Description Language parser
• mineral-database - Mineral preset database
• crystal-renderer - SVG/3D rendering