solvastro 0.1.1

A Rust blind plate solver
Documentation
use cdshealpix::nested::{center, cone_coverage_approx_flat, hash, n_hash};
use flate2::read::GzDecoder;
use image::{Rgb, RgbImage};
use rayon::prelude::*;
use serde::de::DeserializeOwned;
use solvastro::coords::{get_midpoint, CoordUnitSphere};
use solvastro::structs_f64::quad::Quad;
use std::error::Error;
use std::f64::consts::{PI, SQRT_2};
use std::fs::File;
use std::path::{Path, PathBuf};
use std::time::Instant;
use structopt::StructOpt;

pub mod csv_record;
pub mod csv_record_hygv3;
pub mod util;
use util::parse_csv_file;

const TWO_PI: f64 = PI + PI;

#[derive(Debug, StructOpt)]
struct CliArgs {
    // AB angular separation range, in degrees, of quads to include. Defaults
    // span the full catalog build range (see INITIAL_MAX_AB_DEGREES /
    // TERMINAL_MIN_AB_DEGREES in src/k5/star_index.rs).
    #[structopt(long, default_value = "0.0")]
    min_angle_deg: f64,

    #[structopt(long, default_value = "45.0")]
    max_angle_deg: f64,

    #[structopt(long, parse(from_os_str), default_value = "sky-heatmap.png")]
    output: PathBuf,

    #[structopt(long, default_value = "2000")]
    img_width: u32,

    #[structopt(long, default_value = "1000")]
    img_height: u32,

    // HEALPix depth for the accumulator. Depth 7 (nside=128) gives ~196.6k
    // cells of ~0.21 sq deg each, all identical in area -- unlike an
    // equirectangular RA/Dec grid, whose cells shrink to nothing at the
    // poles and would need a per-row solid-angle correction (and still blow
    // up numerically right at the pole).
    #[structopt(long, default_value = "7")]
    depth: u8,
}

// Squared chord distance proxy, as persisted by quad-area-analysis:
// 2 - 2*cos(theta). Monotonic in theta, so this maps an angle bound directly
// to a proxy bound without needing to touch the persisted values themselves.
fn angle_deg_to_area_proxy(angle_deg: f64) -> f64 {
    let theta = angle_deg.to_radians();
    2.0 - 2.0 * theta.cos()
}

#[cfg(not(tarpaulin_include))]
fn main() -> Result<(), Box<dyn Error>> {
    let cli_args = CliArgs::from_args();
    println!("cli_args: {:?}", &cli_args);

    let start = Instant::now();
    let depth = cli_args.depth;

    let quads: Vec<Quad> =
        read_from_file("hyg-cg-v2-quad-list.bincode.gz").expect("could not load quads");
    let proxies: Vec<f64> =
        read_from_file("quad-area-proxy.bincode.gz").expect("could not load quad area proxies");
    assert_eq!(
        quads.len(),
        proxies.len(),
        "quad list and area proxy list must be index-aligned"
    );
    println!(
        "Loaded {} quads + area proxies ({:?} elapsed)",
        quads.len(),
        start.elapsed()
    );

    let csv_file = File::open("hygdata_v3.csv")?;
    let stars = parse_csv_file(csv_file);
    println!(
        "Loaded {} stars ({:?} elapsed)",
        stars.len(),
        start.elapsed()
    );

    let proxy_lo = angle_deg_to_area_proxy(cli_args.min_angle_deg);
    let proxy_hi = angle_deg_to_area_proxy(cli_args.max_angle_deg);

    let matched_count = proxies
        .par_iter()
        .filter(|&&proxy| proxy >= proxy_lo && proxy <= proxy_hi)
        .count();
    println!(
        "{} quads in AB angle range [{}, {}] deg ({:?} elapsed)",
        matched_count,
        cli_args.min_angle_deg,
        cli_args.max_angle_deg,
        start.elapsed()
    );

    let total_cells = n_hash(depth) as usize;

    let counts: Vec<f64> = quads
        .par_iter()
        .zip(proxies.par_iter())
        .filter(|(_, &proxy)| proxy >= proxy_lo && proxy <= proxy_hi)
        .fold(
            || vec![0f64; total_cells],
            |mut acc, (quad, _)| {
                let star_a = &stars[quad.a];
                let star_b = &stars[quad.b];
                let center = get_midpoint(&star_a.spherical(), &star_b.spherical());
                let radius = star_a.dist_to(star_b) / 2.0;
                accumulate_quad(&mut acc, depth, &center, radius);
                acc
            },
        )
        .reduce(
            || vec![0f64; total_cells],
            |mut a, b| {
                for (x, y) in a.iter_mut().zip(b.iter()) {
                    *x += y;
                }
                a
            },
        );
    println!(
        "Built HEALPix depth-{} accumulator ({} cells, {:?} elapsed)",
        depth,
        total_cells,
        start.elapsed()
    );

    // Every cell has identical solid angle at a fixed HEALPix depth, so
    // raw counts are already proportional to density -- this is just a
    // constant rescale to quads/steradian for human-readable diagnostics.
    let cell_area_sr = 4.0 * PI / total_cells as f64;
    let density: Vec<f64> = counts.iter().map(|&c| c / cell_area_sr).collect();

    print_density_diagnostics(&density, depth);

    let img = render_mollweide(&density, depth, cli_args.img_width, cli_args.img_height);
    img.save(&cli_args.output)?;
    println!(
        "Wrote {:?} ({:?} elapsed)",
        &cli_args.output,
        start.elapsed()
    );

    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)?)
}

fn print_density_diagnostics(density: &[f64], depth: u8) {
    let mut sorted = density.to_vec();
    sorted.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
    let p = |pct: f64| sorted[((pct / 100.0) * (sorted.len() - 1) as f64) as usize];
    println!(
        "density (quads/sr) percentiles: min={:.3} p10={:.3} p50={:.3} p90={:.3} p99={:.3} max={:.3}",
        sorted[0],
        p(10.0),
        p(50.0),
        p(90.0),
        p(99.0),
        sorted[sorted.len() - 1]
    );

    let (max_idx, _) = density
        .iter()
        .enumerate()
        .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
        .unwrap();
    let (lon, lat) = center(depth, max_idx as u64);
    println!(
        "max density cell: hash={} (ra={:.2}deg, dec={:.2}deg)",
        max_idx,
        lon.to_degrees(),
        lat.to_degrees()
    );
}

// Marks every HEALPix cell overlapping the spherical cap of the given
// radius centered on `center`. cone_coverage_approx_flat is an
// approximation (it can include cells only partially overlapping the cap),
// which is fine here -- this is a density visualization, not an exact
// membership test.
fn accumulate_quad(counts: &mut [f64], depth: u8, center: &CoordUnitSphere, radius: f64) {
    let dec = center.z.asin();
    let mut ra = center.y.atan2(center.x);
    if ra < 0.0 {
        ra += TWO_PI;
    }

    for cell in cone_coverage_approx_flat(depth, ra, dec, radius).iter() {
        counts[*cell as usize] += 1.0;
    }
}

fn colormap(t: f64) -> Rgb<u8> {
    const STOPS: [(f64, (u8, u8, u8)); 3] = [
        (0.0, (10, 10, 60)),
        (0.5, (255, 220, 0)),
        (1.0, (200, 0, 0)),
    ];

    let t = t.clamp(0.0, 1.0);
    let (lo, hi) = if t < STOPS[1].0 {
        (STOPS[0], STOPS[1])
    } else {
        (STOPS[1], STOPS[2])
    };

    let span = hi.0 - lo.0;
    let frac = if span > 0.0 { (t - lo.0) / span } else { 0.0 };

    let lerp = |a: u8, b: u8| -> u8 { (a as f64 + (b as f64 - a as f64) * frac).round() as u8 };

    Rgb([
        lerp(lo.1 .0, hi.1 .0),
        lerp(lo.1 .1, hi.1 .1),
        lerp(lo.1 .2, hi.1 .2),
    ])
}

// Renders an equal-area Mollweide projection by walking output pixels and
// inverting the closed-form Mollweide (x, y) -> (ra, dec) mapping, then
// sampling the density grid via a HEALPix cell lookup. Equal-area matters
// here specifically because the point of this map is to visually judge
// coverage patchiness -- an equirectangular *display* would exaggerate
// polar density regardless of how the underlying density was computed.
//
// The color scale clips at the 99.5th percentile of nonzero density rather
// than the true max: a handful of outlier cells (e.g. near very bright,
// closely-packed stars) would otherwise wash out contrast everywhere else.
fn render_mollweide(density: &[f64], depth: u8, img_w: u32, img_h: u32) -> RgbImage {
    const OUTSIDE: Rgb<u8> = Rgb([0, 0, 0]);

    let mut nonzero: Vec<f64> = density.iter().copied().filter(|&d| d > 0.0).collect();
    nonzero.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
    let lo_clip = if nonzero.is_empty() {
        0.0
    } else {
        nonzero[((0.005 * (nonzero.len() - 1) as f64) as usize).min(nonzero.len() - 1)]
    };
    let hi_clip = if nonzero.is_empty() {
        1.0
    } else {
        nonzero[((0.995 * (nonzero.len() - 1) as f64) as usize).min(nonzero.len() - 1)]
    };
    // Normalize log density between the observed low/high clip, not from
    // log(0): every cell already has a huge baseline count, so scaling
    // from zero would waste almost the whole gradient below the real
    // range and squeeze all the meaningful variation into a thin band
    // near the top.
    let min_log = lo_clip.ln_1p();
    let max_log = hi_clip.ln_1p().max(min_log + 1e-12);

    let mut img = RgbImage::new(img_w, img_h);

    for py in 0..img_h {
        for px in 0..img_w {
            let x = (px as f64 / img_w as f64 - 0.5) * 4.0 * SQRT_2;
            let y = (0.5 - py as f64 / img_h as f64) * 2.0 * SQRT_2;

            let ellipse = (x / (2.0 * SQRT_2)).powi(2) + (y / SQRT_2).powi(2);
            if ellipse > 1.0 {
                img.put_pixel(px, py, OUTSIDE);
                continue;
            }

            let theta = (y / SQRT_2).clamp(-1.0, 1.0).asin();
            let cos_theta = theta.cos();
            let phi = ((2.0 * theta + (2.0 * theta).sin()) / PI)
                .clamp(-1.0, 1.0)
                .asin();
            let lambda = if cos_theta.abs() < 1e-9 {
                0.0
            } else {
                PI * x / (2.0 * SQRT_2 * cos_theta)
            };

            let dec = phi;
            let ra = (lambda + PI).rem_euclid(TWO_PI);

            let cell = density[hash(depth, ra, dec) as usize];
            let t = ((cell.ln_1p() - min_log) / (max_log - min_log)).clamp(0.0, 1.0);
            img.put_pixel(px, py, colormap(t));
        }
    }

    img
}