Mineral Database - A comprehensive database of mineral crystal habits with CDL notation and gemmological properties for visualization applications.
Part of the Gemmology Project.
pip install mineral-databasefrommineral_databaseimportget_preset, list_presets, search_presets# Get a specific mineral presetdiamond=get_preset('diamond')
print(diamond['cdl']) # 'cubic[m3m]:{111}@1.0 + {110}@0.2'print(diamond['system']) # 'cubic'print(diamond['hardness']) # 10# List all presetsall_presets=list_presets()
# List presets by crystal systemcubic_presets=list_presets('cubic')
# Search presetsgarnet_matches=search_presets('garnet')- 216 CDL expressions across 159 mineral families (116 natural + 19 synthetic + 20 simulant + 4 composite)
- CDL v2.0 notation for crystal habit visualization, including amorphous, nested growth, and aggregate expressions
- FGA-standard properties (RI, SG, optical character, etc.)
- SQLite backend for fast queries
- Full-text search across mineral names and properties
- Backwards compatible with original
CRYSTAL_PRESETSdict API
The database includes presets for all major crystal systems:
| System | Count | Examples |
|---|---|---|
| Cubic | ~25 | Diamond, Garnet, Fluorite, Pyrite |
| Hexagonal | ~8 | Beryl, Emerald, Aquamarine, Apatite |
| Trigonal | ~15 | Quartz, Ruby, Sapphire, Tourmaline |
| Tetragonal | ~5 | Zircon, Rutile, Cassiterite |
| Orthorhombic | ~10 | Topaz, Peridot, Tanzanite |
| Monoclinic | ~10 | Kunzite, Epidote, Gypsum |
| Triclinic | ~5 | Turquoise, Kyanite, Labradorite |
| Amorphous | ~7 | Opal, Pearl, Malachite, Turquoise, Sodalite, Lazurite |
| Twins | ~15 | Japan Law, Spinel Macle, Iron Cross |
All 140 CDL expressions parse successfully with CDL v2.0, including:
- Amorphous expressions for materials without crystalline structure: opal (
amorphous[opalescent]:{botryoidal}), pearl, malachite, turquoise, sodalite, lazurite, rhodochrosite (banded form) - Nested growth expressions using the
>operator: scepter quartz, phantom quartz, diamond phantom - Aggregate expressions using the
~operator: quartz cluster, amethyst geode druse, pyrite cluster, fluorite cluster, calcite parallel growth - Doc comments (
#!) on major expressions documenting system, habit, and species information
The mineral database has been comprehensively enriched with FGA-standard gemmological data:
- 159 mineral families (116 natural + 19 synthetic + 20 simulant + 4 composite) with complete crystallographic data
- 92/95 minerals (96.8%) with complete RI (refractive index)
- 94/95 minerals (98.9%) with complete SG (specific gravity)
- 94/95 minerals (98.9%) with optical character classification
- 93/95 minerals (97.9%) with pleochroism data
- 94/95 minerals (98.9%) with lustre, cleavage, and fracture data
- 60/95 minerals (63.2%) with dispersion values
- 40+ gemstones with comprehensive treatments and diagnostic inclusions
| System | Minerals | RI | SG | Optical Character |
|---|---|---|---|---|
| Cubic | 26 | 92.3% | 100% | 100% |
| Trigonal | 19 | 100% | 100% | 100% |
| Monoclinic | 15 | 100% | 100% | 100% |
| Orthorhombic | 13 | 92.3% | 92.3% | 92.3% |
| Hexagonal | 8 | 100% | 100% | 100% |
| Triclinic | 7 | 100% | 100% | 100% |
| Tetragonal | 6 | 100% | 100% | 100% |
| Amorphous | 1 | 100% | 100% | 100% |
- FGA (Fellowship of the Gemmological Association) curriculum materials
- Mindat.org mineralogical database
- GIA (Gemological Institute of America) gem encyclopedia
- Webmineral.com physical property database
- International Gem Society reference materials
All data has been cross-validated against multiple authoritative sources and validated for consistency with crystal system optical properties.
frommineral_databaseimport (
get_preset, # Get preset dict by nameget_mineral, # Get Mineral object by namelist_presets, # List preset nameslist_preset_categories, # List categoriessearch_presets, # Full-text searchfilter_minerals, # Filter by criteriaget_presets_by_form, # Get by crystal formcount_presets, # Total count
)The package provides dict-like CRYSTAL_PRESETS for code migration:
frommineral_databaseimportCRYSTAL_PRESETS# All dict operations workpreset=CRYSTAL_PRESETS['diamond']
preset=CRYSTAL_PRESETS.get('ruby')
'garnet'inCRYSTAL_PRESETSfornameinCRYSTAL_PRESETS:
print(name)frommineral_databaseimportget_mineral, Mineralmineral=get_mineral('ruby')
print(mineral.id) # 'ruby'print(mineral.name) # 'Ruby'print(mineral.system) # 'trigonal'print(mineral.chemistry) # 'Al2O3:Cr'print(mineral.hardness) # 9print(mineral.ri) # '1.762-1.770'print(mineral.localities) # ['Myanmar', 'Mozambique', ...]frommineral_databaseimport (
INFO_GROUPS,
get_info_properties,
get_property_label,
format_property_value,
)
# Get FGA-style propertiesprops=get_info_properties('ruby', 'fga')
# Returns: {'name': 'Ruby', 'ri': '1.762-1.770', 'sg': 4.0, ...}# Format for displaylabel=get_property_label('sg') # 'SG'value=format_property_value('sg', 4.0) # '4'# List all presets
mineral-db --list
# List by crystal system
mineral-db --list cubic
# Show preset details
mineral-db --info diamond
# Search presets
mineral-db --search garnet
# Output as JSON
mineral-db --json ruby
# Show categories
mineral-db --categoriesThe SQLite database stores minerals with full gemmological properties:
# Core fields (all minerals)id, name, cdl, system, point_group, chemistry, hardness, description# Optional gemmological propertiessg, ri, birefringence, optical_character, dispersion, lustre,
cleavage, fracture, pleochroism, twin_law, phenomenon# List fields (JSON-encoded)localities, forms, colors, treatments, inclusionsFor development, you can rebuild the database from source:
# From legacy Python dict
python scripts/build_db.py --from-legacy crystal_presets.py -o minerals.db
# From YAML files
python scripts/build_db.py --from-yaml data/source/minerals -o minerals.db
# Export to YAML for editing
python scripts/build_db.py --export-yaml minerals.db -o data/source/minerals# Clone and install
git clone https://github.com/gemmology-dev/mineral-database.git
cd mineral-database
pip install -e ".[dev]"# Run tests
pytest
# Build database
python scripts/build_db.py --from-legacy /path/to/crystal_presets.py -o src/mineral_database/data/minerals.dbMIT License - see LICENSE for details.
- cdl-parser - CDL notation parser
- crystal-geometry - 3D geometry from CDL
- crystal-renderer - SVG/3D rendering
- gemmology-plugin - Claude Code plugin