Quick Start

Generate your first crystal visualization in just 5 lines of Python code.

Your First Crystal

Create a simple diamond (octahedron) SVG:

from cdl_parser import parse_cdl
from crystal_geometry import cdl_to_geometry
from crystal_renderer import generate_svg

desc = parse_cdl("cubic[m3m]:{111}")
geom = cdl_to_geometry(desc)
generate_svg(geom, "diamond.svg")

This creates diamond.svg - an octahedral crystal commonly seen in natural diamonds.

Understanding the Code

Step 1: Parse the CDL expression

desc = parse_cdl("cubic[m3m]:{111}")

The CDL expression breaks down as:

  • cubic - Crystal system
  • [m3m] - Point group (highest cubic symmetry)
  • {111} - Miller indices for octahedral form

Step 2: Generate 3D geometry

geom = cdl_to_geometry(desc)

This computes vertices and faces using half-space intersection, applying the symmetry operations from the point group.

Step 3: Render to SVG

generate_svg(geom, "diamond.svg")

Projects the 3D geometry to 2D and creates an SVG file with proper face ordering for realistic rendering.

Combining Crystal Forms

Most real crystals show multiple forms. Use + to combine them:

# Fluorite: cube with octahedron corners
desc = parse_cdl("cubic[m3m]:{100}@1.0 + {111}@1.4")
geom = cdl_to_geometry(desc)
generate_svg(geom, "fluorite.svg")

The @distance value controls form development - lower values produce larger faces.

Using Mineral Presets

For common minerals, use the built-in presets:

from mineral_database import get_preset
from crystal_geometry import cdl_to_geometry
from crystal_renderer import generate_svg

# Get quartz preset
preset = get_preset("quartz")
geom = cdl_to_geometry(preset.cdl)
generate_svg(geom, "quartz.svg")

# List all available presets
from mineral_database import list_presets
print(list_presets())  # 94 minerals

Customizing Output

View angle

generate_svg(geom, "crystal.svg",
    elevation=30,   # degrees from horizontal
    azimuth=-45     # rotation around vertical axis
)

Size and styling

generate_svg(geom, "crystal.svg",
    figsize=(6, 6),      # inches
    face_color="#0ea5e9", # fill color
    edge_color="#0369a1", # stroke color
    show_axes=True        # crystallographic axes
)

Exporting to Other Formats

from crystal_renderer import export_stl, export_gltf

# Export for 3D printing
export_stl(geom, "crystal.stl")

# Export for web/AR/VR
export_gltf(geom, "crystal.gltf")

Try it Interactively

CDL Playground

Experiment with CDL expressions directly in your browser - no installation needed.

Open Playground
Installation CDL Specification