Files
Chronos/src/Chronos.Core/Imaging/Geometry/FrameOrientation.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

138 lines
7.3 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 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);
}
}