Add isolated feature showcase recordings and capture guide
Gitea/canvas-pilot/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-17 12:10:03 +01:00
parent dc3e6cad61
commit 9e6bfb4ddc
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 1375 additions and 106 deletions

3
.gitignore vendored
View File

@ -9,3 +9,6 @@ __pycache__/
.env
/.rust-release/
/dist/
# Local showcase recordings, profiles and generated exchange files.
/showcase-videos/

2
Cargo.lock generated
View File

@ -548,7 +548,7 @@ dependencies = [
[[package]]
name = "canvas-pilot"
version = "0.9.16"
version = "0.9.17"
dependencies = [
"base64",
"craft-dwg",

View File

@ -4,7 +4,7 @@ default-members = ["crates/canvas-pilot"]
resolver = "3"
[workspace.package]
version = "0.9.16"
version = "0.9.17"
edition = "2024"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/canvas-pilot"

View File

@ -4,6 +4,18 @@
## Unreleased
### v0.9.17
- Added isolated feature-recording recipes, a shot-by-shot capture guide and a
Git-ignored local video gallery with captions, contact sheets and fresh profiles.
Recorded 21 clips covering editing, crop/mask, exchange, language packs and
simulator transfers. Offline imagery and simulator footage are labelled.
- The simulator Preview send passed device readback; baseline restoration verified
all captured S1 layer fields in both banks. Python tests and the pinned manual
build pass; this is not physical-output acceptance.
- Added the requested backlog item to validate every Aquilon and Midra model,
starting with AQL C+; existing support claims and adapter checks are unchanged.
### v0.9.16
- Added language-pack management in Settings: installed revisions/languages,

View File

@ -1,130 +1,139 @@
# Canvas Pilot feature demonstration checklist
# Recording the feature showcase
Use one **Slides + Presenter** layout throughout: build it, refine it, exchange
it with other applications, then send it to a device. This is an operation list,
not a narration script. Tick off each item while recording.
Record independent clips, with a fresh project and settings profile for each take.
This avoids carrying a mistake into the next demonstration. The reproducible shot
recipes live in [record-showcase.py](../../scripts/record-showcase.py); the
[advanced guide](guide/overview.md) remains the reference for individual controls.
## Before recording
## Shot list
- [ ] Prepare a reference image of a stage or screen layout.
- [ ] Have simple rectangle layouts ready in Illustrator, Figma and draw.io.
- [ ] Prepare a PPTX or DXF file for file import.
- [ ] Have a Midra or the supported Aquilon emulator ready, with sources already routed.
- [ ] Choose a folder for the demo project and exports.
The two-layer fixture is a 1920 × 1080 output with Slides and Presenter. Special
fixtures start with crop, mask, folder, reference or cached preview state already
prepared. Captions explicitly identify that setup instead of implying it was
created during the clip.
## 1. Start a project
| Clip | Actions and result to check |
| --- | --- |
| 01 Project | Save a named project, move a layer, reopen and confirm replacement; saved geometry returns. |
| 02 Movement | Drag, corner-resize, undo/redo, enter an exact width and nudge; inspector values follow. |
| 03 Alignment | Align to the screen, relocate a pivot, resize and change measurement reference. |
| 04 Group resize | Select two layers, move together and compare same, mirrored and opposite handles with undo between examples. |
| 05 Snapping/grid | Show target choices, snap a moving edge and distinguish overlay visibility from grid snapping. |
| 06 Organization | Move a layer into a prepared folder, collapse, hide/lock, then add, name, reorder and remove a temporary layer. |
| 07 Navigation/output | Pointer-centered zoom, pan, fit screen, zoom to selection and inspect output formats. |
| 08 Crop | Start at 200%, reframe, inspect faded surroundings, recenter and reset without moving the container. |
| 09 Mask | Enter crop, Tab to mask, resize/move the reveal window, inspect hatching, center and reset. |
| 10 Source | Inspect the local source/input/layer distinction and explicit advanced-input opt-in; no input writes. |
| 11 Fit modes | Use a square container to compare Centered, Fullscreen, Cropped and 1:1 against the same image. |
| 12 Clipboard | Paste real SVG text, review destination mapping, apply geometry and undo. |
| 13 File import | Pick a real SVG file, review, import and undo. |
| 14 Export | Show formats, scope and metadata choices, then save a complete SVG layout. |
| 15 Reference | Show a prepared reference, visibility, opacity/native placement controls and layer outlines. |
| 16 Appearance/packs | Inspect installed pack revision and languages, removal confirmation, cancel, change theme and preview French with a return to English. |
| 17 Simulator | Connect to the explicitly identified local Aquilon simulator and inspect device controls. |
| 18 Cached preview | Inspect preview/guide controls using a labelled offline image; this is not live capture. |
| 19 Mask snapping | With only mask targets enabled, snap against the visible picture edge and undo. |
| 20 Pack lifecycle | Install the Ukrainian/Bhojpuri example ZIP, update to revision 2, cancel a downgrade warning and confirm removal. |
| 21 Simulator transfer | With a separately authorized fixture, load a linked Preview layer, edit geometry, review, send and verify readback; restore the simulator afterward. |
- [ ] Start a new project.
- [ ] Show the default Slides and Presenter layers.
- [ ] Open Output format: show presets and custom dimensions.
- [ ] Use 1920 × 1080 for the demonstration.
- [ ] Save the project with a recognizable name.
These clips group related interactions rather than making a clip for every button.
The SVG demonstrations exercise interchange without pretending to record Illustrator,
Figma or draw.io. Actual captures from those applications, live input capture, other
file codecs and physical device output require separate application/device sessions.
## 2. Position the layers
## Recording environment
- [ ] Select a layer from the canvas, then from the layer list.
- [ ] Drag it and resize it using the handles.
- [ ] Toggle aspect-ratio locking and demonstrate the difference.
- [ ] Enter an exact layer width and height.
- [ ] Nudge with arrow keys, then Shift-arrow.
- [ ] Open **Measure position from**: switch between a corner and the center.
- [ ] Show that changing the measurement reference does not move the layer.
- [ ] Enable a different layer measurement point and demonstrate one precise placement.
- [ ] Undo and redo a change.
Use a dedicated X11 display, not the working desktop. The script sends real mouse
and keyboard events, changes its own clipboard and recreates its per-shot settings.
The normal user profile is not used. Requirements:
## 3. Align and resize together
- A built `target/debug/canvas-pilot` (`cargo build -p canvas-pilot`).
- Python 3, Xvfb, xdotool, xclip, FFmpeg/ffprobe and ImageMagick.
- Tesseract with English recognition data; OCR locates labelled controls.
- `dbus-daemon`, `xdg-desktop-portal` and the GTK portal backend for native file pickers.
- [ ] Select both layers using Shift-click or a selection box.
- [ ] Move them together.
- [ ] Demonstrate snapping to guides or another layer.
- [ ] Align one layer to the screen, then align against another layer.
- [ ] Demonstrate **Same handles** resizing.
- [ ] Demonstrate **Mirror horizontally**, then **Opposite handles**.
- [ ] Undo between examples so the layout stays understandable.
Start the virtual display in its own terminal:
## 4. Organize the project
```sh
Xvfb :97 -screen 0 1440x940x24 -nolisten tcp -noreset
```
- [ ] Add a third layer and rename it.
- [ ] Create a folder and drag layers into it.
- [ ] Collapse and expand the folder.
- [ ] Select the folder's layers together.
- [ ] Toggle visibility and locking.
- [ ] Reorder overlapping layers to show stacking.
- [ ] Return to a clean Slides + Presenter arrangement.
Then, from the repository root:
## 5. Use a reference image
```sh
python3 scripts/record-showcase.py --list
python3 scripts/record-showcase.py --display :97 --only 02-move-resize
```
- [ ] Drop the prepared image into the application.
- [ ] Adjust its opacity and display placement.
- [ ] Show outline-only layer display over the reference.
- [ ] Position the layers against the reference.
- [ ] Zoom around the pointer, pan, then use **Fit screen**.
- [ ] Use **Zoom to selection**.
- [ ] Hide the reference when finished.
Omit `--only` to run clips 01–20. Clip 21 requires the separate simulator setup described below. To rehearse a fixture without recording:
## 6. Show source formats and cropping
```sh
python3 scripts/record-showcase.py --display :97 --inspect 08-crop
```
- [ ] Open the Presenter layer's properties.
- [ ] Show the distinction between source dimensions, usable input and final layer size.
- [ ] Apply an asymmetric input crop.
- [ ] Double-click the layer to adjust its crop visually.
- [ ] Zoom and reposition the content while the visible layer box stays fixed.
- [ ] Show the faded cropped-out area.
- [ ] Align the content inside the box.
- [ ] Demonstrate **Recenter**, then **Reset crop**.
- [ ] Undo back to a useful presenter framing.
Stop rehearsal with Ctrl-C. `--tools /path/to/prefix` optionally finds tools under
`usr/bin`, shared libraries under `usr/lib` and English OCR data under
`usr/share/tessdata`. Normal distribution packages need no such prefix. The script
forces X11 for both egui and GTK, uses a private portal bus and sets fresh XDG
configuration/data directories for each shot. Keep the 1440 × 940 resolution and
English interface: icon coordinates are deliberately simple and fixed. Rehearse
again after changing interface layout, font scaling or the desktop tool versions.
## 7. Bring geometry in from other applications
## Output and review
- [ ] Copy a simple layout from Illustrator and paste into Canvas Pilot.
- [ ] Show destination mapping and the before/after geometry.
- [ ] Demonstrate position-only versus position-and-size import.
- [ ] Show the outline-inclusion option using Illustrator's stroked rectangles.
- [ ] Apply, then undo.
- [ ] Briefly repeat copy/paste from Figma and draw.io.
- [ ] Drop the prepared PPTX or DXF file into the window.
- [ ] Show page/slide selection if applicable, map the rectangles and apply.
The initial 2026-11-17 series records application v0.9.16 (`dc3e6ca`). Version
0.9.17 adds the recording tooling and guide without changing application behavior.
The local `manifest.json` records the binary fingerprint, clip durations and hashes.
## 8. Export and reopen
Everything generated stays in the Git-ignored `showcase-videos/` folder. Each shot
has its own `video.mp4` (H.264, 30 fps, no audio), English `captions.vtt`, poster,
contact sheet, start/end captures, starting/ending project JSON and recording log.
The gallery is `showcase-videos/index.html`. For browser caption support, serve it:
- [ ] Open the export format selector to show the available formats.
- [ ] Export the whole layout as SVG.
- [ ] Export only the selected layer.
- [ ] Open one export in its destination application.
- [ ] Save the Canvas Pilot project.
- [ ] Reopen it to show that editable settings and reference images are retained.
```sh
python3 -m http.server 8765 --bind 127.0.0.1 --directory showcase-videos
```
## 9. Connect to a screen processor
Open `http://127.0.0.1:8765/`. There is no autoplay. Videos and source fixtures stay
local; committing the recipe does not publish or upload the recordings.
- [ ] Open device connection settings and connect.
- [ ] Show detected screens and layers.
- [ ] Load a device layer into the editor.
- [ ] Show its saved device destination mapping.
- [ ] Make a visible position or size change locally.
- [ ] Select Preview and review the exact changes.
- [ ] Send and show the resulting device layout.
- [ ] Show the bottom **Send** and **Load** controls.
- [ ] Demonstrate Selected or Folder transfer scope.
- [ ] Briefly show the two sizing strategies.
- [ ] If both devices are available, repeat a short load/edit/send sequence on the other family.
Every take must decode successfully, but that is only the first check. Watch the
clip/contact sheet and inspect the saved result: a clicked disabled button is not
a successful import. Confirm visible movement, readable menus, complete dialogs,
actual saved exports and restoration after undo. Failed takes are named
`FAILED-video.mp4` and excluded from the gallery. Fix the recipe and rerun just that
shot. Keep captions factual about what is visible and what was preloaded.
## 10. Use device input previews
## Simulator and hardware boundaries
- [ ] Enable an input preview on a layer.
- [ ] Capture a still and use it to demonstrate cropping real content.
- [ ] Adjust crop-guide opacity.
- [ ] Enable timed refresh briefly, then pause it.
- [ ] Show importing a snapshot as a fixed reference image.
The device fixture uses `127.0.0.1:3000`, with startup connection disabled. Check
identity before filming. Standalone AQL Cmax 6.2.x is the currently supported
Aquilon profile; the session simulator identifies as 6.2.79. Broader Aquilon/Midra
coverage is tracked in the [project backlog](plan.md#to-do-list).
## 11. Finish
Connection and mapping inspection are read-only. For a separate send demonstration,
first capture the chosen Preview layer's baseline, use already routed sources,
review the exact geometry/crop/mask changes, send, verify readback, then restore
and verify the baseline. Never include TAKE, source routing or shared-input edits
implicitly. Do not use a saved host as authorization for another device. Simulator
readback does not establish physical-output accuracy.
- [ ] Briefly show themes and snapping preferences.
- [ ] Restore the clean finished layout.
- [ ] Fit the screen and save the project.
For the local transfer take, the user authorized temporarily routing **only S1
Preview layer 1 to LIVE_1**. The completed transfer take confirmed application readback, followed by a successful
comparison with the original baseline (`simulator-restoration.json`, no mismatches).
The baseline records source, geometry, anchor, classic
crop and mask for all seven S1 layers in both banks. The local
`showcase-videos/simulator_session.py` captures/restores this fixture, and
`showcase-videos/record-transfer.py` records the take with restoration in `finally`.
Those session-specific helpers and their JSON evidence stay beside the recordings,
not in the reusable recorder or CI. They require the temporary `websocket-client`
package and this session's tool paths; inspect and adapt them before reuse.
Leave the unfinished Midra fill/aspect modes, future adapters and multiple-screen
projects out of the feature demonstration. This checklist covers implemented
workflows as of 2026-11-16. Aquilon support is scoped to standalone AQL Cmax 6.2.x,
validated on the 6.2.79 emulator; describe emulator footage accordingly.
For detailed controls, see the [advanced guide](guide/overview.md).
To take the transfer shot manually: identify the simulator, preserve the same
baseline, route its Preview source explicitly, link Presenter to Aquilon S1/layer
1 in Mapping, connect, and click **Load linked layers**. Set width 720, X 900 and
Y 300, open **Device mapping & transfer**, expand the window, verify Preview and
the linked destination, then **Send mapped layers**. Wait for the readback success
message. Restore the original Preview source and all edited fields, apply the
preset update and compare both banks with the captured baseline. Stop if bank
mapping changes or any restoration check fails.

View File

@ -78,6 +78,13 @@ checks and stretch goals below remain open; the tag does not mark them complete.
## To-do list
- [ ] **Broaden coverage to every Aquilon and Midra model.** Requested 2026-11-17:
inventory both product ranges and their firmware/link modes; validate identity,
bounded reads, geometry/crop/mask conversion, input previews and reviewed writes
per model. Start with the AQL C+ simulator encountered during showcase recording.
Preserve explicit unsupported-mode errors until each adapter path is validated;
emulator coverage and physical-output acceptance remain separate.
- [ ] **Resolve local input-ratio correction scope.** Shared-input Content ratio
and Transform to controls already exist and are [documented](guide/formats-and-crop.md#content-ratio-versus-transform-to).
Whether to add a local correction/preview model remains an unanswered question;

1238
scripts/record-showcase.py Normal file

File diff suppressed because it is too large Load Diff