Installation

The gemmology.dev ecosystem consists of four Python packages that work together to parse, compute, and render crystal structures.

Requirements

Python 3.10 or higher
pip (Python package manager)

Quick Install

Install all packages at once:

pip install cdl-parser crystal-geometry mineral-database crystal-renderer

Virtual Environment (Recommended)

We recommend using a virtual environment to avoid dependency conflicts:

# Create a virtual environment
python -m venv venv

# Activate it (Linux/macOS)
source venv/bin/activate

# Activate it (Windows)
venv\Scripts\activate

# Install packages
pip install cdl-parser crystal-geometry mineral-database crystal-renderer

Individual Packages

You can also install packages individually, depending on your needs:

Package	Purpose	Install Command
`cdl-parser`	Parse CDL expressions	`pip install cdl-parser`
`crystal-geometry`	Generate 3D geometry	`pip install crystal-geometry`
`mineral-database`	Access mineral presets	`pip install mineral-database`
`crystal-renderer`	Render to SVG/STL/glTF	`pip install crystal-renderer`

Development Installation

For contributing or modifying the source code, clone the repositories and install in editable mode:

# Clone the repository
git clone https://github.com/gemmology-dev/cdl-parser.git
cd cdl-parser

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Verify Installation

Verify that everything is installed correctly:

python -c "from cdl_parser import parse_cdl; print(parse_cdl('cubic[m3m]:{111}'))"

You should see a CrystalDescription object printed to the console.

Optional Dependencies

Some features require additional dependencies:

Feature	Dependency	Install Command
STL export	numpy-stl	`pip install numpy-stl`
glTF export	pygltflib	`pip install pygltflib`

Next: Quick Start