Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

Snap a moved picture to the frame and its neighbours, with guides

Jareer920449e336c0
diff --git a/engine/crates/concat/src/main.rs b/engine/crates/concat/src/main.rs
index 5b99cb48..cc987257 100644
--- a/engine/crates/concat/src/main.rs
+++ b/engine/crates/concat/src/main.rs
@@ -121,6 +121,7 @@ fn main() -> Result<(), slint::PlatformError> {
editor.set_tracks(ModelRc::from(models.tracks.clone()));
editor.set_clips(ModelRc::from(models.clips.clone()));
editor.set_stage_items(ModelRc::from(models.stage.clone()));
+ editor.set_stage_guides(ModelRc::from(models.guides.clone()));
editor.set_media(ModelRc::from(models.media.clone()));
editor.set_video_effects(ModelRc::from(models.video_effects.clone()));
editor.set_audio_effects(ModelRc::from(models.audio_effects.clone()));
diff --git a/engine/crates/concat/src/studio.rs b/engine/crates/concat/src/studio.rs
index c6c9fd87..b14af2c6 100644
--- a/engine/crates/concat/src/studio.rs
+++ b/engine/crates/concat/src/studio.rs
@@ -273,6 +273,9 @@ pub enum Gesture {
/// A drag on the stage: every selected picture under the playhead slides
/// with the pointer, from where each one was when the press landed.
StageMove {
+ /// The picture grabbed; it is the one that snaps, and the rest
+ /// follow it by the same amount.
+ primary: String,
origins: Vec<StageOrigin>,
/// The press, in fractions of the frame.
from: (f64, f64),
@@ -318,6 +321,20 @@ pub struct Footprint {
}
impl Footprint {
+ /// The half-extents of the turned box's axis-aligned bounds, in fractions
+ /// of the frame: what snapping measures, since an edge of a turned
+ /// picture is not a line the frame's edges can meet.
+ pub fn half_bounds(&self, frame: (u32, u32)) -> (f64, f64) {
+ let (width, height) = (f64::from(frame.0), f64::from(frame.1));
+ let (sin, cos) = self.rotation.to_radians().sin_cos();
+ let w = self.w * width;
+ let h = self.h * height;
+ (
+ (w * cos.abs() + h * sin.abs()) / 2.0 / width,
+ (w * sin.abs() + h * cos.abs()) / 2.0 / height,
+ )
+ }
+
/// True when the frame point `(x, y)`, in fractions, is inside the turned
/// box. `frame` is the output size, because the box is not square in
/// pixels and the turn has to happen in pixels.
@@ -356,6 +373,7 @@ pub struct Models {
pub tracks: Rc<VecModel<TrackData>>,
pub clips: Rc<VecModel<ClipData>>,
pub stage: Rc<VecModel<StageItemData>>,
+ pub guides: Rc<VecModel<StageGuideData>>,
pub media: Rc<VecModel<MediaItemData>>,
pub video_effects: Rc<VecModel<EffectData>>,
pub audio_effects: Rc<VecModel<EffectData>>,
@@ -376,6 +394,7 @@ impl Models {
tracks: Rc::new(VecModel::default()),
clips: Rc::new(VecModel::default()),
stage: Rc::new(VecModel::default()),
+ guides: Rc::new(VecModel::default()),
media: Rc::new(VecModel::default()),
video_effects: Rc::new(VecModel::default()),
audio_effects: Rc::new(VecModel::default()),
@@ -493,6 +512,8 @@ pub struct Studio {
pub workspace: (f32, f32),
pub divider_press: Option<(usize, f32, f32)>,
pub gesture: Gesture,
+ /// The snap lines of a stage move in flight; empty between moves.
+ pub stage_guides: Vec<StageGuideData>,
pub drop: Option<DropPlan>,
}
@@ -605,6 +626,7 @@ impl Studio {
workspace: (0.0, 0.0),
divider_press: None,
gesture: Gesture::None,
+ stage_guides: Vec::new(),
drop: None,
host,
};
@@ -2055,12 +2077,32 @@ impl Studio {
})
.collect();
self.begin_echo();
+ self.stage_guides.clear();
self.gesture = Gesture::StageMove {
+ primary: id,
origins,
from: (x, y),
};
}
+ /// Where a picture's bounds pull to on one axis. Every candidate is a
+ /// feature of the moving picture — an edge or the centre — against a
+ /// target — the frame's edges and centre, and every other picture's —
+ /// and the nearest pair inside `pull` wins. Returns the shift that lands
+ /// it and the target's position, for the guide.
+ fn stage_snap(features: [f64; 3], targets: &[f64], pull: f64) -> Option<(f64, f64)> {
+ let mut best: Option<(f64, f64)> = None;
+ for feature in features {
+ for &target in targets {
+ let shift = target - feature;
+ if shift.abs() < pull && best.is_none_or(|(held, _)| shift.abs() < held.abs()) {
+ best = Some((shift, target));
+ }
+ }
+ }
+ best
+ }
+
/// A press on a grip of `id`'s box: a corner scales, the handle above
/// turns. Both work about the picture's centre, in frame pixels.
pub fn stage_grip_pressed(&mut self, id: &str, grip: i32, x: f32, y: f32) {
@@ -2103,7 +2145,11 @@ impl Studio {
let (width, height) = self.output_size();
let gesture = std::mem::replace(&mut self.gesture, Gesture::None);
match &gesture {
- Gesture::StageMove { origins, from } => {
+ Gesture::StageMove {
+ primary,
+ origins,
+ from,
+ } => {
let (mut dx, mut dy) = (x - from.0, y - from.1);
if snap {
// Shift holds the axis the drag is mostly along, measured
@@ -2114,6 +2160,54 @@ impl Studio {
dx = 0.0;
}
}
+ self.stage_guides.clear();
+ if self.snap {
+ // The same pull on both axes, in frame pixels: a
+ // hundredth of the long side, which is about eight
+ // pixels on a stage of the size a laptop gives it.
+ let pull = 0.01 * f64::from(width.max(height));
+ let frame = (width, height);
+ let moving = origins
+ .iter()
+ .find(|origin| &origin.clip == primary)
+ .and_then(|origin| self.clip(&origin.clip).map(|clip| (origin, clip)));
+ if let Some((origin, clip)) = moving {
+ let (hw, hh) = self.footprint(clip).half_bounds(frame);
+ let cx = 0.5 + origin.offset_x + dx;
+ let cy = 0.5 + origin.offset_y + dy;
+ // The frame's own lines, then every picture that is
+ // staying put.
+ let mut xs = vec![0.0, 0.5, 1.0];
+ let mut ys = vec![0.0, 0.5, 1.0];
+ for other in self.stage_clips() {
+ if origins.iter().any(|origin| origin.clip == other.id) {
+ continue;
+ }
+ let footprint = self.footprint(other);
+ let (ow, oh) = footprint.half_bounds(frame);
+ xs.extend([footprint.cx - ow, footprint.cx, footprint.cx + ow]);
+ ys.extend([footprint.cy - oh, footprint.cy, footprint.cy + oh]);
+ }
+ if let Some((shift, at)) =
+ Self::stage_snap([cx - hw, cx, cx + hw], &xs, pull / f64::from(width))
+ {
+ dx += shift;
+ self.stage_guides.push(StageGuideData {
+ vertical: true,
+ at: at as f32,
+ });
+ }
+ if let Some((shift, at)) =
+ Self::stage_snap([cy - hh, cy, cy + hh], &ys, pull / f64::from(height))
+ {
+ dy += shift;
+ self.stage_guides.push(StageGuideData {
+ vertical: false,
+ at: at as f32,
+ });
+ }
+ }
+ }
for origin in origins {
if let Some(clip) = self.echo_clip_mut(&origin.clip) {
clip.offset_x = (origin.offset_x + dx).clamp(-1.0, 1.0);
@@ -2169,6 +2263,7 @@ impl Studio {
/// The stage gesture is over: whatever the echo moved becomes one
/// transform command per picture, batched when there are several.
pub fn stage_released(&mut self) {
+ self.stage_guides.clear();
let gesture = std::mem::replace(&mut self.gesture, Gesture::None);
let touched: Vec<String> = match gesture {
Gesture::StageMove { origins, .. } => {
@@ -3078,6 +3173,7 @@ impl Studio {
editor.set_playing(self.playing);
editor.set_preview_frame(self.preview.clone());
sync(&models.stage, self.stage_items());
+ sync(&models.guides, self.stage_guides.clone());
editor.set_drop(match &self.drop {
Some(plan) => DropData {
@@ -3791,10 +3887,44 @@ impl Studio {
#[cfg(test)]
mod tests {
- use super::Footprint;
+ use super::{Footprint, Studio};
const FRAME: (u32, u32) = (1920, 1080);
+ /// A quarter turn swaps the bounds' pixel extents, which in fractions
+ /// of a 16:9 frame is not a swap of the numbers.
+ #[test]
+ fn half_bounds_follow_the_turn() {
+ let flat = Footprint {
+ cx: 0.5,
+ cy: 0.5,
+ w: 0.5,
+ h: 0.5,
+ rotation: 0.0,
+ };
+ let (hw, hh) = flat.half_bounds(FRAME);
+ assert!((hw - 0.25).abs() < 1e-9 && (hh - 0.25).abs() < 1e-9);
+ let turned = Footprint {
+ rotation: 90.0,
+ ..flat
+ };
+ let (hw, hh) = turned.half_bounds(FRAME);
+ // 540px tall becomes 540px wide: 270px each side of 1920.
+ assert!((hw - 270.0 / 1920.0).abs() < 1e-9);
+ assert!((hh - 480.0 / 1080.0).abs() < 1e-9);
+ }
+
+ /// The nearest pair inside the pull wins, and nothing outside it pulls.
+ #[test]
+ fn snap_picks_the_nearest_target_inside_the_pull() {
+ // Centre 0.5 sits just off the frame's centre; the left edge at
+ // 0.2 is nearer to another picture's edge at 0.21.
+ let features = [0.2, 0.5, 0.8];
+ let hit = Studio::stage_snap(features, &[0.0, 0.505, 1.0, 0.21], 0.02).unwrap();
+ assert!((hit.0 - 0.005).abs() < 1e-9 && (hit.1 - 0.505).abs() < 1e-9);
+ assert!(Studio::stage_snap(features, &[0.3, 0.6], 0.02).is_none());
+ }
+
/// A fitted 16:9 picture at rest covers the frame exactly.
#[test]
fn footprint_contains_an_unturned_box() {
diff --git a/engine/crates/concat/ui/app.slint b/engine/crates/concat/ui/app.slint
index 92ac3de0..60ae3c9d 100644
--- a/engine/crates/concat/ui/app.slint
+++ b/engine/crates/concat/ui/app.slint
@@ -33,8 +33,8 @@ import { TooltipLayer } from "primitives/tooltip.slint";
import { Workspace } from "workspace/workspace.slint";
import {
ClipData, ClipField, ClipKind, ClipTextField, DropData, SelectedClipData,
- StageItemData, TextAlignment, TimelineTabData, TimelineTool, TrackData,
- TrackSize,
+ StageGuideData, StageItemData, TextAlignment, TimelineTabData, TimelineTool,
+ TrackData, TrackSize,
} from "timeline/model.slint";
// Re-exported so main.rs can reach the globals and the struct.
@@ -43,8 +43,8 @@ export {
DockDivider, DockSide, PaneKind, SeatBox,
EffectData, MediaFilter, MediaItemData, MediaKind,
ClipData, ClipField, ClipKind, ClipTextField, DropData, SelectedClipData,
- StageItemData, TextAlignment, TimelineTabData, TimelineTool, TrackData,
- TrackSize, MenuItemData, MenuRow, ExportData, ExportPhase, ModelData, SettingsData,
+ StageGuideData, StageItemData, TextAlignment, TimelineTabData, TimelineTool,
+ TrackData, TrackSize, MenuItemData, MenuRow, ExportData, ExportPhase, ModelData, SettingsData,
RecentProjectData, StartData, SystemFactData, ToastData,
}
diff --git a/engine/crates/concat/ui/editor.slint b/engine/crates/concat/ui/editor.slint
index 1f02cf76..a0f0c212 100644
--- a/engine/crates/concat/ui/editor.slint
+++ b/engine/crates/concat/ui/editor.slint
@@ -8,7 +8,8 @@ import { PaneKind } from "workspace/pane-switcher.slint";
import { MenuItemData } from "primitives/context-menu.slint";
import {
ClipData, ClipField, ClipTextField, DropData, SelectedClipData,
- StageItemData, TimelineTabData, TimelineTool, TrackData, TrackSize,
+ StageGuideData, StageItemData, TimelineTabData, TimelineTool, TrackData,
+ TrackSize,
} from "timeline/model.slint";
// Everything the four editor views read and everything they report, in one
@@ -125,6 +126,9 @@ export global Editor {
/// The stage outlines the selected ones and lets them be moved, scaled
/// and turned in place; see StageOverlay in the preview pane.
in-out property <[StageItemData]> stage-items;
+ /// The snap lines live while a picture is being moved on the stage, and
+ /// empty otherwise. Rust decides what snapped; the pane only draws it.
+ in-out property <[StageGuideData]> stage-guides;
/// A press on the stage itself, in fractions of the frame. Rust decides
/// what it landed on — a picture starts a move, empty stage clears the
/// selection — the way `clip-pressed` does for the lanes.
diff --git a/engine/crates/concat/ui/timeline/model.slint b/engine/crates/concat/ui/timeline/model.slint
index 5ede0574..fc4f2992 100644
--- a/engine/crates/concat/ui/timeline/model.slint
+++ b/engine/crates/concat/ui/timeline/model.slint
@@ -239,3 +239,14 @@ export struct StageItemData {
/// The clip's scale, for the readout under the box.
scale: float,
}
+
+/// One snap guide across the stage while a picture is dragged: the line the
+/// picture's centre or edge has just landed on, at the target's position.
+/// A vertical guide says the x axis snapped, a horizontal one the y axis;
+/// centring on both draws both, as a crosshair through the frame.
+export struct StageGuideData {
+ vertical: bool,
+ /// Where the line is, as a fraction of the frame's width (vertical) or
+ /// height (horizontal).
+ at: float,
+}
diff --git a/engine/crates/concat/ui/workspace/preview-pane.slint b/engine/crates/concat/ui/workspace/preview-pane.slint
index 66bbbf90..8c4fcbe1 100644
--- a/engine/crates/concat/ui/workspace/preview-pane.slint
+++ b/engine/crates/concat/ui/workspace/preview-pane.slint
@@ -9,7 +9,7 @@ import { NumberField } from "../primitives/number-field.slint";
import { Select } from "../primitives/select.slint";
import { Pane, PaneHeader } from "pane.slint";
import { PaneKind, PaneSwitcher } from "pane-switcher.slint";
-import { ClipKind, StageItemData } from "../timeline/model.slint";
+import { ClipKind, StageGuideData, StageItemData } from "../timeline/model.slint";
// The programme monitor: a header that says what the output is, a stage on a
// sunken viewport, and a transport tray under it in three parts — timecode on
@@ -419,10 +419,35 @@ component StageItem inherits Rectangle {
}
}
+/// One snap line, dashed by hand: Slint's Path strokes have no dash pattern,
+/// so the line is a run of short rectangles along the axis it marks. Thin and
+/// in the accent, the same as the box it is guiding.
+component Guide inherits Rectangle {
+ in property <StageGuideData> guide;
+
+ property <length> dash: 5px;
+ property <length> gap: 4px;
+ property <length> run: root.guide.vertical ? root.height : root.width;
+ property <int> count: Math.floor(root.run / (root.dash + root.gap)) + 1;
+
+ background: transparent;
+
+ for index in root.count: Rectangle {
+ x: root.guide.vertical ? root.guide.at * root.width - 0.5px
+ : index * (root.dash + root.gap);
+ y: root.guide.vertical ? index * (root.dash + root.gap)
+ : root.guide.at * root.height - 0.5px;
+ width: root.guide.vertical ? 1px : root.dash;
+ height: root.guide.vertical ? root.dash : 1px;
+ background: Theme.accent;
+ }
+}
+
/// The layer over the stage: the floor that takes a press on a picture or on
/// nothing, and one StageItem per selected picture above it.
component StageOverlay inherits Rectangle {
in property <[StageItemData]> items;
+ in property <[StageGuideData]> guides;
callback pressed(x: float, y: float, additive: bool);
callback grip-pressed(id: string, grip: int, x: float, y: float);
@@ -461,6 +486,16 @@ component StageOverlay inherits Rectangle {
}
}
+ // The snap lines, under the boxes: a guide runs the whole frame and the
+ // grips have to stay on top of it.
+ for guide in root.guides: Guide {
+ x: 0;
+ y: 0;
+ width: root.width;
+ height: root.height;
+ guide: guide;
+ }
+
for entry in root.items: Rectangle {
x: 0;
y: 0;
@@ -501,6 +536,8 @@ export component PreviewPane inherits Rectangle {
/// Every picture under the playhead, for the selection drawn over the
/// frame. See StageOverlay.
in property <[StageItemData]> stage-items;
+ /// The snap lines while one of them is being moved.
+ in property <[StageGuideData]> stage-guides;
callback play-toggled();
/// Absolute, in seconds.
@@ -669,6 +706,7 @@ export component PreviewPane inherits Rectangle {
width: stage.width;
height: stage.height;
items: root.stage-items;
+ guides: root.stage-guides;
pressed(x, y, additive) => { root.stage-pressed(x, y, additive); }
grip-pressed(id, grip, x, y) => { root.stage-grip-pressed(id, grip, x, y); }
dragged(x, y, snap) => { root.stage-dragged(x, y, snap); }
diff --git a/engine/crates/concat/ui/workspace/seat.slint b/engine/crates/concat/ui/workspace/seat.slint
index e61837e5..e5309d40 100644
--- a/engine/crates/concat/ui/workspace/seat.slint
+++ b/engine/crates/concat/ui/workspace/seat.slint
@@ -141,6 +141,7 @@ export component Seat inherits Rectangle {
clip-name: Editor.preview-clip-name;
frame: Editor.preview-frame;
stage-items: Editor.stage-items;
+ stage-guides: Editor.stage-guides;
play-toggled => { Editor.play-toggled(); }
seek(seconds) => { Editor.seek(seconds); }