lazou 0.1.0

Minimal real-time laser rendering engine

Lazou is a minimal real-time laser engine for Python.

It is built to stay simple first: define visuals, tweak params live, preview the result, and target laser outputs without falling back into the confusing all-in-one laser software culture inherited from the 2000s.

Quick Start ⚡

pip install lazou
lazou designs list
lazou simulate

That is enough to install Lazou from PyPI, browse the available designs, and run the current show in the simulator.

For local development:

uv sync --dev
uv run lazou simulate

Why Lazou

• simple JSON-driven workflow
• real-time parametric designs
• simulator-first development
• clean separation between geometry, compilation, and output
• made for experimentation, not legacy UI archaeology

Pipeline

flowchart LR
    A["designs/*.json"] --> C["design.generate(t, params)"]
    B["params.json"] --> C
    C --> D["Shapes"]
    D --> E["compile_scene"]
    E --> F["Laser Frame"]
    F --> G["Simulator"]
    F --> H["DAC Output"]

Lazou follows a simple pipeline: JSON selects a design and live params, the design generates intent-level shapes, the compiler turns them into a laser-ready frame, and that frame is sent to one or more outputs.

Highlights 🚀

• real-time design generation driven by t and live params
• intent-level shapes compiled into laser-friendly frames
• blanking, dwell, and interpolation handled in the compiler
• simulator preview with visible and blanked path rendering
• CLI tools for design inspection, simulation, and schema export

ParamMap

Runtime params are validated against a strict shared catalog.

Param	Type	Allowed Range / Rule	Meaning
speed	float	0..10	animation speed
size	float	0..1	normalized size or motion amount
rotation_speed	float	-10..10	rotational or phase speed
line_count	int	1..256	number of generated lines
color_hue	float	0..1	base hue in HSV space
brightness	int	0..255	output brightness
label	string	non-empty, max 40 chars	short design label
closed	bool	true or false	open or closed geometry

Designs may only use params they explicitly declare in their own params block, with a default value.

Example runtime file:

{
  "design": "moving-lines",
  "params": {
    "line_count": 12,
    "speed": 0.5,
    "color_hue": 0.62,
    "brightness": 220
  }
}

Design Preview 🎨

Preview one design before compilation:

lazou designs show diamond
lazou designs show orbit-diamond --time 1.5
lazou designs show moving-lines --set line_count=12 --set speed=0.5

--time is in seconds.

--set accepts params defined by the selected design. Values use JSON scalar syntax, so numbers and booleans keep their type.

Runtime

Run the simulator:

lazou simulate

Run without laser output:

lazou run --no-laser

Run one headless frame and print metrics:

lazou run --no-laser --no-simulator

Use a custom params file when needed:

lazou run my-show.json --no-laser
lazou simulate my-show.json

Useful runtime options:

lazou simulate --fps 60 --kps 30

Outputs

Lazou is designed around interchangeable outputs so the same compiled frame can eventually target different playback backends.

Output	Role	State
Simulator	2D preview for development and debugging	Ready
Helios DAC	Native hardware laser output	🚧
Ether Dream	Network laser DAC backend	🚧
RIYA DAC	USB DAC backend	🚧
LaserDock DAC	Compact USB DAC backend	🚧
Moncha.NET	Pangolin-compatible output target	🚧
OpenLase	Software laser output integration	🚧

Today, the simulator is the stable path. Hardware and external output backends are part of the roadmap and the output layer is being shaped to support them cleanly.

JSON Workflow

Starter files included in the repository:

designs/moving-lines.json
designs/chubby-cheek-cat.json
params.json

Export local JSON Schema files for editor autocomplete and validation:

lazou dev export-schemas

This writes:

schemas/design.schema.json
schemas/params.schema.json

Safety ⚠️

This project is educational and experimental. It is not production laser safety software. Treat real laser output as unsafe until hardware support and safety limits are implemented and tested.