Verify Eikos preview round trip and add read-only import bridge
Beffroi/beffroi-tools/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-13 16:29:14 +01:00
parent 1d4616abe9
commit 793c3cb9d0
6 changed files with 354 additions and 4 deletions

View File

@ -0,0 +1,47 @@
# Midra device snapshot and container SVG bridge
Implementation: [`tools/midra_probe.py`](../../tools/midra_probe.py).
Tests: [`tests/test_midra_probe.py`](../../tests/test_midra_probe.py).
Hardware evidence and usage: [Eikos check](../midra-layout-device-check.md).
## Snapshot
`--save-snapshot` writes UTF-8 JSON containing the raw object from
`GET /api/stores/device`; the root key is `device`. No editor project version
or custom wrapper is added. This is **vendor state**, not a Midra Layout project.
The firmware owns its schema; compatibility was checked on Eikos 4K 3.3.10 only.
`--snapshot` reads it offline, at most 32 MiB, and rejects missing required fields
when extracting geometry. Unknown vendor fields are preserved on capture.
Snapshots can contain private configuration. They are never sent back to a unit.
Geometry extraction uses these paths below `device`:
- `transition/screenList/items/{screen}/status/pp/transition`: only `AT_DOWN`
(Preview `UP`) or `AT_UP` (Preview `DOWN`) is accepted. Transitional states fail.
- `screenList/items/{screen}/canvas/status/size/pp/{sizeH,sizeV}`: canvas pixels.
- `screenList/items/{screen}/presetList/items/{bank}/liveLayerList/items/{layer}`:
`position/pp/{posH,posV}` is the center in canvas pixels;
`size/pp/{sizeH,sizeV}` is the device container size in pixels.
- `crop/pp` and `mask/pp`: all four edges must be zero for SVG extraction.
Their nonzero units/semantics are intentionally not converted yet.
## Container SVG
This uses the existing [geometry SVG marker](midra-layout.md#svg-geometry-exchange-version-1),
`data-midra-layout-geometry="1"`, so a full-screen container is not mistaken for
an ignorable background. Root `width`, `height`, and `viewBox` come from the device
canvas. One or two rectangles are emitted in explicit `--layers` order, with IDs
`screen-{screen}-layer-{layer}`, opaque fill and no stroke. Duplicate selections
are refused. Missing slots fail rather than being skipped.
Rectangle x/y = center minus half-size. Values are not rounded: this is an import
bridge preserving device measurements, not the editor's rounded export. SVG
imports accept fractional pixels. Numeric values must be finite, non-boolean,
within ±1,000,000; widths/heights must be positive. The editor performs its own
validation again before applying. Existing destinations are refused.
Only container position/size round-trips. No source association, aspect fitting,
input crop, zoom, visibility, borders, effects or device connection is encoded.
The desktop SVG mapping dialog must be reviewed before applying; the image's
visible bounds are not guaranteed to equal the container. This format must not
be presented as a full device/project backup or as validated crop conversion.

View File

@ -0,0 +1,88 @@
# Eikos connectivity and Preview check
## Verified on 2026-11-13
User-authorized hardware check on an **Eikos 4K, firmware 3.3.10**. The unit
reported this identity through `GET /api/tpp/v1/system`. Its WebRCS bundle was
`app.e42fce4879f318b28cde.js`. The device address was supplied for this session;
it is not a compiled-in application default.
- HTTP read access and WebRCS WebSocket feedback worked without authentication
on this configured device. Do not assume other installations permit this.
- `GET /api/stores/device` returned the state tree used by WebRCS, including
screen canvas dimensions, layer center positions/container sizes, source
assignments, crop/mask fields and transition state.
- The explicit REST read
`/api/tpp/v1/screens/2/live-layers/1/presets/preview` reported input 4,
matching the internal Preview bank. That REST response contained source/status,
not the full geometry. Geometry was obtained from the WebRCS state endpoint.
- Screen 2's transition state was `AT_DOWN`: Program was `DOWN`, Preview `UP`.
WebRCS's own bank-selection code maps `AT_UP` the other way around. These
are physical banks, **not permanent Program/Preview identifiers**.
- A single Preview layer property was changed over the WebRCS WebSocket:
screen 2, bank `UP`, layer 1, `position.pp.posH`, **1436 → 1437 → 1436**.
Readback confirmed the intermediate change and restoration. The complete
tested layer matched its original state after restoration. All four screen
Program preset trees matched before, during and after this test.
- No TAKE, CUT, transition, Program, input/global crop, output configuration,
source-routing or preset-memory command was sent. Raw snapshots remain
temporary local artifacts and are not committed.
The message envelope observed and tested was `channel: "DEVICE"`, with
`data.path` an array of state-tree keys and `data.value` the new scalar value.
The read path for the tested property was:
```
device/screenList/items/2/presetList/items/UP/liveLayerList/items/1/position/pp/posH
```
This is evidence of a working bidirectional link, **not validation of either
advanced-crop export strategy**. Only horizontal center movement was exercised.
The WebRCS internal endpoint/protocol is firmware-specific, rather than a promise
of stable public REST geometry support. Manufacturer references are linked from
[the official Eikos downloads section](https://www.analogway.com/products/eikos-4k).
The linked API PDFs were not accessible during this check; protocol findings
above come from the installed device and its own WebRCS bundle.
## Read-only import bridge
The desktop app remains offline. A standard-library Python helper provides a
reproducible read-only bridge while the GUI device adapter is developed:
```sh
python3 tools/midra_probe.py --host DEVICE_IP --save-snapshot /tmp/eikos-state.json
python3 tools/midra_probe.py --host DEVICE_IP --screen 2 --layers 1 2 --svg /tmp/preview.svg
# Replay a saved snapshot without connecting:
python3 tools/midra_probe.py --snapshot /tmp/eikos-state.json --screen 2 --layers 1 2 --svg /tmp/replay.svg
```
Select the matching number of editor layers, choose **Import SVG**, and review
mapping before applying. Match the editor output resolution to the device canvas;
SVG geometry import does not replace the editor's screen settings.
The helper exports **container geometry only**: center minus half-size becomes
top-left x/y, preserving half pixels. Source aspect fitting can make the visible
picture differ from this container. Routing, source resolution, source cropping,
effects, borders, opacity and zoom are not imported. Nonzero layer crop or mask
is refused rather than silently imported as final visible bounds. Device slots
are explicitly selected; unused slots are not assumed to be available layers.
The helper has no device write operation, bypasses system proxies, refuses
redirects, bounds reads to 32 MiB and never overwrites an existing output file.
Snapshots may contain network/private configuration; keep them out of Git and
sanitize before sharing. Its exchange contract is documented in
[interfaces](interfaces/midra-device-import.md).
## Remaining integration work
- Build a reviewed GUI import with explicit screen/layer mapping and unsupported
state reporting; preserve the current project until import is accepted.
- Verify source/input and layer crop units and Centered aspect behavior. Observed
crop edge values such as `18350` must not be interpreted as editor source pixels.
- Validate size, vertical position, odd dimensions and both export strategies
independently before enabling their device commands.
- Production writes need explicit Preview targeting, transition-state monitoring,
fresh before/after review and stale-state rejection. A GET followed by a
physical-bank write is not atomic: another controller can TAKE between them.
Do not expose this diagnostic write technique as a generally safe send button.
- Never write shared input/output configuration to implement a Preview-only edit.
No Program or TAKE operation belongs in this layout tool's Preview adapter.

View File

@ -6,7 +6,8 @@ selection, explicit-target alignment, numeric corner positioning/size, undo/redo
and camera zoom/pan. Concept A is user-approved.
Reference images, output presets/custom resolution, source/input formats and
advanced crop-backed content zoom/offset are implemented offline. Device mapping
verification, connectivity and REST calls remain deferred. Checklist gates
verification and GUI connectivity remain deferred. An authorized Eikos 3.3.10
read/Preview-write/restore check passed; see [hardware findings and import bridge](midra-layout-device-check.md). Checklist gates
that combine implemented and outstanding work remain open.
Target: Analog Way Eikos 4K, running the latest firmware according to the user.
Record the actual installed version during compatibility checks; do not infer it
@ -31,8 +32,10 @@ Remaining work, in priority order:
3. Additional clipboard adapters after obtaining real application/version samples.
4. Local device mappings, specific-layer export, destination review, and two
independently tested sizing/crop strategies. Hardware values remain provisional.
5. Mocked REST integration and exact-firmware verification in an isolated setup.
No authorization to probe/write the currently live Eikos is implied.
5. GUI device integration and broader exact-firmware verification. The user
authorized the 2026-11-13 read and Preview-only test; bidirectional connectivity
passed on Eikos 3.3.10. Program writes remain forbidden. See the hardware
findings for remaining crop, race-condition and mapping gates.
6. Operator-laptop/DPI/OS acceptance, performance measurements and release packaging.
Checked entries below refer to implemented offline behavior. Items combining an
@ -55,7 +58,8 @@ The reference image is an editing aid, not an additional hardware layer. Screen
resolution is independent of the application window size, zoom and image size.
Source routing, transitions, playback, masking, rotation, keying, live preview
and device control remain outside the offline implementation scope. Device writes
are a later stretch goal (step 10), not authorized work on the connected unit.
remain a later GUI stretch goal (step 10). The separately authorized hardware
check is documented above; it does not enable automatic device sends.
Input cropping and virtual layer
resolutions are implemented offline; device mapping still requires verification.
Their coordinate spaces must be designed from the start. See the

View File

@ -508,3 +508,9 @@ a rigid group. Hidden layers are ignored; visible locked layers can be targets.
Hold **Alt** to bypass snapping. Turning snapping on/off alone never moves layers.
Exact numeric entry and nudges bypass proximity snapping; resize and crop handles
retain their existing behavior. One drag remains one undo step, with Escape to cancel.
## Hardware connectivity check
The [Eikos 3.3.10 check](midra-layout-device-check.md) records the authorized
Preview-only round trip and a read-only snapshot/SVG import helper. The desktop
editor remains offline; full device crop mapping and GUI connectivity are pending.

84
tests/test_midra_probe.py Normal file
View File

@ -0,0 +1,84 @@
import contextlib
import copy
import io
import json
from pathlib import Path
import tempfile
import unittest
from unittest.mock import patch
from xml.etree import ElementTree as ET
from tools import midra_probe as probe
def snapshot():
layer = {'position': {'pp': {'posH': 1436, 'posV': 540}},
'size': {'pp': {'sizeH': 967, 'sizeV': 544}},
'crop': {'pp': dict.fromkeys(('left', 'right', 'top', 'bottom'), 0)},
'mask': {'pp': dict.fromkeys(('left', 'right', 'top', 'bottom'), 0)}}
screen = {'canvas': {'status': {'size': {'pp': {'sizeH': 1920, 'sizeV': 1080}}}},
'presetList': {'items': {'UP': {'liveLayerList': {'items': {'1': layer}}},
'DOWN': {'liveLayerList': {'items': {'1': copy.deepcopy(layer)}}}}}}
screen['presetList']['items']['DOWN']['liveLayerList']['items']['1']['position']['pp']['posH'] = 100
return {'device': {'screenList': {'items': {'2': screen}},
'transition': {'screenList': {'items': {'2': {'status': {'pp': {'transition': 'AT_DOWN'}}}}}}}}
class MidraProbeTests(unittest.TestCase):
def test_preview_bank_and_half_pixel_container(self):
data = snapshot()
root = ET.fromstring(probe.container_svg(data, '2', ['1']))
rect = root.find('{http://www.w3.org/2000/svg}rect')
self.assertEqual(rect.attrib['x'], '952.5')
self.assertEqual(rect.attrib['y'], '268.0')
self.assertEqual(root.attrib['data-midra-layout-geometry'], '1')
data['device']['transition']['screenList']['items']['2']['status']['pp']['transition'] = 'AT_UP'
self.assertEqual(probe.preview_bank(data, '2'), 'DOWN')
self.assertIn('x="-383.5"', probe.container_svg(data, '2', ['1']))
def test_reject_transition_crop_mask_and_bad_selection(self):
for field in ('crop', 'mask'):
data = snapshot()
data['device']['screenList']['items']['2']['presetList']['items']['UP']['liveLayerList']['items']['1'][field]['pp']['left'] = 18350
with self.assertRaisesRegex(ValueError, field):
probe.container_svg(data, '2', ['1'])
for ids in ([], ['1', '1'], ['1', '2', '3']):
with self.assertRaises(ValueError):
probe.container_svg(snapshot(), '2', ids)
data = snapshot()
data['device']['transition']['screenList']['items']['2']['status']['pp']['transition'] = 'EFFECT_FROM_UP'
with self.assertRaisesRegex(ValueError, 'transitioning'):
probe.preview_bank(data, '2')
def test_reject_invalid_numbers(self):
for value in (True, '12', float('nan'), float('inf'), 1000001):
with self.assertRaises(ValueError):
probe.number(value)
with self.assertRaises(ValueError):
probe.number(0, positive=True)
def test_network_is_get_only_and_bounded(self):
with patch.object(probe, 'build_opener') as factory:
response = factory.return_value.open.return_value.__enter__.return_value
response.read.return_value = json.dumps(snapshot()).encode()
self.assertEqual(probe.read_snapshot('192.0.2.1'), snapshot())
factory.return_value.open.assert_called_once_with('http://192.0.2.1/api/stores/device', timeout=15)
response.read.assert_called_once_with(probe.LIMIT + 1)
response.read.return_value = b'x' * (probe.LIMIT + 1)
with self.assertRaisesRegex(ValueError, '32 MiB'):
probe.read_snapshot('192.0.2.1')
with self.assertRaises(ValueError):
probe.read_snapshot('example.org/path')
self.assertIsNone(probe.NoRedirect().redirect_request(None, None, 302, '', {}, 'http://elsewhere'))
def test_offline_import_and_no_overwrite(self):
with tempfile.TemporaryDirectory() as folder, contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
source = Path(folder) / 'source.json'
output = Path(folder) / 'import.svg'
source.write_text(json.dumps(snapshot()))
argv = ['--snapshot', str(source), '--svg', str(output), '--screen', '2', '--layers', '1']
self.assertEqual(probe.main(argv), 0)
saved = output.read_bytes()
self.assertEqual(probe.main(argv), 1)
self.assertEqual(output.read_bytes(), saved)
self.assertEqual(probe.main(['--snapshot', str(source), '--svg', str(source)]), 1)

121
tools/midra_probe.py Normal file
View File

@ -0,0 +1,121 @@
"""Read-only Midra snapshot capture and layer-container SVG import bridge."""
import argparse
import ipaddress
import json
import math
from pathlib import Path
import sys
from urllib.request import HTTPRedirectHandler, ProxyHandler, build_opener
from xml.etree import ElementTree as ET
LIMIT = 32 * 1024 * 1024
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def read_snapshot(host):
"""GET only; explicit IP, no proxies, credentials, redirects or write API."""
address = ipaddress.ip_address(host)
authority = f'[{address}]' if address.version == 6 else str(address)
opener = build_opener(ProxyHandler({}), NoRedirect())
with opener.open(f'http://{authority}/api/stores/device', timeout=15) as response:
data = response.read(LIMIT + 1)
if len(data) > LIMIT:
raise ValueError('Device snapshot exceeds 32 MiB')
return json.loads(data)
def preview_bank(snapshot, screen):
transition = snapshot['device']['transition']['screenList']['items'][screen]
state = transition['status']['pp']['transition']
if state not in ('AT_UP', 'AT_DOWN'):
raise ValueError(f'Screen {screen} is transitioning ({state}); retry when idle')
return 'DOWN' if state == 'AT_UP' else 'UP'
def number(value, *, positive=False):
if isinstance(value, bool) or not isinstance(value, (float, int)):
raise ValueError('Expected numeric device geometry')
if not math.isfinite(value) or abs(value) > 1_000_000 or (positive and value <= 0):
raise ValueError('Invalid device geometry')
return value
def container_svg(snapshot, screen, layers):
"""Export device containers, deliberately not inferred visible/cropped bounds."""
if not 1 <= len(layers) <= 2 or len(set(layers)) != len(layers):
raise ValueError('Choose one or two distinct layer IDs to match editor selection')
bank = preview_bank(snapshot, screen)
data = snapshot['device']['screenList']['items'][screen]
size = data['canvas']['status']['size']['pp']
width, height = (number(size[k], positive=True) for k in ('sizeH', 'sizeV'))
root = ET.Element('svg', {
'xmlns': 'http://www.w3.org/2000/svg', 'data-midra-layout-geometry': '1',
'width': str(width), 'height': str(height), 'viewBox': f'0 0 {width} {height}',
})
ET.SubElement(root, 'title').text = f'Midra screen {screen} Preview layer containers'
for layer_id in layers:
layer = data['presetList']['items'][bank]['liveLayerList']['items'][layer_id]
# Never silently treat cropped/masked containers as the final visible box.
for field in ('crop', 'mask'):
edges = layer[field]['pp']
if any(number(edges[edge]) != 0 for edge in ('left', 'right', 'top', 'bottom')):
raise ValueError(f'Layer {layer_id} has {field}; visible bounds conversion is not verified')
w, h = (number(layer['size']['pp'][k], positive=True) for k in ('sizeH', 'sizeV'))
cx, cy = (number(layer['position']['pp'][k]) for k in ('posH', 'posV'))
ET.SubElement(root, 'rect', {
'id': f'screen-{screen}-layer-{layer_id}',
'x': str(cx - w / 2), 'y': str(cy - h / 2),
'width': str(w), 'height': str(h), 'fill': '#173b50',
})
ET.indent(root)
return ET.tostring(root, encoding='unicode') + '\n'
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
source = parser.add_mutually_exclusive_group(required=True)
source.add_argument('--host', help='Device IP address; read-only HTTP GET')
source.add_argument('--snapshot', type=Path, help='Previously captured device JSON; no network')
parser.add_argument('--save-snapshot', type=Path, help='Save raw vendor state (may contain private configuration)')
parser.add_argument('--svg', type=Path, help='Export Preview container geometry for Import SVG')
parser.add_argument('--screen', default='1')
parser.add_argument('--layers', nargs='+', help='Explicit device layer IDs, one or two in mapping order')
args = parser.parse_args(argv)
try:
if args.svg and not args.layers:
raise ValueError('--svg requires --layers; device slots are not editor slots')
outputs = [p for p in (args.save_snapshot, args.svg) if p is not None]
if len({p.resolve() for p in outputs}) != len(outputs):
raise ValueError('Snapshot and SVG require different output files')
if any(p.exists() for p in outputs):
raise ValueError('Output already exists; choose a new filename')
if args.snapshot:
with args.snapshot.open('rb') as stream:
raw = stream.read(LIMIT + 1)
if len(raw) > LIMIT:
raise ValueError('Snapshot exceeds 32 MiB')
snapshot = json.loads(raw)
else:
snapshot = read_snapshot(args.host)
bank = preview_bank(snapshot, args.screen)
svg = container_svg(snapshot, args.screen, args.layers) if args.svg else None
if args.save_snapshot:
with args.save_snapshot.open('x', encoding='utf-8') as stream:
stream.write(json.dumps(snapshot, indent=2, allow_nan=False) + '\n')
if args.svg:
with args.svg.open('x', encoding='utf-8') as stream:
stream.write(svg)
print('SVG contains layer containers only; source framing, effects and routing are not imported.')
print(f'Read screen {args.screen}: Preview = {bank}. No device writes.')
return 0
except (OSError, ValueError, KeyError, TypeError) as error:
print(f'Midra read/import failed: {error}', file=sys.stderr)
return 1
if __name__ == '__main__':
sys.exit(main())