feat(project): settle phase 4 contracts: conditional settings format, transforms, look, output size

Groundwork for owner review 1, phase 4, so the parallel packages build on
fixed contracts and strings.

- Settings: camera rotate/mirror/flip/straighten and a look, declared after
  the existing members and omitted at default. ToJson writes the lowest
  format that renders the same (2 only while a transform or look is used),
  so projects without them keep byte-identical text and hash; an old-build
  simulation test proves the order survives an older build's round trip.
- RenderSize and RenderRules: proportions win over a fixed preset box, and
  the routing format a job needs.
- FrameOrientation, CropFrame, OrientationEdit, LookFilter (identity) and
  FrameFinish (look, then knee) wired into the render pipeline and preview;
  RenderGeometry gains view-frame members equivalent to today.
- Protocol trailing members for node, job and server formats; SyncText keys;
  EditPath counts transforms and the look as hand values.
- New en/it strings and tooltips, five icons, test fixtures moved to v3 as
  the first unread format, and the 18 DECISIONS rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-04 19:10:12 +01:00
1 parent 4ad29977b9
commit e4364c4f25
43 files changed
+1544 -178

No files matched your search

+104 -5
View File
@@ -164,16 +164,59 @@ public sealed record MotionSettings
public sealed record CameraSettings
{
/// <summary>Normalised crop (0..1) or null for the full frame.</summary>
/// <summary>
/// Normalised [x, y, width, height] of the view frame (oriented, straightened and cover-zoomed: see
/// <see cref="Rotate"/>), or null for the whole view. The editor writes the box locked to <see cref="Aspect"/> with
/// the offsets at 0; the render fits any other rectangle to the aspect.
/// </summary>
public double[]? Crop { get; init; }
/// <summary>"source", "16:9", "21:9", "4:3", "3:2", "1:1", "9:16", "4:5" or "w:h".</summary>
/// <summary>
/// The output proportions: "source", "16:9", "21:9", "4:3", "3:2", "1:1", "9:16", "4:5" or "w:h". A preset of a fixed
/// size adapts its size to them (4K at 9:16 = 2160×3840); "source" keeps the preset's own.
/// </summary>
public Auto<string> Aspect { get; init; } = new();
/// <summary>Placement of the aspect-fitted crop inside <see cref="Crop"/>, −1..1 per axis; 0 for a crop the editor wrote.</summary>
public double OffsetX { get; init; }
/// <inheritdoc cref="OffsetX"/>
public double OffsetY { get; init; }
/// <summary>Virtual-camera keyframes; their centres are normalised in the view frame, like <see cref="Crop"/>.</summary>
public IReadOnlyList<CameraKey> Keyframes { get; init; } = [];
/// <summary>
/// Quarter turns of the picture in degrees clockwise (0, 90, 180 or 270), after the Exif orientation applied at decode.
/// A value that is not a multiple of 90 renders as 0 (<c>Export.Render.RotationIgnored</c>). Settings format 2.
/// </summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public int Rotate { get; init; }
/// <summary>Left and right swapped, in screen axes after <see cref="Rotate"/>. Settings format 2.</summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public bool Mirror { get; init; }
/// <summary>Top and bottom swapped, in screen axes after <see cref="Rotate"/>. Settings format 2.</summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public bool Flip { get; init; }
/// <summary>
/// Free-angle levelling in degrees, positive clockwise, after <see cref="Mirror"/> and <see cref="Flip"/>, with an
/// automatic cover zoom (never stored) that never shows a border. Clamped to ±15, a value that is not finite counting as
/// 0 (<c>Export.Render.StraightenClamped</c>). Settings format 2.
/// </summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
public double Straighten { get; init; }
/// <summary>Quarter turns clockwise, 0..3; meaningful only when <see cref="Rotate"/> is a multiple of 90.</summary>
[JsonIgnore]
public int Turns => ((Rotate / 90 % 4) + 4) % 4;
/// <summary>A turn, mirror, flip or straighten is set: the view frame differs from the decoded frame.</summary>
[JsonIgnore]
public bool IsOriented => Rotate % 360 != 0 || Mirror || Flip || Straighten != 0;
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
@@ -240,13 +283,50 @@ public sealed record ExportSettings
public Dictionary<string, JsonElement>? Extra { get; set; }
}
/// <summary>
/// The colour look of a render (owner review 1, R6): a built-in parametric filter blended by its strength, applied to
/// every output frame in linear light before the highlight knee. <see cref="ProjectSettings.Look"/> is null for none.
/// </summary>
public sealed record LookSettings
{
/// <summary>
/// The filter's name: null or "none", "mono", "sepia", "warm", "cool", "vivid", "muted" or "fade"
/// (<c>LookFilter.Names</c>). A text, not an enum, so a newer Chronos can add looks; one this Chronos does not know
/// renders as none (<c>Export.Render.LookIgnored</c>).
/// </summary>
public string? Filter { get; init; }
/// <summary>Share of the filter applied, 0..1; null for 1.</summary>
public double? Strength { get; init; }
/// <summary>The look leaves the picture as it is.</summary>
[JsonIgnore]
public bool IsIdentity => Filter is null or "none" || Strength is <= 0;
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
/// <summary>
/// The "project" of a sequence (<c>.chronos/project.json</c>, BRIEF §7): every render decision. Originals are
/// never modified; all edits live here.
/// </summary>
/// <remarks>
/// The settings format (<see cref="Version"/>) is conditional: <see cref="ToJson"/> writes the lowest format that renders
/// the same (<see cref="RequiredFormat"/>), so a project that uses nothing newer keeps format 1, its canonical text and its
/// hash, and older builds read it as before. Rules for a member added later: one that changes pixels and that the previous
/// format would ignore raises the written format only while it is used; it is declared after the existing members of its
/// section (before <c>Extra</c>) and omitted at its default, so an older build keeps it in <c>Extra</c> and writes it
/// back in the same place; a list of choices that may grow is a text, never an enum.
/// </remarks>
public sealed record ProjectSettings
{
public const int CurrentVersion = 1;
/// <summary>The highest settings format this Chronos reads; a project of a higher one opens read-only (<see cref="IsNewerFormat"/>).</summary>
public const int CurrentVersion = 2;
/// <summary>The format of a project that uses nothing added since the first one, which most projects are written as.</summary>
public const int BaseVersion = 1;
/// <summary>Layout of a project edited as JSON (<see cref="MoveFramePositions"/>): indented like <see cref="ToJson"/>.</summary>
private static readonly JsonSerializerOptions IndentedJson = new() { WriteIndented = true };
@@ -254,7 +334,8 @@ public sealed record ProjectSettings
/// <summary>Member names as a project edited as JSON reads them (an older or hand-written file may use any casing).</summary>
private static readonly JsonNodeOptions CaseInsensitive = new() { PropertyNameCaseInsensitive = true };
public int Version { get; init; } = CurrentVersion;
/// <summary>The settings format read; <see cref="ToJson"/> writes <see cref="WrittenFormat"/>.</summary>
public int Version { get; init; } = BaseVersion;
public TimingSettings Timing { get; init; } = new();
public ExposureSettings Exposure { get; init; } = new();
public MotionSettings Motion { get; init; } = new();
@@ -274,6 +355,9 @@ public sealed record ProjectSettings
/// </summary>
public IReadOnlyList<PendingFrame>? PendingFrames { get; init; }
/// <summary>The colour look (owner review 1, R6); null for none, which the editor writes whenever the look is the identity.</summary>
public LookSettings? Look { get; init; }
/// <summary>The hero waits for its photo, so advice does not choose one meanwhile.</summary>
[JsonIgnore]
public bool HeroPending => PendingFrames?.Any(p => p.Hero) == true;
@@ -292,7 +376,22 @@ public sealed record ProjectSettings
[JsonIgnore]
public bool IsNewerFormat => Version > CurrentVersion;
public string ToJson() => JsonSerializer.Serialize(this, ProjectJson.Default.ProjectSettings);
/// <summary>
/// The lowest settings format that renders these settings the same: 2 while a turn, mirror, flip or straighten
/// (<see cref="CameraSettings.IsOriented"/>) or a look other than the identity is set, otherwise <see cref="BaseVersion"/>.
/// </summary>
[JsonIgnore]
public int RequiredFormat => Camera.IsOriented || Look is { IsIdentity: false } ? 2 : BaseVersion;
/// <summary>The format <see cref="ToJson"/> writes: <see cref="RequiredFormat"/>, or a newer format read, kept as it is.</summary>
[JsonIgnore]
public int WrittenFormat => IsNewerFormat ? Version : RequiredFormat;
/// <summary>
/// The settings as JSON, stamped with <see cref="WrittenFormat"/>. Every serialisation of a project goes through here,
/// so the version written always matches the members used.
/// </summary>
public string ToJson() => JsonSerializer.Serialize(Version == WrittenFormat ? this : this with { Version = WrittenFormat }, ProjectJson.Default.ProjectSettings);
/// <summary>
/// Reads a project; members missing from <paramref name="json"/> (an API client's partial settings, an older file)