3.3 KiB
Offline LightBurn project MOPA import seam
The addon's project_import.py reads observed CutSetting and
CutSetting_Img elements without loading Rayforge, geometry or any transport.
It preserves raw frequency, QPulseWidth, layer order and image dither mode.
The synthetic unit tests contain no private geometry or complete recipes.
Normalization requires the caller to opt into the evidence-backed serialized
unit contract frequency=Hz;QPulseWidth=ns. The contract is restricted to
LightBurn AppVersion="2.1.03"; a missing or different version fails closed.
It comes from correlating an operator-verified project's raw
frequency=1000000 and QPulseWidth=10 with LightBurn's visible 1000 kHz
and 10 ns controls. This is not an inference from magnitude or an
authorization claim. Frequency is represented in Hz and kHz (division by
1000), while pulse width remains in ns. Without explicit contract selection,
only raw values are returned.
Absent fields remain absent, never zero or inherited defaults. Malformed,
non-finite, non-positive, duplicate and excessively large values are rejected.
The numeric ceiling is a parser bound, not a machine operating limit. Image
settings remain blocked pending image-processing equivalence, including
3dslice. XML declarations and unsupported project formats are rejected.
Every result has encoding_allowed=False, hardware_use_allowed=False and
transport=None, even with complete normalized values. This is a callable
offline metadata seam. The companion workflow bridge matches the normalized
LightBurn layer index to Rayforge's source-segment layer ID and stages complete
vector MOPA values through the host's setters. Every staged step is disabled
through Step.set_visible(False), and its raw values, normalized values, exact
unit-contract provenance, review status and blockers are saved in the
serializable Step.extra data. Tampered or missing provenance is rejected
before any step is mutated.
Image settings and incomplete settings remain disabled without applying MOPA
values. Multi-step staging is preflighted and rolled back on setter failure.
The bridge deliberately has no function that enables output or removes a blocker. Host UI and preflight integration must still resolve absent pulse width and validate exact machine, lens, correction and parameter limits before a separate reviewed promotion path can exist. Image-layer equivalence remains unverified. Rayforge's relevant Step and LaserStep files are included in the pinned upstream contract manifest.
The addon now also exposes a transport-free document preflight report with
stable issue codes and human-readable blocker messages. Its packaged frontend
adds a read-only PirateRay Import Preflight action to Rayforge's Tools menu;
the dialog renders those codes and keeps output disabled. The offline driver
runs this check before it prepares encoded buffers. A staged import is rejected;
manually re-enabling its step adds a distinct error, and malformed review data
fails closed. There is intentionally no accepted or promoted import state yet.
Validation covers unit conversion, absent fields, case sensitivity, duplicate values, invalid numbers, image modes, mixed layers, exact layer binding, transactional rollback and malformed XML. Existing packaging, no-device and public evidence checks remain part of the test suite.