From 3ba68fef1d376e6b734c8c106b08d7e2954f1a39 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 10:27:09 +0000 Subject: [PATCH] feat(ui-visuals): add Filmstrip with frame markers and thumbnail cache Cells sampled across the sequence load asynchronously into an LRU cache; exposure-step and keyframe markers sit above; click, drag, wheel and keys seek CurrentIndex, whose cell is outlined in Accent. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Ui/Visuals/Filmstrip.cs | 337 +++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 src/Titano.Ui/Visuals/Filmstrip.cs diff --git a/src/Titano.Ui/Visuals/Filmstrip.cs b/src/Titano.Ui/Visuals/Filmstrip.cs new file mode 100644 index 00000000..efa9001a --- /dev/null +++ b/src/Titano.Ui/Visuals/Filmstrip.cs @@ -0,0 +1,337 @@ +using System.Diagnostics.CodeAnalysis; +using System.Windows; +using System.Windows.Input; +using System.Windows.Media; +using Titano.Core.Diagnostics; + +namespace Titano.Ui.Visuals; + +/// +/// Strip of thumbnails sampled across a sequence (BRIEF §12.3, Editor mockup) with frame markers above it +/// (exposure steps ▼ in Sun/Warning, keyframes ◆ in Accent). The cell holding is outlined +/// in Accent and an accent ▼ marks the exact frame. Click or drag seeks, the wheel and arrow keys step one frame +/// (PageUp/PageDown one cell, Home/End the ends). Thumbnails load asynchronously from into an +/// LRU cache; cells show a placeholder until their image arrives. Hovering a marker reads out its label. +/// +public sealed class Filmstrip : DrawingElement +{ + public static readonly DependencyProperty SourceProperty = DependencyProperty.Register( + nameof(Source), typeof(IThumbnailSource), typeof(Filmstrip), new PropertyMetadata(null, OnSourceChanged)); + + public static readonly DependencyProperty CurrentIndexProperty = DependencyProperty.Register( + nameof(CurrentIndex), typeof(int), typeof(Filmstrip), + new FrameworkPropertyMetadata(0, FrameworkPropertyMetadataOptions.BindsTwoWayByDefault, OnCurrentIndexChanged, CoerceCurrentIndex)); + + public static readonly DependencyProperty MarkersProperty = DependencyProperty.Register( + nameof(Markers), typeof(IReadOnlyList), typeof(Filmstrip), new PropertyMetadata(null, OnDataPropertyChanged)); + + public static readonly DependencyProperty CellWidthProperty = DependencyProperty.Register( + nameof(CellWidth), typeof(double), typeof(Filmstrip), + new FrameworkPropertyMetadata(38.0, FrameworkPropertyMetadataOptions.AffectsRender), v => v is double d && d >= 4); + + public static readonly DependencyProperty CacheCapacityProperty = DependencyProperty.Register( + nameof(CacheCapacity), typeof(int), typeof(Filmstrip), new PropertyMetadata(256, OnCacheCapacityChanged), v => v is int i && i > 0); + + private const double MarkerRow = 11; + private const double Gap = 2; + private const double Radius = 4; + private const double CellHeight = 44; + + private static readonly MarkerKind[] Kinds = Enum.GetValues(); + + private LruCache _cache = new(256); + private readonly HashSet _pending = []; + private CancellationTokenSource _loads = new(); + private StripLayout _strip; + private Rect _cells; + private bool _dragging; + private int _wheelDelta; + + static Filmstrip() + { + FocusableProperty.OverrideMetadata(typeof(Filmstrip), new FrameworkPropertyMetadata(true)); + CursorProperty.OverrideMetadata(typeof(Filmstrip), new FrameworkPropertyMetadata(Cursors.Hand)); + } + + public Filmstrip() + : base(hasOverlay: true) + { + } + + /// Frames of the sequence. + public IThumbnailSource? Source { get => (IThumbnailSource?)GetValue(SourceProperty); set => SetValue(SourceProperty, value); } + + /// Current frame (two-way): set by clicks, drags, wheel and keys. + public int CurrentIndex { get => (int)GetValue(CurrentIndexProperty); set => SetValue(CurrentIndexProperty, value); } + + /// Markers drawn above the cells. + public IReadOnlyList? Markers { get => (IReadOnlyList?)GetValue(MarkersProperty); set => SetValue(MarkersProperty, value); } + + /// Target cell width; the cells stretch to fill the strip exactly. + public double CellWidth { get => (double)GetValue(CellWidthProperty); set => SetValue(CellWidthProperty, value); } + + /// Decoded thumbnails kept in memory. + public int CacheCapacity { get => (int)GetValue(CacheCapacityProperty); set => SetValue(CacheCapacityProperty, value); } + + private int FrameCount => Source?.Count ?? 0; + + protected override Size MeasureOverride(Size availableSize) => new(0, MarkerRow + 3 + CellHeight); + + protected override void OnRender(DrawingContext dc) + { + DrawHitArea(dc); + var width = ActualWidth; + _cells = new Rect(0, MarkerRow + 3, width, Math.Max(0, ActualHeight - MarkerRow - 3)); + _strip = new StripLayout(width, CellWidth, Gap, FrameCount); + if (_strip.CellCount == 0 || _cells.Height <= 0) + { + dc.DrawRoundedRectangle(GetBrush("Brush.Card"), null, _cells, Radius, Radius); + RenderOverlay(); + return; + } + + var scale = PixelScale; + // Request enough pixels to cover the cell for frames up to 16:9 (UniformToFill crop). + var pixelWidth = (int)Math.Ceiling(Math.Max(_strip.CellWidth, _cells.Height * 16 / 9) * scale); + var placeholder = GetBrush("Brush.Card"); + dc.PushClip(new RectangleGeometry(_cells, Radius, Radius)); + for (var c = 0; c < _strip.CellCount; c++) + { + var cell = new Rect(PixelGrid.Snap(_strip.CellLeft(c), scale), _cells.Top, 0, _cells.Height); + cell.Width = PixelGrid.Snap(_strip.CellLeft(c) + _strip.CellWidth, scale) - cell.Left; + var frame = _strip.FrameForCell(c); + if (TryGetFrame(frame, pixelWidth, out var image)) DrawCover(dc, image, cell); + else dc.DrawRectangle(placeholder, null, cell); + } + dc.Pop(); + DrawMarkers(dc); + RenderOverlay(); + } + + protected override void OnRenderOverlay(DrawingContext dc) + { + if (_strip.CellCount == 0) return; + var frame = Math.Clamp(CurrentIndex, 0, _strip.FrameCount - 1); + var cellIndex = _strip.CellForFrame(frame); + var scale = PixelScale; + var left = PixelGrid.Snap(_strip.CellLeft(cellIndex), scale); + var right = PixelGrid.Snap(_strip.CellLeft(cellIndex) + _strip.CellWidth, scale); + // 2-px accent outline drawn inside the cell. + var outline = new Rect(left + 1, _cells.Top + 1, Math.Max(0, right - left - 2), Math.Max(0, _cells.Height - 2)); + dc.DrawRectangle(null, GetPen("Brush.Accent", 2), outline); + + var marker = new StreamGeometry(); + using (var ctx = marker.Open()) AddTriangleDown(ctx, _strip.XForFrame(frame), 1, 9); + marker.Freeze(); + dc.DrawGeometry(GetBrush("Brush.Accent"), null, marker); + } + + protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e) + { + base.OnMouseLeftButtonDown(e); + if (_strip.FrameCount == 0) return; + Focus(); + _dragging = CaptureMouse(); + Seek(e.GetPosition(this).X); + e.Handled = true; + } + + protected override void OnMouseMove(MouseEventArgs e) + { + base.OnMouseMove(e); + var p = e.GetPosition(this); + if (_dragging) + { + Seek(p.X); + Readout.Hide(); + return; + } + Readout.Show(p.Y < _cells.Top ? MarkerLabelAt(p.X) : null, p); + } + + protected override void OnMouseLeftButtonUp(MouseButtonEventArgs e) + { + base.OnMouseLeftButtonUp(e); + if (_dragging) ReleaseMouseCapture(); + } + + protected override void OnLostMouseCapture(MouseEventArgs e) + { + base.OnLostMouseCapture(e); + _dragging = false; + } + + protected override void OnMouseLeave(MouseEventArgs e) + { + base.OnMouseLeave(e); + Readout.Hide(); + } + + protected override void OnMouseWheel(MouseWheelEventArgs e) + { + base.OnMouseWheel(e); + if (_strip.FrameCount == 0) return; + // Accumulate so precision touchpads step once per notch-equivalent; wheel down moves forward. + _wheelDelta += e.Delta; + var steps = _wheelDelta / Mouse.MouseWheelDeltaForOneLine; + _wheelDelta -= steps * Mouse.MouseWheelDeltaForOneLine; + if (steps != 0) SetCurrentValue(CurrentIndexProperty, CurrentIndex - steps); + e.Handled = true; + } + + protected override void OnKeyDown(KeyEventArgs e) + { + base.OnKeyDown(e); + var count = FrameCount; + if (count == 0) return; + var cellFrames = Math.Max(1, count / Math.Max(1, _strip.CellCount)); + int? target = e.Key switch + { + Key.Left => CurrentIndex - 1, + Key.Right => CurrentIndex + 1, + Key.PageUp => CurrentIndex - cellFrames, + Key.PageDown => CurrentIndex + cellFrames, + Key.Home => 0, + Key.End => count - 1, + _ => null, + }; + if (target is null) return; + SetCurrentValue(CurrentIndexProperty, target.Value); + e.Handled = true; + } + + private static void OnSourceChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) + { + var strip = (Filmstrip)d; + strip.ResetCache(); + strip.CoerceValue(CurrentIndexProperty); + strip.InvalidateVisual(); + } + + private static void OnCurrentIndexChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) => ((Filmstrip)d).RenderOverlay(); + + private static object CoerceCurrentIndex(DependencyObject d, object value) + { + var count = ((Filmstrip)d).FrameCount; + return count == 0 ? 0 : Math.Clamp((int)value, 0, count - 1); + } + + private static void OnCacheCapacityChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) => + ((Filmstrip)d)._cache.Capacity = (int)e.NewValue; + + /// Draws scaled to cover , centred and cropped. + private static void DrawCover(DrawingContext dc, ImageSource image, Rect cell) + { + var w = image.Width; + var h = image.Height; + if (!(w > 0) || !(h > 0)) return; + var s = Math.Max(cell.Width / w, cell.Height / h); + var target = new Rect(cell.Left + (cell.Width - w * s) / 2, cell.Top + (cell.Height - h * s) / 2, w * s, h * s); + dc.PushClip(new RectangleGeometry(cell)); + dc.DrawImage(image, target); + dc.Pop(); + } + + private void DrawMarkers(DrawingContext dc) + { + if (Markers is not { Count: > 0 } markers) return; + foreach (var kind in Kinds) + { + StreamGeometry? geometry = null; + StreamGeometryContext? ctx = null; + for (var i = 0; i < markers.Count; i++) + { + var m = markers[i]; + if (m.Kind != kind || m.Index < 0 || m.Index >= _strip.FrameCount) continue; + if (ctx is null) + { + geometry = new StreamGeometry(); + ctx = geometry.Open(); + } + var x = _strip.XForFrame(m.Index); + if (kind == MarkerKind.Keyframe) AddDiamond(ctx, x, MarkerRow / 2, 8); + else AddTriangleDown(ctx, x, 1, 9); + } + if (ctx is null || geometry is null) continue; + ctx.Close(); + geometry.Freeze(); + dc.DrawGeometry(GetBrush(TimelineMarker.BrushKeyOf(kind)), null, geometry); + } + } + + /// Labels of the markers within 5 px of , one per line. + private string? MarkerLabelAt(double x) + { + if (Markers is not { Count: > 0 } markers || _strip.FrameCount == 0) return null; + string? text = null; + for (var i = 0; i < markers.Count; i++) + { + var m = markers[i]; + if (string.IsNullOrEmpty(m.Label) || Math.Abs(_strip.XForFrame(m.Index) - x) > 5) continue; + text = text is null ? m.Label : text + Environment.NewLine + m.Label; + } + return text; + } + + private void Seek(double x) + { + var frame = _strip.FrameAt(x); + if (frame >= 0) SetCurrentValue(CurrentIndexProperty, frame); + } + + private bool TryGetFrame(int frame, int pixelWidth, [NotNullWhen(true)] out ImageSource? image) + { + if (_cache.TryGet(frame, out var cached)) + { + // An image narrower than 80 % of the need (e.g. after a resize) stays on screen while a sharper one loads. + if (cached.PixelWidth < pixelWidth * 0.8) Request(frame, pixelWidth); + image = cached.Image; + return true; + } + Request(frame, pixelWidth); + image = null; + return false; + } + + private void Request(int frame, int pixelWidth) + { + if (Source is not { } source || !_pending.Add(frame)) return; + _ = LoadAsync(source, frame, pixelWidth, _loads.Token); + } + + private async Task LoadAsync(IThumbnailSource source, int frame, int pixelWidth, CancellationToken token) + { + try + { + // Requests are issued while rendering; leave the render pass before touching the cache. + await Task.Yield(); + token.ThrowIfCancellationRequested(); + var image = await source.GetAsync(frame, pixelWidth, token); + if (token.IsCancellationRequested || image is null) return; + _cache.Set(frame, new CachedFrame(image, pixelWidth)); + InvalidateVisual(); + } + catch (OperationCanceledException) + { + } + catch (Exception ex) + { + Log.Warning("ui.filmstrip", $"Thumbnail {frame} failed", ex); + } + finally + { + if (!token.IsCancellationRequested) _pending.Remove(frame); + } + } + + private void ResetCache() + { + // Not disposed: loads still in flight may observe the token after this point. + _loads.Cancel(); + _loads = new CancellationTokenSource(); + _pending.Clear(); + _cache = new LruCache(CacheCapacity); + } + + private readonly record struct CachedFrame(ImageSource Image, int PixelWidth); +}