Files
Chronos/docs/DECISIONS.md
T

23 KiB
Raw Blame History

Decisions

One line per decision: date · decision · alternative · reason.

Date Decision Alternative Reason
2026-10-02 The prototype dump docs/reference/titano-prototype.md was not supplied; algorithms are implemented from the brief's descriptions and the cited literature, with the §20.4 thresholds as acceptance tests. Wait for the dump Not available in the repository or uploads; the brief fully specifies behaviour and gates.
2026-10-02 Custom WPF theme dictionaries (Titano.Ui/Themes) implementing DESIGN.md tokens instead of Application.ThemeMode Fluent. Fluent theme + overrides DESIGN.md fixes exact colours/sizes; Fluent is still flagged experimental (WPF0001) and would need restyling of most controls anyway (§2.1 permits in-house dictionaries).
2026-10-02 Added shared WPF library src/Titano.Ui (theme, icons, controls, Loc markup extension) used by App, Uploader and Setup. Duplicate resources per app One visual system for three programs.
2026-10-02 Added tests/Titano.Core.Windows.Tests for WIC / Media Foundation / DXGI tests. Put them in App.Tests Keeps engine interop tests independent of the WPF app.
2026-10-02 Localization areas extended with Common, Jobs, Uploader, Setup. Fold into Shell Smaller, owned files; same key scheme.
2026-10-02 Resources live in i18n/<culture>/<Area>[.<culture>].resx, embedded into Titano.Core (satellite assemblies), base name Titano.Core.i18n.<Area>. Keys marked <comment>invariant</comment> need no translation. Raw XML loader Uses ResourceManager as the brief requires; satellites bundle into single-file publishes.
2026-10-02 Program icons (ICO) are generated at build time into artifacts/icons by Titano.Tools make-icon, invoked from Directory.Build.targets. Commit generated ICO files Brief forbids committing generated binaries and raster sources.
2026-10-02 In-house CRC-32 (Titano.Core.Hashing.Crc32). System.IO.Hashing That assembly is a NuGet package, not part of the shared framework.
2026-10-02 Windows projects target net10.0-windows (platform version 7.0) without a Windows SDK projection TFM; Windows 10 APIs are reached by P/Invoke/COM. net10.0-windows10.0.19041.0 Avoids the CsWinRT projection; toasts use the in-window toast host plus tray balloon.
2026-10-02 Test projects use an explicit TestMain entry point. Top-level statements Avoids the Program type clash with the server's top-level program.
2026-10-02 SQLite P/Invoke binding lives in Titano.Data with a library resolver (winsqlite3 on Windows, system libsqlite3 elsewhere for tests/dev); the Linux server still refuses SQLite at configuration time. Binding in Core.Windows only Lets repository tests run on Linux CI against both dialects.
2026-10-02 Client preferences needed before the database opens (language, theme, window placement) are stored in settings.json next to the database. Settings table only Language and theme must apply before the first window appears.
2026-10-02 Server Windows-service hosting will use an in-house advapi32 P/Invoke host. Microsoft.Extensions.Hosting.WindowsServices That assembly is a NuGet package, not part of the shared framework.
2026-10-02 Admin panel files are embedded resources served by an in-house middleware with ETags and SPA fallback. ManifestEmbeddedFileProvider Its manifest generator ships in a NuGet package.
2026-10-02 Container health check runs Titano.Server --healthcheck (in-process HTTP probe). curl/wget in the image Keeps the runtime image free of extra tools.
2026-10-02 Container drops privileges with setpriv to PUID:PGID; /data is chowned, /archive only checked for write access. Recursive chown of the archive The archive may hold terabytes on NAS shares.
2026-10-02 Release workflow publishes to RELEASES_REPO (default <owner>/titano-releases) when the RELEASES_TOKEN secret exists, otherwise to this repository. Fail without the token First releases work before the public repository is set up.
2026-10-02 Release notes are generated by Titano.Tools changelog from git log piped on stdin. Tool spawning git Keeps the tool free of external process calls.
2026-10-02 CI dotnet format gate checks whitespace formatting. Full style/analyzer verification Analyzer rules already fail the build (warnings as errors); style preferences stay suggestions.
2026-10-02 Test runner exits 0 for a project with no tests and 2 when a filter matches nothing. Always 2 Empty projects during bootstrap are not failures; mistyped filters are.
2026-10-02 COM via [ComImport] + explicit ReleaseComObject; flat APIs via LibraryImport. [GeneratedComInterface] Deterministic release keeps files unlocked; the apps are not trimmed.
2026-10-02 WIC decodes to 64bppRGBA and linearises with the exact sRGB LUT (128bpp float only for float sources). Always 128bppPRGBAFloat WIC's integer→float gamma is not the exact sRGB curve and premultiplication darkens edges.
2026-10-02 Exif orientation is applied in managed code while de-interleaving. IWICBitmapFlipRotator Microsoft documents quadratic behaviour of the flip-rotator over scanline decoders.
2026-10-02 Volume watcher uses a hidden top-level tool window plus 3 s polling. Message-only window Message-only windows do not receive broadcast WM_DEVICECHANGE.
2026-10-02 Camera RAW is "native" via WIC only when the Raw Image Extension package is installed. Decoder CLSID alone The in-box RAW codec shares the CLSID but only reads embedded previews.
2026-10-02 HEVC/AV1 decoder presence is detected with MFTEnumEx. Store package names Also covers OEM and hardware decoders.
2026-10-02 Math code lives in src/Titano.Core/Math with namespace Titano.Core.Mathematics. Titano.Core.Math That namespace would shadow System.Math in every Titano.Core.* file.
2026-10-02 CCT = McCamy refined to the nearest Planckian point (Krystek, CIE 1960 uv), valid for |Duv| ≤ 0.02. Plain McCamy McCamy alone misses the 100 K gate above ~9000 K.
2026-10-02 Deflicker keeps (1 − strength)·ρ·S of a frame's deviation (ρ own Tukey weight, S window surviving fraction). Blend by S only S alone barely isolates outliers.
2026-10-02 LOWESS uses the k nearest valid samples with bandwidth = farthest distance + one spacing. Fixed half-width Constant sample count at sequence edges.
2026-10-02 Clock jump = backward step > 3× median interval or a ±1 h offset from cadence (DST); counts as one interval. Any whole-hour step Scheduled multi-hour pauses look the same.
2026-10-02 Time zone for solar labels: recorded offset → camera−GPS clock (15 min) → longitude/15 with a "time zone estimated" finding. No day phases Usable labels, honestly flagged.
2026-10-02 Holy-grail step is "received" when the detrended median jump ≥ 50 % of the metadata step (same sign); metadata amplitude is redistributed with smoothstep ramps lengthened until ≤ 0.3 EV/frame. Measured amplitude Flicker makes the measured jump noisy.
2026-10-02 Flicker fundamental = first autocorrelation peak within 80 % of the strongest; window ∈ [15, 151], odd. Strongest peak Avoids harmonics at fractional periods.
2026-10-02 Optical flow: dense pyramidal Lucas–Kanade with box filters, neighbour-flow correction, σ = 1 px pre-blur; grid step 4/2/1 px for Draft/Balanced/Best. Farnebäck Separable, SIMD-friendly, stable and as accurate on smooth motion.
2026-10-02 Phase correlation: Gaussian-shaped peak + log-parabola sub-pixel fit, both patches in one complex FFT. Foroosh sinc fit Exact for Gaussian peaks, half the FFT work.
2026-10-02 Stabiliser: noise-corrected texture gate, exhaustive pairwise similarity hypotheses (≤ 36) + weighted LS, path smoothed by Gaussian-weighted local linear regression (σ = 12). RANSAC / plain Gaussian Deterministic with nine patches; keeps intentional pans.
2026-10-02 Interpolation chooses velocities by forward–backward consistency with per-sample flow-agreement weights (τ = 3 px). Super SloMo combination Better at motion boundaries (36.8 vs 33 dB).
2026-10-02 Virtual-camera zoom is interpolated geometrically; trail length L ↦ decay 0.01^(1/L). Linear zoom / half-life Even perceived speed; the trail is gone at its stated length.
2026-10-02 Motion estimation, sharpness and noise use sRGB-encoded luminance. Linear light Shadows keep texture weight; less exposure dependence.
2026-10-02 Archive presets use 0.30 bpp (≈60 Mb/s at 4K24 HEVC 10-bit); share presets use the brief's per-codec defaults (0.10/0.07/0.05). 0.07 bpp everywhere An archive must survive later re-encoding; star fields are the hardest content.
2026-10-02 All metadata fallback chains (time, ISO, serial, lens, rating, size) live in MetadataBuilder.Build; parsers only collect candidates. Fallbacks inside each parser One place for priority rules; parsers are order-independent.
2026-10-02 MetadataReader.Read(path) throws when the file cannot be opened; malformed content becomes warnings (with a parser-fault safety net the fuzz tests require to stay unused). Swallow everything An unopenable file is not malformed input.
2026-10-02 HEIF irot/imir override Exif orientation (imir axis 0 = top↔bottom). Exif first HEIF decoders apply the transforms themselves; both would rotate twice.
2026-10-02 Main image size comes from the container's own size field (SOF, IHDR, ispe, VP8X, RAF crop record, RW2 borders, CR3 CMP1) before raster IFDs. Always the largest raster IFD That is what each container defines and what decoders output.
2026-10-02 Only MPF large-thumbnail entries count as previews; XMP date-only values are never used as capture times. Every secondary image / midnight Gain maps are not previews; midnight would be invented.
2026-10-02 Media Foundation interop uses [GeneratedComInterface] with explicit release; threads entering MF call Win32Com.EnsureInitialized() (MTA unless already STA). [ComImport] like WIC Hardware encoders stall when sample references wait for GC; source-generated COM does not initialise apartments, so it is done explicitly.
2026-10-02 MP4: 16-byte free+mdat placeholder rewritten to a 64-bit header past 4 GiB; negative composition offsets shifted to ctts v0 plus an edit list; parameter sets moved into avcC/hvcC; fast start on by default. Always 64-bit mdat / ctts v1 Small files stay maximally compatible; wider player support.
2026-10-02 GIF: Wu-criterion median cut, frame differencing against the source last drawn, identical frames merged by holding one back. Plain median cut / diff against dithered output Max palette error 37 → small; 945 KB → 52 KB at equal PSNR; exact delays.
2026-10-02 AVI always carries OpenDML indexes plus idx1 (1 GiB RIFF segments). idx1 only Files beyond 2 GB stay playable.
2026-10-02 MF encoder capabilities: software H.264 ≤ 4096×2304, hardware assumed 4096² (H.264) / 8192² (HEVC/AV1); an unsupported size fails at media-type negotiation and the next encoder is tried. Querying limits MF has no reliable capability query.
2026-10-02 Full-size JPEG IDCT is a port of libjpeg's accurate integer IDCT (bit-identical to djpeg); reduced-size (1/2–1/8) decoding uses float IDCTs with triangle chroma upsampling. SIMD float IDCT everywhere Float produced rare ±3 differences after YCbCr; reduced sizes gain 6.7 dB with triangle upsampling.
2026-10-02 Codecs throw only InvalidDataException for bad structure or unsupported features; damaged scan data yields a partial image plus warnings. NotSupportedException for features One exception type for callers and fuzzing.
2026-10-02 Linear DNG export: raw image in IFD0, lossless-JPEG tiles, ColorMatrix1 + ForwardMatrix1 for Rec.709 D65; source camera Make/Model kept when Exif is supplied. Preview IFD + SubIFD raw Simplest valid DNG; LibRaw renders test patches back exactly.
2026-10-02 Resampler keeps negative/overshoot values in linear light. Clamp to 0–1 Ringing stays within each kernel's exact bound; clamping happens at encode.
2026-10-02 Codec fixtures (each < 12 KB) are generated by tests/fixtures/codecs/make-fixtures.sh with libjpeg-turbo/libtiff dev tools and committed. Fetch at test time Reference outputs must be stable; the tools are not build or runtime dependencies.
2026-10-02 Installer payload "TPK1": deduplicated, deflate-ratio-bounded entries after the setup stub; footer aligned to 8 bytes and found before an Authenticode table so signing works before and after packing. Spec fields only Every offset is bounds-checked; signtool can append without breaking the payload.
2026-10-02 Setup runs asInvoker and relaunches itself elevated (runas) only for all-users installs; the unelevated parent starts Titano afterwards. requireAdministrator Titano never runs elevated.
2026-10-02 Uninstaller self-removal via a %TEMP% copy started with /CLEANUP; running programs are only asked to close (never killed; silent mode exits 5). MoveFileEx alone / kill Per-user installs have no admin rights; user data safety.
2026-10-02 Setup has its own Program.Main (silent and cleanup modes run without WPF) and is published with single-file compression (70 MB stub). App.xaml-generated Main Reliable exit codes; smaller installers.
2026-10-02 SQLite: one in-process async write lock with BEGIN IMMEDIATE, shared-cache in-memory mode for tests, fixed-width ISO-8601 UTC text with microseconds and lower-case UUID text. busy_timeout alone / epochs Writers queue instead of failing; text order equals time order on both dialects.
2026-10-02 PostgreSQL: parameters typed by OID, results in text decoded by OID, named prepared statements (128 LRU), session settings pinned in the startup packet, cancel = CancelRequest then socket abort after 5 s, transient retry once for idempotent reads only. Untyped params / tracking ParameterStatus Predictable decoding, no "could not determine data type", a dead server never hangs a caller, writes never repeat.
2026-10-02 Migrations: all pending ones in one transaction under pg_advisory_xact_lock. One transaction per migration Atomic and safe when several servers start together.
2026-10-02 Case-insensitive search/sort via lower-cased search_text/title_key columns (and COLLATE "C" on PG). ILIKE / NOCASE Identical results on both dialects.
2026-10-02 Job claim: UPDATE … WHERE id = (SELECT … FOR UPDATE SKIP LOCKED) RETURNING on PG; immediate transaction on SQLite. Advisory locks Exclusive under concurrency, as specified.
2026-10-02 One JobEngine in Titano.Data runs every long operation for both the client and the server: handlers per JobKind, progress persisted at most every 5 s, a failed persist (job no longer running) stops the handler, a shutdown leaves jobs running so the next start requeues them from their checkpoint. Per-feature background loops One queue, one cancel/pause/resume path and one crash-recovery rule everywhere.
2026-10-02 Job throughput is a moving average over windows of at least 2 s. Average since start ETA follows speed changes (cache warm-up, network) without jitter.
2026-10-02 Visual controls (card grid, filmstrip, charts, preview, curve editor) keep their layout and math in WPF-free classes; colours are theme brush keys re-resolved on theme switch; charts, filmstrip and preview never mirror in RTL. Math inside controls / brush properties Testable on Linux; view models hold no brushes; time axes and images must not flip.
2026-10-02 VirtualizingWrapPanel does its own keyboard navigation and recycling; the focused container is kept alive. ListBox navigation Direct targets, wrapping across rows; focus survives scrolling.
2026-10-02 Library card slot 236 × 208 with a 16:9 thumbnail. Mockup's 150 px thumbnail DESIGN §4 specifies 16:9.
2026-10-02 Uploader sessions: key = 8 hex chars of the source folder's SHA-256 + first-frame time; leading test shots (first group < 8 frames) join the next session; watch-folder files always use automatic sessions. Group by time only Simultaneous cameras stay apart; unattended files never land in a sequence chosen for a manual drop.
2026-10-02 Uploader: a watch file counts as processed only after the server confirms it; offline, rejected-token and changed-certificate failures do not use up the three retries; a changed certificate signs the user out. Mark at enqueue / count every failure Clearing the queue loses nothing; an outage does not exhaust a large batch; never upload to an unverified server.
2026-10-02 Delete-after-upload also requires size and write time unchanged since hashing. Server confirmation alone BRIEF rule 8.
2026-10-02 Uploader settings are an in-window panel; single instance via a per-session mutex and a current-user named pipe; native tray menu (TrackPopupMenuEx). Dialog / WM_COPYDATA / WPF ContextMenu §12.1 allows modals only for login and destructive confirmations; works while hidden in the tray; dismisses reliably.
2026-10-02 Network watch folders are polled (default 5 min); local folders every 60 s plus FileSystemWatcher hints. Watcher everywhere SMB change notifications are unreliable.
2026-10-02 The Dockerfile uses BuildKit's built-in frontend (no # syntax=docker/dockerfile:1). Pinned external frontend Every feature used is built in; the build no longer depends on Docker Hub (a 502 there failed CI). Base images come from mcr.microsoft.com.
2026-10-02 SQLite sessions run every blocking call on the thread pool (ThreadPoolHop) and cancel through a per-connection flag polled by sqlite3_progress_handler (every 1000 VM instructions) in addition to sqlite3_interrupt. Callers offload themselves / interrupt only A repository awaited on the UI thread never freezes it; an interrupt that lands before sqlite3_step starts was silently lost and the query ran to the end.
2026-10-02 Deep analysis persists per-frame shifts from the nine-patch Stabilizer and smooths the path itself; per-frame data is stored as columns (~80–110 bytes/frame) with a JSON-lines checkpoint that drops a torn last line. Stabilizer.Solve / row objects Solve cannot resume from a checkpoint; the report stays small for 100k-frame sequences.
2026-10-02 Sky/land mask from a pre-pass over 15 sampled frames before the main pass. Segment after the pass Cloud coverage and per-region luminance need the mask during the pass.
2026-10-02 Scene distance: chi-square on histograms smoothed by ⅛ EV and levelled to the same mean; flow statistics use brightness-levelled images and forward–backward-consistent vectors only; noise is median-based (Immerkær). Raw chi-square / raw flow / mean noise Flicker and exposure steps no longer read as scene changes or motion; stars no longer inflate noise.
2026-10-02 Shake and motion thresholds are judged in output pixels (stabilise above 0.3 px RMS). Source pixels That is what the viewer sees.
2026-10-02 Automatic output stops at 4K UHD; no automatic stacking advice. 8K / temporal-median denoise 8K stays a manual choice; a median erases moving stars and stillness cannot be verified reliably.
2026-10-02 Apply records a missing-data reason only where no advice exists; Optimise returns modules to Auto and only adds to the user's hero, exclusions, offset or output cap; a preset's own choices are stored as manual values, content-derived values stay Auto. Overwrite Manual values stay in force; re-analysis does not undo a chosen preset.
2026-10-02 Advisor namespace is Titano.Core.Advice (class Advisor). Titano.Core.Advisor A class named like its namespace needed an alias in every Titano.Core.* caller.
2026-10-02 CI also force-pushes each same-repository PR run's screenshots as one commit to the ci-screenshots branch (separate job, only it has contents: write). Artifact only Artifacts need an authenticated download; a branch can be fetched with plain git for visual review. The branch never merges and holds a single commit.
2026-10-02 Export fps is the encoded grid; Timing.FrameRate is the playback rate (source frames per video second, default = export fps). Durations are quantised to output periods on rounded 90 kHz boundaries; whole frames are sampled at the period centre. One fps / free durations Presets keep their meaning, Interpolated can synthesise slow motion, AVI and image sequences stay exact.
2026-10-02 Adaptive timing is proportional up to 3× the median interval; longer gaps show for 3 + log2(r/3) frames (max 5); pauses ≥ 20× median and ≥ 120 s become a 0.2 s cut. Interpolated fills gaps of up to 3 missing/excluded frames. Fixed clamps Bursts stay faithful and long gaps cannot stall the video.
2026-10-02 A non-monotonic time-remap curve is repaired (sorted, clamped, made non-decreasing) with a warning; virtual-camera keyframes are keyed to source frame positions. Reject the curve / output frame index The remap is always monotone; keyframes stay on the content when timing or fps change.
2026-10-02 Per frame: exposure → one warp (stabilisation⁻¹ ∘ camera ∘ crop) to output size → flow, synthesis and blur in output space → stacking → knee. Stabilisation zooms by 1/max(crop scale, 0.75), warning below 0.75. Modules run only when Auto resolves true. Flow in source space / no zoom A single resample; flow sees stabilised content; borders stay hidden.
2026-10-02 Blur fraction = BlurFraction(target × speed, real) / steps, speed clamped to 4, no blur across cuts. Fixed fraction The look survives speed changes.
2026-10-02 Encoding overlaps processing by one frame; image sequences encode up to one frame per core into a hidden .tmp folder renamed at the end, named <name>/<name>_000001.ext. Strictly sequential / frame_%05d 1080p PNG 1.0 → 2.5 fps; crash-safe and editor-friendly.
2026-10-02 JPEG/MJPEG use 4:4:4 at quality ≥ 90, else 4:2:0; HEVC/AV1 → H.264 fallback rescales the bit rate by bits-per-pixel; size capped to the highest level, then the encoder maximum; managed bit depth moves to the shallowest supported depth ≥ the request; linear DNG tiles are sized to the frame (≤ 256 px). — Predictable quality and sizes; small DNGs are ~3× smaller.
2026-10-02 Auto<T> carries HasAdvice; Resolve falls back only when there is no advice. Treat default as "no advice" A value type's advised 0/false was indistinguishable from "no advice".
2026-10-02 i18n check also treats any C# string literal shaped Area.Group.Name with an existing area as a used key. Marker functions such as LocKey(…) Reason and warning keys travel as data; 53 render/export keys had no resources and the check did not notice.