Add native reference placement and background image imports
Beffroi/beffroi-tools/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-13 17:35:31 +01:00
parent 1cdf66941b
commit ec371e00d2
10 changed files with 355 additions and 28 deletions

View File

@ -45,6 +45,9 @@ pub struct Editor {
show_pattern: bool,
show_toolbar_icon_names: bool,
reference: Option<super::reference::Reference>,
reference_pending:
Option<std::sync::mpsc::Receiver<Result<super::reference::Reference, String>>>,
outline_layers: bool,
reference_open: bool,
reference_error: String,
}
@ -209,6 +212,8 @@ impl Default for Editor {
show_pattern: false,
show_toolbar_icon_names: false,
reference: None,
reference_pending: None,
outline_layers: false,
reference_open: false,
reference_error: String::new(),
};
@ -261,7 +266,28 @@ impl Editor {
}
}
fn load_reference(&mut self, ctx: &egui::Context, file: &egui::DroppedFile) {
match super::reference::Reference::load(ctx, file) {
let (tx, rx) = std::sync::mpsc::channel();
self.reference_pending = Some(rx);
self.reference_error.clear();
let ctx = ctx.clone();
let file = file.clone();
std::thread::spawn(move || {
let result = super::reference::Reference::load(&ctx, &file);
let _ = tx.send(result);
ctx.request_repaint();
});
}
fn poll_reference(&mut self) {
let Some(rx) = &self.reference_pending else {
return;
};
let result = match rx.try_recv() {
Ok(result) => result,
Err(std::sync::mpsc::TryRecvError::Empty) => return,
Err(_) => Err("Reference reader stopped. Please import again.".into()),
};
self.reference_pending = None;
match result {
Ok(reference) => {
self.reference = Some(reference);
self.reference_error.clear();
@ -269,6 +295,15 @@ impl Editor {
Err(error) => self.reference_error = error,
}
}
#[cfg(test)]
fn wait_reference(&mut self) {
let until = std::time::Instant::now() + std::time::Duration::from_secs(5);
while self.reference_pending.is_some() && std::time::Instant::now() < until {
self.poll_reference();
std::thread::sleep(std::time::Duration::from_millis(1));
}
assert!(self.reference_pending.is_none());
}
fn import_reference_file(&mut self, ctx: &egui::Context) {
if let Some(path) = rfd::FileDialog::new()
.add_filter("Pictures", &["png", "jpg", "jpeg", "bmp"])
@ -294,6 +329,14 @@ impl Editor {
self.import_reference_file(ctx);
}
ui.label("Or drag one PNG, JPEG or BMP into the window.");
if self.reference_pending.is_some() {
ui.spinner();
ui.label("Loading image… current reference remains available.");
if ui.button("Cancel image import").clicked() {
self.reference_pending = None;
}
}
ui.checkbox(&mut self.outline_layers, "Outline-only layers");
let mut remove = false;
if let Some(reference) = &mut self.reference {
ui.label(format!(
@ -302,6 +345,34 @@ impl Editor {
));
ui.checkbox(&mut reference.visible, "Show reference");
ui.add(egui::Slider::new(&mut reference.opacity, 0.0..=1.0).text("Opacity"));
ui.checkbox(
&mut reference.native_size,
"Native pixels (1 image pixel = 1 screen pixel)",
);
ui.horizontal(|ui| {
ui.label("Offset in screen pixels");
ui.add(
egui::DragValue::new(&mut reference.offset[0])
.prefix("X ")
.range(-1_000_000.0..=1_000_000.0)
.max_decimals(1),
);
ui.add(
egui::DragValue::new(&mut reference.offset[1])
.prefix("Y ")
.range(-1_000_000.0..=1_000_000.0)
.max_decimals(1),
);
});
if ui
.add_enabled(
reference.offset != [0.0; 2],
egui::Button::new("Reset image offset"),
)
.clicked()
{
reference.offset = [0.0; 2];
}
ui.radio_value(
&mut reference.preserve_ratio,
false,
@ -327,6 +398,7 @@ impl Editor {
}
if remove {
self.reference = None;
self.reference_pending = None;
self.reference_error.clear();
}
if !self.reference_error.is_empty() {
@ -1921,6 +1993,7 @@ impl Editor {
reference.paint(
&screen.painter,
Rect::from_min_size(origin, Vec2::new(sw, sh) * scale),
output,
);
} else if output == [1920, 1080] {
screen_artwork(&screen);
@ -1978,7 +2051,9 @@ impl Editor {
p.rect(
rect,
0.0,
if self.reference.as_ref().is_some_and(|r| r.visible) {
if self.outline_layers {
Color32::TRANSPARENT
} else if self.reference.as_ref().is_some_and(|r| r.visible) {
Color32::from_rgba_unmultiplied(
palette.layer.r(),
palette.layer.g(),
@ -1991,7 +2066,9 @@ impl Editor {
Stroke::new(1.0_f32, color),
StrokeKind::Inside,
);
if self.show_pattern || (self.edit_content && self.layout.selected() == Some(i)) {
if (self.show_pattern && !self.outline_layers)
|| (self.edit_content && self.layout.selected() == Some(i))
{
format_ui::paint_pattern(
p,
rect,
@ -2220,6 +2297,7 @@ fn click(ui: &egui::Ui, ink: &Ink, b: [f32; 4], id: impl std::hash::Hash) -> boo
}
impl Editor {
fn ui(&mut self, ctx: &egui::Context) {
self.poll_reference();
let palette = theme::palette(ctx);
let dropped = ctx.input(|i| i.raw.dropped_files.clone());
if !dropped.is_empty() {
@ -3283,6 +3361,7 @@ mod tests {
},
|ctx| app.ui(ctx),
);
app.wait_reference();
assert!(
app.reference
.as_ref()
@ -3302,6 +3381,7 @@ mod tests {
..Default::default()
},
);
app.wait_reference();
assert!(!app.reference_error.is_empty());
assert_eq!(app.reference.as_ref().unwrap().texture.id(), texture);
app.layout.nudge(1.0, 0.0).unwrap();

View File

@ -69,6 +69,10 @@ impl Editor {
}
});
ui.separator();
ui.checkbox(
&mut self.outline_layers,
"Outline-only layers (this project)",
);
ui.checkbox(&mut self.show_toolbar_icon_names, "Show toolbar icon names");
ui.checkbox(
&mut self.keep_aspect_ratio,

View File

@ -51,9 +51,18 @@ pub struct Reference {
pub visible: bool,
pub opacity: f32,
pub preserve_ratio: bool,
pub native_size: bool,
pub offset: [f64; 2],
}
impl Reference {
pub fn bytes(&self) -> Result<Vec<u8>, String> {
if self
.offset
.iter()
.any(|v| !v.is_finite() || v.abs() > 1_000_000.0)
{
return Err("Reference offsets must be finite and within ±1,000,000 pixels.".into());
}
if !self.opacity.is_finite() || !(0.0..=1.0).contains(&self.opacity) {
return Err("Reference opacity must be between 0 and 1.".into());
}
@ -79,6 +88,7 @@ pub struct EditorSettings {
pub viewport_pan: [f32; 2],
pub show_source_pattern: bool,
pub show_toolbar_icon_names: bool,
pub outline_layers: bool,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
@ -96,7 +106,7 @@ impl Project {
pub fn from_layout(layout: &Layout) -> Self {
Self {
format: FORMAT.into(),
version: 3,
version: 4,
next_layer_id: layout.next_id,
output_resolution: layout.formats.output.into(),
inputs: (0..layout.formats.sources.len())
@ -135,14 +145,15 @@ impl Project {
viewport_pan: [0.0; 2],
show_source_pattern: false,
show_toolbar_icon_names: false,
outline_layers: false,
},
}
}
/// Build a fresh document only after validating the entire file. No history is restored.
pub fn layout(&self) -> Result<Layout, String> {
if self.format != FORMAT || self.version != 3 {
if self.format != FORMAT || self.version != 4 {
return Err(
"Unsupported project format/version; expected beffroi.midra-layout version 3."
"Unsupported project format/version; expected beffroi.midra-layout version 4."
.into(),
);
}
@ -259,7 +270,7 @@ impl Project {
}
let header: Header =
serde_json::from_str(text).map_err(|e| format!("Invalid project JSON: {e}"))?;
let p: Self = if header.version == 1 || header.version == 2 {
let mut migrated: serde_json::Value = if header.version == 1 || header.version == 2 {
let mut value: serde_json::Value =
serde_json::from_str(text).map_err(|e| format!("Invalid project JSON: {e}"))?;
if header.version == 1 {
@ -301,10 +312,33 @@ impl Project {
}
value["next_layer_id"] = 3.into();
value["version"] = 3.into();
serde_json::from_value(value).map_err(|e| format!("Invalid project JSON: {e}"))?
value
} else {
serde_json::from_str(text).map_err(|e| format!("Invalid project JSON: {e}"))?
};
if (1..=3).contains(&header.version) {
let editor = migrated
.get_mut("editor")
.and_then(|v| v.as_object_mut())
.ok_or("Missing editor settings")?;
if editor.contains_key("outline_layers") {
return Err("Unexpected outline setting in old project".into());
}
editor.insert("outline_layers".into(), false.into());
if let Some(reference) = migrated
.get_mut("reference")
.and_then(|v| v.as_object_mut())
{
if reference.contains_key("native_size") || reference.contains_key("offset") {
return Err("Unexpected placement fields in old project".into());
}
reference.insert("native_size".into(), false.into());
reference.insert("offset".into(), serde_json::json!([0.0, 0.0]));
}
migrated["version"] = 4.into();
}
let p: Self =
serde_json::from_value(migrated).map_err(|e| format!("Invalid project JSON: {e}"))?;
p.layout()?;
Ok(p)
}

View File

@ -17,6 +17,7 @@ impl Editor {
p.editor.viewport_zoom = self.zoom;
p.editor.viewport_pan = [self.pan.x, self.pan.y];
p.editor.show_source_pattern = self.show_pattern;
p.editor.outline_layers = self.outline_layers;
p.editor.show_toolbar_icon_names = self.show_toolbar_icon_names;
p.reference = self.reference.as_ref().map(|r| SavedReference {
name: r.name.clone(),
@ -24,6 +25,8 @@ impl Editor {
visible: r.visible,
opacity: r.opacity,
preserve_ratio: r.preserve_ratio,
native_size: r.native_size,
offset: r.offset,
});
p
}
@ -42,6 +45,8 @@ impl Editor {
reference.visible = r.visible;
reference.opacity = r.opacity;
reference.preserve_ratio = r.preserve_ratio;
reference.native_size = r.native_size;
reference.offset = r.offset;
Ok::<_, String>(reference)
})
.transpose()?;
@ -57,6 +62,7 @@ impl Editor {
zoom: e.viewport_zoom,
pan: Vec2::from(e.viewport_pan),
show_pattern: e.show_source_pattern,
outline_layers: e.outline_layers,
show_toolbar_icon_names: e.show_toolbar_icon_names,
..Default::default()
};
@ -233,10 +239,14 @@ mod tests {
..Default::default()
};
app.load_reference(&ctx, &file);
app.wait_reference();
let reference = app.reference.as_mut().unwrap();
reference.opacity = 0.4;
reference.visible = false;
reference.preserve_ratio = true;
reference.native_size = true;
reference.offset = [-12.5, 34.25];
app.outline_layers = true;
app.zoom = 2.5;
app.pan = Vec2::new(-20.5, 40.0);
app.corner = Corner::BottomRight;

View File

@ -1,5 +1,7 @@
use super::*;
use std::io::{Cursor, Read};
// Keep large concurrent imports from multiplying decoder peak memory.
static DECODE_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
pub(super) struct Reference {
pub texture: egui::TextureHandle,
@ -9,10 +11,15 @@ pub(super) struct Reference {
pub visible: bool,
pub opacity: f32,
pub preserve_ratio: bool,
pub native_size: bool,
pub offset: [f64; 2],
}
impl Reference {
pub fn load(ctx: &egui::Context, file: &egui::DroppedFile) -> Result<Self, String> {
let _decode_guard = DECODE_LOCK
.lock()
.map_err(|_| "Image decoder lock failed")?;
let bytes = if let Some(bytes) = &file.bytes {
bytes.to_vec()
} else if let Some(path) = &file.path {
@ -39,36 +46,62 @@ impl Reference {
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_else(|| file.name.clone());
Ok(Self {
texture: ctx.load_texture("reference", color, egui::TextureOptions::NEAREST),
texture: ctx.load_texture(
"reference",
color,
egui::TextureOptions {
magnification: egui::TextureFilter::Nearest,
minification: egui::TextureFilter::Linear,
..Default::default()
},
),
name,
bytes,
size,
visible: true,
opacity: 1.0,
preserve_ratio: false,
native_size: false,
offset: [0.0; 2],
})
}
pub fn warning(&self, output: [u32; 2]) -> Option<(bool, String)> {
warning(self.size, self.preserve_ratio, output)
if self.native_size {
None
} else {
warning(self.size, self.preserve_ratio, output)
}
}
pub fn paint(&self, painter: &egui::Painter, screen: Rect) {
pub fn paint(&self, painter: &egui::Painter, screen: Rect, output: [u32; 2]) {
painter.rect_filled(screen, 0.0, theme::palette(painter.ctx()).canvas);
if !self.visible {
return;
}
let rect = if self.preserve_ratio {
let rect = self.placed_rect(screen, output);
painter
.with_clip_rect(painter.clip_rect().intersect(screen))
.image(
self.texture.id(),
rect,
Rect::from_min_max(Pos2::ZERO, Pos2::new(1.0, 1.0)),
Color32::WHITE.gamma_multiply(self.opacity),
);
}
fn placed_rect(&self, screen: Rect, output: [u32; 2]) -> Rect {
let scale = screen.width() / output[0] as f32;
let rect = if self.native_size {
Rect::from_min_size(
screen.min,
Vec2::new(self.size[0] as f32, self.size[1] as f32) * scale,
)
} else if self.preserve_ratio {
let size = Vec2::new(self.size[0] as f32, self.size[1] as f32);
let scale = (screen.width() / size.x).min(screen.height() / size.y);
Rect::from_center_size(screen.center(), size * scale)
} else {
screen
};
painter.image(
self.texture.id(),
rect,
Rect::from_min_max(Pos2::ZERO, Pos2::new(1.0, 1.0)),
Color32::WHITE.gamma_multiply(self.opacity),
);
rect.translate(Vec2::new(self.offset[0] as f32, self.offset[1] as f32) * scale)
}
}
@ -126,6 +159,35 @@ fn warning([w, h]: [u32; 2], preserve_ratio: bool, [ow, oh]: [u32; 2]) -> Option
mod tests {
use super::*;
#[test]
fn native_mapping_and_offsets_are_in_screen_pixels() {
let ctx = egui::Context::default();
let mut bytes = Cursor::new(Vec::new());
image::RgbaImage::from_pixel(4, 2, image::Rgba([40, 90, 150, 255]))
.write_to(&mut bytes, image::ImageFormat::Png)
.unwrap();
let file = egui::DroppedFile {
name: "guide.png".into(),
bytes: Some(bytes.into_inner().into()),
..Default::default()
};
let mut reference = Reference::load(&ctx, &file).unwrap();
reference.native_size = true;
reference.offset = [20.0, 30.0];
let screen = Rect::from_min_size(Pos2::new(10.0, 20.0), Vec2::new(960.0, 540.0));
assert_eq!(
reference.placed_rect(screen, [1920, 1080]),
Rect::from_min_size(Pos2::new(20.0, 35.0), Vec2::new(2.0, 1.0))
);
assert!(reference.warning([1920, 1080]).is_none());
reference.native_size = false;
reference.preserve_ratio = false;
assert_eq!(
reference.placed_rect(screen, [1920, 1080]).size(),
screen.size()
);
assert!(reference.warning([1920, 1080]).unwrap().0);
}
#[test]
fn scaling_warnings_distinguish_resolution_and_ratio() {
assert!(warning([1920, 1080], false, [1920, 1080]).is_none());
assert!(warning([1920, 1080], false, [1920, 1200]).unwrap().0);

View File

@ -172,3 +172,22 @@ fn version_two_requires_captions_preference_and_preserves_it() {
Project::from_layout(&Layout::default())
);
}
#[test]
fn v4_example_and_old_version_migrations_preserve_defaults() {
assert_eq!(
Project::from_json(include_str!(
"../../../docs/interfaces/midra-layout-v4.example.json"
))
.unwrap(),
Project::from_layout(&Layout::default())
);
let mut value = serde_json::to_value(Project::from_layout(&Layout::default())).unwrap();
value["version"] = 0.into();
assert!(Project::from_json(&value.to_string()).is_err());
value["version"] = 4.into();
value["editor"]
.as_object_mut()
.unwrap()
.remove("outline_layers");
assert!(Project::from_json(&value.to_string()).is_err());
}

View File

@ -0,0 +1,97 @@
{
"format": "beffroi.midra-layout",
"version": 4,
"output_resolution": {
"width": 1920,
"height": 1080
},
"inputs": [
{
"id": 1,
"source_format": "sixteen_nine",
"native_resolution": {
"width": 1920,
"height": 1080
},
"input_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
}
},
{
"id": 2,
"source_format": "sixteen_nine",
"native_resolution": {
"width": 1920,
"height": 1080
},
"input_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
}
}
],
"layers": [
{
"id": 1,
"source_id": 1,
"bounds": {
"x": 120.0,
"y": 180.0,
"width": 640.0,
"height": 360.0
},
"advanced_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
},
"visible": true,
"locked": false,
"name": "Presenter",
"folder": ""
},
{
"id": 2,
"source_id": 2,
"bounds": {
"x": 1160.0,
"y": 180.0,
"width": 640.0,
"height": 360.0
},
"advanced_crop": {
"left": 0.0,
"right": 0.0,
"top": 0.0,
"bottom": 0.0
},
"visible": true,
"locked": false,
"name": "Slides",
"folder": ""
}
],
"reference": null,
"editor": {
"selected_layer_ids": [
2
],
"position_corner": "top_left",
"keep_aspect_ratio": true,
"viewport_zoom": 1.0,
"viewport_pan": [
0.0,
0.0
],
"show_source_pattern": false,
"show_toolbar_icon_names": false,
"outline_layers": false
},
"next_layer_id": 3
}

View File

@ -5,7 +5,7 @@ These are offline editor formats, not Analog Way REST payloads. Implementation:
[`project.rs`](../../crates/midra-layout/tests/project.rs). Update this contract,
examples and tests in the same change as any save/export schema change.
## Project JSON, version 3
## Project JSON, version 4
Suggested filename: `layout.midra.json`. Encoding: UTF-8, pretty-printed JSON,
with a trailing newline. A project preserves applied document values at their
@ -16,16 +16,18 @@ versions. Version 1 files first gain
with their original two layer IDs, names `Presenter` and `Slides`, empty folders,
and `next_layer_id: 3`; other values are preserved.
The [version 1 example](midra-layout-v1.example.json) remains a migration fixture.
Saving always writes version 3. Older applications reject version 3 files.
Version 4 adds `editor.outline_layers: false`, and reference `native_size: false`
and `offset: [0, 0]` when migrating versions 1–3. Old fitting behavior is preserved.
Saving always writes version 4. Older applications reject version 4 files.
Incompatible files are never partially applied.
[Complete example](midra-layout-v3.example.json) is a valid default project,
[Complete example](midra-layout-v4.example.json) is a valid default project,
without a reference image. It is loaded by the regression tests.
| Root field | Representation / meaning |
| --- | --- |
| `format` | Exactly `"beffroi.midra-layout"` |
| `version` | Integer `3` |
| `version` | Integer `4` |
| `next_layer_id` | Positive integer strictly greater than every layer ID; not rewound by undo |
| `output_resolution` | `{ "width": integer, "height": integer }`, screen pixels |
| `inputs` | 1–1024 input objects, consecutive IDs starting at 1 |
@ -74,7 +76,9 @@ Reference object:
| `image_base64` | Standard padded RFC 4648 base64 of the original PNG/JPEG/BMP file bytes; no data-URL prefix |
| `visible` | Boolean |
| `opacity` | Number from 0 to 1 |
| `preserve_ratio` | Boolean: fit proportionally if true, stretch to screen if false |
| `preserve_ratio` | Boolean: fit proportionally if true, stretch to screen if false; applies when native sizing is off |
| `native_size` | Boolean: image pixels map 1:1 to screen pixels; anchored at screen top-left before offset |
| `offset` | `[x, y]` finite screen-pixel translation, each within ±1,000,000; applies after fitting/native placement |
The image is embedded, so moving the project does not break the reference. No
external files, URLs or device endpoints are accessed on load. Image dimensions
@ -94,6 +98,7 @@ Editor object:
| `viewport_pan` | `[x, y]`, viewport pan in screen-coordinate pixels; finite, absolute value at most 1e9 |
| `show_source_pattern` | Boolean source-coordinate preview setting |
| `show_toolbar_icon_names` | Boolean: show names beneath toolbar icons; false by default |
| `outline_layers` | Boolean: transparent layer fill for reference alignment; selection/handles remain visible |
Resolution dimensions must be whole pixels from 1 to 16384. Layer x/y must be finite and within ±1,000,000 pixels; layer widths/heights
and retained input dimensions must be positive, finite, and at most 1,000,000
@ -158,7 +163,7 @@ and `viewBox="0 0 W H"` equal to the output screen. The root carries
## Compatibility changes
Project version 3 and SVG version 1 are strict contracts. A breaking project field/meaning change must bump
Project version 4 and SVG version 1 are strict contracts. A breaking project field/meaning change must bump
`version` and either implement a tested migration or clearly reject older/newer
files. Changing rectangle/marker semantics requires a corresponding documented
SVG interface revision and importer tests. Update this document and its example

View File

@ -28,9 +28,9 @@ Remaining work, in priority order:
1. Stable-ID collections, add/remove/rename, folder labels/filtering, selected-layer
SVG export and project v3 migration are implemented. Nested folder trees and
hardware mapping controls remain follow-ups.
2. Reference native-size/offset mapping, outline-only layer display, adaptive image
filtering and decoding away from the UI thread. Current decoding is bounded
but synchronous. Pixel-grid/ruler refinement and resize snapping are follow-ups.
2. Reference native-size/offset mapping, outline-only display, adaptive filtering
and background picture import are implemented. Embedded-image project loading
remains synchronous. Pixel-grid/ruler refinement and resize snapping remain.
3. Additional clipboard adapters after obtaining real application/version samples.
4. Local device mappings, specific-layer export, destination review, and two
independently tested sizing/crop strategies. Hardware values remain provisional.

View File

@ -527,6 +527,22 @@ Stable IDs survive removal and are independent of Midra layer numbers. Group
movement, alignment and Same-handles resizing work across the selection;
Mirror/Opposite resizing still require exactly two layers.
Project JSON is now version 3, with tested migration from versions 1 and 2.
Project JSON is now version 4, with tested migration from versions 1–3.
**Project → Export SVG → Selected layers…** exports just the current selection,
including a single layer. All/visible export remains available.
## Reference placement and loading
Reference settings now offer **Native pixels**, mapping each image pixel to one
screen pixel at the screen's top-left, plus X/Y offsets in screen pixels. Offsets
also work with Fit/Stretch. The image is clipped to the output screen. Native
mode does not scale or distort the image, so stretch warnings do not apply.
**Outline-only layers** keeps the reference unobscured while retaining selection
and resize handles; it is also available in viewport options. Crop editing still
shows its source guide. Placement and outline mode are saved in project v4.
Picture import/drop reads and decodes off the UI thread, retaining the current
reference until successful completion. Canceling/removing discards late results;
failed replacements keep the current image. Decoder work is serialized to bound
peak memory. Minification uses linear filtering, magnification nearest-neighbor.
Embedded reference decoding during project load remains synchronous.