diff --git a/docs/interfaces/midra-device-import.md b/docs/interfaces/midra-device-import.md new file mode 100644 index 0000000..2e69e8c --- /dev/null +++ b/docs/interfaces/midra-device-import.md @@ -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. diff --git a/docs/midra-layout-device-check.md b/docs/midra-layout-device-check.md new file mode 100644 index 0000000..37c4090 --- /dev/null +++ b/docs/midra-layout-device-check.md @@ -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. diff --git a/docs/midra-layout-plan.md b/docs/midra-layout-plan.md index bfc3fcc..fe60818 100644 --- a/docs/midra-layout-plan.md +++ b/docs/midra-layout-plan.md @@ -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 diff --git a/docs/midra-layout.md b/docs/midra-layout.md index e4433ed..1df21b6 100644 --- a/docs/midra-layout.md +++ b/docs/midra-layout.md @@ -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. diff --git a/tests/test_midra_probe.py b/tests/test_midra_probe.py new file mode 100644 index 0000000..fcf4dbf --- /dev/null +++ b/tests/test_midra_probe.py @@ -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) diff --git a/tools/midra_probe.py b/tools/midra_probe.py new file mode 100644 index 0000000..2aeee16 --- /dev/null +++ b/tools/midra_probe.py @@ -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())