Command Line Interface

The gemmology ecosystem provides three CLI tools for parsing CDL expressions, querying the mineral database, and generating crystal visualizations.

`cdl` - CDL Parser CLI

pip install gemmology-cdl-parser

Parse a CDL Expression

# Parse and display the result
cdl parse "cubic[m3m]:{111}"

# Parse with JSON output
cdl parse "cubic[m3m]:{111}@1.0 + {100}@1.3" --json

# Parse a complex expression
cdl parse "trigonal[-3m]:{10-10}@1.0 + {10-11}@0.8 | elongate(c:1.5)"

Validate a CDL Expression

# Returns exit code 0 if valid, 1 if invalid
cdl validate "cubic[m3m]:{111}"
cdl validate "hexagonal[6/mmm]:{10-10} + {0001}"

Reference Data

# List all crystal systems with default point groups
cdl --list-systems

# List all point groups by crystal system
cdl --list-point-groups

# List all named forms (e.g., octahedron, cube, prism)
cdl --list-forms

# List all twin laws
cdl --list-twins

# Show version
cdl --version

`mineral-db` - Mineral Database CLI

pip install gemmology-mineral-database

List Presets

# List all 128 presets
mineral-db --list

# List presets by crystal system
mineral-db --list cubic
mineral-db --list trigonal

# List preset categories
mineral-db --categories

# Count total presets
mineral-db --count

Query Preset Details

# Show detailed info for a preset
mineral-db --info diamond-octahedron

# Output preset as JSON
mineral-db --json diamond-octahedron

# Search presets by name, mineral, or chemistry
mineral-db --search garnet
mineral-db --search SiO2

Synthetic and Simulant Queries

# List all synthetic minerals
mineral-db --synthetics

# Filter synthetics by growth method
mineral-db --synthetics flux
mineral-db --synthetics cvd

# List all simulants
mineral-db --simulants

# Filter simulants by target mineral
mineral-db --simulants diamond

# Show all counterparts for a natural mineral
mineral-db --counterparts diamond

# Filter by origin type
mineral-db --list --origin natural
mineral-db --list --origin synthetic
mineral-db --list --origin simulant
mineral-db --list --origin composite

`gemmology` - Plugin CLI

pip install gemmology-plugin

The gemmology command is installed with the plugin package and provides crystal visualization from the terminal.

Basic Usage

# Generate from CDL
gemmology --cdl "cubic[m3m]:{111}" -o octahedron.svg

# Use a preset
gemmology --preset diamond -o diamond.svg

# Generate twin
gemmology --twin japan -o japan_twin.svg

Options

Option	Description
`--cdl <expr>`	CDL expression to render
`--preset <name>`	Use a mineral preset from the database
`--twin <law>`	Generate a twin using specified twin law
`--habit <name>`	Use a named crystal habit
`-o, --output <file>`	Output file path
`--format <fmt>`	Output format: `svg`, `stl`, `gltf`
`--elev <deg>`	Elevation angle in degrees (default: 30)
`--azim <deg>`	Azimuth angle in degrees (default: -45)
`--no-grid`	Disable grid background
`--no-axes`	Disable crystallographic axes
`--info-fga`	Add FGA-style info panel with properties
`--info-basic`	Add basic info panel (name, system, CDL)
`--list-presets`	List all available presets
`--list-twins`	List all available twin laws

Examples

# Custom CDL with view angles
gemmology --cdl "cubic[m3m]:{111}@1.0 + {100}@1.3" \
  --elev 45 --azim -30 -o truncated.svg

# Export to STL for 3D printing
gemmology --preset quartz --format stl -o quartz.stl

# Generate with FGA info panel
gemmology --preset ruby --info-fga --no-grid -o ruby.svg

# Japan law twin
gemmology --twin japan --elev 20 --azim -60 -o japan_twin.svg

Programmatic Usage

The CLI tools are thin wrappers around the Python packages. For programmatic use:

from cdl_parser import parse_cdl
from crystal_geometry import cdl_to_geometry
from crystal_renderer import generate_cdl_svg, export_stl
from mineral_database import get_preset

# From CDL string (simplest approach)
generate_cdl_svg("cubic[m3m]:{111}", "diamond.svg")

# Step by step with geometry access
desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
geom = cdl_to_geometry(desc)
print(f"Vertices: {len(geom.vertices)}, Faces: {len(geom.faces)}")

# Export to STL
export_stl(geom.vertices, geom.faces, "diamond.stl")

# From preset
preset = get_preset("diamond-octahedron")
if preset:
    generate_cdl_svg(preset['cdl'], "diamond.svg")

Need help?

cdl --help
mineral-db --help
gemmology --help