114 lines
7.7 KiB
Markdown
114 lines
7.7 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 selected configuration captures one physical bank. Send writes directly without a preflight read or stale-snapshot refusal. 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. Valid plans remain sendable even when stored geometry matches: sending still applies staged values. Failure reports
|
||
partial/uncertain outcomes without blind retries or automatic rollback.
|
||
|
||
Program selection is explicit. The application defaults to Preview and hides Program unless the persisted `allow_sending_to_program` preference is enabled. Turning it off resets the exporter to Preview, including quick Apply. Layer screen/destination links are saved in project version 5. 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 preserve saved links. Physical display
|
||
validation remains separate from the successful device-field and import round trips.
|
||
|
||
The status-bar and Export-menu **Apply changes…** actions only open export configuration, even when current layers have valid saved links. They never start a write. The user chooses layers, mappings, target and sizing, then explicitly clicks **Send mapped layers**. Busy/offline actions are disabled. **Send all linked layers** remains a separate direct-send action using saved links. No persistent schema changes are involved.
|
||
|
||
Snapshot layer lists omit unassigned source slots (`NONE` or empty), before geometry validation. Assigned layers remain available even when OFF.
|
||
|
||
**Send all linked layers** includes all linked document layers, even unselected, hidden or locked ones. Plans are grouped by saved screen ID and all groups are validated before starting. Screen groups send sequentially with readback; on failure later groups are not sent, and the result reports the failed screen and completed-group count. Links never auto-send and are not tied to an IP address.
|
||
|
||
## Preset apply pulse
|
||
|
||
After the geometry writes, send two DEVICE WebSocket messages at
|
||
`device/preset/control/pp/xUpdate`: `false`, then `true`, matching WebRCS's
|
||
`DEVICE_PRESET_CONTROL_SET_ONE` action sequence. This commits staged preset edits
|
||
when `enableAutoUpdate` is false. Do not change `enableAutoUpdate` or issue TAKE.
|
||
The pulse is global and may apply other pending preset edits; it is not scoped to
|
||
an individual screen/layer. Each screen send currently ends with this pulse.
|
||
Always pulse on an explicit valid send, even if the staged geometry already
|
||
matches and the change list is empty. A pulse-write failure is reported separately
|
||
from geometry-write failure. Geometry readback follows the pulse; a readable store
|
||
alone does not prove the physical video output updated. The trigger itself is not
|
||
included in geometry comparisons, because it is a command rather than geometry.
|
||
|
||
**Send all linked layers** sends immediately using saved links and the current target and sizing settings, without opening the export window. The button shows progress and its tooltip reports completion. Invalid links or send failures open the export window with the error.
|
||
|
||
**Load linked layers**, beside the connection status and in Export, reads fresh
|
||
Midra Preview geometry and crop framing into all linked editor layers, regardless
|
||
of selection. **Apply changes… → Load mapped layers** reads only the selected
|
||
editor layers using the links chosen in that window. Both actions are read-only
|
||
on the device and always load Preview (independent of the send target). They do
|
||
not recall device memories or presets. Loading is one atomic Undo step; links
|
||
remain saved. Missing screens/layers, mismatched output resolutions, unsupported
|
||
geometry, and hidden or locked editor destinations reject the complete import
|
||
without changing the document. Unlock/show destinations before loading. Results
|
||
appear in the transfer window or the load button's status tooltip. No project or
|
||
settings schema changes are involved.
|
||
|
||
Closing a device import review with chosen destinations offers Apply/Discard.
|
||
Apply imports into the local editor atomically; it never writes to the device.
|
||
Closing send configuration does not send. Local property edits that apply
|
||
immediately still require an explicit device Send action.
|