# Analysis design and architecture ## Evidence and scope The supplied 1,920 originals cover four targets and five sessions, with 2160×3840 GRBG Bayer data, 30-second exposures and two filter settings. Original FITS files are opened read-only. This application evaluates and exports lights; Siril handles calibration, registration, stacking and post-processing. The first algorithm failed real owner-reviewed examples: cloud structure inflated detected-star counts; flux only sampled surviving detections; rolling baselines absorbed prolonged cloud; a small ellipticity deviation reviewed a clear image. The v2 design replaces the cloud measurements, reference construction and classification policy. Rejection counts are not a target or a validation criterion. Version 1.1.1 refines this policy with geometric fit diagnostics, local cloud-aperture corroboration, and matched-star morphology checks. The original v2 results remain a baseline; see [the 1.1.1 comparison](algorithm-1.1.1-validation.md) for the measurements and limits of the new validation. ## Components - **Engine:** FITS reader, independent `IFrameDetector` measurements, background reference construction, aperture photometry, named decision rules, persistence and export. No GUI, Python runtime, AI or GPU dependency. - **Desktop:** Avalonia/.NET 8 on Windows and Linux; asynchronous orchestration, graph inspection, spatial overlay and manual labels. Windows software rendering and native window decorations. - **Validation:** CLI analysis, real labeled regressions, provisional fixed-time visual samples and synthetic image invariants. Stack quality remains a separate validation task. Additional detectors can add measurements independently. A future AI reviewer can consume previews/measurements and supply evidence without replacing deterministic analysis or human overrides. GPU acceleration remains optional and unimplemented. ## Measurements and reference 1. Read one FITS image at a time. Bayer data use equal-phase 2×2 averages. A 24×40 grid measures a clipped median sky and difference-based noise. The local interpolated sky, rather than a coarse global region, sets detection significance. A local annulus verifies that a peak rises above its own background, rejecting diffuse cloud texture. Core moments estimate FWHM and ellipticity; they are not calibrated Siril PSF fits. 2. Group by target, camera, exposure, filter, gain, dimensions and Bayer pattern; split by timestamps, gaps over two hours and coordinate changes. Each session has its own reference. 3. Select an anchor from low-curvature backgrounds with representative star population and morphology. Bright-star pairs estimate a similarity transform, then hundreds of correspondences refine rotation/translation. Maps and reference aperture coordinates follow that transform. Field edges outside the overlap remain unmeasured. 4. Robustly remove each map's additive offset and planar gradient. Form an aligned median background map, measure transient residuals, and rebuild three times from the least transient 40% of exposures. This fraction constructs a reference; it is **not** a rejection quota. Persistent target nebulosity belongs to the reference. Smooth sky gradients and offsets are removed rather than interpreted as cloud. 5. Read each exposure once more, sequentially, for signed aperture photometry at up to 600 reference coordinates. A local annulus subtracts sky. Reference brightness establishes aperture eligibility; a star need not be detected in the tested exposure. Median fluxes from reference exposures normalize global and 3×4 regional transparency. This addresses survivor bias. Saturated apertures and positions outside the field are excluded explicitly. 6. Compare 960 aligned sky cells with the reference. Cell scatter comes from reference-frame residual MAD with a floor relative to measured image noise. Store a mask above five times that scatter, affected overlap fraction, largest connected component, 95th-percentile significance, residual ADU, aperture counts and reference overlap. These are named evidence, not an opaque combined score. Grid background estimation and local aperture subtraction are standard image-analysis techniques; see [Photutils background documentation](https://photutils.readthedocs.io/en/stable/api/photutils.background.Background2D.html). This implementation is independent C#, using the supplied data to establish its comparison distributions. ## Classification Morphology and flux baselines use the nearest 40 low-transient reference exposures, excluding the tested frame. Cloud-contaminated neighborhoods do not train their own normal baseline. This follows gradual changes where clear comparison frames exist while retaining a wider session reference during cloudy gaps. REJECT evidence routes are explicit: - Strong spatial structure: at least 25× reference scatter at the 95th percentile, at least 8% affected overlap and a connected area of at least 3.5%. A lone sky signal must be overwhelming before discarding integration; weaker coherent structure needs stellar corroboration or routes to REVIEW. - Moderate coherent spatial structure plus substantial global flux loss, regional forced-flux loss or detected-star loss. - Coherent structure at least 8× reference scatter, at least 8% affected overlap, and a connected anomalous area of at least 3.5%, corroborated by positive excess-sky coverage of at least 8% and a positive connected area of at least 3.5%. At least 20 reference apertures in two regions inside that excess sky must show below 90% of nearby same-aperture flux, with at least three times the larger of reference scatter, a 3% floor, and propagated local photometry uncertainty. Affected-aperture comparisons use the nearest 40 reference members, excluding the tested exposure, and require at least 12 valid comparison frames. - Severe global flux loss (below 60% of clear-frame baseline) with substantial detected-star loss. - Severe combined stellar width and ellipticity degradation, or almost complete star disappearance relative to a rich reference field. Automatic rejection requires enough comparable frames, valid time and adequate aligned overlap. Ordinary spatial rejection also requires verified geometry: at least 20 tight correspondences, at least 80% of correspondences within the width-scaled tight tolerance, three regions with at least three tight matches each, and a spread of at least 15% of the image width and height. The median residual must be at most the larger of 0.5 original pixels and 0.2× reference width; the 95th percentile must be at most the larger of one original pixel and 0.5× reference width. Transform scale must remain between 0.975 and 1.025. Missing stars alone no longer veto a cloud rejection when geometry and aperture coverage are verified; low star survival still cannot certify KEEP. Catalog-only classification retains its previous match-fraction safeguard. An existing elongation flag can be dismissed only when at least 50 matched bright reference stars and 12 nearby reference frames provide a precise, small shape change. Its median change plus three estimated standard errors must be below 0.10, and the uncertainty must not exceed 0.025. Missing pairs cannot dismiss a warning. Matched stars use the same reference identities rather than independently selected detection populations. This remains moment-based photometry, not a new PSF-fitting implementation. Ambiguous structure, moderate flux loss, substantial single-metric morphology changes and uncertain measurements route to REVIEW. Minor ellipticity fluctuations and a high global background alone do not trigger review. These significance and effect-size limits are **engineering policy, not calibrated probabilities or guarantees**. Reference scatter, noise, star population, flux, seeing and background are measured separately per session. No fixed acceptable star count or absolute sky brightness is used. The score exists only for sorting. ## Limits that need validation A wholly uniform, cloudy session may lack any internally observable clear reference. Clouds that resemble a smooth gradient and have little detectable attenuation are difficult. Dense nebulosity, alignment failures, crowded fields, large drift/rotation and changing PSFs can bias maps or fixed-aperture flux. The current model removes only a planar sky trend; a legitimate time-varying nonlinear sky pattern can require review. The red overlay identifies anomalous sky structure, not a pixel-accurate physical cloud segmentation. Small sessions and unreliable references cannot automatically reject. Reference stability also checks reference-map residuals against measured pixel noise; a wholly unstable comparison population routes to REVIEW. This does not detect a perfectly uniform, consistently attenuated session. Human overrides remain separate from automatic results. Do not claim the method matches manual Siril selection until independently processed stacks support that claim. ## Memory, caching and safety Version 1.1.0 selects up to 16 workers from CPU capacity, leaving two logical processors unused where possible. A 48-frame measurement run on a 16-logical-processor machine took 2.93 seconds with four workers and 1.32 seconds with fourteen, with identical star counts (peak working sets 251 and 762 MiB). This measures stellar/background processing, not whole-project speedup. No full-resolution image collection or stack is held in RAM. Windows uses a verified process ceiling based on physical RAM minus its reserve, rounded to an allocation boundary. Fixed 6 GiB process, 3 GiB heap and 256 MiB frame caps have been removed. Per-frame estimates include a 64 MiB working margin and are limited to half the machine budget. Both image passes, previews and star detail acquire atomic memory reservations, sampling physical headroom for every frame. The OS/desktop reserve remains one quarter of RAM up to 8 GiB; page-file capacity does not satisfy it. Sustained external pressure stops safely after active frames finish and saves completed measurements. Small JSON metadata stores decisions, notes, evidence and compact masks. Binary versioned caches hold stars, sky maps and forced photometry, validated against source size and modification time and reference identity. A new engine version invalidates analysis without losing human labels. Repeated analysis uses cached measurements and forced apertures when valid. Project writes replace a temporary file atomically. Cancellation leaves analysis incomplete and export disabled. Display caches have a separate version. They contain compressed, linear, area-averaged thumbnails rather than a permanently stretched byte image. **Frame view** retains its noise-aware black point and adjustable median brightness. **Nebula view** applies a 3×3 median and four separable binomial smoothing passes at the existing thumbnail dimensions, suppressing small stars and noise while retaining faint filaments. Its black point also includes the lower background percentile, and its median is displayed slightly brighter. **Asinh view** applies an adjustable inverse-hyperbolic-sine transfer to this same smoothed plane, with a brightness-adjusted gamma fallback when its normalized median already exceeds the requested brightness. **Color nebula** reads recognized RGGB, GRBG, GBRG or BGGR Bayer layouts and their offsets through a separate streaming display reader. It bins linear RGB superpixels, uses the same diffuse luminance preview, neutralizes each channel's median sky, smooths chroma and suppresses departures consistent with noise. A linked channel scale limits saturation and preserves neutral black and white highlights. Color is approximate and uncalibrated; no color is invented for monochrome or unknown Bayer layouts, which show the grayscale nebula preview with an explanatory label. Color has a separate fingerprinted linear cache generated only on demand. Neither display reader changes the monochrome analysis path, classifications, or original FITS files. Prepared display statistics are cached in the viewer so slider changes remain responsive. Disk loading and first-time thumbnail creation run off the UI thread, with cancellation and a single preview-loading gate preventing queued FITS reads during rapid navigation. Both comparison panes use the selected mode and shared zoom/pan. Old projects regenerate only requested displays on demand. Single-frame previews cannot recover signal absent from the exposure and can remain noisy; these are human-readable viewing aids, not stacked images. The preview is not an input to classification. Source-star inspection reads two originals, maps identical stars through their stored alignment, and displays enlarged source superpixels without interpolation. Crops are independently normalized to judge morphology. See [Siril's screen-transfer discussion](https://siril.readthedocs.io/en/latest/processing/stretching.html) for the distinction between display stretching and linear image data. The desktop allows one instance. UI tests run sequentially. The earlier native memory-access crash has not received a confirmed root-cause diagnosis; memory enforcement and later successful runs must not be confused with that diagnosis. Export validates source fingerprints, refuses source/output-tree overlap and nonempty destinations, never overwrites original FITS, and supports hardlinks or bounded byte-for-byte copy fallback. Hardlinks share source bytes; downstream tools must write separate outputs. Export separates different targets and retains an audit manifest with classifications and cloud/flux measurements.