Gemmology Plugin

A Claude Code plugin for coloured gemstone expertise and crystal visualization.

Part of the Gemmology Project.

Features

• Crystal Visualization: Generate SVG, STL, and glTF visualizations of crystal structures
• Mineral Database: Access FGA-curriculum aligned gemstone data for 50+ minerals
• CDL Parser: Parse and validate Crystal Description Language notation
• Gem Identification: Interactive workflow for systematic gemstone identification

Installation

pip install gemmology-plugin

This installs the core plugin along with all component packages:

• cdl-parser - Crystal Description Language parser
• mineral-database - Gemstone property database
• crystal-geometry - 3D crystal geometry engine
• crystal-renderer - SVG/STL/glTF visualization

Optional: Language Server

For editor integration with CDL syntax highlighting and completion:

pip install gemmology-plugin[lsp]

Quick Start

Command Line

# Generate crystal visualization
gemmology crystal-svg --preset diamond -o diamond.svg

# List available presets
gemmology list-presets

# Get mineral information
gemmology info ruby

Python API

from gemmology_plugin import generate_crystal_svg, get_preset

# Generate from CDL notation
svg = generate_crystal_svg("cubic[m3m]:{111}@1.0 + {100}@1.3")

# Generate from preset
ruby = get_preset("ruby")
svg = generate_crystal_svg(ruby['cdl'], info_properties={'name': ruby['name']})

Claude Code Plugin

When used as a Claude Code plugin, this package provides:

Commands

• /crystal-svg - Generate crystal structure visualizations
• /identify-gem - Interactive gemstone identification workflow

Agents

Expert agents for domain-specific tasks:

• crystallography-expert - Crystal systems, symmetry, Miller indices
• gemmology-expert - Gemstone properties, FGA data
• cdl-expert - CDL syntax and parsing

Skills

Reference skills covering FGA curriculum topics:

• Physical properties (hardness, SG, cleavage)
• Optical properties (RI, birefringence, dispersion)
• Inclusions and fingerprints
• Treatments and enhancements
• Synthetics and simulants
• Origin determination

Image-Based Questions

IMPORTANT: When answering questions that involve interpreting gemstone images or photographs:

1. Always take a screenshot to view the actual image content
2. Double and triple check your interpretation before answering
3. Ask the user for confirmation if uncertain about visual features
4. Be explicit about what you see - describe the visual features before selecting an answer

Visual identification of features like colour zoning, asterism, chatoyancy, stress cracks, and inclusions requires careful examination. Similar features can appear differently depending on:

• Lighting conditions in the photograph
• Image quality and resolution
• Orientation of the gemstone
• Whether the feature is surface or internal

When in doubt, describe what you observe and ask the user to confirm before committing to an answer.

CDL Syntax Overview

Crystal Description Language (CDL) provides precise control over crystal morphology:

system[point_group]:{form}@distance + {form}@distance

Examples:

cubic[m3m]:{111}                    # Octahedron
cubic[m3m]:{111}@1.0 + {100}@1.3    # Truncated octahedron
trigonal[-3m]:{10-10}@1.0 + {0001}@0.5  # Quartz prism

Component Packages

This plugin integrates:

Package	Description
cdl-parser	CDL parsing and validation
mineral-database	Gemstone property database
crystal-geometry	3D geometry generation
crystal-renderer	Visualization and export
cdl-lsp	Language server (optional)

Development

git clone https://github.com/gemmology-dev/gemmology-plugin
cd gemmology-plugin
pip install -e ".[dev]"
pytest tests/ -v

License

MIT License - see LICENSE for details.

Links

• Documentation
• CDL Specification
• GitHub Repository