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>
300 lines
16 KiB
C#
300 lines
16 KiB
C#
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;
|
||
}
|
||
}
|