crystal-geometry

Generate 3D crystal geometry from CDL descriptions using half-space intersection and crystallographic symmetry operations. Version 1.0.5.

pip install gemmology-crystal-geometry

Core Functions

# cdl_to_geometry(description: CrystalDescription) → CrystalGeometry

Convert a parsed CDL description into 3D geometry. Uses desc.flat_forms() internally to handle FormGroup nodes.

from cdl_parser import parse_cdl
from crystal_geometry import cdl_to_geometry

desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
geom = cdl_to_geometry(desc)

print(f"Vertices: {len(geom.vertices)}")  # 24
print(f"Faces: {len(geom.faces)}")        # 14

Parameters:

description - Parsed CrystalDescription from cdl-parser

Returns: CrystalGeometry object with vertices, faces, and normals

# cdl_string_to_geometry(cdl_string: str) → CrystalGeometry

Convenience function that parses a CDL string and generates geometry in one call.

from crystal_geometry import cdl_string_to_geometry

geom = cdl_string_to_geometry("cubic[m3m]:{111}")
print(len(geom.vertices))  # 6
print(len(geom.faces))     # 8

# halfspace_intersection_3d(normals, distances) → tuple[ndarray, list[list[int]]]

Compute the convex polyhedron defined by half-space intersection. Returns vertices and faces.

Convenience Constructors

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

# Create common crystal forms directly
geom = create_octahedron()       # {111} in m3m
geom = create_cube()             # {100} in m3m
geom = create_dodecahedron()     # {110} in m3m
geom = create_truncated_octahedron()  # {111} + {100}

Symmetry Operations

# get_point_group_operations(point_group: str) → list[np.ndarray]

Get the 3x3 rotation/reflection matrices for a crystallographic point group.

from crystal_geometry import get_point_group_operations

matrices = get_point_group_operations("m3m")
print(len(matrices))  # 48 operations

matrices = get_point_group_operations("-3m")
print(len(matrices))  # 12 operations

# generate_equivalent_faces(miller, point_group: str) → list[ndarray]

Generate all symmetry-equivalent face normals from a single Miller index.

# miller_to_normal(h, k, l, lattice) → ndarray

Convert Miller indices to a Cartesian normal vector using lattice parameters.

# get_lattice_for_system(system: str) → LatticeParams

Get default lattice parameters for a crystal system.

Modification Functions

# apply_modifications(vertices, modifications) → ndarray

Apply morphological modifications (elongate, flatten, taper) to vertices.

from crystal_geometry import apply_elongation, apply_flatten, apply_taper

# Elongate along c-axis
vertices = apply_elongation(vertices, axis='c', ratio=1.5)

# Flatten along c-axis
vertices = apply_flatten(vertices, axis='c', ratio=0.5)

# Taper toward one end
vertices = apply_taper(vertices, direction='c', factor=0.3)

Twin System

from crystal_geometry import (
    get_twin_law,
    list_twin_laws,
    get_gemstone_twins,
    TwinLaw,
)

# List all available twin laws
laws = list_twin_laws()
print(laws)  # ['spinel', 'iron_cross', 'brazil', ...]

# Get a specific twin law
law = get_twin_law("spinel")
print(law.name)      # 'spinel'
print(law.axis)      # Twin axis
print(law.angle)     # Rotation angle

# Get all twin laws for a specific gemstone
twins = get_gemstone_twins("quartz")
print(twins)  # ['dauphine', 'brazil', 'japan']

Habit System

from crystal_geometry import (
    get_habit,
    list_habits,
    get_gemstone_habits,
    CrystalHabit,
)

# List all registered habits
habits = list_habits()
print(habits)  # ['octahedron', 'cube', 'hexagonal_prism', ...]

# Get a specific habit
habit = get_habit("hexagonal_prism")
geom = habit.generate()

# Get habits for a specific gemstone
gem_habits = get_gemstone_habits("diamond")
print(gem_habits)  # ['octahedron', 'cube', 'dodecahedron']

Classes

`CrystalGeometry`

Container for 3D crystal geometry data.

Attribute	Type	Description
`vertices`	`np.ndarray`	Nx3 array of vertex coordinates
`faces`	`list[list[int]]`	List of faces (each face is a list of vertex indices)
`face_normals`	`list[np.ndarray]`	Normal vectors for each face
`face_millers`	`list[tuple]`	Miller indices for each face
`face_forms`	`list[int]`	Form index for each face (for color-by-form rendering)
`twin`	`TwinMetadata \| None`	Twin metadata if geometry is twinned

`LatticeParams`

Unit cell lattice parameters.

Attribute	Type	Description
`a`	`float`	Unit cell parameter a
`b`	`float`	Unit cell parameter b
`c`	`float`	Unit cell parameter c
`alpha`	`float`	Angle alpha in degrees
`beta`	`float`	Angle beta in degrees
`gamma`	`float`	Angle gamma in degrees

Backend Acceleration

from crystal_geometry import get_backend, get_backend_info

# Check which backend is active
print(get_backend())      # 'native' or 'python'
print(get_backend_info()) # Detailed backend information