beffroi-tools/docs/interfaces/midra-input-preview.md

105 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Midra input preview stills
This is a device-read interface, not a new project or export format. Verified on
Eikos 4K firmware 3.3.10, WebRCS `app.e42fce4879f318b28cde.js`.
## Discovery and request
The connected snapshot's `/device/inputList/items/INPUT_N` supplies:
- `status.pp.isAvailable`: only existing hardware inputs appear.
- `status.pp.plug`: selects `plugList.items[plug].status.signal.pp.isValid`
for the last-read signal indicator.
- `snapshot.pp.enable`: capture is disabled in the editor when WebRCS snapshots
are disabled. The application does not write this field or snapshot size.
Each explicit **Capture still** or automatic timer request issues
`GET http://<configured-IP>/api/device/snapshots/inputs/N`, with N an integer
1–16 and `Cache-Control: no-cache`. IPv4 and IPv6 literal addresses are accepted;
no proxy or redirect is followed. No immediate retries, WebSocket subscription,
still-library capture or source-routing/preset writes are involved.
Only one request may be in flight, with at least five seconds between starts.
Closing the separate import dialog discards its pending dialog result; cancelling
a request also discards its result. Neither permits another request until the
first completes or times out. Closing layer properties does not cancel a direct
layer capture. The request has a 5-second connection timeout
and 20-second overall timeout. Device-provided resolution is retained; no request
to increase resolution or refresh frequency is made.
## Response and validation
A successful response must be a PNG, at most 16 MiB, and pass the common image
decoder's dimensions/allocation limits. HTTP errors, redirects, invalid PNGs,
oversize responses and decode errors leave references unchanged.
The active-input test returned 512 × 288 pixels; an inactive input returned a
blank 128 × 128 PNG. The device controls image freshness (Last-Modified) and
resolution; GET fetches the latest available snapshot, not a guaranteed
new full-resolution frame. Signal indicators may be stale until reconnect/refresh.
## Editor and persistence
**Import input snapshot…** displays the image and its actual pixel dimensions.
Its destination selector lists every editor layer by stable ID and a Reference
image option, independently of current selection. Layer destinations offer
**Keep refreshing this layer**; this is staged until Import into layer and sets
that layer's automatic-refresh flag. Reference destinations never expose or apply
that flag and remain fixed images. Import does not alter selection or geometry. **Add as reference**
is explicit and obeys the 32-image/64 MiB combined-reference limits. Existing
upscale/aspect warnings apply. Capture in this separate import dialog only stages
an image until Import into layer or Add as reference is chosen.
Changing device address/disconnecting invalidates the pending preview; input changes
clear the old preview. A cancelled/late result cannot become a new reference.
The initial image name contains the input number and configured device IP.
Added stills use the existing [project v10 reference object](midra-layout.md):
name, embedded PNG image_base64, visible, opacity, preserve_ratio,
native_size, offset. No new fields, version or migration are needed.
**Import into layer** assigns a session-only still texture to the destination
editor layer's stable ID and current local input. It uses the editor's native
source rectangle, input crop and dynamic crop/zoom mapping, including faded
overflow while editing. It does not infer or change device routing. Changing the
local input hides that assignment; opening/New/Recovery clears assignments.
Reordering layers does not move an assignment to another layer.
In the layer Preview tab, the workflow is **Enable input preview → Input →
Capture still → Auto-refresh this preview**. Enable and auto-refresh are separate
per-layer session booleans. An enabled preview may have an input selected but no
texture yet. Capture still directly replaces only that layer's texture; repeating
it recaptures. Auto-refresh can fetch the first image without a manual capture.
The physical input picker uses available device inputs and is unrelated to the
editor input identity or Midra layer mapping. Input changes discard the old image.
Manual jobs bind to the layer's stable ID, source identity, physical input and
host at request time; selection changes do not redirect results. Changed/removed
assignments and disabled previews reject late results. Disabling a preview hides
its image and pauses requests without losing its still or chosen opacity. **Crop guide
opacity** is a per-layer session value from 0–100%, initially 35% when assigned.
The source test-pattern guides paint above the image; selection borders/handles
remain opaque. When the preview is hidden or absent, the slider is disabled at
100% and the original opaque pattern is used. Showing the preview again restores
the chosen opacity. Outside-box content retains the existing 50% ghost treatment.
The same mapping/compositing is used in the viewport and the dedicated Preview
tab in Layer properties. That tab contains capture, auto-refresh, visibility and
guide-opacity controls; Crop contains geometry controls. Opening Preview does not
activate visual crop editing. The layer context menu also exposes preview controls.
Layer-preview assignments, texture bytes, visibility toggles and guide opacity
are not saved/exported. Add as reference remains the separate persistent path;
generic artwork exports include those references only through the existing
background option. Reloading a project makes no capture requests.
**Auto-refresh this preview** is opt-in per layer and session-only, with a shared request interval
of 5–300 seconds (default 10). Assignments also retain the device address and
physical input number in memory. Visible layers with enabled automatic previews, unchanged
local inputs and the current device address are eligible; unavailable or
snapshot-disabled inputs are skipped. Unique inputs refresh round-robin, one
request per interval, sharing the returned texture only across matching automatic
assignments. Manual stills are never replaced by another layer's automatic refresh.
Manual and automatic capture share one worker slot and the five-second minimum.
Automatic capture pauses offline, during project loading and while the capture
dialog is open. Errors retain the last good image and wait for the next interval;
there are no immediate retries. Turning off refresh prevents applying an in-flight
automatic result. Project replacement clears assignments and discards stale results.
Automatic refresh never changes fixed references or device settings. Timer settings
are not persisted; no save schema changes are involved.
Live feeds and separate image-file saving are not implemented.