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>
138 lines
7.3 KiB
C#
138 lines
7.3 KiB
C#
using Chronos.Core.Project;
|
||
|
||
namespace Chronos.Core.Imaging.Geometry;
|
||
|
||
/// <summary>
|
||
/// The view frame T of a camera (owner review 1, R6): the decoded (Exif-oriented, stabilised) frame of
|
||
/// <see cref="FrameWidth"/>×<see cref="FrameHeight"/> turned by <see cref="Turns"/> quarter turns clockwise, then mirrored
|
||
/// and flipped in screen axes, then straightened by <see cref="Straighten"/> degrees clockwise about its centre and
|
||
/// magnified by <see cref="CoverZoom"/> so no border shows. <see cref="FrameToView"/> is <c>O = S · F · Q</c> in
|
||
/// pixel-centre coordinates (<see cref="Affine2D"/>); the quarter turns and the mirror/flip are exact integer matrices, so
|
||
/// an unstraightened view resamples to an exact permutation of the pixels. The crop and the keyframe centres are
|
||
/// normalised in T. Pixels are never turned after decode: the render folds <see cref="ViewToFrame"/> into its single warp.
|
||
/// </summary>
|
||
public sealed record FrameOrientation
|
||
{
|
||
/// <summary>The largest straighten angle in degrees, either way.</summary>
|
||
public const double MaxStraighten = 15;
|
||
|
||
private FrameOrientation(int turns, bool mirror, bool flip, double straighten, int frameWidth, int frameHeight)
|
||
{
|
||
Turns = turns;
|
||
Mirror = mirror;
|
||
Flip = flip;
|
||
Straighten = straighten;
|
||
FrameWidth = frameWidth;
|
||
FrameHeight = frameHeight;
|
||
(ViewWidth, ViewHeight) = turns % 2 == 1 ? (frameHeight, frameWidth) : (frameWidth, frameHeight);
|
||
// On the pixel-centre extents, so every output pixel centre samples between frame pixel centres (full coverage).
|
||
CoverZoom = CoverZoomOf(straighten, int.Max(1, ViewWidth - 1), int.Max(1, ViewHeight - 1));
|
||
FrameToView = Straightening(1) * MirrorFlip() * QuarterTurns();
|
||
ViewToFrame = QuarterTurns().Invert() * MirrorFlip() * Straightening(-1);
|
||
}
|
||
|
||
/// <summary>Quarter turns clockwise, 0..3.</summary>
|
||
public int Turns { get; }
|
||
|
||
/// <summary>Left and right swapped after the turns.</summary>
|
||
public bool Mirror { get; }
|
||
|
||
/// <summary>Top and bottom swapped after the turns.</summary>
|
||
public bool Flip { get; }
|
||
|
||
/// <summary>Degrees clockwise, within ±<see cref="MaxStraighten"/>.</summary>
|
||
public double Straighten { get; }
|
||
|
||
/// <summary>The decoded frame's size in pixels.</summary>
|
||
public int FrameWidth { get; }
|
||
|
||
public int FrameHeight { get; }
|
||
|
||
/// <summary>The view frame's size in pixels: the frame's, swapped for an odd number of turns.</summary>
|
||
public int ViewWidth { get; }
|
||
|
||
public int ViewHeight { get; }
|
||
|
||
/// <summary>
|
||
/// The straighten's cover zoom c = cos|θ| + max(W'/H', H'/W')·sin|θ| (1 without straighten), never stored, taken on the
|
||
/// pixel-centre extents (W' − 1)×(H' − 1): the view's outermost pixel centres land on the frame's, so a resample needs no
|
||
/// sample outside the frame (with a transparent border, every pixel is fully covered).
|
||
/// </summary>
|
||
public double CoverZoom { get; }
|
||
|
||
/// <summary>Frame pixel-centre coordinates to view pixel-centre coordinates (O).</summary>
|
||
public Affine2D FrameToView { get; }
|
||
|
||
/// <summary>View pixel-centre coordinates to frame pixel-centre coordinates (O⁻¹), for <see cref="GeometrySettings.Warp"/>.</summary>
|
||
public Affine2D ViewToFrame { get; }
|
||
|
||
/// <summary>No turn, mirror, flip or straighten: the view is the frame.</summary>
|
||
public bool IsIdentity => Turns == 0 && !Mirror && !Flip && Straighten == 0;
|
||
|
||
/// <summary>The orientation of <paramref name="camera"/> for a frame of the given size, its values normalised (<see cref="TurnsOf"/>, <see cref="StraightenOf"/>).</summary>
|
||
public static FrameOrientation Of(CameraSettings camera, int frameWidth, int frameHeight)
|
||
{
|
||
ArgumentNullException.ThrowIfNull(camera);
|
||
return Of(camera.Rotate, camera.Mirror, camera.Flip, camera.Straighten, frameWidth, frameHeight);
|
||
}
|
||
|
||
/// <inheritdoc cref="Of(CameraSettings, int, int)"/>
|
||
public static FrameOrientation Of(int rotate, bool mirror, bool flip, double straighten, int frameWidth, int frameHeight)
|
||
{
|
||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameWidth);
|
||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(frameHeight);
|
||
return new FrameOrientation(TurnsOf(rotate), mirror, flip, StraightenOf(straighten), frameWidth, frameHeight);
|
||
}
|
||
|
||
/// <summary>The identity orientation of a frame of the given size.</summary>
|
||
public static FrameOrientation Identity(int frameWidth, int frameHeight) => Of(0, false, false, 0, frameWidth, frameHeight);
|
||
|
||
/// <summary>The same orientation for a frame of another size (a decode at another long edge).</summary>
|
||
public FrameOrientation Resized(int frameWidth, int frameHeight) => frameWidth == FrameWidth && frameHeight == FrameHeight
|
||
? this
|
||
: Of(Turns * 90, Mirror, Flip, Straighten, frameWidth, frameHeight);
|
||
|
||
/// <summary>A rotation stored in degrees is a multiple of 90 (anything else renders as no turn).</summary>
|
||
public static bool IsValidRotate(int rotate) => rotate % 90 == 0;
|
||
|
||
/// <summary>Quarter turns clockwise, 0..3, of a rotation in degrees; 0 when it is not a multiple of 90.</summary>
|
||
public static int TurnsOf(int rotate) => IsValidRotate(rotate) ? ((rotate / 90 % 4) + 4) % 4 : 0;
|
||
|
||
/// <summary>A straighten angle as rendered: clamped to ±<see cref="MaxStraighten"/>, 0 when not finite.</summary>
|
||
public static double StraightenOf(double degrees) => double.IsFinite(degrees) ? double.Clamp(degrees, -MaxStraighten, MaxStraighten) : 0;
|
||
|
||
/// <summary>The angle is rendered as stored (finite and within ±<see cref="MaxStraighten"/>).</summary>
|
||
public static bool IsValidStraighten(double degrees) => double.IsFinite(degrees) && double.Abs(degrees) <= MaxStraighten;
|
||
|
||
/// <summary>
|
||
/// The smallest zoom about the centre at which a view of <paramref name="viewWidth"/>×<paramref name="viewHeight"/>
|
||
/// rotated by <paramref name="degrees"/> still covers the whole view: cos|θ| + max(W/H, H/W)·sin|θ|.
|
||
/// </summary>
|
||
public static double CoverZoomOf(double degrees, double viewWidth, double viewHeight)
|
||
{
|
||
if (degrees == 0) return 1;
|
||
var (sin, cos) = double.SinCos(double.Abs(degrees) * double.Pi / 180);
|
||
return cos + double.Max(viewWidth / viewHeight, viewHeight / viewWidth) * sin;
|
||
}
|
||
|
||
/// <summary>Q: the quarter turns, frame → turned frame, exact.</summary>
|
||
private Affine2D QuarterTurns() => Turns switch
|
||
{
|
||
1 => new Affine2D(0, -1, 1, 0, FrameHeight - 1, 0),
|
||
2 => new Affine2D(-1, 0, 0, -1, FrameWidth - 1, FrameHeight - 1),
|
||
3 => new Affine2D(0, 1, -1, 0, 0, FrameWidth - 1),
|
||
_ => Affine2D.Identity,
|
||
};
|
||
|
||
/// <summary>F: mirror and flip in the turned frame, exact (its own inverse).</summary>
|
||
private Affine2D MirrorFlip() => new(Mirror ? -1 : 1, 0, 0, Flip ? -1 : 1, Mirror ? ViewWidth - 1 : 0, Flip ? ViewHeight - 1 : 0);
|
||
|
||
/// <summary>S (<paramref name="direction"/> 1) or S⁻¹ (−1): the straighten and its cover zoom about the view's centre.</summary>
|
||
private Affine2D Straightening(int direction)
|
||
{
|
||
if (Straighten == 0) return Affine2D.Identity;
|
||
var scale = direction > 0 ? CoverZoom : 1 / CoverZoom;
|
||
return Affine2D.About(Affine2D.Similarity(scale, direction * Straighten * double.Pi / 180, 0, 0), (ViewWidth - 1) / 2.0, (ViewHeight - 1) / 2.0);
|
||
}
|
||
}
|