79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# Midra reviewed layer exchange
|
||
|
||
This is a transient device protocol, not a project/save schema. Project v4 remains
|
||
unchanged. Compatibility exercised: Eikos 4K firmware 3.3.10, installed WebRCS
|
||
`app.e42fce4879f318b28cde.js`. Other firmware needs verification.
|
||
|
||
## Addressing and fields
|
||
|
||
HTTP GET `/api/tpp/v1/system` and `/api/stores/device` supply identity and snapshots.
|
||
A WebSocket at `ws://DEVICE_IP/` accepts JSON text:
|
||
|
||
```json
|
||
{"channel":"DEVICE","data":{"path":["device","screenList","items","2","presetList","items","UP","liveLayerList","items","1","position","pp","posH"],"value":162}}
|
||
```
|
||
|
||
Reviewed fields under the mapped live layer are only:
|
||
|
||
- `size.pp.sizeH`, `size.pp.sizeV`: integer container pixels, 1–65535.
|
||
- `position.pp.posH`, `position.pp.posV`: integer center coordinates, −67268–67268.
|
||
- `crop.pp.left`, `right`, `top`, `bottom`: normalized integers, 0–65535.
|
||
- `crop.pp.aspectOverride`: `CENTERED`.
|
||
|
||
At `AT_DOWN`, Preview is UP and Program DOWN; `AT_UP` reverses those roles.
|
||
The review captures one physical bank. Preflight rejects changed transition,
|
||
canvas, mapped source, size, position, crop, mask or content dimensions. A TAKE
|
||
between checking and writing can change the bank's role; the user explicitly
|
||
permits this. Commands do not retarget halfway through. No TAKE or source routing,
|
||
mask, effect, opacity, shared input crop or output setting is sent.
|
||
|
||
## Conversion
|
||
|
||
The editor native source dimensions must equal the destination layer's reported
|
||
`status.pp.contentWidth/contentHeight`. These describe the incoming content used
|
||
for this layer, not an instruction to change input hardware configuration.
|
||
|
||
Combine each local input crop edge with its advanced layer crop edge, in native
|
||
source pixels. Quantize each combined edge to `round(edge / native_axis * 65535)`.
|
||
Reject exhausted retained regions, invalid geometry, masked destinations and
|
||
source-resolution mismatch. Input correction is folded into the layer crop,
|
||
so it affects only the mapped destination.
|
||
|
||
For **Output-sized**, round the requested visible width/height to container pixels.
|
||
For **Source aspect**, compute `k = max(visible_width/native_width,
|
||
visible_height/native_height)` and round `native * k` as the container size. The
|
||
post-crop retained source fits inside this container with Centered aspect. Both
|
||
modes center the container at the rounded requested visible center.
|
||
|
||
Reconstruct the retained size from quantized crop fractions, then use
|
||
`min(container_width/retained_width, container_height/retained_height)` to derive
|
||
visible bounds. Reject size errors above one output pixel. Center rounding has
|
||
at most half a pixel of error. Stored editor coordinates retain full precision;
|
||
review values use one decimal and transmitted geometry uses whole pixels.
|
||
|
||
## Import and round trip
|
||
|
||
Centered layers with zero masks and valid content dimensions reconstruct their
|
||
visible geometry with the same fit calculation. Imported sources are independent
|
||
local sources with the device content dimensions, zero input correction, and all
|
||
combined cropping stored in advanced crop. Thus the visual framing survives;
|
||
the original separation into input correction and layer crop cannot be recovered.
|
||
Imports are atomic and undoable, including creation of new layers/sources.
|
||
|
||
Other aspect modes retain container-only import and reject nonzero crop/mask.
|
||
The Python snapshot-to-SVG bridge remains container-only under its existing
|
||
[contract](midra-device-import.md).
|
||
|
||
## Execution and failure semantics
|
||
|
||
Only an explicit Send click creates a worker. Read/refresh, editing, project load,
|
||
import, undo and redo never write. Requests run off the UI thread with bounded
|
||
socket operations. After preflight, changed fields are written sequentially once. Crop decreases precede increases
|
||
to avoid temporarily exhausting the retained area while moving a crop.
|
||
Readback checks every changed field. No-op plans are disabled. Failure reports
|
||
partial/uncertain outcomes without blind retries or automatic rollback.
|
||
|
||
Program selection is explicit. The application defaults to Preview. Mappings,
|
||
plans and raw snapshots are not saved in projects or preferences. The device address is saved in [application settings](midra-layout-settings.md), never in projects. Refresh and screen changes reset destination review. Physical display
|
||
validation remains separate from the successful device-field and import round trips.
|