Files
Chronos/src/Chronos.Core/Render/RenderGeometry.cs
T
Alby96andClaude Opus 5.5 bee66da63a feat(render): orient, straighten and let the chosen proportions win in the render geometry
Owner review 1, phase 4, package P1: the Core geometry behind the visual
crop (R5) and the orientation controls (R6).

- RenderGeometry: one warp stab⁻¹ · O⁻¹ · V with the crop and the keyframe
  centres in the view frame T (turned, mirrored, flipped, straightened);
  the output size comes from RenderSize, so a fixed preset adapts to the
  aspect (4K at 9:16 = 2160×3840) and AspectFromPreset is gone; the decode
  grows by the straighten cover zoom; ViewFor, ViewToFrame, EditableCrop
  and FootprintInView get their real bodies; a rotation that is not a
  quarter turn and an out-of-range straighten render as none or clamped,
  with their warnings.
- FrameOrientation: the cover zoom is taken on the pixel-centre extents,
  so every output pixel samples inside the frame (full alpha coverage at
  ±15°, never a smeared border).
- CropFrame: crops are written on the 12-decimal grid OrientationEdit
  remaps on, so four turns or two mirrors give back the same text; a
  stored crop is read value by value as the render reads it.
- Advisor: the aspect (and the horizon framing) is advised on the view
  turned by the camera (SequenceContext.Rotate/Flip, ForCamera); the
  analyser passes the project's camera.
- Self-test: proc.orient, proc.straighten, proc.portrait.
- Tests: exact pixel permutations for turns, mirror and flip, the
  orientation algebra, straighten against an analytic ramp and its full
  coverage, Create sizes, a crop keeping its content through every press,
  CropFrame move/resize/refit/rows, OrientationEdit round trips and its
  agreement with FrameOrientation, the turned-view advice, determinism.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 19:35:05 +01:00

300 lines
16 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
using System.Globalization;
using Chronos.Core.Export;
using Chronos.Core.Imaging.Geometry;
using Chronos.Core.Motion;
using Chronos.Core.Project;
namespace Chronos.Core.Render;
/// <summary>
/// Output size, decode size and per-frame warp of a render. The decoded frame is turned, mirrored, flipped and
/// straightened into the view frame T (<see cref="FrameOrientation"/>); <see cref="CameraSettings.Crop"/> is a normalised
/// [x, y, width, height] rectangle of T and the keyframe centres are normalised in it. The chosen proportions win
/// (owner review 1, R5): the output ratio is the camera aspect, a fixed-size preset adapting its size to it
/// (<see cref="RenderSize"/>), and "source" keeps the preset's ratio (else the view's). Virtual-camera keyframes are keyed
/// to source frame positions, so they stay attached to the content when timing, frame rate or fitting change. The
/// stabiliser correction, the orientation, the camera pose (zoomed by the stabilisation zoom) and the crop become one
/// output→source map, <c>stab⁻¹ · O⁻¹ · V</c>, resampled once.
/// </summary>
public sealed class RenderGeometry
{
private static readonly CameraState Neutral = new(0.5, 0.5, 1, 0);
private readonly VirtualCamera? _camera;
private readonly FrameOrientation _orientation;
private readonly RectD _crop;
private readonly double _offsetX;
private readonly double _offsetY;
private readonly double _stabilizationZoom;
private readonly double _fittedWidth;
private readonly double _fittedHeight;
private readonly double _maxZoom;
private readonly int _maxWorkingLongEdge;
private RenderGeometry(VirtualCamera? camera, FrameOrientation orientation, RectD crop, double offsetX, double offsetY, double stabilizationZoom, int sourceWidth, int sourceHeight,
int outputWidth, int outputHeight, double fittedWidth, double fittedHeight, double maxZoom, int maxWorkingLongEdge, IReadOnlyList<RenderWarning> warnings,
double outputRatio)
{
OutputRatio = outputRatio;
_camera = camera;
_orientation = orientation;
_crop = crop;
_offsetX = offsetX;
_offsetY = offsetY;
_stabilizationZoom = stabilizationZoom;
SourceWidth = sourceWidth;
SourceHeight = sourceHeight;
OutputWidth = outputWidth;
OutputHeight = outputHeight;
_fittedWidth = fittedWidth;
_fittedHeight = fittedHeight;
_maxZoom = maxZoom;
_maxWorkingLongEdge = maxWorkingLongEdge;
Warnings = warnings;
}
public int SourceWidth { get; }
public int SourceHeight { get; }
public int OutputWidth { get; }
public int OutputHeight { get; }
/// <summary>
/// Width of the view frame T at full resolution (<see cref="FrameOrientation"/>): the source turned, mirrored and
/// straightened. <see cref="CameraSettings.Crop"/> and the keyframe centres are normalised in it.
/// </summary>
public int ViewWidth => _orientation.ViewWidth;
/// <inheritdoc cref="ViewWidth"/>
public int ViewHeight => _orientation.ViewHeight;
/// <summary>The camera's orientation at full resolution, its values as rendered (<see cref="FrameOrientation.Of(CameraSettings, int, int)"/>).</summary>
public FrameOrientation Orientation => _orientation;
/// <summary>The output ratio (width / height) the crop is fitted to (<see cref="RenderSize.Ratio"/>), before rounding to whole pixels.</summary>
public double OutputRatio { get; }
/// <summary>
/// The crop box's width over its height in normalised view units (<see cref="OutputRatio"/> × <see cref="ViewHeight"/> /
/// <see cref="ViewWidth"/>): the lock ratio of <see cref="CropFrame"/>.
/// </summary>
public double LockRatio => OutputRatio * ViewHeight / ViewWidth;
/// <summary>
/// The crop the editor shows and edits, normalised in the view frame and the same on every frame: the stored crop
/// fitted to the output ratio and placed by the offsets (<see cref="CropFrame.Locked"/>).
/// </summary>
public RectD EditableCrop => AspectRatio.FitCrop(_crop, LockRatio, _offsetX, _offsetY);
/// <summary>Remarks about ignored camera values.</summary>
public IReadOnlyList<RenderWarning> Warnings { get; }
/// <summary>
/// Long edge to decode source frames at: enough that the most zoomed-in view (keyframe zoom × stabilisation zoom ×
/// straighten cover zoom) still has one source pixel per output pixel, never more than the source, capped by
/// <see cref="RenderOptions.MaxWorkingLongEdge"/>. Quarter turns do not change the long edge.
/// </summary>
public int WorkingLongEdge
{
get
{
var needed = double.Max(OutputWidth / _fittedWidth, OutputHeight / _fittedHeight) * _maxZoom;
var edge = (int)double.Ceiling(int.Max(SourceWidth, SourceHeight) * double.Min(1, needed));
edge = int.Clamp(edge, int.Min(16, int.Max(SourceWidth, SourceHeight)), int.Max(SourceWidth, SourceHeight));
return _maxWorkingLongEdge > 0 ? int.Min(edge, _maxWorkingLongEdge) : edge;
}
}
/// <summary>Plans the geometry of <paramref name="export"/> for a source of the given full-resolution size.</summary>
/// <param name="stabilizationZoom">Zoom that hides stabilisation borders (<see cref="RenderCorrections.StabilizationZoom"/>).</param>
/// <param name="maxWorkingLongEdge">Decode-size cap (0 = none); it also caps source-sized outputs.</param>
public static RenderGeometry Create(CameraSettings camera, ResolvedExport export, int sourceWidth, int sourceHeight, double stabilizationZoom = 1, int maxWorkingLongEdge = 0)
{
ArgumentNullException.ThrowIfNull(camera);
ArgumentNullException.ThrowIfNull(export);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceWidth);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceHeight);
var warnings = new List<RenderWarning>();
var orientation = OrientationOf(camera, sourceWidth, sourceHeight, warnings);
var crop = NormalisedCrop(camera.Crop, warnings);
if (!AspectRatio.TryParse(camera.Aspect.Resolve("source"), out _))
warnings.Add(new RenderWarning("Export.Render.AspectIgnored", camera.Aspect.Resolve(string.Empty)));
// The chosen proportions win: a fixed-size preset is a box the aspect is fitted in (RenderSize).
var ratio = RenderSize.Ratio(camera, export, sourceWidth, sourceHeight);
var (viewWidth, viewHeight) = (orientation.ViewWidth, orientation.ViewHeight);
var cropPixels = new RectD(crop.X * viewWidth, crop.Y * viewHeight, crop.Width * viewWidth, crop.Height * viewHeight);
var fitted = AspectRatio.FitCrop(cropPixels, ratio, camera.OffsetX, camera.OffsetY);
var (width, height) = RenderSize.Of(camera, export, sourceWidth, sourceHeight, maxWorkingLongEdge);
var cameraPath = Camera(camera.Keyframes, warnings);
var maxZoom = (cameraPath?.Keyframes.Max(k => k.Zoom) ?? 1) * stabilizationZoom * orientation.CoverZoom;
return new RenderGeometry(cameraPath, orientation, crop, camera.OffsetX, camera.OffsetY, stabilizationZoom, sourceWidth, sourceHeight, width, height,
fitted.Width, fitted.Height, maxZoom, maxWorkingLongEdge, warnings, ratio);
}
/// <summary>The same geometry rendering into a different output size (e.g. capped by the encoder).</summary>
public RenderGeometry WithOutputSize(int width, int height) => width == OutputWidth && height == OutputHeight
? this
: new RenderGeometry(_camera, _orientation, _crop, _offsetX, _offsetY, _stabilizationZoom, SourceWidth, SourceHeight, width, height, _fittedWidth, _fittedHeight,
_maxZoom, _maxWorkingLongEdge, Warnings, OutputRatio);
/// <summary>Camera pose at a (fractional) source position, including the stabilisation zoom.</summary>
public CameraState PoseAt(double sourcePosition)
{
var pose = _camera?.Evaluate(sourcePosition) ?? Neutral;
return pose with { Zoom = pose.Zoom * _stabilizationZoom };
}
/// <summary>
/// Geometry of one decoded frame of <paramref name="frameWidth"/>×<paramref name="frameHeight"/> pixels: the crop in the
/// view frame, and the warp <c>stab⁻¹ · O⁻¹ · V</c> from the camera view (the pose in the view frame) through the view
/// frame to the stabilised and then the decoded frame.
/// </summary>
/// <param name="stabilization">The frame's stabiliser correction at this frame size (source → stabilised).</param>
public GeometrySettings For(int frameWidth, int frameHeight, double sourcePosition, Affine2D stabilization)
{
var orientation = _orientation.Resized(frameWidth, frameHeight);
var (viewWidth, viewHeight) = (orientation.ViewWidth, orientation.ViewHeight);
var view = VirtualCamera.ViewToSource(PoseAt(sourcePosition), viewWidth, viewHeight);
if (!orientation.IsIdentity) view = orientation.ViewToFrame * view;
return new GeometrySettings
{
Crop = new RectD(_crop.X * viewWidth, _crop.Y * viewHeight, _crop.Width * viewWidth, _crop.Height * viewHeight),
Aspect = AspectRatio.Source,
OffsetX = _offsetX,
OffsetY = _offsetY,
OutputWidth = OutputWidth,
OutputHeight = OutputHeight,
Warp = stabilization.IsIdentity() ? view : stabilization.Invert() * view,
Border = BorderMode.Clamp,
};
}
/// <summary>
/// The view frame→decoded frame map (O⁻¹, <see cref="FrameOrientation.ViewToFrame"/>) for a frame of
/// <paramref name="frameWidth"/>×<paramref name="frameHeight"/> pixels, without stabilisation: what maps overlays
/// drawn in frame pixels (the horizon, the region mask) into the view through its inverse.
/// </summary>
public Affine2D ViewToFrame(int frameWidth, int frameHeight)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameWidth);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameHeight);
return _orientation.Resized(frameWidth, frameHeight).ViewToFrame;
}
/// <summary>
/// The whole view frame of one decoded frame at <paramref name="outputWidth"/>×<paramref name="outputHeight"/>
/// pixels, without crop, camera pose or stabilisation: the editor's Source framing of an oriented camera.
/// </summary>
public GeometrySettings ViewFor(int frameWidth, int frameHeight, int outputWidth, int outputHeight)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(outputWidth);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(outputHeight);
var orientation = _orientation.Resized(frameWidth, frameHeight);
return new GeometrySettings
{
Crop = RectD.FromSize(orientation.ViewWidth, orientation.ViewHeight),
Aspect = AspectRatio.Source,
OutputWidth = outputWidth,
OutputHeight = outputHeight,
Warp = orientation.ViewToFrame,
Border = BorderMode.Clamp,
};
}
/// <summary>
/// The footprint of a planned output frame (<see cref="GeometryStage.Plan"/> of <see cref="For"/> on a frame of
/// <paramref name="frameWidth"/>×<paramref name="frameHeight"/>) in the view frame: the bounding box of its warped
/// corners, normalised and clamped to [0,1]²; the whole view without a plan. The Export step's crop mask.
/// </summary>
public RectD FootprintInView(GeometryPlan? plan, int frameWidth, int frameHeight)
{
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameWidth);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameHeight);
if (plan is not { } p) return new RectD(0, 0, 1, 1);
var orientation = _orientation.Resized(frameWidth, frameHeight);
var toView = orientation.FrameToView * p.OutputToSource;
double left = double.MaxValue, top = double.MaxValue, right = double.MinValue, bottom = double.MinValue;
foreach (var (u, v) in new[] { (-0.5, -0.5), (p.OutputWidth - 0.5, -0.5), (-0.5, p.OutputHeight - 0.5), (p.OutputWidth - 0.5, p.OutputHeight - 0.5) })
{
var (x, y) = toView.Apply(u, v);
(left, top, right, bottom) = (double.Min(left, x + 0.5), double.Min(top, y + 0.5), double.Max(right, x + 0.5), double.Max(bottom, y + 0.5));
}
var (viewWidth, viewHeight) = (orientation.ViewWidth, orientation.ViewHeight);
left = double.Clamp(left / viewWidth, 0, 1);
top = double.Clamp(top / viewHeight, 0, 1);
return new RectD(left, top, double.Clamp(right / viewWidth, 0, 1) - left, double.Clamp(bottom / viewHeight, 0, 1) - top);
}
/// <summary>
/// The camera's orientation as rendered: a rotation that is not a quarter turn counts as none
/// (<c>Export.Render.RotationIgnored</c>), a straighten beyond ±15° (or not finite) is clamped
/// (<c>Export.Render.StraightenClamped</c>).
/// </summary>
private static FrameOrientation OrientationOf(CameraSettings camera, int sourceWidth, int sourceHeight, List<RenderWarning> warnings)
{
if (!FrameOrientation.IsValidRotate(camera.Rotate))
warnings.Add(new RenderWarning("Export.Render.RotationIgnored", camera.Rotate.ToString(CultureInfo.InvariantCulture)));
if (!FrameOrientation.IsValidStraighten(camera.Straighten))
warnings.Add(new RenderWarning("Export.Render.StraightenClamped", camera.Straighten.ToString(CultureInfo.InvariantCulture),
FrameOrientation.StraightenOf(camera.Straighten).ToString(CultureInfo.InvariantCulture)));
return FrameOrientation.Of(camera, sourceWidth, sourceHeight);
}
private static RectD NormalisedCrop(double[]? crop, List<RenderWarning> warnings)
{
var full = new RectD(0, 0, 1, 1);
if (crop is null) return full;
if (crop.Length != 4 || !crop.All(double.IsFinite))
{
warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
return full;
}
var x = double.Clamp(crop[0], 0, 1);
var y = double.Clamp(crop[1], 0, 1);
var w = double.Min(crop[2], 1 - x);
var h = double.Min(crop[3], 1 - y);
if (w <= 1e-3 || h <= 1e-3)
{
warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
return full;
}
return new RectD(x, y, w, h);
}
private static VirtualCamera? Camera(IReadOnlyList<CameraKey> keys, List<RenderWarning> warnings)
{
if (keys.Count == 0) return null;
var frames = new Dictionary<int, CameraKeyframe>();
foreach (var k in keys)
{
if (!double.IsFinite(k.CenterX + k.CenterY + k.Zoom + k.Rotation))
{
warnings.Add(new RenderWarning("Export.Render.KeyframeIgnored", k.Frame.ToString(CultureInfo.InvariantCulture)));
continue;
}
frames[k.Frame] = new CameraKeyframe(k.Frame, k.CenterX, k.CenterY, double.Max(1, k.Zoom), k.Rotation) { Easing = Easing(k.Easing, warnings) };
}
return frames.Count == 0 ? null : new VirtualCamera(frames.Values);
}
/// <summary>"Linear", "EaseIn", "EaseOut", "EaseInOut" or "x1,y1,x2,y2" control points (CSS cubic-bezier).</summary>
private static BezierEasing Easing(string? text, List<RenderWarning> warnings)
{
switch (text?.Trim().ToLowerInvariant())
{
case null or "" or "easeinout": return BezierEasing.EaseInOut;
case "linear": return BezierEasing.Linear;
case "easein": return BezierEasing.EaseIn;
case "easeout": return BezierEasing.EaseOut;
}
var parts = text.Split(',');
if (parts.Length == 4
&& double.TryParse(parts[0], NumberStyles.Float, CultureInfo.InvariantCulture, out var x1) && x1 is >= 0 and <= 1
&& double.TryParse(parts[1], NumberStyles.Float, CultureInfo.InvariantCulture, out var y1) && double.IsFinite(y1)
&& double.TryParse(parts[2], NumberStyles.Float, CultureInfo.InvariantCulture, out var x2) && x2 is >= 0 and <= 1
&& double.TryParse(parts[3], NumberStyles.Float, CultureInfo.InvariantCulture, out var y2) && double.IsFinite(y2))
return new BezierEasing(x1, y1, x2, y2);
warnings.Add(new RenderWarning("Export.Render.EasingIgnored", text));
return BezierEasing.EaseInOut;
}
}