AstroFrame/src/AstroFrame.Engine/Classification.cs
Elijah c0ef081e4d
All checks were successful
Release AstroFrame / packages (push) Successful in 56s
Release 1.1.7: reject moderate thin cloud and confirmed star elongation
Frames the sky-structure detector already flags become REJECT when
strong cloud texture is backed by two independent moderate dimming
measurements. Elongation confirmed on the same matched reference stars
(lower 3-sigma bound of the change >= 0.10) rejects as a roundness
outlier, following Siril's Seestar -filter-round practice. NGC 1432:
Review 36 -> 1; every Keep unchanged across the validation corpus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 19:48:07 -07:00

140 lines
15 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.

namespace AstroFrame.Engine;
public static class Classification
{
public static void Sessions(List<Frame> frames)
{
foreach(var group in frames.GroupBy(f=>$"{f.Target}|{f.Instrument}|{f.Filter}|{f.Gain}|{f.Exposure}|{f.Width}x{f.Height}|{f.Bayer}"))
{
string label="";DateTime? previous=null;Frame? previousFrame=null;int segment=0;
foreach(var f in group.OrderBy(f=>f.Timestamp).ThenBy(f=>f.Path))
{
if(previous==null||f.Timestamp==null||f.Timestamp-previous>TimeSpan.FromHours(2)||previousFrame!=null&&(Math.Abs(f.Ra-previousFrame.Ra)>.3||Math.Abs(f.Dec-previousFrame.Dec)>.3))label=$"{f.Target} · {f.Timestamp?.ToString("yyyy-MM-dd HH:mm")??"unknown"} · {++segment} · {f.Filter}";
f.Session=label;previous=f.Timestamp;previousFrame=f;
}
}
}
public static void Run(List<Frame> frames,CancellationToken ct=default)
{
Sessions(frames);
foreach(var session in frames.GroupBy(f=>f.Session))
{
var a=session.Where(f=>f.Measured&&f.Error=="").OrderBy(f=>f.Timestamp).ToArray();if(a.Length==0)continue;
// Catalog-only callers cannot claim spatial evidence.
bool spatial=a.Any(f=>f.SkyMap.Length==SkyModel.Count||f.CloudMask.Length==SkyModel.Count);
if(!spatial)
{
var reference=a.OrderBy(f=>Math.Abs(f.StarCount-Robust.Median(a.Select(x=>(double)x.StarCount)))).First();
foreach(var f in a)Matching.Measure(reference,f);
}
var clear=a.Where(f=>spatial?f.AdditionalMeasurements.GetValueOrDefault("Clear reference member")>0&&f.CloudSignificance<5:f.Transparency>=Robust.Quantile(a.Select(x=>x.Transparency),.5)*.8).ToArray();
for(int i=0;i<a.Length;i++)
{
ct.ThrowIfCancellationRequested();var f=a[i];f.Evidence=[];f.Baselines=[];
var local=clear.Where(x=>x.Id!=f.Id).OrderBy(x=>Math.Abs((x.Timestamp.GetValueOrDefault()-f.Timestamp.GetValueOrDefault()).TotalSeconds)).Take(40).ToArray();
bool reliable=a.Length>=20&&local.Length>=12&&f.Timestamp!=null&&(!spatial||f.ReferenceConfidence>.6);
double Metric(string name,Func<Frame,double> get,bool low,double floor)
{
var values=local.Select(get).Where(x=>x>0&&double.IsFinite(x)).ToArray();double normal=Robust.Median(values),value=get(f),spread=Math.Max(Robust.Mad(values),Math.Abs(normal)*floor);
f.Baselines[name]=normal;return normal>0?(low?normal-value:value-normal)/Math.Max(spread,.0001):0;
}
double countZ=Metric("Star count",x=>x.StarCount,true,.10),fluxZ=Metric("Stellar flux",x=>x.Transparency,true,.06),widthZ=Metric("FWHM",x=>x.Fwhm,false,.08),shapeZ=Metric("Ellipticity",x=>x.Ellipticity,false,.15),bgZ=Metric("Background",x=>x.Background,false,.06),noiseZ=Metric("Noise",x=>x.Noise,false,.08);
Metric("Background variation",x=>x.BackgroundVariation,false,.20);
double Ratio(string key,double value)=>value/Math.Max(f.Baselines.GetValueOrDefault(key),.00001);
double Measured(string key)=>f.AdditionalMeasurements.GetValueOrDefault(key);
double countRatio=Ratio("Star count",f.StarCount),fluxRatio=Ratio("Stellar flux",f.Transparency),widthRatio=Ratio("FWHM",f.Fwhm);
double connected=f.AdditionalMeasurements.GetValueOrDefault("Cloud connected coverage");
// A single sky detector must be overwhelming to discard integration on its own.
// Smaller coherent changes remain REVIEW unless stellar measurements corroborate them.
bool strongStructure=spatial&&f.CloudSignificance>=25&&f.CloudCoverage>=.08&&connected>=.035;
bool moderateStructure=spatial&&f.CloudSignificance>=5&&f.CloudCoverage>=.02&&connected>=.01;
bool fluxLoss=fluxZ>=4&&fluxRatio<.78,starLoss=countZ>=3&&countRatio<.75;
bool strongFlux=fluxZ>=5&&fluxRatio<.60&&starLoss;
bool localCloudLoss=spatial&&f.CloudSignificance>=8&&f.CloudCoverage>=.08&&connected>=.035&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud positive coverage")>=.08&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud positive connected coverage")>=.035&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud aperture samples")>=20&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud aperture regions")>=2&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud aperture flux ratio")<.90&&
f.AdditionalMeasurements.GetValueOrDefault("Cloud aperture flux deviation")>=3;
if(localCloudLoss)f.Evidence.Add(new("Cloud aperture flux",f.AdditionalMeasurements["Cloud aperture flux ratio"],1,f.AdditionalMeasurements["Cloud aperture flux deviation"],
$"Coherent excess sky coincides with stellar flux {f.AdditionalMeasurements["Cloud aperture flux ratio"]:P0} of the same-aperture reference ({f.AdditionalMeasurements["Cloud aperture samples"]:0} apertures); uncertainty {f.AdditionalMeasurements.GetValueOrDefault("Cloud aperture flux uncertainty"):P1}"));
bool regionLoss=false;
for(int r=0;r<12;r++)
{
var peers=local.Where(x=>x.RegionMatches[r]>=5&&x.RegionFlux[r]>0).ToArray();if(peers.Length<8||f.RegionMatches[r]<5)continue;
double normal=Robust.Median(peers.Select(x=>x.RegionFlux[r]));f.Baselines[$"Region {r+1}"]=normal;
double z=(normal-f.RegionFlux[r])/Math.Max(Robust.Mad(peers.Select(x=>x.RegionFlux[r])),normal*.10);
if(z>=4&&f.RegionFlux[r]<normal*.65)
{
regionLoss=true;f.Evidence.Add(new($"Region {r+1}",f.RegionFlux[r],normal,z,$"{RegionName(r)}: forced stellar flux {f.RegionFlux[r]/normal:P0} of clear-frame baseline ({f.RegionMatches[r]} reference apertures, including undetected stars)"));
}
}
if(moderateStructure||strongStructure)
{
int[] areas=new int[12];for(int cell=0;cell<f.CloudMask.Length;cell++)if(f.CloudMask[cell]>0)areas[cell/SkyModel.Columns/(SkyModel.Rows/4)*3+cell%SkyModel.Columns/(SkyModel.Columns/3)]++;
int strongest=Array.IndexOf(areas,areas.Max());
f.Evidence.Add(new("Cloud structure",f.CloudCoverage,0,f.CloudSignificance,$"Transient sky structure covers {f.CloudCoverage:P0} of the aligned overlap, strongest in {RegionName(strongest).ToLowerInvariant()}; largest connected area {connected:P0}, residual {f.AdditionalMeasurements.GetValueOrDefault("Sky residual ADU"):0.0} ADU ({f.CloudSignificance:0.0} × reference scatter). Offset and smooth gradient removed; compared with {f.AdditionalMeasurements.GetValueOrDefault("Reference frames"):0} reference exposures."));
}
if(fluxLoss)f.Evidence.Add(new("Stellar flux",f.Transparency,f.Baselines["Stellar flux"],fluxZ,$"Forced stellar flux reduced to {fluxRatio:P0} of nearby clear-frame baseline; lost detections remain in the measurement"));
if(starLoss)f.Evidence.Add(new("Star count",f.StarCount,f.Baselines["Star count"],countZ,$"Detected stars reduced to {countRatio:P0} of clear-frame baseline"));
bool widthBad=widthZ>4&&widthRatio>1.25,shapeBad=shapeZ>4&&f.Ellipticity>f.Baselines["Ellipticity"]+.15;
if(shapeBad&&f.AdditionalMeasurements.GetValueOrDefault("Matched shape samples")>=50&&
f.AdditionalMeasurements.GetValueOrDefault("Matched shape reference frames")>=12&&
f.AdditionalMeasurements.GetValueOrDefault("Matched shape uncertainty")>0&&
f.AdditionalMeasurements["Matched shape uncertainty"]<=.025&&
f.AdditionalMeasurements.GetValueOrDefault("Matched shape change")+3*f.AdditionalMeasurements["Matched shape uncertainty"]<.10)
{
shapeBad=false;
f.Evidence.Add(new("Matched stellar shape",f.AdditionalMeasurements["Matched shape change"],.10,0,"Matched reference stars do not corroborate the detection-cohort elongation flag"));
}
if(widthBad)f.Evidence.Add(new("FWHM",f.Fwhm,f.Baselines["FWHM"],widthZ,$"Stellar width {widthRatio:0.00} × clear-frame baseline"));
if(shapeBad)f.Evidence.Add(new("Ellipticity",f.Ellipticity,f.Baselines["Ellipticity"],shapeZ,$"Substantial stellar elongation ({f.Ellipticity:0.00} vs {f.Baselines["Ellipticity"]:0.00})"));
// Stacking workflows such as Siril's Seestar script discard roundness outliers rather than
// averaging trailed stars into the result. Reject elongation that the same matched reference
// stars confirm well beyond their measurement uncertainty; unconfirmed flags stay REVIEW.
bool confirmedElongation=shapeBad&&Measured("Matched shape samples")>=50&&Measured("Matched shape reference frames")>=12&&
Measured("Matched shape uncertainty")>0&&Measured("Matched shape uncertainty")<=.025&&
Measured("Matched shape change")-3*Measured("Matched shape uncertainty")>=.10;
if(confirmedElongation)f.Evidence.Add(new("Matched stellar shape",Measured("Matched shape change"),0,Measured("Matched shape change")/Measured("Matched shape uncertainty"),
$"The same {Measured("Matched shape samples"):0} reference stars are {Measured("Matched shape change"):0.00} more elongated than in nearby clear frames (±{Measured("Matched shape uncertainty"):0.000}); a roundness outlier that stacking filters discard"));
bool optics=widthBad&&shapeBad&&widthRatio>1.65||confirmedElongation;
bool catastrophic=f.StarCount<3&&f.Baselines["Star count"]>50;
bool cloud=strongStructure||moderateStructure&&(fluxLoss||regionLoss||starLoss)||strongFlux||localCloudLoss;
bool lowMatches=f.MatchFraction<.35;
bool geometryWeak=spatial?f.AdditionalMeasurements.GetValueOrDefault("Alignment verified")<=0:lowMatches;
bool weak=geometryWeak||f.Transparency<=0||f.Fwhm<=0||(spatial&&f.AdditionalMeasurements.GetValueOrDefault("Forced flux samples")<20);
bool skyNoise=bgZ>5&&noiseZ>4&&Ratio("Background",f.Background)>1.4;
if(skyNoise)f.Evidence.Add(new("Sky noise",f.Noise,f.Baselines["Noise"],noiseZ,"Background and sky noise are substantially above the clear-frame baseline"));
bool suspicious=moderateStructure||fluxLoss||regionLoss||widthBad||shapeBad||skyNoise||starLoss||lowMatches;
// Thin cloud adds little residual glow, but it is coherent after smooth curvature is
// removed and dims the stars beneath it relative to clear parts of the same exposure.
// Requiring both keeps sky-only changes, such as gradients, out of this route. It only
// resolves frames other measurements already flag; it never rejects an otherwise clean KEEP.
bool texture=suspicious&&spatial&&Measured("Cloud texture significance")>=10&&Measured("Cloud texture connected coverage")>=.05&&
Measured("Cloud texture differential samples")>=20&&Measured("Cloud texture differential flux ratio")>0;
// Moderate dimming suffices when the plane-detrended structure detector also flags the frame,
// the texture is strong, and the excess-sky apertures independently lose flux against nearby frames.
bool thinCloud=texture&&(Measured("Cloud texture differential flux ratio")<=.98&&Measured("Cloud texture differential flux deviation")>=2.5||
moderateStructure&&Measured("Cloud texture significance")>=20&&
Measured("Cloud texture differential flux ratio")<=.985&&Measured("Cloud texture differential flux deviation")>=1.5&&
Measured("Cloud aperture samples")>=20&&Measured("Cloud aperture regions")>=2&&
Measured("Cloud aperture flux ratio")>0&&Measured("Cloud aperture flux ratio")<=.93&&Measured("Cloud aperture flux deviation")>=2.5);
if(thinCloud)f.Evidence.Add(new("Cloud texture",Measured("Cloud texture differential flux ratio"),1,Measured("Cloud texture differential flux deviation"),
$"Thin cloud texture covers {Measured("Cloud texture coverage"):P0} of the aligned overlap (largest connected area {Measured("Cloud texture connected coverage"):P0}, {Measured("Cloud texture significance"):0.0} × clear-frame scatter); stars beneath it are {1-Measured("Cloud texture differential flux ratio"):P1} fainter relative to clear parts of the same exposure ({Measured("Cloud texture differential flux deviation"):0.0} × nearby clear-frame scatter, {Measured("Cloud texture differential samples"):0} apertures)"));
cloud|=thinCloud;
f.Automatic=reliable&&(catastrophic||!weak&&(cloud||optics))?Verdict.Reject:!reliable||weak||suspicious||f.Warning!=""?Verdict.Review:Verdict.Keep;
f.Cause=!reliable?"Insufficient reliable session reference":catastrophic?"Severe disappearance of reference stars":weak?"Uncertain alignment / reference photometry":cloud?"Likely cloud / transparency loss":optics?"Likely tracking or focus failure":suspicious?"Quality change needs review":"Consistent with the clean session reference";
if(!reliable)f.Evidence.Add(new("Reference",local.Length,12,0,"Automatic rejection disabled: insufficient clear comparison frames, timestamp or aligned overlap"));
if(weak)f.Evidence.Add(new("Matching",f.MatchFraction,.35,0,"Unverified geometric alignment or insufficient reference photometry; inspect manually"));
else if(lowMatches)f.Evidence.Add(new("Alignment",f.AdditionalMeasurements.GetValueOrDefault("Alignment tight matches"),20,0,
$"Star survival is low, but {f.AdditionalMeasurements.GetValueOrDefault("Alignment tight matches"):0} tight matches verify geometry; median residual {f.AdditionalMeasurements.GetValueOrDefault("Alignment median residual pixels"):0.00} source pixels"));
if(f.Warning!="")f.Evidence.Add(new("Metadata",0,0,0,f.Warning));
if(!widthBad)f.Evidence.Add(new("FWHM",f.Fwhm,f.Baselines["FWHM"],0,"Stellar width is within the practical tolerance of nearby clear frames"));
if(f.Evidence.Count==1)f.Evidence.Add(new("Reference",f.Transparency,f.Baselines["Stellar flux"],0,"Aligned sky structure, stellar flux and morphology show no substantial degradation"));
f.Score=Math.Clamp(100-4*Math.Max(0,f.CloudSignificance)-25*Math.Max(0,1-fluxRatio)-10*Math.Max(0,widthRatio-1),0,100);
}
}
foreach(var f in frames.Where(f=>f.Error!="")){f.Automatic=Verdict.Review;f.Cause="Unreadable or unsupported FITS";f.Evidence=[new("Read error",0,0,0,f.Error)];}
}
public static string RegionName(int i)=>new[]{"Upper","Upper-middle","Lower-middle","Lower"}[i/3]+" "+new[]{"left","center","right"}[i%3];
}