solvastro 0.1.1

A Rust blind plate solver
Documentation
use flate2::read::GzDecoder;
use serde::de::DeserializeOwned;
use std::error::Error;
use std::fs::File;
use std::path::Path;

const PERCENTILES: &[f64] = &[
    0.0, 1.0, 5.0, 10.0, 25.0, 50.0, 75.0, 90.0, 95.0, 99.0, 99.9, 100.0,
];
const BUCKET_COUNTS: &[usize] = &[4, 8, 16, 32];
const HISTOGRAM_BINS: usize = 20;

#[cfg(not(tarpaulin_include))]
fn main() -> Result<(), Box<dyn Error>> {
    let mut areas: Vec<f64> =
        read_from_file("quad-area-proxy.bincode.gz").expect("could not load quad area proxies");
    println!("Loaded {} quad area proxies", areas.len());

    areas.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());

    print_percentiles(&areas);
    print_histogram(&areas);
    print_bucket_suggestions(&areas);

    Ok(())
}

fn read_from_file<T: DeserializeOwned>(filename: &str) -> Result<T, Box<dyn Error>> {
    let file = File::open(Path::new(filename))?;
    let decompressor = GzDecoder::new(file);
    Ok(bincode::deserialize_from(decompressor)?)
}

// area_proxy = 2 - 2*cos(theta), where theta is the great-circle angle
// between a quad's A and B stars. Solve for theta to report a human-readable
// angle alongside the raw proxy value.
fn angle_degrees(area_proxy: f64) -> f64 {
    (1.0 - area_proxy / 2.0).acos().to_degrees()
}

fn percentile(sorted_areas: &[f64], p: f64) -> f64 {
    let rank = (p / 100.0 * (sorted_areas.len() - 1) as f64).round() as usize;
    sorted_areas[rank]
}

fn print_percentiles(sorted_areas: &[f64]) {
    println!("\nPercentiles (area proxy is a monotonic stand-in for subtended area, not true steradians):");
    println!(
        "{:>8}  {:>14}  {:>14}",
        "pctile", "area_proxy", "AB angle (deg)"
    );
    for &p in PERCENTILES {
        let value = percentile(sorted_areas, p);
        println!("{:>8}  {:>14.6}  {:>14.4}", p, value, angle_degrees(value));
    }
}

fn print_histogram(sorted_areas: &[f64]) {
    let min = sorted_areas[0];
    let max = sorted_areas[sorted_areas.len() - 1];
    let range = max - min;

    let mut counts = vec![0usize; HISTOGRAM_BINS];
    for &value in sorted_areas {
        let bin = (((value - min) / range) * HISTOGRAM_BINS as f64) as usize;
        counts[bin.min(HISTOGRAM_BINS - 1)] += 1;
    }

    println!("\nHistogram ({HISTOGRAM_BINS} equal-width bins over the observed area proxy range):");
    println!(
        "{:>14}  {:>14}  {:>10}  {:>7}",
        "bin start", "bin end", "count", "% "
    );
    for (i, &count) in counts.iter().enumerate() {
        let bin_start = min + range * (i as f64 / HISTOGRAM_BINS as f64);
        let bin_end = min + range * ((i + 1) as f64 / HISTOGRAM_BINS as f64);
        let pct = 100.0 * count as f64 / sorted_areas.len() as f64;
        println!(
            "{:>14.6}  {:>14.6}  {:>10}  {:>6.2}%",
            bin_start, bin_end, count, pct
        );
    }
}

// Equal-count bucket boundaries: the same primitive the brightest-star-first
// bucketed star tree uses (bucket_ends_exclusive), applied here to area proxy
// instead of star index order. Each bucket holds the same number of quads;
// the printed angle is the upper edge (smallest area) of that bucket.
fn print_bucket_suggestions(sorted_areas: &[f64]) {
    // sorted_areas is ascending; buckets are numbered largest-area-first to
    // match the proposed descending-area bucketing scheme.
    println!("\nEqual-count bucket boundaries (bucket 0 = largest area, searched first):");
    for &num_buckets in BUCKET_COUNTS {
        println!("\n  {num_buckets} buckets:");
        let bucket_size = sorted_areas.len() / num_buckets;
        for bucket in 0..num_buckets {
            // descending-area bucket `bucket` covers ascending-area rank range
            // [len - (bucket+1)*bucket_size, len - bucket*bucket_size)
            let hi_rank = sorted_areas.len() - bucket * bucket_size - 1;
            let lo_rank = if bucket + 1 == num_buckets {
                0
            } else {
                sorted_areas.len() - (bucket + 1) * bucket_size
            };
            let hi = sorted_areas[hi_rank];
            let lo = sorted_areas[lo_rank];
            println!(
                "    bucket {:>2}: {:>7} quads, area_proxy [{:.6}, {:.6}], AB angle [{:.4}, {:.4}] deg",
                bucket,
                hi_rank - lo_rank + 1,
                lo,
                hi,
                angle_degrees(lo),
                angle_degrees(hi)
            );
        }
    }
}