diff --git a/README.md b/README.md index 0c05e34..8ac6839 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ opening reports, and reading video timings. - [ASCII filename cleaner](docs/ascii-names.md) - [Document exports](docs/exporter.md) - [Rundown converter](docs/rundown-converter.md) · [Sample findings](docs/rundown-corpus.md) +- [Midra layout helper: plan and visual proposals](docs/midra-layout-plan.md) (design stage) - [Development](docs/development.md) · [CI and coverage](docs/ci.md) - [Cross builds and portable releases](docs/releases.md) - [MPC-HC Companion module development](companion-modules/media-player-classic/README.md) diff --git a/docs/design/midra-layout/a-concept.svg b/docs/design/midra-layout/a-concept.svg new file mode 100644 index 0000000..6872774 --- /dev/null +++ b/docs/design/midra-layout/a-concept.svg @@ -0,0 +1,116 @@ + +Midra Layout — concept AStatic design proposal, not working software. Two 640 by 360 layers on a 1920 by 1080 screen. Right inspector shows corner offsets and converted center coordinates. + + + +MIDRA / LAYOUT +Offline position helper +DESIGN CONCEPT A + +Copy coordinates + + + +Screen 1 · 1920 × 1080 + +Reference image + +Snap: off + +Undo + +Fit screen + +Zoom ▾ +A / OPERATOR DESK +Large canvas. Familiar controls. Values always visible. +SCREEN 1 +1920 × 1080 px + + +ANNUAL FORUM / MAIN STAGE +Ideas worth sharing. +Illustrative reference artwork · opacity 65% + + + + + + + + + + + + + + + + + +01 / PRESENTER +640 × 360 px + +02 / SLIDES +640 × 360 px + + + + + + + + + +180 + +120 px +Space + drag Pan Scroll Zoom at pointer Arrows Move 1 px +Reference: stage-layout.png 1920 × 1080 1:1 mapping Locked +LAYERS + +01 Presenter +Visible + +02 Slides +Visible + +02 / Slides +Position from screen corner + + + + + +Top right +Offsets inward +From right + +120 px +From top + +180 px +Width + +640 px +Height + +360 px +Changing corner keeps the layer in place. + +WEBRCS / CENTER POSITION +Horizontal · from left + +1480 px +Vertical · from top + +360 px +Size 640 × 360 px + +Copy position values +Paste geometry… +Preview coordinates before applying. + +OFFLINE · No device connection +Static proposal · coordinate convention to verify + diff --git a/docs/design/midra-layout/b-concept.svg b/docs/design/midra-layout/b-concept.svg new file mode 100644 index 0000000..399de85 --- /dev/null +++ b/docs/design/midra-layout/b-concept.svg @@ -0,0 +1,141 @@ + +Midra Layout — concept BStatic design proposal, not working software. Two 640 by 360 layers on a 1920 by 1080 screen. Right inspector shows corner offsets and converted center coordinates. + + + +MIDRA / LAYOUT +Offline position helper +DESIGN CONCEPT B + +Copy coordinates + + + +Screen 1 · 1920 × 1080 + +Reference image + +Snap: off + +Undo + +Fit screen + +Zoom ▾ +B / PRECISION DESK +Light drafting surface with rulers and visible dimensions. +SCREEN 1 +1920 × 1080 px + + +ANNUAL FORUM / MAIN STAGE +Ideas worth sharing. +Illustrative reference artwork · opacity 65% + +0 + + +240 + + +480 + + +720 + + +960 + + +1200 + + +1440 + + +1680 + + +1920 + + +0 + +180 + +360 + +540 + +720 + +900 + +1080 + +01 / PRESENTER +640 × 360 px + +02 / SLIDES +640 × 360 px + + + + + + + + + +180 + +120 px +Space + drag Pan Scroll Zoom at pointer Arrows Move 1 px +Reference: stage-layout.png 1920 × 1080 1:1 mapping Locked +LAYERS + +01 Presenter +Visible + +02 Slides +Visible + +02 / Slides +Position from screen corner + + + + + +Top right +Offsets inward +From right + +120 px +From top + +180 px +Width + +640 px +Height + +360 px +Changing corner keeps the layer in place. + +WEBRCS / CENTER POSITION +Horizontal · from left + +1480 px +Vertical · from top + +360 px +Size 640 × 360 px + +Copy position values +Paste geometry… +Preview coordinates before applying. + +OFFLINE · No device connection +Static proposal · coordinate convention to verify + diff --git a/docs/design/midra-layout/c-concept.svg b/docs/design/midra-layout/c-concept.svg new file mode 100644 index 0000000..4c91dab --- /dev/null +++ b/docs/design/midra-layout/c-concept.svg @@ -0,0 +1,110 @@ + +Midra Layout — concept CStatic design proposal, not working software. Two 640 by 360 layers on a 1920 by 1080 screen. Right inspector shows corner offsets and converted center coordinates. + + + +MIDRA / LAYOUT +Offline position helper +DESIGN CONCEPT C + +Copy coordinates + + + +Screen 1 · 1920 × 1080 + +Reference image + +Snap: off + +Undo + +Fit screen + +Zoom ▾ +C / FOCUS DESK +More canvas space, with a compact selection inspector. +SCREEN 1 +1920 × 1080 px + + +ANNUAL FORUM / MAIN STAGE +Ideas worth sharing. +Illustrative reference artwork · opacity 65% + + + + + + + + + + + + + + + + + +01 / PRESENTER +640 × 360 px + + + + + + + +02 / SLIDES +640 × 360 px + + + + + + + + + +180 + +120 px + +Aligned top edges · Y 180 px +Space + drag Pan Scroll Zoom at pointer Arrows Move 1 px +Reference: stage-layout.png 1920 × 1080 1:1 mapping Locked +LAYERS + +01 Presenter +Visible + +02 Slides +Visible + +2 layers selected +Reference layer: 01 / Presenter +ALIGN TO + +Reference layer: Presenter ▾ + +Align left + +Align top +Changes position only; keeps size. +Common top edge + +180 px +WEBRCS CENTER POSITIONS +01 Presenter +H 440 V 360 +02 Slides +H 1480 V 360 + +Copy both layer positions +Alignment is a later milestone. + +OFFLINE · No device connection +Static proposal · coordinate convention to verify + diff --git a/docs/midra-layout-plan.md b/docs/midra-layout-plan.md new file mode 100644 index 0000000..9d07a03 --- /dev/null +++ b/docs/midra-layout-plan.md @@ -0,0 +1,294 @@ +# Midra layout helper: plan and visual proposals + +Status: design only. No application, device connection or REST calls implemented. +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 +from a different Midra generation's documentation. Working name: **Midra Layout**. + +## Intended workflow + +Set the screen resolution, optionally load a reference picture, then place one or +two rectangular live layers visually or by entering exact offsets from a chosen +screen corner. Read or copy their equivalent WebRCS position values. Select layers +on the canvas or in the right-hand list. All work is local and offline. + +For this plan, “window” means the application window and “layer” means a video +rectangle within one screen viewport. There is no additional window/group object. +The first release supports two layers; the underlying collection should support +more later without promising that every device configuration supports them. + +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, cropping, masking, rotation, keying, live +preview and device control are outside this project phase. Width and height are +needed for positioning, but this is not an image or presentation editor. + +## Ordered task list + +Complete each acceptance gate before broadening the scope. The first usable +release comprises steps 1–6 and release checks in step 8. Step 7 is later work. + +### 1. Establish the Eikos 4K coordinate contract + +- [ ] Record device model, exact firmware and relevant WebRCS field labels. +- [ ] Check horizontal and vertical origins, signs, pixel units, numeric step, + accepted size/position ranges and off-screen placement in that WebRCS version. +- [ ] Verify whether the editable bounds refer to the layer rectangle rather + than cropped source content. Start with an unmasked, uncropped live layer. +- [ ] Check odd widths/heights and half-pixel centers; do not round silently. +- [ ] Record examples at all four screen corners and at screen center using a + simulator or manual entry in an appropriate test setup, without API calls. + +Gate: a small verified input/output table establishes what the application may +label as WebRCS-compatible. The example math below is provisional until then. + +### 2. Review visual direction and prove the viewport + +- [ ] Choose a direction from the three proposals below. Recommended: A, with + B's optional rulers and C's contextual alignment panel later. +- [ ] Build a disposable viewport interaction spike with two rectangles before + committing to the full UI. Rust/egui is the preferred starting point because + the repository already uses it; validate interaction quality before settling. +- [ ] Prove pointer-centered zoom, pan, selection, hit testing, keyboard nudge, + image rendering and display scaling on the target operator laptop. +- [ ] Try a dense reference image at Fit, 100%, 400% and 1600% zoom and at several + OS display scales. Zooming must not move layer coordinates. +- [ ] Review at 1440 × 900 and 1024 × 768 logical window sizes, including enlarged + UI text. Keep numerical controls usable with a scrollable right inspector. + +Gate: the viewport feels predictable and shows exact edges clearly. If the +toolkit cannot meet these needs, resolve that before building the rest. + +### 3. Implement geometry independently of the UI + +- [ ] Add the future workspace member `crates/midra-layout/` with shared geometry + and a desktop binary. Do not add placeholder workspace members during planning. +- [ ] Model screen dimensions and stable layer IDs with canonical top-left + position and size. Keep selection, camera and reference image separate. +- [ ] Implement four-corner offset conversion and inverse WebRCS conversion + under the verified device contract. +- [ ] Switching corner changes the displayed offsets without moving the layer. + Resizing keeps the chosen corner and its offsets fixed; moving changes offsets. +- [ ] Preserve precision internally. Validate finite numbers, positive sizes and + device limits; report unsupported values without silently clamping them. +- [ ] Test all corners, inverse round trips, odd dimensions, negative offsets, + non-16:9 screens, exact screen edges and resizing from each anchor. + +Gate: viewport scale and UI state cannot affect geometry or conversion results. + +### 4. Build the two-layer positioning workspace + +- [ ] Add screen resolution controls, one/two-layer setup, persistent layer IDs + and names, and a right-hand layer list with a selected-layer inspector. +- [ ] Support click selection, Shift-click multi-selection, clear selection and + list selection for overlapped or off-screen rectangles. Define deterministic + overlap hit testing; list order represents preview stacking, not device routing. +- [ ] Add dragging, exact width/height fields, four-corner selection and inward + offsets. Prefer numeric sizing first; add resize handles only with anchor + behavior consistent with the geometry contract. +- [ ] Show WebRCS horizontal/vertical center values beside corner inputs; make + output values read-only initially. Offer per-value copy and labeled plain text + for a whole layer. Do not imply plain text is a WebRCS-native clipboard format. +- [ ] Add arrow nudges of 1 screen pixel and Shift-arrow nudges of 10; focused + text fields must receive these keys instead of moving the selection. +- [ ] Implement Space-drag/middle-button pan, pointer-centered zoom, Fit screen, + Fit selection, explicit zoom percentage and a clearly defined 1:1 pixel view. +- [ ] Keep handles/hit areas legible at every zoom; distinguish UI logical points, + screen pixels and physical display pixels on HiDPI screens. +- [ ] Add visible optional snapping to pixel edges, screen edges and other layer + edges. Exact numeric entry bypasses proximity snapping. Show the active guide + and allow a temporary snap override; toggling snapping must not move anything. +- [ ] Add undo/redo for geometry changes, one undo step per drag or committed + field edit, and Escape to cancel an in-progress drag or uncommitted edit. + +Gate: place a layer 120 px from the right and 180 px from the top, change zoom, +switch anchors and move it by one pixel without losing track of the real values. +Selection and dragging never alter unrelated layers. No selection shows screen +and reference settings; multi-selection shows mixed values explicitly. + +### 5. Add accurate reference-picture placement + +- [ ] Load PNG/JPEG through a file picker or drag/drop; report decoding failures + while preserving the current image. Keep source files unchanged. +- [ ] Use a matching-resolution image at screen origin with 1 image pixel per + screen pixel. For mismatched dimensions, display the mismatch and require an + explicit mapping choice: native pixels with offset, fit preserving aspect, or + stretch to screen. Show scale, offsets and any letterboxing. +- [ ] Lock the reference by default, add hide/show and opacity controls, and + offer outline-only layer display so image edges remain visible. +- [ ] Use sharp nearest-neighbor inspection at high zoom and an appropriate + downsampled view when zoomed out. Do not confuse filtering with coordinate + precision. Reveal the screen-pixel grid only when it is legible. +- [ ] Decode large images away from the input/render loop, cap supported image + dimensions/memory with useful errors, and preserve viewport responsiveness. + +Gate: a known rectangle in a 1920 × 1080 test image can be matched exactly by a +layer; changing image opacity, visibility, zoom or filtering changes no geometry. + +### 6. Add extensible clipboard position import + +- [ ] Start with an explicit, documented plain-text geometry format and a + paste-preview panel. For example: `x=1160; y=180; width=640; height=360; origin=top-left; unit=px`. +- [ ] Preview parsed values, origin, units, target layer and before/after bounds. + Allow position-only import; importing size must be an explicit choice. +- [ ] Treat Ctrl/Cmd-V in a focused text input as normal text paste. Elsewhere, + open geometry preview; do not mutate the document merely by reading clipboard. +- [ ] Define adapters by source format/version. Collect actual clipboard samples + from the first requested software before claiming support; that software is + not yet specified. Do not guess an application from an unlabeled number tuple. +- [ ] Make points, inches, percentages, source canvas origins, decimal conventions + and scale explicit. Ambiguity produces an explanation, not a guessed placement. +- [ ] Validate the complete proposed edit before applying it atomically, with one + undo step. Unknown formats, missing fields and invalid values preserve state. +- [ ] Test real fixtures for every added adapter and clipboard failure behavior + on supported desktop platforms, including Wayland where applicable. + +Gate: supported data places the selected rectangle correctly; malformed or +ambiguous data makes no changes. Ship the basic format first if no external +software format has yet been selected; do not claim that completes an adapter. + +### 7. Later: explicit multi-layer alignment + +- [ ] Add Align top and Align left first; show the alignment target explicitly: + screen, selection bounds or a named reference layer. +- [ ] For a reference layer, keep that layer fixed and move only the others. + For selection bounds, align to the minimum top/left edge. For the screen, + align to coordinate zero on the selected axis. +- [ ] Preserve sizes and the other axis, preview the affected selection, and + make each alignment a single undoable operation. +- [ ] Extend to right/bottom/center alignment and more layers only when needed, + within verified device capabilities. No distribution or constraint system yet. + +Gate: two differently sized layers align exactly against the chosen target, +regardless of selection order except when explicitly choosing a reference layer. + +### 8. Harden and package the first release + +- [ ] Include empty, invalid-input, reference-load-error, off-screen and clipboard + error states in UI review, with an obvious way to recover or frame the selection. +- [ ] Verify tab order, keyboard focus, numeric input commit/cancel, contrast and + selection indicators that do not rely on color alone. +- [ ] Manually exercise screen/reference setup → corner positioning → nudge → + paste preview → copy values → undo. Verify results in the target WebRCS setup. +- [ ] Add geometry/import regression tests and interaction tests for camera + transforms and undo. Establish a smooth-drag baseline on the operator laptop; + target a 60 Hz interaction budget, measuring rather than assuming performance. +- [ ] Document supported firmware, coordinate conventions, clipboard formats, + limits and shortcuts. Keep the root README to a short link/quick start. +- [ ] Integrate the actual crate into workspace CI, coverage and manual packaging; + run the repository Rust gates, whole-application coverage and relevant packaging + tests. Document unavailable device or desktop checks. +- [ ] Commit each completed task; no automatic release publishing. + +Session-file save/load can follow if needed; it is not required to demonstrate +precise positioning. No networking work is included in this plan. + +## Coordinate contract to verify + +Proposed internal model: screen origin at its top-left, X increases rightward, +Y increases downward, and a layer is `(x, y, width, height)`. Positive corner +offsets point inward. A corner means the matching corner of the layer measured +from that screen corner; there are not two independent anchor selectors in v1. + +For screen size `W × H`, layer size `w × h`, and offsets `dx, dy`: + +| Selected corner | Layer left `x` | Layer top `y` | +| --- | --- | --- | +| Top left | `dx` | `dy` | +| Top right | `W - dx - w` | `dy` | +| Bottom left | `dx` | `H - dy - h` | +| Bottom right | `W - dx - w` | `H - dy - h` | + +Under the user's described center-position convention, WebRCS values are +`horizontal = x + w/2`, `vertical = y + h/2`. The inverse subtracts the half-size. +The corresponding inward margins are `left=x`, `top=y`, `right=W-x-w` and +`bottom=H-y-h`. Switching corner just chooses which margins to display. + +Example used in every mockup: on a **1920 × 1080** screen, a **640 × 360** layer +**120 px from the right** and **180 px from the top** has top-left **1160, 180** +and center **1480, 360**. The other layer is at **120, 180**, center **440, 360**. +An odd width such as 641 produces a half-pixel center when the left edge is an +integer; hardware acceptance/rounding is a compatibility question, not something +to hide with display formatting. + +## Visual proposals + +These are original, editable SVG interface mockups, not application screenshots. +Open them in a browser or image viewer to inspect at full size. The example +background is illustrative artwork standing in for an imported picture. Labels +such as “Copy” and “Paste” illustrate planned controls; nothing is interactive yet. + +### A. Operator desk — recommended + +Dark slate surfaces, cyan selection, amber second-layer identity and a restrained +purple primary action consistent with existing repository interfaces. A large +viewport occupies the left; the fixed right inspector groups the layer list, +corner selector, offsets, size and WebRCS outputs in reading order. Thin outlines, +corner markers, center crosshairs and dimension guides make selection unambiguous. + +![Concept A: dark operator workspace](design/midra-layout/a-concept.svg) + +Best for working beside show-control tools. The tradeoff is less contrast against +dark reference images; add a contrasting outline halo and an outline-only mode. +Keep the output card visible while upper inspector sections scroll. A compact +bottom status line carries camera/pixel information and shortcut hints. + +### B. Precision desk + +A light inspector and drafting surface with screen-coordinate rulers. The same +placement workflow emphasizes measurements and field readability. The artwork +retains its own colors independently of the UI theme. + +![Concept B: light workspace with coordinate rulers](design/midra-layout/b-concept.svg) + +Best for daytime preparation and detailed artwork matching. It uses more visible +measurement marks and can feel busier; rulers and guides should be optional. Its +useful features can be incorporated into A without maintaining two different apps. + +### C. Focus desk + +A wider viewport and narrower contextual inspector. This proposal shows the +future multi-selection state: a named reference layer, explicit alignment actions +and a compact per-layer coordinate table. The layer list remains on the right. + +![Concept C: compact workspace with two selected layers](design/midra-layout/c-concept.svg) + +Best for repeated placement and comparison once the basic workflow is familiar. +Less space for numeric explanations makes it weaker as the initial default. +The alignment state belongs to step 7; it does not imply a larger first release. + +### Shared interaction and responsive behavior + +Keep the screen aspect ratio exact, surround it with a neutral pan area, and use +consistent screen-space selection markers. Display only relevant guides, with +labels in screen pixels. Layer identity and selected state must be distinct. +Always allow selecting a layer from the list when its outline is hard to hit. + +The desktop window should retain a right inspector at normal working sizes. +At narrow widths, reduce decorative padding and collapse secondary sections; +below the proven minimum width, use a right drawer rather than crushing numeric +fields. At short heights, scroll sections while retaining access to conversion +outputs. Mouse and keyboard interaction are the first priority; a mobile UI is +not part of this desktop tool. + +## Research and open decisions + +The [Analog Way Midra 4K V3.2 manual, July 2024, pp. 83–85](https://www.bhphotovideo.com/lit_files/1168243.pdf#page=83) +documents layer alignment, snapping, position and size controls. This supports +the workflow research; it does not establish the precise coordinate convention +or current firmware behavior for the user's installation. Avoid portraying all +WebRCS versions as lacking alignment. The proposed improvement is more explicit +corner-based positioning and reference-image inspection. + +[Figma's zoom/view documentation](https://help.figma.com/hc/en-us/articles/360041065034-Adjust-your-zoom-and-view-options) +provides useful precedents for fit-to-view, selection zoom and pixel inspection. +Borrow those interaction ideas, without introducing vector-editor features. + +Analog Way's [Midra 4K FAQ](https://www.analogway.com/midra-4k-faqs) identifies an +offline simulator that may help verify behavior without connecting this helper +to hardware. Simulator agreement should still be checked against the installed +WebRCS version. + +Open decisions before implementation: preferred visual direction; exact installed +firmware; first clipboard source application and representative payload; primary +operator OS/display scale. None prevents reviewing these design proposals.