crystal-renderer

Render crystal geometry to SVG for visualization, STL for 3D printing, and glTF for web/AR/VR applications. Version 1.0.1.

pip install gemmology-crystal-renderer

SVG Rendering

# generate_cdl_svg(cdl_string, output_path, **options) → Path

Generate an SVG visualization directly from a CDL string. This is the primary rendering function - it parses the CDL, generates geometry, and renders to SVG in one call.

from crystal_renderer import generate_cdl_svg

# Basic octahedron
generate_cdl_svg("cubic[m3m]:{111}", "diamond.svg")

# Truncated octahedron with options
generate_cdl_svg(
    "cubic[m3m]:{111}@1.0 + {100}@1.3",
    "truncated.svg",
    elev=30,
    azim=-45,
    color_by_form=True,
    show_grid=False,
    figsize=(10, 10),
    dpi=150,
)

# With face labels and info panel
generate_cdl_svg(
    "cubic[m3m]:{111}@1.0 + {100}@1.3",
    "labelled.svg",
    face_labels=True,
    info_properties={"Name": "Diamond", "System": "Cubic"},
)

Parameters

Parameter	Type	Default	Description
`cdl_string`	`str`	`Required`	CDL notation string
`output_path`	`str \| Path`	`Required`	Output SVG file path
`show_axes`	`bool`	`True`	Show crystallographic axes
`elev`	`float`	`30`	Elevation angle in degrees
`azim`	`float`	`-45`	Azimuth angle in degrees
`color_by_form`	`bool`	`False`	Color faces by which form they belong to
`show_grid`	`bool`	`True`	Show background grid and panes
`face_labels`	`bool`	`False`	Show Miller index labels on visible faces
`info_properties`	`dict \| None`	`None`	Dictionary of properties for info panel
`info_position`	`str`	`"top-right"`	Info panel position
`info_style`	`str`	`"compact"`	Panel style: compact, detailed, or minimal
`info_fontsize`	`int`	`10`	Font size for info panel
`figsize`	`tuple[int, int]`	`(10, 10)`	Figure size in inches
`dpi`	`int`	`150`	Output resolution in DPI
`c_ratio`	`float \| None`	`None`	c/a ratio for non-cubic systems (default 1.1 for trigonal/hexagonal)

# generate_geometry_svg(vertices, faces, output_path, **options) → Path

Generate an SVG from raw geometry data (vertices and faces). Use this when you already have computed geometry and want control over face/edge colours.

from crystal_renderer import generate_geometry_svg
from crystal_geometry import cdl_to_geometry
from cdl_parser import parse_cdl

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

generate_geometry_svg(
    geom.vertices,
    geom.faces,
    "crystal.svg",
    face_color="#81D4FA",
    edge_color="#0277BD",
    title="Octahedron",
    show_axes=True,
)

Parameters

Parameter	Type	Default	Description
`vertices`	`np.ndarray`	`Required`	Nx3 array of vertex positions
`faces`	`list[list[int]]`	`Required`	List of faces (vertex index lists)
`output_path`	`str \| Path`	`Required`	Output SVG file path
`face_normals`	`list \| None`	`None`	Optional face normal vectors
`show_axes`	`bool`	`True`	Show crystallographic axes
`elev`	`float`	`30`	Elevation angle in degrees
`azim`	`float`	`-45`	Azimuth angle in degrees
`show_grid`	`bool`	`True`	Show background grid and panes
`face_color`	`str`	`"#81D4FA"`	Face fill color (hex)
`edge_color`	`str`	`"#0277BD"`	Edge stroke color (hex)
`title`	`str \| None`	`None`	Optional title text
`info_properties`	`dict \| None`	`None`	Properties for info panel
`figsize`	`tuple[int, int]`	`(10, 10)`	Figure size in inches
`dpi`	`int`	`150`	Output resolution in DPI

3D Export

# export_stl(vertices, faces, output_path, binary=True) → Path

Export crystal geometry to STL format for 3D printing. Takes raw vertices and faces, not a geometry object.

from crystal_renderer import export_stl
from crystal_geometry import cdl_to_geometry
from cdl_parser import parse_cdl

desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
geom = cdl_to_geometry(desc)

# Binary STL (smaller file)
export_stl(geom.vertices, geom.faces, "crystal.stl")

# ASCII STL (human-readable)
export_stl(geom.vertices, geom.faces, "crystal.stl", binary=False)

# geometry_to_stl(vertices, faces, binary=True) → bytes

Convert geometry to STL format in memory, returning the file content as bytes.

# export_gltf(vertices, faces, output_path, color=None, name='crystal') → Path

Export crystal geometry to glTF 2.0 format for web, AR, and VR applications. Stores original polygon edges in extras.crystalEdges for accurate edge rendering.

from crystal_renderer import export_gltf
from crystal_geometry import cdl_to_geometry
from cdl_parser import parse_cdl

desc = parse_cdl("cubic[m3m]:{111}@1.0 + {100}@1.3")
geom = cdl_to_geometry(desc)

# Basic export
export_gltf(geom.vertices, geom.faces, "crystal.gltf")

# With RGBA colour
export_gltf(
    geom.vertices,
    geom.faces,
    "crystal.gltf",
    color=(0.05, 0.65, 0.91, 0.8),  # RGBA (0-1)
    name="diamond",
)

# geometry_to_gltf(vertices, faces, color=None, name='crystal') → dict

Convert geometry to glTF format in memory, returning the glTF JSON structure.

Format Conversion

# convert_svg_to_raster(svg_path, output_path, output_format='png', scale=2.0, quality=95) → Path

Convert an SVG file to raster format (PNG, JPG, or BMP). Requires the raster optional dependencies.

from crystal_renderer import convert_svg_to_raster, generate_cdl_svg

# Generate SVG first
generate_cdl_svg("cubic[m3m]:{111}", "crystal.svg")

# Convert to PNG (2x scale for high resolution)
convert_svg_to_raster("crystal.svg", "crystal.png", scale=2.0)

# Convert to JPEG with quality setting
convert_svg_to_raster("crystal.svg", "crystal.jpg", output_format="jpg", quality=90)

pip install gemmology-crystal-renderer[raster]

# generate_with_format(generator_func, output_path, output_format='svg', scale=2.0, quality=95, **kwargs) → Path

Generate a crystal visualization in any supported format. Wraps a generator function, automatically converting through SVG for raster outputs.

Info Panel

# render_info_panel(ax, properties, position='top-right', style='compact', fontsize=10)

Render a properties info panel on a matplotlib axes.

# create_fga_info_panel(preset) → dict

Create an FGA-style info panel dictionary from a mineral preset.

Rendering Primitives

Low-level drawing functions for building custom visualizations:

from crystal_renderer import (
    draw_crystallographic_axes,
    draw_unit_cell_box,
    draw_atoms,
    draw_bonds,
    draw_atom_labels,
    draw_coordination_polyhedra,
    draw_legend,
    set_axes_equal,
    hide_axes_and_grid,
    blend_colors,
    get_element_colour,
    get_element_radius,
)

Projection Utilities

Functions for 3D-to-2D projection and visibility calculations:

from crystal_renderer import (
    calculate_view_direction,
    calculate_vertex_visibility,
    calculate_axis_origin,
    calculate_view_bounds,
    calculate_face_normal,
    calculate_face_center,
    calculate_bounding_box,
    is_face_visible,
    cell_to_vectors,
)

Constants

from crystal_renderer import (
    FORM_COLORS,         # Colour palette for form-based colouring
    HABIT_COLOURS,       # Colours keyed by crystal system
    AXIS_COLOURS,        # Crystallographic axis colours
    ELEMENT_COLOURS,     # Element colours for atomic rendering
    CRYSTAL_SYSTEMS,     # Crystal system metadata
    TWIN_COLOURS,        # Twin-specific colours
    CLEAVAGE_COLOUR,     # Cleavage plane colour
    PROPERTY_LABELS,     # Info panel property labels
)