Add Pattern Studio, SMC-PAD MIDI helpers, and the current venue workspaces.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
jimmyandCursor committed 2026-10-20 15:05:04 +13:00
1 parent 55a38478db
commit 12420bec93
19 files changed
+8954

No files matched your search

+418
View File
@@ -0,0 +1,418 @@
"""Pattern maths.
`EFX*` is a faithful port of QLC+ 4.12 `EFX::calculatePoint` / `rotateAndScale`
/ `EFXFixture::timeOffset`, so the preview here matches what QLC+ renders.
`Path*` samples a list of waypoints (optionally Catmull-Rom smoothed) into
keyframes that become a QLC+ Sequence.
Both produce the same output shape — a list of per-fixture keyframe tracks —
so the browser preview and the live Art-Net preview share one code path.
"""
from __future__ import annotations
import math
from dataclasses import dataclass, field
from typing import Any
ALGORITHMS = (
"Circle",
"Eight",
"Line",
"Line2",
"Diamond",
"Square",
"SquareChoppy",
"Leaf",
"Lissajous",
)
DIRECTIONS = ("Forward", "Backward")
RUN_ORDERS = ("Loop", "SingleShot", "PingPong")
PROPAGATIONS = ("Parallel", "Serial", "Asymmetric")
RELATIVE_ZERO = 127
PREVIEW_STEPS = 128 # same as EFX::preview
def clamp(v: float, lo: float = 0, hi: float = 255) -> float:
return max(lo, min(hi, v))
def clamp8(v: float) -> int:
return int(clamp(round(v)))
# --------------------------------------------------------------------------- EFX
@dataclass
class EfxFixture:
id: int
head: int = 0
direction: str = "Forward"
start_offset: int = 0
# Only used when `relative` is on: absolute home aim written to the base Scene.
pan: int = 128
tilt: int = 128
@classmethod
def from_dict(cls, d: dict[str, Any]) -> "EfxFixture":
return cls(
id=int(d["id"]),
head=int(d.get("head", 0)),
direction="Backward" if d.get("direction") == "Backward" else "Forward",
start_offset=int(d.get("start_offset", 0)) % 360,
pan=clamp8(d.get("pan", 128)),
tilt=clamp8(d.get("tilt", 128)),
)
@dataclass
class Efx:
algorithm: str = "Circle"
width: int = 40
height: int = 40
rotation: int = 0
start_offset: int = 0
x_offset: int = 128
y_offset: int = 128
x_frequency: int = 1
y_frequency: int = 1
x_phase: int = 0
y_phase: int = 0
duration_ms: int = 8000
fade_in_ms: int = 0
fade_out_ms: int = 0
direction: str = "Forward"
run_order: str = "Loop"
propagation: str = "Parallel"
relative: bool = False
fixtures: list[EfxFixture] = field(default_factory=list)
@classmethod
def from_dict(cls, d: dict[str, Any]) -> "Efx":
alg = d.get("algorithm", "Circle")
if alg not in ALGORITHMS:
raise ValueError(f"unknown algorithm {alg!r}")
return cls(
algorithm=alg,
width=int(clamp(int(d.get("width", 40)), 0, 127)),
height=int(clamp(int(d.get("height", 40)), 0, 127)),
rotation=int(d.get("rotation", 0)) % 360,
start_offset=int(d.get("start_offset", 0)) % 360,
x_offset=clamp8(d.get("x_offset", 128)),
y_offset=clamp8(d.get("y_offset", 128)),
x_frequency=int(clamp(int(d.get("x_frequency", 1)), 0, 5)),
y_frequency=int(clamp(int(d.get("y_frequency", 1)), 0, 5)),
x_phase=int(d.get("x_phase", 0)) % 360,
y_phase=int(d.get("y_phase", 0)) % 360,
duration_ms=max(20, int(d.get("duration_ms", 8000))),
fade_in_ms=max(0, int(d.get("fade_in_ms", 0))),
fade_out_ms=max(0, int(d.get("fade_out_ms", 0))),
direction=d.get("direction") if d.get("direction") in DIRECTIONS else "Forward",
run_order=d.get("run_order") if d.get("run_order") in RUN_ORDERS else "Loop",
propagation=d.get("propagation") if d.get("propagation") in PROPAGATIONS else "Parallel",
relative=bool(d.get("relative", False)),
fixtures=[EfxFixture.from_dict(f) for f in d.get("fixtures", [])],
)
# -- QLC+ port ---------------------------------------------------------
def _direction_iterator(self, fixture_dir: str, it: float) -> float:
if fixture_dir == self.direction:
return it
if self.algorithm == "Line":
return it - math.pi if it > math.pi else it + math.pi
return 2.0 * math.pi - it
def _raw_point(self, it: float) -> tuple[float, float]:
a = self.algorithm
if a == "Circle":
return math.cos(it + math.pi / 2), math.cos(it)
if a == "Eight":
return math.cos(it * 2 + math.pi / 2), math.cos(it)
if a == "Line":
return math.cos(it), math.cos(it)
if a == "Line2":
v = it / math.pi - 1
return v, v
if a == "Diamond":
return math.cos(it - math.pi / 2) ** 3, math.cos(it) ** 3
if a == "Square":
h = math.pi / 2
if it < h:
return (it * 2 / math.pi) * 2 - 1, 1.0
if it < math.pi:
return 1.0, (1 - (it - h) * 2 / math.pi) * 2 - 1
if it < math.pi * 1.5:
return (1 - (it - math.pi) * 2 / math.pi) * 2 - 1, -1.0
return -1.0, ((it - math.pi * 1.5) * 2 / math.pi) * 2 - 1
if a == "SquareChoppy":
return float(round(math.cos(it))), float(round(math.sin(it)))
if a == "Leaf":
return math.cos(it + math.pi / 2) ** 5, math.cos(it)
if a == "Lissajous":
return (
self._lissajous_axis(it, self.x_frequency, math.radians(self.x_phase)),
self._lissajous_axis(it, self.y_frequency, math.radians(self.y_phase)),
)
raise ValueError(a)
@staticmethod
def _lissajous_axis(it: float, freq: int, phase: float) -> float:
if freq > 0:
return math.cos(freq * it - phase)
# Frequency 0 = triangle wave (QLC+ "linear" axis).
it0 = (it + phase) / math.pi
fff = int(it0)
it0 -= fff - fff % 2
forward = 1 - math.floor(it0)
backward = 1 - forward
it0 -= math.floor(it0)
return (forward * it0 + backward * (1 - it0)) * 2 - 1
def point(self, fixture_dir: str, fixture_offset: int, it: float) -> tuple[float, float]:
"""Pan/tilt (0–255 float) for iterator `it` in 0..2π — EFX::calculatePoint."""
it = self._direction_iterator(fixture_dir, it)
it += math.radians((fixture_offset + self.start_offset) % 360)
if it >= 2 * math.pi:
it -= 2 * math.pi
x, y = self._raw_point(it)
r = math.radians(self.rotation)
c, s = math.cos(r), math.sin(r)
px = self.x_offset + x * c * self.width + y * s * self.height
py = self.y_offset + -x * s * self.width + y * c * self.height
return clamp(px), clamp(py)
def time_offset_ms(self, serial: int) -> int:
if self.propagation in ("Serial", "Asymmetric"):
return self.duration_ms // (len(self.fixtures) + 1) * serial
return 0
def sample(self, steps: int = PREVIEW_STEPS) -> dict[str, Any]:
tracks = []
for serial, fx in enumerate(self.fixtures):
pts = []
for i in range(steps):
it = 2 * math.pi * i / steps
px, py = self.point(fx.direction, fx.start_offset, it)
pts.append([round(px, 2), round(py, 2)])
tracks.append(
{
"id": fx.id,
"head": fx.head,
"points": pts,
# Asymmetric: shifted in phase, starts immediately.
# Serial: shifted in phase AND waits before starting.
"time_offset_ms": self.time_offset_ms(serial),
"start_delay_ms": self.time_offset_ms(serial) if self.propagation == "Serial" else 0,
}
)
return {
"kind": "efx",
"loop_ms": self.duration_ms,
"run_order": self.run_order,
"relative": self.relative,
"tracks": tracks,
}
def live_point(self, serial: int, elapsed_ms: float) -> tuple[float, float] | None:
"""Pan/tilt for a running fixture at wall time — EFXFixture::nextStep."""
fx = self.fixtures[serial]
loop = self.duration_ms
off = self.time_offset_ms(serial)
if self.propagation == "Serial" and elapsed_ms < off:
return None
cycles, pos = divmod(elapsed_ms, loop)
if self.run_order == "SingleShot" and cycles >= 1:
return None
d = fx.direction
if self.run_order == "PingPong" and int(cycles) % 2 == 1:
d = "Backward" if d == "Forward" else "Forward"
pos = (pos + off) % loop
it = 2 * math.pi * pos / loop
return self.point(d, fx.start_offset, it)
# --------------------------------------------------------------------------- Path
@dataclass
class PathPoint:
pan: float
tilt: float
fade_ms: int = 1000
hold_ms: int = 0
@classmethod
def from_dict(cls, d: dict[str, Any]) -> "PathPoint":
return cls(
pan=clamp(float(d["pan"])),
tilt=clamp(float(d["tilt"])),
fade_ms=max(0, int(d.get("fade_ms", 1000))),
hold_ms=max(0, int(d.get("hold_ms", 0))),
)
@dataclass
class PathFixture:
id: int
head: int = 0
pan_offset: int = 0
tilt_offset: int = 0
mirror_pan: bool = False # head hung the other way round: pan = 255 - pan
mirror_tilt: bool = False
@classmethod
def from_dict(cls, d: dict[str, Any]) -> "PathFixture":
return cls(
id=int(d["id"]),
head=int(d.get("head", 0)),
pan_offset=int(d.get("pan_offset", 0)),
tilt_offset=int(d.get("tilt_offset", 0)),
mirror_pan=bool(d.get("mirror_pan", False)),
mirror_tilt=bool(d.get("mirror_tilt", False)),
)
def apply(self, pan: float, tilt: float) -> tuple[float, float]:
if self.mirror_pan:
pan = 255 - pan
if self.mirror_tilt:
tilt = 255 - tilt
return clamp(pan + self.pan_offset), clamp(tilt + self.tilt_offset)
@dataclass
class Path:
points: list[PathPoint] = field(default_factory=list)
smooth: bool = False
subdivisions: int = 6 # extra steps per segment when smoothing
closed: bool = True # last point flows back into the first
run_order: str = "Loop"
direction: str = "Forward"
fixtures: list[PathFixture] = field(default_factory=list)
@classmethod
def from_dict(cls, d: dict[str, Any]) -> "Path":
return cls(
points=[PathPoint.from_dict(p) for p in d.get("points", [])],
smooth=bool(d.get("smooth", False)),
subdivisions=int(clamp(int(d.get("subdivisions", 6)), 1, 32)),
closed=bool(d.get("closed", True)),
run_order=d.get("run_order") if d.get("run_order") in RUN_ORDERS else "Loop",
direction=d.get("direction") if d.get("direction") in DIRECTIONS else "Forward",
fixtures=[PathFixture.from_dict(f) for f in d.get("fixtures", [])],
)
# -- steps ----------------------------------------------------------------
def steps(self) -> list[PathPoint]:
"""Resolved step list (smoothing expanded), in the pattern's base frame."""
pts = self.points
if len(pts) < 2 or not self.smooth:
return list(pts)
# A waypoint's fade_ms is the travel time *into* it. When the segment
# before it is split into `sub` sub-steps, each sub-step (and the
# waypoint itself) gets fade_ms / sub so the total travel time holds.
out: list[PathPoint] = []
n = len(pts)
sub = self.subdivisions
seg_count = n if self.closed else n - 1
def split_fade(p: PathPoint) -> int:
return max(1, p.fade_ms // sub)
for i in range(seg_count):
p0 = pts[(i - 1) % n] if (self.closed or i > 0) else pts[0]
p1 = pts[i]
p2 = pts[(i + 1) % n]
p3 = pts[(i + 2) % n] if (self.closed or i + 2 < n) else pts[-1]
arrive = split_fade(p1) if (self.closed or i > 0) else p1.fade_ms
out.append(PathPoint(p1.pan, p1.tilt, fade_ms=arrive, hold_ms=p1.hold_ms))
for k in range(1, sub):
t = k / sub
pan = _catmull(p0.pan, p1.pan, p2.pan, p3.pan, t)
tilt = _catmull(p0.tilt, p1.tilt, p2.tilt, p3.tilt, t)
out.append(PathPoint(clamp(pan), clamp(tilt), fade_ms=split_fade(p2), hold_ms=0))
if not self.closed:
last = pts[-1]
out.append(PathPoint(last.pan, last.tilt, fade_ms=split_fade(last), hold_ms=last.hold_ms))
return out
def loop_ms(self) -> int:
return sum(s.fade_ms + s.hold_ms for s in self.steps())
def sample(self) -> dict[str, Any]:
steps = self.steps()
tracks = []
for fx in self.fixtures:
keys = []
t = 0
for s in steps:
pan, tilt = fx.apply(s.pan, s.tilt)
t += s.fade_ms
keys.append([t, round(pan, 2), round(tilt, 2)])
if s.hold_ms:
t += s.hold_ms
keys.append([t, round(pan, 2), round(tilt, 2)])
tracks.append({"id": fx.id, "head": fx.head, "keys": keys})
return {
"kind": "path",
"loop_ms": self.loop_ms(),
"run_order": self.run_order,
"direction": self.direction,
"tracks": tracks,
"step_count": len(steps),
}
def live_point(self, serial: int, elapsed_ms: float) -> tuple[float, float] | None:
steps = self.steps()
if not steps:
return None
loop = self.loop_ms()
if loop <= 0:
pan, tilt = steps[0].pan, steps[0].tilt
return self.fixtures[serial].apply(pan, tilt)
cycles, pos = divmod(elapsed_ms, loop)
if self.run_order == "SingleShot" and cycles >= 1:
pos = loop
reverse = self.direction == "Backward"
if self.run_order == "PingPong" and int(cycles) % 2 == 1:
reverse = not reverse
order = list(reversed(steps)) if reverse else steps
t = 0.0
prev = order[-1]
for s in order:
if pos <= t + s.fade_ms:
f = (pos - t) / s.fade_ms if s.fade_ms else 1.0
pan = prev.pan + (s.pan - prev.pan) * f
tilt = prev.tilt + (s.tilt - prev.tilt) * f
return self.fixtures[serial].apply(pan, tilt)
t += s.fade_ms
if pos <= t + s.hold_ms:
return self.fixtures[serial].apply(s.pan, s.tilt)
t += s.hold_ms
prev = s
last = order[-1]
return self.fixtures[serial].apply(last.pan, last.tilt)
def _catmull(p0: float, p1: float, p2: float, p3: float, t: float) -> float:
t2, t3 = t * t, t * t * t
return 0.5 * (
2 * p1
+ (-p0 + p2) * t
+ (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2
+ (-p0 + 3 * p1 - 3 * p2 + p3) * t3
)
# --------------------------------------------------------------------------- entry
def pattern_from_dict(d: dict[str, Any]) -> Efx | Path:
kind = d.get("type", "efx")
if kind == "efx":
return Efx.from_dict({**d.get("efx", {}), "fixtures": d.get("fixtures", [])})
if kind == "path":
return Path.from_dict({**d.get("path", {}), "fixtures": d.get("fixtures", [])})
raise ValueError(f"unknown pattern type {kind!r}")