How kjkoeller/glyphx works
Purpose and public entry points
GlyphX is a Python 3.12+ visualization library that produces SVG-first charts, self-contained interactive HTML, and optional raster/PPTX exports. Its principal APIs are package imports and one-line plotting in glyphx/__init__.py, figure construction in glyphx/figure.py, 3-D construction in glyphx/figure3d.py, DataFrame integration in glyphx/accessor.py, and terminal commands in glyphx/cli.py.
Figure composition model
Figure is the central 2-D orchestration object: it owns chart state, series, axes/subplots, theme, annotations, layout, display, and persistence. Axes provides the coordinate-system and subplot boundary; Series classes represent chart-specific data and SVG emission contracts. Core paths: glyphx/figure.py, glyphx/axes.py, glyphx/series.py.
Control flow is generally: caller/API adapter → Figure/Axes configuration → add one or more series → layout/scale calculation → SVG rendering → optional HTML wrapping or file export.
Plot-type implementation layer
Chart types are distributed as specialized series modules rather than a monolithic renderer. Basic series are concentrated in glyphx/series.py; specialized statistical, financial, hierarchical, and composite visualizations each have dedicated implementations such as glyphx/ecdf.py, glyphx/candlestick.py, and glyphx/treemap.py. This lets the Figure pipeline treat heterogeneous visualizations through a common add/render interface.
Convenience dispatch lives in glyphx/plot.py; dataframe-oriented selection, grouping, aggregation, and hue splitting are handled at the pandas boundary by glyphx/accessor.py and glyphx/hue_mixin.py.
Rendering, HTML, and browser interaction
SVG rendering is separated from output packaging and browser behavior. Rendering support is centered on glyphx/renderer.py; HTML/SVG augmentation and export capabilities reside in glyphx/assets/ and glyphx/figure.py. Browser-side interactivity is shipped as local JavaScript assets, including glyphx/assets/tooltip.js, glyphx/assets/zoom.js, and glyphx/assets/brush.js, enabling offline self-contained HTML rather than requiring a chart server or CDN.
Accessibility is a first-class rendering concern through glyphx/a11y.py plus glyphx/assets/accessibility.js, producing ARIA metadata and keyboard interactions alongside visual output.
Performance and real-time paths
Large-data preprocessing occurs before SVG generation. glyphx/downsample.py implements the common 2-D/3-D thinning and decimation algorithms, while series retain rendering/downsampling metadata. Streaming charts use a mutable series and live-refresh control path in glyphx/streaming.py, without a required server runtime.
3-D pipeline
3-D charts use a separate figure and series family: glyphx/figure3d.py, glyphx/plot3d.py, and glyphx/projection3d.py, with concrete series in files such as glyphx/scatter3d.py and glyphx/surface3d.py. This boundary supports interactive WebGL-oriented HTML output with SVG fallback and applies 3-D-specific camera-aware/downsampling behavior.
External dependencies and delivery
Core runtime relies on NumPy and pandas. Optional export integrations require CairoSVG and python-pptx; natural-language chart generation in glyphx/nlp.py uses Anthropic and an API key. Distribution is Python packaging via pyproject.toml and setup.cfg; CI and PyPI publishing are defined in .github/workflows/ci_tests.yml and .github/workflows/python-publish.yml.
Main entry points: figure.py Figure · renderer.py SVG renderer · figure3d.py Figure3D · scatter3d.py 3-D series
Components 21
Public APIs
- Package API · One-line plotting and package imports.
glyphx/__init__.py - Plot dispatch
glyphx/plot.py - DataFrame accessor · Selects, groups, aggregates, and splits data by hue.
glyphx/accessor.py - CLI
glyphx/cli.py - Natural-language charts · Uses Anthropic with an API key.
glyphx/nlp.py
2-D Chart Pipeline
- Figure · Owns chart state, layout, display, and persistence.
glyphx/figure.py - Axes & subplots
glyphx/axes.py - Core series · Common chart data and SVG emission interface.
glyphx/series.py - Specialized series · Statistical, financial, hierarchical, and composite charts.
glyphx/ecdf.py - Hue splitting
glyphx/hue_mixin.py - Downsampling · 2-D and 3-D thinning and decimation.
glyphx/downsample.py - Streaming charts · Mutable series with local live refresh control.
glyphx/streaming.py
Rendering & Output
- SVG renderer
glyphx/renderer.py - HTML interaction assets · Offline tooltip, zoom, and brush behavior.
glyphx/assets/tooltip.js - Accessibility · Adds ARIA metadata and keyboard interaction.
glyphx/a11y.py
3-D Pipeline
- Figure3D
glyphx/figure3d.py - 3-D plot dispatch
glyphx/plot3d.py - 3-D projection · Camera-aware projection and rendering behavior.
glyphx/projection3d.py - 3-D series · Includes scatter and surface chart families.
glyphx/scatter3d.py
Distribution
- Python packaging
pyproject.toml - CI & PyPI publishing
.github/workflows/python-publish.yml
Connections 21
- Package API → Plot dispatch: exposes
- Plot dispatch → Figure: constructs
- DataFrame accessor → Hue splitting: uses
- DataFrame accessor → Figure: adapts data into
- CLI → Figure: drives
- Figure → Axes & subplots: manages
- Figure → Core series: adds and coordinates
- Figure → Specialized series: accepts
- Core series → Downsampling: preprocesses large data
- Specialized series → Downsampling: uses
- Streaming charts → Core series: mutates
- Figure → SVG renderer: lays out then renders
- SVG renderer → HTML interaction assets: packages SVG with
- SVG renderer → Accessibility: augments with
- 3-D plot dispatch → Figure3D: constructs
- Figure3D → 3-D series: coordinates
- 3-D series → 3-D projection: uses
- 3-D series → Downsampling: uses
- Figure3D → SVG renderer: WebGL HTML or SVG fallback
- Python packaging → CI & PyPI publishing: released by
- Natural-language charts → Figure: generates charts through