Metadata-Version: 2.4
Name: lazou
Version: 0.1.0
Summary: Minimal real-time laser rendering engine
Author: fregogui
License-Expression: MIT
Project-URL: Homepage, https://github.com/fregogui/lazou
Project-URL: Repository, https://github.com/fregogui/lazou
Project-URL: Issues, https://github.com/fregogui/lazou/issues
Keywords: laser,simulator,ilda,generative-art,creative-coding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4.4
Requires-Dist: pydantic>=2.13.3
Requires-Dist: pyglet>=2.1.14
Requires-Dist: typer>=0.25.1
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="Lazou logo" width="220">
</p>

<p align="center">
  <a href="https://github.com/fregogui/lazou/actions/workflows/tests.yml">
    <img src="https://github.com/fregogui/lazou/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests">
  </a>
  <a href="https://github.com/fregogui/lazou/actions/workflows/lint.yml">
    <img src="https://github.com/fregogui/lazou/actions/workflows/lint.yml/badge.svg?branch=main" alt="Lint">
  </a>
  <a href="https://github.com/fregogui/lazou/actions/workflows/typecheck.yml">
    <img src="https://github.com/fregogui/lazou/actions/workflows/typecheck.yml/badge.svg?branch=main" alt="Type Check">
  </a>
  <img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+">
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
  </a>
</p>

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 ⚡

```bash
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:

```bash
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

```mermaid
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:

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

## Design Preview 🎨

Preview one design before compilation:

```bash
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:

```bash
lazou simulate
```

Run without laser output:

```bash
lazou run --no-laser
```

Run one headless frame and print metrics:

```bash
lazou run --no-laser --no-simulator
```

Use a custom params file when needed:

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

Useful runtime options:

```bash
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:

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

Export local JSON Schema files for editor autocomplete and validation:

```bash
lazou dev export-schemas
```

This writes:

```text
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.
