"""Read QLC+ workspaces (.qxw) and write pattern functions into them. Reading uses ElementTree. Writing is done on the raw text so QLC+'s own formatting, DOCTYPE and everything we do not understand are left untouched. """ from __future__ import annotations import re import shutil import xml.etree.ElementTree as ET from dataclasses import dataclass, field from pathlib import Path from typing import Any from xml.sax.saxutils import quoteattr from .efx import Efx, Path as PathPattern, RELATIVE_ZERO, clamp8 from .fixturedefs import FixtureDef, FixtureLibrary, ModeInfo NS = {"q": "http://www.qlcplus.org/Workspace"} INVALID_ID = 4294967295 @dataclass class WsFixture: id: int name: str manufacturer: str model: str mode_name: str universe: int address: int channels: int definition: FixtureDef | None = None mode: ModeInfo | None = None @property def is_mover(self) -> bool: return self.mode is not None and self.mode.is_mover def to_dict(self) -> dict[str, Any]: d: dict[str, Any] = { "id": self.id, "name": self.name, "manufacturer": self.manufacturer, "model": self.model, "mode": self.mode_name, "universe": self.universe, "address": self.address, "channels": self.channels, "is_mover": self.is_mover, "definition_found": self.definition is not None, } if self.definition: d["pan_max"] = self.definition.pan_max d["tilt_max"] = self.definition.tilt_max if self.mode: d["pan_msb"] = self.mode.pan_msb d["tilt_msb"] = self.mode.tilt_msb d["pan_lsb"] = self.mode.pan_lsb d["tilt_lsb"] = self.mode.tilt_lsb return d @dataclass class WsFunction: id: int type: str name: str def to_dict(self) -> dict[str, Any]: return {"id": self.id, "type": self.type, "name": self.name} @dataclass class Workspace: path: Path text: str fixtures: list[WsFixture] functions: list[WsFunction] artnet: dict[int, dict[str, Any]] # universe id → {"ip":..., "universe":...} vc_widget_ids: list[int] = field(default_factory=list) vc_bottom: int = 0 # lowest used Y in the root VC frame # ------------------------------------------------------------------ load @classmethod def load(cls, path: Path, library: FixtureLibrary) -> "Workspace": text = path.read_text(encoding="utf-8") root = ET.fromstring(text) engine = root.find("q:Engine", NS) fixtures: list[WsFixture] = [] functions: list[WsFunction] = [] artnet: dict[int, dict[str, Any]] = {} if engine is not None: for fx in engine.findall("q:Fixture", NS): manu = _t(fx, "Manufacturer") model = _t(fx, "Model") mode_name = _t(fx, "Mode") wsf = WsFixture( id=int(_t(fx, "ID", "0")), name=_t(fx, "Name"), manufacturer=manu, model=model, mode_name=mode_name, universe=int(_t(fx, "Universe", "0")), address=int(_t(fx, "Address", "0")), channels=int(_t(fx, "Channels", "0")), ) if manu != "Generic" or model != "Generic": wsf.definition = library.find(manu, model) if wsf.definition: wsf.mode = wsf.definition.mode(mode_name) fixtures.append(wsf) for fn in engine.findall("q:Function", NS): functions.append( WsFunction(id=int(fn.get("ID", "0")), type=fn.get("Type", ""), name=fn.get("Name", "")) ) iomap = engine.find("q:InputOutputMap", NS) if iomap is not None: for uni in iomap.findall("q:Universe", NS): out = uni.find("q:Output", NS) if out is None or out.get("Plugin") != "ArtNet": continue params = out.find("q:PluginParameters", NS) ip = params.get("outputIP") if params is not None else None art_uni = params.get("outputUni") if params is not None else None artnet[int(uni.get("ID", "0"))] = { "ip": ip or out.get("UID") or "", "universe": int(art_uni) if art_uni is not None else int(uni.get("ID", "0")), } widget_ids: list[int] = [] bottom = 0 vc = root.find("q:VirtualConsole", NS) if vc is not None: for el in vc.iter(): wid = el.get("ID") if wid is not None and not el.tag.endswith("}Function"): try: widget_ids.append(int(wid)) except ValueError: pass frame = vc.find("q:Frame", NS) if frame is not None: for child in frame: ws = child.find("q:WindowState", NS) if ws is not None: try: bottom = max(bottom, int(ws.get("Y", "0")) + int(ws.get("Height", "0"))) except ValueError: pass return cls( path=path, text=text, fixtures=fixtures, functions=functions, artnet=artnet, vc_widget_ids=widget_ids, vc_bottom=bottom, ) def fixture(self, fid: int) -> WsFixture | None: return next((f for f in self.fixtures if f.id == fid), None) def next_function_id(self) -> int: return (max((f.id for f in self.functions), default=-1)) + 1 def next_widget_id(self) -> int: return (max(self.vc_widget_ids, default=-1)) + 1 def function_by_name(self, name: str, ftype: str | None = None) -> WsFunction | None: for f in self.functions: if f.name == name and (ftype is None or f.type == ftype): return f return None def to_dict(self) -> dict[str, Any]: return { "path": str(self.path), "name": self.path.name, "fixtures": [f.to_dict() for f in self.fixtures], "functions": [f.to_dict() for f in self.functions], "artnet": {str(k): v for k, v in self.artnet.items()}, } # ------------------------------------------------------------------ import def pattern_from_function(self, fid: int) -> dict[str, Any] | None: """Turn an existing EFX or pan/tilt Sequence back into an editable pattern.""" root = ET.fromstring(self.text) engine = root.find("q:Engine", NS) if engine is None: return None for fn in engine.findall("q:Function", NS): if int(fn.get("ID", "-1")) != fid: continue if fn.get("Type") == "EFX": return _efx_to_pattern(fn) if fn.get("Type") == "Sequence": return _sequence_to_pattern(fn, self) return None def _t(el: ET.Element, tag: str, default: str = "") -> str: child = el.find(f"q:{tag}", NS) return (child.text or default).strip() if child is not None and child.text is not None else default def _efx_to_pattern(fn: ET.Element) -> dict[str, Any]: speed = fn.find("q:Speed", NS) axes = {ax.get("Name"): ax for ax in fn.findall("q:Axis", NS)} def axis(name: str, tag: str, default: str) -> int: ax = axes.get(name) return int(_t(ax, tag, default)) if ax is not None else int(default) fixtures = [] for fx in fn.findall("q:Fixture", NS): fixtures.append( { "id": int(_t(fx, "ID", "0")), "head": int(_t(fx, "Head", "0")), "direction": _t(fx, "Direction", "Forward"), "start_offset": int(_t(fx, "StartOffset", "0")), } ) return { "name": fn.get("Name", ""), "type": "efx", "source_function_id": int(fn.get("ID", "0")), "fixtures": fixtures, "efx": { "algorithm": _t(fn, "Algorithm", "Circle"), "width": int(_t(fn, "Width", "0")), "height": int(_t(fn, "Height", "0")), "rotation": int(_t(fn, "Rotation", "0")), "start_offset": int(_t(fn, "StartOffset", "0")), "relative": _t(fn, "IsRelative", "0") == "1", "x_offset": axis("X", "Offset", "127"), "y_offset": axis("Y", "Offset", "127"), "x_frequency": axis("X", "Frequency", "1"), "y_frequency": axis("Y", "Frequency", "1"), "x_phase": axis("X", "Phase", "0"), "y_phase": axis("Y", "Phase", "0"), "duration_ms": int(speed.get("Duration", "8000")) if speed is not None else 8000, "fade_in_ms": int(speed.get("FadeIn", "0")) if speed is not None else 0, "fade_out_ms": int(speed.get("FadeOut", "0")) if speed is not None else 0, "direction": _t(fn, "Direction", "Forward"), "run_order": _t(fn, "RunOrder", "Loop"), "propagation": _t(fn, "PropagationMode", "Parallel"), }, } def _sequence_to_pattern(fn: ET.Element, ws: Workspace) -> dict[str, Any] | None: steps = fn.findall("q:Step", NS) if not steps: return None # Which fixtures carry pan/tilt in this sequence? fixture_ids: list[int] = [] for s in steps: for fid, _vals in _parse_step_values(s.text or ""): if fid not in fixture_ids: fixture_ids.append(fid) movers = [ws.fixture(fid) for fid in fixture_ids] movers = [m for m in movers if m is not None and m.is_mover] if not movers: return None ref = movers[0] points = [] for s in steps: vals = dict(_parse_step_values(s.text or "")).get(ref.id, {}) pan = vals.get(ref.mode.pan_msb) # type: ignore[union-attr] tilt = vals.get(ref.mode.tilt_msb) # type: ignore[union-attr] if pan is None or tilt is None: return None points.append( {"pan": pan, "tilt": tilt, "fade_ms": int(s.get("FadeIn", "0")), "hold_ms": int(s.get("Hold", "0"))} ) return { "name": fn.get("Name", ""), "type": "path", "source_function_id": int(fn.get("ID", "0")), "fixtures": [{"id": m.id} for m in movers], "path": { "points": points, "smooth": False, "closed": True, "direction": _t(fn, "Direction", "Forward"), "run_order": _t(fn, "RunOrder", "Loop"), }, } def _parse_step_values(text: str) -> list[tuple[int, dict[int, int]]]: """'8:0,10,2,20:9:0,30,2,40' → [(8, {0:10, 2:20}), (9, {0:30, 2:40})].""" out: list[tuple[int, dict[int, int]]] = [] parts = text.strip().split(":") i = 0 while i + 1 < len(parts): try: fid = int(parts[i]) except ValueError: break nums = [int(x) for x in parts[i + 1].split(",") if x.strip() != ""] out.append((fid, {nums[k]: nums[k + 1] for k in range(0, len(nums) - 1, 2)})) i += 2 return out # ----------------------------------------------------------------------------- render def _speed(fade_in: int, fade_out: int, duration: int) -> str: return f' ' def render_efx(fid: int, name: str, efx: Efx) -> str: fixtures = "\n".join( f""" {fx.id} {fx.head} {fx.direction} {fx.start_offset} """ for fx in efx.fixtures ) x_off = RELATIVE_ZERO if efx.relative else efx.x_offset y_off = RELATIVE_ZERO if efx.relative else efx.y_offset return f""" {fixtures} {efx.propagation} {efx.direction} {efx.run_order} {efx.algorithm} {efx.width} {efx.height} {efx.rotation} {efx.start_offset} {1 if efx.relative else 0} {x_off} {efx.x_frequency} {efx.x_phase} {y_off} {efx.y_frequency} {efx.y_phase} """ def render_scene(fid: int, name: str, values: dict[int, dict[int, int]], fade_in: int = 0) -> str: vals = "\n".join( f' {",".join(f"{ch},{v}" for ch, v in sorted(chs.items()))}' for fxid, chs in values.items() if chs ) return f""" {_speed(fade_in, 0, fade_in)} {vals} """ def render_collection(fid: int, name: str, members: list[int]) -> str: steps = "\n".join(f' {m}' for i, m in enumerate(members)) return f""" {steps} """ def render_sequence( fid: int, scene_id: int, name: str, path: PathPattern, movers: dict[int, WsFixture], ) -> tuple[str, str]: """Returns (bound scene xml, sequence xml).""" steps = path.steps() if not steps: raise ValueError("path has no points") def channels_for(fx_cfg, step) -> dict[int, int]: m = movers[fx_cfg.id].mode assert m is not None and m.pan_msb is not None and m.tilt_msb is not None pan, tilt = fx_cfg.apply(step.pan, step.tilt) ch = {m.pan_msb: clamp8(pan), m.tilt_msb: clamp8(tilt)} # Fine channels: carry the fractional part like EFXFixture does. if m.pan_lsb is not None: ch[m.pan_lsb] = clamp8((pan - int(pan)) * 255) if m.tilt_lsb is not None: ch[m.tilt_lsb] = clamp8((tilt - int(tilt)) * 255) return ch step_xml = [] for i, s in enumerate(steps): chunks = [] count = 0 for fx in path.fixtures: ch = channels_for(fx, s) count += len(ch) chunks.append(f"{fx.id}:" + ",".join(f"{c},{v}" for c, v in sorted(ch.items()))) step_xml.append( f' ' + ":".join(chunks) + "" ) first = {fx.id: channels_for(fx, steps[0]) for fx in path.fixtures} scene = render_scene(scene_id, f"{name} (base)", first) seq = f""" {_speed(steps[0].fade_ms, 0, steps[0].fade_ms + steps[0].hold_ms)} {path.direction} {path.run_order} {chr(10).join(step_xml)} """ return scene, seq def render_vc_button(wid: int, caption: str, fid: int, x: int, y: int, w: int = 110, h: int = 60, bg: str = "4282664004") -> str: return f""" """ # ----------------------------------------------------------------------------- write _FUNC_RE_TMPL = r'[ \t]*]*?(?:/>|>.*?)[ \t]*\r?\n?' def remove_function(text: str, fid: int) -> str: return re.sub(_FUNC_RE_TMPL.format(fid=fid), "", text, count=1, flags=re.S) def insert_functions(text: str, xml: str) -> str: """Insert function XML at the end of the Engine section (order is not significant to QLC+).""" idx = text.find("") if idx < 0: raise ValueError("workspace has no section") # back up to the start of that line line_start = text.rfind("\n", 0, idx) + 1 return text[:line_start] + xml + "\n" + text[line_start:] def insert_vc_widget(text: str, xml: str) -> str: vc = text.find("") if vc < 0: raise ValueError("workspace has no ") props = text.find("", vc) end = text.rfind("", vc, props if props > 0 else len(text)) if end < 0: raise ValueError("VirtualConsole has no root ") line_start = text.rfind("\n", 0, end) + 1 return text[:line_start] + xml + "\n" + text[line_start:] @dataclass class ExportResult: path: Path backup: Path | None function_ids: dict[str, int] widget_id: int | None replaced: list[int] def to_dict(self) -> dict[str, Any]: return { "path": str(self.path), "backup": str(self.backup) if self.backup else None, "function_ids": self.function_ids, "widget_id": self.widget_id, "replaced": self.replaced, } def export_pattern( ws: Workspace, pattern: dict[str, Any], *, name: str, overwrite: bool = True, add_button: bool = False, button_xy: tuple[int, int] | None = None, out_path: Path | None = None, backup: bool = True, ) -> ExportResult: """Write the pattern into `ws` (in place, or to `out_path`).""" from .efx import pattern_from_dict obj = pattern_from_dict(pattern) name = name.strip() or "Mover Pattern" text = ws.text replaced: list[int] = [] ids: dict[str, int] = {} xml_parts: list[str] = [] next_id = ws.next_function_id() def alloc(kind: str, fname: str) -> int: """Reuse the ID of a same-named function (keeps VC buttons wired) or take a fresh one.""" nonlocal next_id, text existing = ws.function_by_name(fname) if overwrite else None if existing and existing.id not in replaced: text = remove_function(text, existing.id) replaced.append(existing.id) ids[kind] = existing.id return existing.id fid = next_id next_id += 1 ids[kind] = fid return fid movers = {f.id: f for f in ws.fixtures if f.is_mover} for fx in obj.fixtures: if fx.id not in movers: raise ValueError(f"fixture {fx.id} is not a mover in this workspace") if not obj.fixtures: raise ValueError("pattern has no fixtures") main_id: int if isinstance(obj, Efx): if obj.relative: # Base positions scene + EFX around RELATIVE_ZERO + Collection to run both. base_vals: dict[int, dict[int, int]] = {} for fx in obj.fixtures: m = movers[fx.id].mode assert m is not None and m.pan_msb is not None and m.tilt_msb is not None base_vals[fx.id] = {m.pan_msb: fx.pan, m.tilt_msb: fx.tilt} scene_id = alloc("scene", f"{name} (home)") efx_id = alloc("efx", f"{name} (EFX)") coll_id = alloc("collection", name) xml_parts.append(render_scene(scene_id, f"{name} (home)", base_vals, fade_in=obj.fade_in_ms)) xml_parts.append(render_efx(efx_id, f"{name} (EFX)", obj)) xml_parts.append(render_collection(coll_id, name, [scene_id, efx_id])) main_id = coll_id else: efx_id = alloc("efx", name) xml_parts.append(render_efx(efx_id, name, obj)) main_id = efx_id else: scene_id = alloc("scene", f"{name} (base)") seq_id = alloc("sequence", name) scene_xml, seq_xml = render_sequence(seq_id, scene_id, name, obj, movers) xml_parts.append(scene_xml) xml_parts.append(seq_xml) main_id = seq_id text = insert_functions(text, "\n".join(xml_parts)) widget_id = None if add_button: widget_id = ws.next_widget_id() x, y = button_xy or (10, ws.vc_bottom + 10) text = insert_vc_widget(text, render_vc_button(widget_id, name, main_id, x, y)) # Make sure what we are about to write is still well-formed before touching disk. ET.fromstring(text) target = out_path or ws.path backup_path = None if backup and target.exists(): backup_path = target.with_suffix(target.suffix + ".bak") shutil.copyfile(target, backup_path) target.write_text(text, encoding="utf-8") return ExportResult(path=target, backup=backup_path, function_ids=ids, widget_id=widget_id, replaced=replaced)