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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:27:09 +00:00
1 parent 0ac73793c7
commit 3ba68fef1d
1 file changed
+337
+337
View File
@@ -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;
/// <summary>
/// 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 <see cref="CurrentIndex"/> 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 <see cref="Source"/> into an
/// LRU cache; cells show a placeholder until their image arrives. Hovering a marker reads out its label.
/// </summary>
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<TimelineMarker>), 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<MarkerKind>();
private LruCache<int, CachedFrame> _cache = new(256);
private readonly HashSet<int> _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)
{
}
/// <summary>Frames of the sequence.</summary>
public IThumbnailSource? Source { get => (IThumbnailSource?)GetValue(SourceProperty); set => SetValue(SourceProperty, value); }
/// <summary>Current frame (two-way): set by clicks, drags, wheel and keys.</summary>
public int CurrentIndex { get => (int)GetValue(CurrentIndexProperty); set => SetValue(CurrentIndexProperty, value); }
/// <summary>Markers drawn above the cells.</summary>
public IReadOnlyList<TimelineMarker>? Markers { get => (IReadOnlyList<TimelineMarker>?)GetValue(MarkersProperty); set => SetValue(MarkersProperty, value); }
/// <summary>Target cell width; the cells stretch to fill the strip exactly.</summary>
public double CellWidth { get => (double)GetValue(CellWidthProperty); set => SetValue(CellWidthProperty, value); }
/// <summary>Decoded thumbnails kept in memory.</summary>
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;
/// <summary>Draws <paramref name="image"/> scaled to cover <paramref name="cell"/>, centred and cropped.</summary>
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);
}
}
/// <summary>Labels of the markers within 5 px of <paramref name="x"/>, one per line.</summary>
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<int, CachedFrame>(CacheCapacity);
}
private readonly record struct CachedFrame(ImageSource Image, int PixelWidth);
}