AstroFrame/src/AstroFrame.Engine/Classification.cs
Elijah 65ded0b606
All checks were successful
Release AstroFrame / packages (push) Successful in 1m8s
Release 1.1.1: corroborate cloudy frames with local stellar attenuation
2026-10-04 10:45:10 -07:00

115 lines
12 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 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})"));
bool optics=widthBad&&shapeBad&&widthRatio>1.65;
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;
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];
}