using Chronos.Core.Project;
namespace Chronos.Core.Imaging.Geometry;
///
/// The view frame T of a camera (owner review 1, R6): the decoded (Exif-oriented, stabilised) frame of
/// × turned by quarter turns clockwise, then mirrored
/// and flipped in screen axes, then straightened by degrees clockwise about its centre and
/// magnified by so no border shows. is O = S · F · Q in
/// pixel-centre coordinates (); 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 into its single warp.
///
public sealed record FrameOrientation
{
/// The largest straighten angle in degrees, either way.
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);
}
/// Quarter turns clockwise, 0..3.
public int Turns { get; }
/// Left and right swapped after the turns.
public bool Mirror { get; }
/// Top and bottom swapped after the turns.
public bool Flip { get; }
/// Degrees clockwise, within ±.
public double Straighten { get; }
/// The decoded frame's size in pixels.
public int FrameWidth { get; }
public int FrameHeight { get; }
/// The view frame's size in pixels: the frame's, swapped for an odd number of turns.
public int ViewWidth { get; }
public int ViewHeight { get; }
///
/// 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).
///
public double CoverZoom { get; }
/// Frame pixel-centre coordinates to view pixel-centre coordinates (O).
public Affine2D FrameToView { get; }
/// View pixel-centre coordinates to frame pixel-centre coordinates (O⁻¹), for .
public Affine2D ViewToFrame { get; }
/// No turn, mirror, flip or straighten: the view is the frame.
public bool IsIdentity => Turns == 0 && !Mirror && !Flip && Straighten == 0;
/// The orientation of for a frame of the given size, its values normalised (, ).
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);
}
///
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);
}
/// The identity orientation of a frame of the given size.
public static FrameOrientation Identity(int frameWidth, int frameHeight) => Of(0, false, false, 0, frameWidth, frameHeight);
/// The same orientation for a frame of another size (a decode at another long edge).
public FrameOrientation Resized(int frameWidth, int frameHeight) => frameWidth == FrameWidth && frameHeight == FrameHeight
? this
: Of(Turns * 90, Mirror, Flip, Straighten, frameWidth, frameHeight);
/// A rotation stored in degrees is a multiple of 90 (anything else renders as no turn).
public static bool IsValidRotate(int rotate) => rotate % 90 == 0;
/// Quarter turns clockwise, 0..3, of a rotation in degrees; 0 when it is not a multiple of 90.
public static int TurnsOf(int rotate) => IsValidRotate(rotate) ? ((rotate / 90 % 4) + 4) % 4 : 0;
/// A straighten angle as rendered: clamped to ±, 0 when not finite.
public static double StraightenOf(double degrees) => double.IsFinite(degrees) ? double.Clamp(degrees, -MaxStraighten, MaxStraighten) : 0;
/// The angle is rendered as stored (finite and within ±).
public static bool IsValidStraighten(double degrees) => double.IsFinite(degrees) && double.Abs(degrees) <= MaxStraighten;
///
/// The smallest zoom about the centre at which a view of ×
/// rotated by still covers the whole view: cos|θ| + max(W/H, H/W)·sin|θ|.
///
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;
}
/// Q: the quarter turns, frame → turned frame, exact.
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,
};
/// F: mirror and flip in the turned frame, exact (its own inverse).
private Affine2D MirrorFlip() => new(Mirror ? -1 : 1, 0, 0, Flip ? -1 : 1, Mirror ? ViewWidth - 1 : 0, Flip ? ViewHeight - 1 : 0);
/// S ( 1) or S⁻¹ (−1): the straighten and its cover zoom about the view's centre.
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);
}
}