How kojix2/orbits works
Purpose and Entry Points
orbits is a Crystal CLI that generates strange-attractor density images and renders them directly in terminals, as PNG, SIXEL, terminal graphics protocols, or ANSI Unicode text. Library loading begins at src/orbits.cr; the executable entry point is src/orbits_cli.cr. Command parsing and invocation orchestration live in src/orbits/cli.cr.
CLI Configuration and Reproducibility
The CLI selects an attractor (or randomizes one), accepts attractor-specific coefficients, image/raster controls, transforms, colormaps, output destinations, and rendering protocols. Seeded random parameter selection makes the full generated configuration reproducible. Presentation of resolved settings and persistence/display output are separated into src/orbits/cli/config_presenter.cr and src/orbits/cli/output_writer.cr, with randomization in src/orbits/random_params.cr.
Attractor Model Layer
Attractor implementations provide the iterative mathematical systems that generate orbit points. The shared attractor surface is organized under src/orbits/attractors.cr; concrete Clifford, De Jong, Hopalong, and Ikeda implementations are in src/orbits/attractors/clifford.cr, src/orbits/attractors/de_jong.cr, and src/orbits/attractors/ikeda.cr. Common domain data types are centralized in src/orbits/types.cr.
Orbit Generation and Rasterization
Generation converts selected attractor parameters into one or more independent orbit trajectories, including nearby starts. src/orbits/generator.cr is the computational generation boundary. Generated points are mapped into a bounded density raster according to configured size/window in src/orbits/raster.cr; this separates mathematical coordinates from pixel-space accumulation.
Image Transformation and Color Rendering
Post-generation transforms modify raster density before colorization, supporting modes such as linear, logarithmic, cubic, and equalized. This stage is implemented in src/orbits/xforms.cr. src/orbits/colormap.cr maps transformed values to named palettes, while src/orbits/renderer.cr coordinates raster-to-image rendering for the chosen output path.
Terminal Image Abstraction
src/term_image.cr provides a terminal-output subsystem independent of attractor generation. src/term_image/protocol.cr defines the protocol-facing abstraction, and src/term_image/detector.cr selects an available graphics protocol from environment/terminal capabilities. Concrete binary terminal graphics backends include src/term_image/iterm2.cr, src/term_image/kitty.cr, and src/term_image/sixel.cr; tmux-specific wrapping is handled by src/term_image/tmux.cr.
File and Text Output Boundaries
The image representation and PNG encoding are isolated from terminal protocol emission in src/term_image/image.cr and src/term_image/png.cr. When graphics protocols are unavailable or explicitly requested, ANSI truecolor Unicode renderers produce Braille or shaded text via src/term_image/text.cr. The CLI output writer decides whether the rendered result is emitted to the terminal or saved as formats such as PNG/SIXEL.
Runtime and Delivery
The project targets the Crystal runtime and uses Shards for dependency/build management (shard.yml). Build and test/release automation are defined in .github/workflows/test.yml and .github/workflows/release.yml. It relies on local terminal capabilities and environment signals rather than a network service or persistent backend.
Main entry points: attractors.cr Attractor model surface · cli.cr Command orchestration · output_writer.cr Output writer · term_image.cr Terminal image subsystem
Components 26
CLI and configuration
- CLI entry point
src/orbits_cli.cr - Command orchestration
src/orbits/cli.cr - Resolved settings
src/orbits/cli/config_presenter.cr - Seeded random parameters · Makes randomized configurations reproducible.
src/orbits/random_params.cr - Output writer
src/orbits/cli/output_writer.cr
Generation pipeline
- Library loader
src/orbits.cr - Attractor model surface · Unifies Clifford, De Jong, Hopalong, and Ikeda systems.
src/orbits/attractors.cr - Clifford attractor
src/orbits/attractors/clifford.cr - De Jong attractor
src/orbits/attractors/de_jong.cr - Ikeda attractor
src/orbits/attractors/ikeda.cr - Domain types
src/orbits/types.cr - Orbit generator · Generates independent trajectories including nearby starts.
src/orbits/generator.cr - Density rasterizer
src/orbits/raster.cr - Density transforms
src/orbits/xforms.cr - Palette mapping
src/orbits/colormap.cr - Image renderer
src/orbits/renderer.cr
Terminal output
- Terminal image subsystem · Independent of attractor generation.
src/term_image.cr - Graphics protocol abstraction
src/term_image/protocol.cr - Protocol detector · Selects a protocol from terminal and environment signals.
src/term_image/detector.cr - Binary graphics backends
- tmux wrapper
src/term_image/tmux.cr - Image representation
src/term_image/image.cr - PNG encoder
src/term_image/png.cr - ANSI Unicode renderer · Renders Braille or shaded truecolor text.
src/term_image/text.cr
Runtime and delivery
- Crystal and Shards
shard.yml - CI and release automation
.github/workflows/test.yml
Connections 26
- CLI entry point → Command orchestration: starts
- Library loader → Attractor model surface: loads
- Command orchestration → Seeded random parameters: randomizes
- Command orchestration → Resolved settings: presents config
- Command orchestration → Attractor model surface: selects
- Attractor model surface → Clifford attractor: implements
- Attractor model surface → De Jong attractor: implements
- Attractor model surface → Ikeda attractor: implements
- Attractor model surface → Orbit generator: iterates
- Domain types → Attractor model surface: defines domain data
- Orbit generator → Density rasterizer: orbit points
- Density rasterizer → Density transforms: density raster
- Density transforms → Palette mapping: transformed values
- Palette mapping → Image renderer: colored pixels
- Image renderer → Image representation: builds image
- Command orchestration → Output writer: routes result
- Output writer → Terminal image subsystem: emits terminal output
- Output writer → PNG encoder: saves PNG
- Terminal image subsystem → Protocol detector: detects capabilities
- Protocol detector → Graphics protocol abstraction: selects
- Graphics protocol abstraction → Binary graphics backends: uses
- Binary graphics backends → tmux wrapper: wraps when needed
- Terminal image subsystem → ANSI Unicode renderer: falls back to
- Image representation → PNG encoder: encodes
- Crystal and Shards → CLI entry point: builds
- CI and release automation → Crystal and Shards: tests and releases