253 lines
9.3 KiB
Python
253 lines
9.3 KiB
Python
"""Operations behind the CLI and the MCP server."""
|
||
|
||
from __future__ import annotations
|
||
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
from patternstudio.efx import (
|
||
ALGORITHMS,
|
||
DIRECTIONS,
|
||
PROPAGATIONS,
|
||
RUN_ORDERS,
|
||
Efx,
|
||
EfxFixture,
|
||
Path as EfxPath,
|
||
PathFixture,
|
||
PathPoint,
|
||
)
|
||
from patternstudio.fixturedefs import load_fixture_def
|
||
|
||
from .play import load_show, play
|
||
from .spec import PROJECT_ROOT, SpecError, collect_errors, from_spec, show_schema
|
||
|
||
__all__ = [
|
||
"list_fixtures",
|
||
"sample_animation",
|
||
"show_schema",
|
||
"validate_show",
|
||
"write_show",
|
||
"run_script",
|
||
]
|
||
|
||
|
||
def list_fixtures(root: Path | None = None) -> dict[str, Any]:
|
||
"""Manufacturer, model, modes, and channel maps from the project's fixtures/ directory."""
|
||
folder = (root or PROJECT_ROOT) / "fixtures"
|
||
fixtures = []
|
||
if folder.is_dir():
|
||
for path in sorted(folder.glob("*.qxf")):
|
||
definition = load_fixture_def(str(path))
|
||
fixtures.append(
|
||
{
|
||
"manufacturer": definition.manufacturer,
|
||
"model": definition.model,
|
||
"type": definition.type,
|
||
"modes": [
|
||
{
|
||
"name": mode.name,
|
||
"pan_msb": mode.pan_msb,
|
||
"pan_lsb": mode.pan_lsb,
|
||
"tilt_msb": mode.tilt_msb,
|
||
"tilt_lsb": mode.tilt_lsb,
|
||
"channels": [
|
||
{"index": ch.index, "name": ch.name, "preset": ch.preset, "group": ch.group}
|
||
for ch in mode.channels
|
||
],
|
||
}
|
||
for mode in definition.modes.values()
|
||
],
|
||
}
|
||
)
|
||
return {"fixtures": fixtures}
|
||
|
||
|
||
def validate_show(spec: dict[str, Any], root: Path | None = None) -> dict[str, Any]:
|
||
"""Check a show spec. Writes nothing."""
|
||
errors = collect_errors(spec, root=root)
|
||
return {"ok": not errors, "errors": errors}
|
||
|
||
|
||
def write_show(spec: dict[str, Any], path: str, root: Path | None = None) -> dict[str, Any]:
|
||
"""Write a .qxw inside the project and return the ids that were assigned."""
|
||
base = (root or PROJECT_ROOT).resolve()
|
||
try:
|
||
target = _inside(base, path)
|
||
show = from_spec(spec, root=base)
|
||
except SpecError as exc:
|
||
return {"ok": False, "errors": exc.errors}
|
||
target.parent.mkdir(parents=True, exist_ok=True)
|
||
show.write(target)
|
||
return {"ok": True, "path": str(target.relative_to(base)), **show.summary()}
|
||
|
||
|
||
def sample_animation(block: dict[str, Any], steps: int = 32) -> dict[str, Any]:
|
||
"""Pan/tilt samples for one efx or path block, before it is written into a show."""
|
||
if not isinstance(block, dict) or block.get("type") not in ("efx", "path"):
|
||
return {"ok": False, "errors": [{"path": "type", "message": "sample an efx or path block"}]}
|
||
count = max(1, min(128, int(steps)))
|
||
try:
|
||
if block["type"] == "efx":
|
||
return {"ok": True, **_sample_efx(block, count)}
|
||
return {"ok": True, **_sample_path(block)}
|
||
except (KeyError, TypeError, ValueError) as exc:
|
||
return {"ok": False, "errors": [{"path": "", "message": str(exc)}]}
|
||
|
||
|
||
def run_script(
|
||
path: str,
|
||
*,
|
||
seconds: float | None = None,
|
||
ip: str | None = None,
|
||
universe: int = 0,
|
||
hz: float = 40.0,
|
||
root: Path | None = None,
|
||
) -> dict[str, Any]:
|
||
"""Play a Python build() script, or a JSON spec, and return samples or send Art-Net."""
|
||
base = (root or PROJECT_ROOT).resolve()
|
||
try:
|
||
source = _inside(base, path)
|
||
show = load_show(source)
|
||
return play(show, seconds=seconds, ip=ip, universe=universe, hz=hz)
|
||
except SpecError as exc:
|
||
return {"ok": False, "errors": exc.errors}
|
||
|
||
|
||
def _inside(root: Path, rel: str) -> Path:
|
||
candidate = Path(rel)
|
||
target = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
|
||
if target != root and root not in target.parents:
|
||
raise SpecError([{"path": "path", "message": f"{rel} is outside the project"}])
|
||
return target
|
||
|
||
|
||
def _sample_efx(block: dict[str, Any], steps: int) -> dict[str, Any]:
|
||
algorithm = block.get("algorithm", "Circle")
|
||
if algorithm not in ALGORITHMS:
|
||
raise ValueError(f"unknown algorithm {algorithm!r}")
|
||
_choice(block.get("direction", "Forward"), DIRECTIONS, "direction")
|
||
_choice(block.get("run_order", "Loop"), RUN_ORDERS, "run_order")
|
||
_choice(block.get("propagation", "Parallel"), PROPAGATIONS, "propagation")
|
||
entries = block.get("fixtures") or []
|
||
if not entries:
|
||
raise ValueError("efx has no fixtures")
|
||
relative = bool(block.get("relative"))
|
||
homes = block.get("homes") or {}
|
||
fixtures = []
|
||
keys = []
|
||
for index, item in enumerate(entries):
|
||
if isinstance(item, str):
|
||
key, direction, offset = item, "Forward", 0
|
||
pan = tilt = 128
|
||
elif isinstance(item, dict) and "fixture" in item:
|
||
key = str(item["fixture"])
|
||
direction = item.get("direction", "Forward")
|
||
offset = int(item.get("start_offset", 0))
|
||
pan = int(item.get("pan", 128))
|
||
tilt = int(item.get("tilt", 128))
|
||
else:
|
||
raise ValueError("each efx fixture is a key or {fixture, ...}")
|
||
if key in homes:
|
||
pan, tilt = int(homes[key][0]), int(homes[key][1])
|
||
keys.append(key)
|
||
fixtures.append(EfxFixture(id=index, direction=direction, start_offset=offset, pan=pan, tilt=tilt))
|
||
width = _bounded(block.get("width", 40), 0, 127, "width")
|
||
height = _bounded(block.get("height", 40), 0, 127, "height")
|
||
duration = int(block.get("duration_ms", 8000))
|
||
if duration < 20:
|
||
raise ValueError("duration_ms must be at least 20")
|
||
pattern = Efx(
|
||
algorithm=algorithm,
|
||
width=width,
|
||
height=height,
|
||
rotation=int(block.get("rotation", 0)) % 360,
|
||
start_offset=int(block.get("start_offset", 0)) % 360,
|
||
x_offset=127 if relative else _bounded(block.get("x_offset", 128), 0, 255, "x_offset"),
|
||
y_offset=127 if relative else _bounded(block.get("y_offset", 128), 0, 255, "y_offset"),
|
||
x_frequency=_bounded(block.get("x_frequency", 1), 0, 5, "x_frequency"),
|
||
y_frequency=_bounded(block.get("y_frequency", 1), 0, 5, "y_frequency"),
|
||
x_phase=int(block.get("x_phase", 0)) % 360,
|
||
y_phase=int(block.get("y_phase", 0)) % 360,
|
||
duration_ms=duration,
|
||
direction=block.get("direction", "Forward"),
|
||
run_order=block.get("run_order", "Loop"),
|
||
propagation=block.get("propagation", "Parallel"),
|
||
relative=relative,
|
||
fixtures=fixtures,
|
||
)
|
||
sampled = pattern.sample(steps=steps)
|
||
for track, fx in zip(sampled["tracks"], fixtures):
|
||
track["key"] = keys[fx.id]
|
||
if relative:
|
||
track["points"] = [
|
||
[
|
||
round(max(0.0, min(255.0, fx.pan + (x - 127))), 2),
|
||
round(max(0.0, min(255.0, fx.tilt + (y - 127))), 2),
|
||
]
|
||
for x, y in track["points"]
|
||
]
|
||
return sampled
|
||
|
||
|
||
def _sample_path(block: dict[str, Any]) -> dict[str, Any]:
|
||
entries = block.get("fixtures") or []
|
||
points = block.get("points") or []
|
||
if not entries or not points:
|
||
raise ValueError("path needs fixtures and points")
|
||
fixtures = []
|
||
keys = []
|
||
for index, item in enumerate(entries):
|
||
if isinstance(item, str):
|
||
key, pan_offset, tilt_offset, mirror_pan, mirror_tilt = item, 0, 0, False, False
|
||
elif isinstance(item, dict):
|
||
key = str(item["fixture"])
|
||
pan_offset = int(item.get("pan_offset", 0))
|
||
tilt_offset = int(item.get("tilt_offset", 0))
|
||
mirror_pan = bool(item.get("mirror_pan", False))
|
||
mirror_tilt = bool(item.get("mirror_tilt", False))
|
||
else:
|
||
raise ValueError("each path fixture is a key or {fixture, mirror_pan}")
|
||
keys.append(key)
|
||
fixtures.append(
|
||
PathFixture(
|
||
id=index,
|
||
pan_offset=pan_offset,
|
||
tilt_offset=tilt_offset,
|
||
mirror_pan=mirror_pan,
|
||
mirror_tilt=mirror_tilt,
|
||
)
|
||
)
|
||
path = EfxPath(
|
||
points=[
|
||
PathPoint(
|
||
pan=float(point["pan"]),
|
||
tilt=float(point["tilt"]),
|
||
fade_ms=int(point.get("fade_ms", 1000)),
|
||
hold_ms=int(point.get("hold_ms", 0)),
|
||
)
|
||
for point in points
|
||
],
|
||
smooth=bool(block.get("smooth", False)),
|
||
subdivisions=int(block.get("subdivisions", 6)),
|
||
closed=bool(block.get("closed", True)),
|
||
run_order=block.get("run_order", "Loop"),
|
||
direction=block.get("direction", "Forward"),
|
||
fixtures=fixtures,
|
||
)
|
||
sampled = path.sample()
|
||
for track in sampled["tracks"]:
|
||
track["key"] = keys[track["id"]]
|
||
return sampled
|
||
|
||
|
||
def _choice(value: str, allowed: tuple[str, ...], label: str) -> None:
|
||
if value not in allowed:
|
||
raise ValueError(f"{label} must be one of {', '.join(allowed)}")
|
||
|
||
|
||
def _bounded(value: Any, lo: int, hi: int, label: str) -> int:
|
||
number = int(value)
|
||
if not lo <= number <= hi:
|
||
raise ValueError(f"{label} must be {lo}–{hi}")
|
||
return number
|