"""EFX, sequences, paths, and chasers.""" from __future__ import annotations from dataclasses import dataclass from typing import Any from patternstudio.efx import ( ALGORITHMS, DIRECTIONS, PROPAGATIONS, RELATIVE_ZERO, RUN_ORDERS, Efx, EfxFixture, Path, PathFixture, PathPoint, clamp8, ) from .model import Show, blend_maps from .xmlutil import attr Axis = tuple[int | None, int | None, int | None, int | None] def locate( steps: list[Any], elapsed_ms: float, run_order: str, direction: str, ) -> tuple[int, float, int | None, float]: """Return step index, fade progress, previous index, and ms into the step. A looping timeline treats the last step as the fade source for the first, so a loop is seamless. Single Shot fades the first step up from black and holds the last step after the end. """ spans = [max(0, s.fade_ms) + max(0, s.hold_ms) + max(0, s.fade_out_ms) for s in steps] total = float(sum(spans)) count = len(steps) if count == 0 or total <= 0: return 0, 1.0, None, 0.0 elapsed = max(0.0, float(elapsed_ms)) seamless = run_order != "SingleShot" if run_order == "SingleShot" and elapsed >= total: prev = count - 2 if count > 1 else None return count - 1, 1.0, prev, spans[-1] if run_order == "PingPong": cycle = int(elapsed // total) pos = elapsed % total if cycle % 2 == 1: pos = total - pos elif run_order == "SingleShot": pos = elapsed else: pos = elapsed % total if direction == "Backward": pos = total - pos if pos >= total: pos = total - 1e-6 if pos < 0: pos = 0.0 acc = 0.0 for index, span in enumerate(spans): fade = max(0, steps[index].fade_ms) prev = None if index == 0 and not seamless else (index - 1) % count if pos < acc + fade or span == 0: prog = 1.0 if fade <= 0 else (pos - acc) / fade return index, min(1.0, max(0.0, prog)), prev, pos - acc if pos < acc + span or index == count - 1: return index, 1.0, prev, pos - acc acc += span return count - 1, 1.0, None, spans[-1] def _fixture(show: Show, item: Any) -> Any: if isinstance(item, str): return show.fixtures_by_key[item] if isinstance(item, int) and not isinstance(item, bool): return next(fx for fx in show.fixtures if fx.id == item) return item @dataclass class EfxFunction: id: int key: str name: str pattern: Efx homes: dict[int, tuple[int, int]] relative: bool axes: dict[int, Axis] preview: dict[int, dict[int, int]] primary: bool = True type: str = "EFX" def duration_ms(self, _show: Show) -> int: return self.pattern.duration_ms def apply(self, _show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: for serial, fx in enumerate(self.pattern.fixtures): bucket = into.setdefault(fx.id, {}) for ch, val in self.preview.get(fx.id, {}).items(): bucket.setdefault(ch, val) point = self.pattern.live_point(serial, elapsed_ms) if point is None: continue pan, tilt = point if self.relative: home_pan, home_tilt = self.homes.get(fx.id, (RELATIVE_ZERO, RELATIVE_ZERO)) pan = home_pan + (pan - RELATIVE_ZERO) tilt = home_tilt + (tilt - RELATIVE_ZERO) pan_msb, pan_lsb, tilt_msb, tilt_lsb = self.axes[fx.id] _write_axis(bucket, pan_msb, pan_lsb, pan) _write_axis(bucket, tilt_msb, tilt_lsb, tilt) def render(self) -> str: pattern = self.pattern fixtures = "\n".join( " \n" f" {fx.id}\n" f" {fx.head}\n" f" {fx.direction}\n" f" {fx.start_offset}\n" " " for fx in pattern.fixtures ) return ( f' \n' f"{fixtures}\n" f" {pattern.propagation}\n" f' \n' f" {pattern.direction}\n" f" {pattern.run_order}\n" f" {pattern.algorithm}\n" f" {pattern.width}\n" f" {pattern.height}\n" f" {pattern.rotation}\n" f" {pattern.start_offset}\n" f" {1 if self.relative else 0}\n" " \n" f" {pattern.x_offset}\n" f" {pattern.x_frequency}\n" f" {pattern.x_phase}\n" " \n" " \n" f" {pattern.y_offset}\n" f" {pattern.y_frequency}\n" f" {pattern.y_phase}\n" " \n" " " ) @dataclass class SequenceStep: values: dict[int, dict[int, int]] fade_ms: int = 0 hold_ms: int = 0 fade_out_ms: int = 0 @dataclass class SequenceFunction: id: int key: str name: str bound_id: int steps: list[SequenceStep] direction: str = "Forward" run_order: str = "Loop" primary: bool = True type: str = "Sequence" def duration_ms(self, _show: Show) -> int: return sum(step.fade_ms + step.hold_ms + step.fade_out_ms for step in self.steps) def apply(self, _show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: index, prog, prev, _local = locate(self.steps, elapsed_ms, self.run_order, self.direction) if not self.steps: return current = self.steps[index].values previous = {} if prev is None else self.steps[prev].values blend_maps(into, previous, current, prog) def render(self) -> str: lines = [] for index, step in enumerate(self.steps): body, count = _step_values(step.values) lines.append( f' {body}' ) first = self.steps[0] if self.steps else SequenceStep({}) fade_mode, duration_mode = _speed_modes(self.steps) return ( f' \n' f' \n' f" {self.direction}\n" f" {self.run_order}\n" f' \n' + "\n".join(lines) + "\n " ) @dataclass class ChaserStep: function_id: int fade_ms: int = 0 hold_ms: int = 0 fade_out_ms: int = 0 @dataclass class ChaserFunction: id: int key: str name: str steps: list[ChaserStep] direction: str = "Forward" run_order: str = "Loop" primary: bool = True type: str = "Chaser" def duration_ms(self, _show: Show) -> int: return sum(step.fade_ms + step.hold_ms + step.fade_out_ms for step in self.steps) def apply(self, show: Show, elapsed_ms: float, into: dict[int, dict[int, int]]) -> None: from .model import Scene if not self.steps: return index, prog, prev, local = locate(self.steps, elapsed_ms, self.run_order, self.direction) current = show.functions_by_id[self.steps[index].function_id] if isinstance(current, Scene): previous: dict[int, dict[int, int]] = {} if prev is not None: prev_fn = show.functions_by_id[self.steps[prev].function_id] if isinstance(prev_fn, Scene): previous = prev_fn.values else: prev_fn.apply(show, prev_fn.duration_ms(show), previous) blend_maps(into, previous, current.values, prog) return current.apply(show, local, into) def render(self) -> str: lines = [ f' {step.function_id}' for i, step in enumerate(self.steps) ] first = self.steps[0] if self.steps else ChaserStep(0) fade_mode, duration_mode = _speed_modes(self.steps) return ( f' \n' f' \n' f" {self.direction}\n" f" {self.run_order}\n" f' \n' + "\n".join(lines) + "\n " ) def add_efx(show: Show, name: str, fixtures: list[Any], **kwargs: Any) -> Any: key = kwargs.pop("key", None) or _auto_key(show, name) relative = bool(kwargs.pop("relative", False)) homes_in = kwargs.pop("homes", None) or {} entries = [_efx_entry(show, item, homes_in) for item in fixtures] if not entries: raise ValueError("efx has no fixtures") for fixture, _direction, _offset, _pan, _tilt in entries: if fixture.pan_msb is None or fixture.tilt_msb is None: raise ValueError(f"{fixture.key} has no pan/tilt in mode {fixture.mode}") pattern = _build_efx(entries, relative=relative, **kwargs) homes = {fixture.id: (pan, tilt) for fixture, _d, _o, pan, tilt in entries} axes = { fixture.id: (fixture.pan_msb, fixture.pan_lsb, fixture.tilt_msb, fixture.tilt_lsb) for fixture, *_rest in entries } preview = {fixture.id: fixture.preview_channels() for fixture, *_rest in entries} if relative: home_values = {} for fixture, _d, _o, pan, tilt in entries: channels: dict[int, int] = {} if fixture.pan_msb is not None: channels[fixture.pan_msb] = pan if fixture.pan_lsb is not None: channels[fixture.pan_lsb] = 0 if fixture.tilt_msb is not None: channels[fixture.tilt_msb] = tilt if fixture.tilt_lsb is not None: channels[fixture.tilt_lsb] = 0 home_values[fixture.id] = channels show.scene(f"{name} (home)", home_values, key=f"{key}.home", primary=False) efx = EfxFunction( id=show.alloc_function(), key=f"{key}.efx", name=f"{name} (EFX)", pattern=pattern, homes=homes, relative=True, axes=axes, preview=preview, primary=False, ) show._add_function(efx) return show.collection(name, [f"{key}.home", f"{key}.efx"], key=key, primary=True) efx = EfxFunction( id=show.alloc_function(), key=key, name=name, pattern=pattern, homes=homes, relative=False, axes=axes, preview=preview, ) return show._add_function(efx) def add_sequence( show: Show, name: str, steps: list[Any], *, direction: str = "Forward", run_order: str = "Loop", key: str | None = None, primary: bool = True, ) -> SequenceFunction: _check_choice("direction", direction, DIRECTIONS) _check_choice("run_order", run_order, RUN_ORDERS) fn_key = key or _auto_key(show, name) norm = [_sequence_step(show, step) for step in steps] if not norm: raise ValueError("sequence has no steps") show.scene(f"{name} (base)", norm[0].values, key=f"{fn_key}.base", primary=False) bound = show.functions_by_key[f"{fn_key}.base"] seq = SequenceFunction( id=show.alloc_function(), key=fn_key, name=name, bound_id=bound.id, steps=norm, direction=direction, run_order=run_order, primary=primary, ) return show._add_function(seq) def add_path( show: Show, name: str, fixtures: list[Any], points: list[Any], *, smooth: bool = False, subdivisions: int = 6, closed: bool = True, run_order: str = "Loop", direction: str = "Forward", key: str | None = None, ) -> SequenceFunction: entries = [_path_entry(show, item) for item in fixtures] if not entries: raise ValueError("path has no fixtures") path_points = [_path_point(point) for point in points] if len(path_points) < 1: raise ValueError("path has no points") for fixture, *_rest in entries: if fixture.pan_msb is None or fixture.tilt_msb is None: raise ValueError(f"{fixture.key} has no pan/tilt in mode {fixture.mode}") path = Path( points=path_points, smooth=smooth, subdivisions=int(subdivisions), closed=closed, run_order=run_order, direction=direction, fixtures=[ PathFixture( id=fixture.id, pan_offset=pan_offset, tilt_offset=tilt_offset, mirror_pan=mirror_pan, mirror_tilt=mirror_tilt, ) for fixture, pan_offset, tilt_offset, mirror_pan, mirror_tilt in entries ], ) resolved = path.steps() by_id = {fixture.id: fixture for fixture, *_rest in entries} steps = [] for point in resolved: values: dict[int, dict[int, int]] = {} for cfg in path.fixtures: fixture = by_id[cfg.id] pan, tilt = cfg.apply(point.pan, point.tilt) channels: dict[int, int] = {} _write_axis(channels, fixture.pan_msb, fixture.pan_lsb, pan) _write_axis(channels, fixture.tilt_msb, fixture.tilt_lsb, tilt) values[fixture.id] = channels steps.append(SequenceStep(values, fade_ms=point.fade_ms, hold_ms=point.hold_ms)) return add_sequence(show, name, steps, direction=direction, run_order=run_order, key=key) def add_chaser( show: Show, name: str, steps: list[Any], *, direction: str = "Forward", run_order: str = "Loop", key: str | None = None, primary: bool = True, ) -> ChaserFunction: _check_choice("direction", direction, DIRECTIONS) _check_choice("run_order", run_order, RUN_ORDERS) norm = [_chaser_step(show, step) for step in steps] if not norm: raise ValueError("chaser has no steps") fn_key = key or _auto_key(show, name) chaser = ChaserFunction( id=show.alloc_function(), key=fn_key, name=name, steps=norm, direction=direction, run_order=run_order, primary=primary, ) return show._add_function(chaser) def add_colour_chase( show: Show, name: str, fixtures: list[Any], channels: dict[str, int], frames: list[Any], *, fade_ms: int = 0, hold_ms: int = 0, run_order: str = "Loop", key: str | None = None, ) -> ChaserFunction: if not frames: raise ValueError("colour chase has no frames") fn_key = key or _auto_key(show, name) names = list(channels) scene_keys = [] for index, frame in enumerate(frames): if len(frame) != len(fixtures): raise ValueError(f"frame {index} has {len(frame)} colours for {len(fixtures)} fixtures") values: dict[int, dict[int, int]] = {} for fixture_item, colour in zip(fixtures, frame): fixture = _fixture(show, fixture_item) if isinstance(colour, dict): values[fixture.id] = {int(ch): int(val) for ch, val in colour.items()} else: if len(colour) != len(names): raise ValueError( f"frame {index} colour has {len(colour)} values for channels {names}" ) values[fixture.id] = {int(channels[names[i]]): int(colour[i]) for i in range(len(names))} scene_key = f"{fn_key}.{index}" show.scene(f"{name} {index + 1}", values, key=scene_key, primary=False) scene_keys.append(scene_key) steps = [ ChaserStep(show.functions_by_key[scene_key].id, fade_ms=int(fade_ms), hold_ms=int(hold_ms)) for scene_key in scene_keys ] return add_chaser(show, name, steps, run_order=run_order, key=fn_key) def _write_axis(bucket: dict[int, int], msb: int | None, lsb: int | None, value: float) -> None: if msb is not None: bucket[msb] = clamp8(value) if lsb is not None: bucket[lsb] = clamp8((value - int(value)) * 255) def _step_values(values: dict[int, dict[int, int]]) -> tuple[str, int]: chunks = [] count = 0 for fid, channels in sorted(values.items()): if not channels: continue count += len(channels) body = ",".join(f"{ch},{val}" for ch, val in sorted(channels.items())) chunks.append(f"{fid}:{body}") return ":".join(chunks), count def _speed_modes(steps: list[Any]) -> tuple[str, str]: if not steps: return "Common", "Common" first = (steps[0].fade_ms, steps[0].hold_ms, steps[0].fade_out_ms) if all((step.fade_ms, step.hold_ms, step.fade_out_ms) == first for step in steps): return "Common", "Common" return "PerStep", "PerStep" def _check_choice(label: str, value: str, allowed: tuple[str, ...]) -> None: if value not in allowed: raise ValueError(f"{label} must be one of {', '.join(allowed)}") def _check_range(label: str, value: int, lo: int, hi: int) -> int: number = int(value) if not lo <= number <= hi: raise ValueError(f"{label} must be {lo}–{hi}") return number def _build_efx(entries: list[tuple[Any, str, int, int, int]], *, relative: bool, **kwargs: Any) -> Efx: algorithm = kwargs.get("algorithm", "Circle") _check_choice("algorithm", algorithm, ALGORITHMS) direction = kwargs.get("direction", "Forward") run_order = kwargs.get("run_order", "Loop") propagation = kwargs.get("propagation", "Parallel") _check_choice("direction", direction, DIRECTIONS) _check_choice("run_order", run_order, RUN_ORDERS) _check_choice("propagation", propagation, PROPAGATIONS) duration = int(kwargs.get("duration_ms", 8000)) if duration < 20: raise ValueError("duration_ms must be at least 20") x_offset = RELATIVE_ZERO if relative else _check_range("x_offset", kwargs.get("x_offset", 128), 0, 255) y_offset = RELATIVE_ZERO if relative else _check_range("y_offset", kwargs.get("y_offset", 128), 0, 255) return Efx( algorithm=algorithm, width=_check_range("width", kwargs.get("width", 40), 0, 127), height=_check_range("height", kwargs.get("height", 40), 0, 127), rotation=int(kwargs.get("rotation", 0)) % 360, start_offset=int(kwargs.get("start_offset", 0)) % 360, x_offset=x_offset, y_offset=y_offset, x_frequency=_check_range("x_frequency", kwargs.get("x_frequency", 1), 0, 5), y_frequency=_check_range("y_frequency", kwargs.get("y_frequency", 1), 0, 5), x_phase=int(kwargs.get("x_phase", 0)) % 360, y_phase=int(kwargs.get("y_phase", 0)) % 360, duration_ms=duration, fade_in_ms=max(0, int(kwargs.get("fade_in_ms", 0))), fade_out_ms=max(0, int(kwargs.get("fade_out_ms", 0))), direction=direction, run_order=run_order, propagation=propagation, relative=relative, fixtures=[ EfxFixture(id=fixture.id, direction=direction, start_offset=offset, pan=pan, tilt=tilt) for fixture, direction, offset, pan, tilt in entries ], ) def _efx_entry(show: Show, item: Any, homes: dict[Any, Any]) -> tuple[Any, str, int, int, int]: if isinstance(item, str) or (isinstance(item, int) and not isinstance(item, bool)): fixture = _fixture(show, item) direction, offset, pan, tilt = "Forward", 0, 128, 128 home_key: Any = item elif hasattr(item, "pan_msb"): fixture = item direction, offset, pan, tilt = "Forward", 0, 128, 128 home_key = fixture.key else: fixture = _fixture(show, 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)) home_key = item["fixture"] home = _home_for(homes, fixture, home_key) if home is not None: pan, tilt = int(home[0]), int(home[1]) return fixture, direction, offset, pan, tilt def _home_for(homes: dict[Any, Any], fixture: Any, home_key: Any) -> Any: if not homes: return None for candidate in (home_key, fixture.key, fixture.id): if candidate in homes: return homes[candidate] for key, value in homes.items(): if key is fixture: return value return None def _sequence_step(show: Show, step: Any) -> SequenceStep: if isinstance(step, SequenceStep): values = { show.fixture_id(fid): {int(ch): int(val) for ch, val in channels.items()} for fid, channels in step.values.items() } return SequenceStep(values, step.fade_ms, step.hold_ms, step.fade_out_ms) values = { show.fixture_id(fid): {int(ch): int(val) for ch, val in channels.items()} for fid, channels in step["values"].items() } return SequenceStep( values, fade_ms=int(step.get("fade_ms", 0)), hold_ms=int(step.get("hold_ms", 0)), fade_out_ms=int(step.get("fade_out_ms", 0)), ) def _path_entry(show: Show, item: Any) -> tuple[Any, int, int, bool, bool]: if isinstance(item, str) or hasattr(item, "pan_msb"): return _fixture(show, item), 0, 0, False, False return ( _fixture(show, item["fixture"]), int(item.get("pan_offset", 0)), int(item.get("tilt_offset", 0)), bool(item.get("mirror_pan", False)), bool(item.get("mirror_tilt", False)), ) def _path_point(point: Any) -> PathPoint: if isinstance(point, PathPoint): return point return 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)), ) def _chaser_step(show: Show, step: Any) -> ChaserStep: if isinstance(step, ChaserStep): return ChaserStep(_function_id(show, step.function_id), step.fade_ms, step.hold_ms, step.fade_out_ms) if isinstance(step, tuple): function, fade, hold = step[0], step[1], step[2] if len(step) > 2 else 0 fade_out = step[3] if len(step) > 3 else 0 return ChaserStep(_function_id(show, function), int(fade), int(hold), int(fade_out)) return ChaserStep( _function_id(show, step["function"] if isinstance(step, dict) else step), fade_ms=int(step.get("fade_ms", 0)) if isinstance(step, dict) else 0, hold_ms=int(step.get("hold_ms", 0)) if isinstance(step, dict) else 0, fade_out_ms=int(step.get("fade_out_ms", 0)) if isinstance(step, dict) else 0, ) def _function_id(show: Show, function: Any) -> int: if isinstance(function, int) and not isinstance(function, bool): return function if isinstance(function, str): return show.functions_by_key[function].id return function.id def _auto_key(show: Show, name: str) -> str: from .model import _key_for return _key_for(name, show.functions_by_key)