Files

578 lines
21 KiB
Python

"""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' <Speed FadeIn="{fade_in}" FadeOut="{fade_out}" Duration="{duration}"/>'
def render_efx(fid: int, name: str, efx: Efx) -> str:
fixtures = "\n".join(
f""" <Fixture>
<ID>{fx.id}</ID>
<Head>{fx.head}</Head>
<Direction>{fx.direction}</Direction>
<StartOffset>{fx.start_offset}</StartOffset>
</Fixture>"""
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""" <Function ID="{fid}" Type="EFX" Name={quoteattr(name)}>
{fixtures}
<PropagationMode>{efx.propagation}</PropagationMode>
<Speed FadeIn="{efx.fade_in_ms}" FadeOut="{efx.fade_out_ms}" Duration="{efx.duration_ms}"/>
<Direction>{efx.direction}</Direction>
<RunOrder>{efx.run_order}</RunOrder>
<Algorithm>{efx.algorithm}</Algorithm>
<Width>{efx.width}</Width>
<Height>{efx.height}</Height>
<Rotation>{efx.rotation}</Rotation>
<StartOffset>{efx.start_offset}</StartOffset>
<IsRelative>{1 if efx.relative else 0}</IsRelative>
<Axis Name="X">
<Offset>{x_off}</Offset>
<Frequency>{efx.x_frequency}</Frequency>
<Phase>{efx.x_phase}</Phase>
</Axis>
<Axis Name="Y">
<Offset>{y_off}</Offset>
<Frequency>{efx.y_frequency}</Frequency>
<Phase>{efx.y_phase}</Phase>
</Axis>
</Function>"""
def render_scene(fid: int, name: str, values: dict[int, dict[int, int]], fade_in: int = 0) -> str:
vals = "\n".join(
f' <FixtureVal ID="{fxid}">{",".join(f"{ch},{v}" for ch, v in sorted(chs.items()))}</FixtureVal>'
for fxid, chs in values.items()
if chs
)
return f""" <Function ID="{fid}" Type="Scene" Name={quoteattr(name)}>
{_speed(fade_in, 0, fade_in)}
{vals}
</Function>"""
def render_collection(fid: int, name: str, members: list[int]) -> str:
steps = "\n".join(f' <Step Number="{i}">{m}</Step>' for i, m in enumerate(members))
return f""" <Function ID="{fid}" Type="Collection" Name={quoteattr(name)}>
{steps}
</Function>"""
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' <Step Number="{i}" FadeIn="{s.fade_ms}" Hold="{s.hold_ms}" FadeOut="0" Values="{count}">'
+ ":".join(chunks)
+ "</Step>"
)
first = {fx.id: channels_for(fx, steps[0]) for fx in path.fixtures}
scene = render_scene(scene_id, f"{name} (base)", first)
seq = f""" <Function ID="{fid}" Type="Sequence" Name={quoteattr(name)} BoundScene="{scene_id}">
{_speed(steps[0].fade_ms, 0, steps[0].fade_ms + steps[0].hold_ms)}
<Direction>{path.direction}</Direction>
<RunOrder>{path.run_order}</RunOrder>
<SpeedModes FadeIn="PerStep" FadeOut="Common" Duration="PerStep"/>
{chr(10).join(step_xml)}
</Function>"""
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""" <Button Caption={quoteattr(caption)} ID="{wid}" Icon="">
<WindowState Visible="True" X="{x}" Y="{y}" Width="{w}" Height="{h}"/>
<Appearance>
<FrameStyle>None</FrameStyle>
<ForegroundColor>4294967295</ForegroundColor>
<BackgroundColor>{bg}</BackgroundColor>
<BackgroundImage>None</BackgroundImage>
<Font>Default</Font>
</Appearance>
<Function ID="{fid}"/>
<Action>Toggle</Action>
<Intensity Adjust="False">100</Intensity>
</Button>"""
# ----------------------------------------------------------------------------- write
_FUNC_RE_TMPL = r'[ \t]*<Function ID="{fid}"[^>]*?(?:/>|>.*?</Function>)[ \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("</Engine>")
if idx < 0:
raise ValueError("workspace has no <Engine> 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("<VirtualConsole>")
if vc < 0:
raise ValueError("workspace has no <VirtualConsole>")
props = text.find("<Properties>", vc)
end = text.rfind("</Frame>", vc, props if props > 0 else len(text))
if end < 0:
raise ValueError("VirtualConsole has no root <Frame>")
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)