astro-metrics

Statistical metrics and analysis for astronomical images.

Overview

astro-metrics provides functionality for analyzing astronomical images, including star detection, measurement, and quality assessment. It uses the Source Extractor as a Library (SEP) for efficient star detection and implements various metrics for evaluating image quality.

Features

• Star detection using Source Extractor (SEP)
• Star measurements (FWHM, eccentricity, elongation, etc.)
• Background analysis (median, RMS, uniformity)
• Quality scoring for image comparison
• Comprehensive metrics for astronomical image evaluation

Installation

Add to your Cargo.toml:

[dependencies]
astro-metrics = "0.4.0"

API Reference

Core Types

StarMetrics

pub struct StarMetrics {
    pub x: f64,                // X centroid position
    pub y: f64,                // Y centroid position
    pub flux: f32,             // Total flux
    pub peak: f32,             // Peak pixel value
    pub a: f32,                // Semi-major axis
    pub b: f32,                // Semi-minor axis
    pub theta: f32,            // Position angle in radians
    pub eccentricity: f32,     // Eccentricity (derived from a and b)
    pub fwhm: f32,             // Full Width at Half Maximum (derived from a and b)
    pub kron_radius: f32,      // Kron radius (radius containing 50% of flux)
    pub flux_auto: f32,        // Total flux in automatic aperture
    pub fluxerr_auto: f32,     // Error on flux_auto
    pub npix: usize,           // Number of pixels in the object
    pub elongation: f32,       // Elongation (a/b, alternative to eccentricity)
    pub flag: u8,              // Extraction flag
}

Key methods:

impl StarMetrics {
    /// Calculate FWHM as average of semi-major and semi-minor axes
    pub fn calc_fwhm(&mut self)
    
    /// Calculate eccentricity from semi-major and semi-minor axes
    pub fn calc_eccentricity(&mut self)
}

StarStats

pub struct StarStats {
    pub count: usize,                  // Total number of stars detected
    pub median_fwhm: f32,              // Median FWHM across all stars
    pub median_eccentricity: f32,      // Median eccentricity across all stars
    pub fwhm_std_dev: f32,             // Standard deviation of FWHM
    pub eccentricity_std_dev: f32,     // Standard deviation of eccentricity
    pub median_kron_radius: f32,       // Median Kron radius
    pub median_flux: f32,              // Median flux
    pub median_snr: f32,               // Median signal-to-noise ratio
    pub median_elongation: f32,        // Median elongation
    pub flagged_fraction: f32,         // Fraction of stars with flag != 0
    pub kron_radius_std_dev: f32,      // Standard deviation of Kron radius
    pub flux_std_dev: f32,             // Standard deviation of flux
    pub snr_std_dev: f32,              // Standard deviation of SNR
}

Key methods:

impl StarStats {
    /// Calculate aggregate statistics from a collection of star metrics
    pub fn from_stars(stars: &[StarMetrics], max_stars: Option<usize>) -> Self
}

BackgroundMetrics

pub struct BackgroundMetrics {
    pub median: f32,       // Median background level
    pub rms: f32,          // Root mean square of background
    pub min: f32,          // Minimum background value
    pub max: f32,          // Maximum background value
    pub uniformity: f32,   // Background uniformity (0-1, higher is better)
}

QualityScores

pub struct QualityScores {
    pub fwhm: f32,             // FWHM score (higher means better focus/seeing)
    pub eccentricity: f32,     // Eccentricity score (higher means rounder stars)
    pub background: f32,       // Background score (higher means better background)
    pub kron_radius: f32,      // Kron radius score (higher means tighter stars)
    pub snr: f32,              // SNR score (higher means better signal-to-noise ratio)
    pub flag: f32,             // Flag score (higher means fewer flagged stars)
    pub overall: f32,          // Overall quality score (weighted average of scores)
}

QualityWeights

pub struct QualityWeights {
    pub fwhm: f32,             // Weight for FWHM score (default: 0.3)
    pub eccentricity: f32,     // Weight for eccentricity score (default: 0.2)
    pub background: f32,       // Weight for background score (default: 0.2)
    pub kron_radius: f32,      // Weight for Kron radius score (default: 0.15)
    pub snr: f32,              // Weight for SNR score (default: 0.1)
    pub flag: f32,             // Weight for flag score (default: 0.05)
}

FrameQualityMetrics

pub struct FrameQualityMetrics {
    pub frame_id: String,          // Identifier for the frame
    pub star_stats: StarStats,     // Star statistics
    pub background: BackgroundMetrics, // Background metrics
    pub scores: QualityScores,     // Quality scores
}

SEP Detection

/// Detect stars using SEP's built-in background estimation and object detection
pub fn detect_stars_with_sep_background(
    data: &[f32],
    width: usize,
    height: usize,
    max_stars: Option<usize>,
) -> Result<(StarStats, BackgroundMetrics)>

/// Detect stars using the SEP library and return detailed measurements for each star
pub fn detect_stars_sep(
    data: &[f32],
    width: usize,
    height: usize,
    background: f32,
    std_dev: f32,
    max_stars: Option<usize>,
) -> Result<StarStats>

• Parameters:
  • data: Flattened pixel data as 32-bit floats
  • width: Width of the image in pixels
  • height: Height of the image in pixels
  • max_stars: Optional maximum number of stars to use for statistics
  • background: Background level (for detect_stars_sep)
  • std_dev: Background standard deviation (for detect_stars_sep)
• Returns:
  • StarStats: Statistics about detected stars
  • BackgroundMetrics: Background metrics
• Errors:
  • If the image is too small
  • If SEP encounters an error during detection

Quality Metrics

/// Calculate quality scores for a frame
pub fn calculate_quality_scores(
    star_stats: &StarStats,
    background: &BackgroundMetrics,
) -> QualityScores

/// Calculate overall quality score from individual scores and weights
pub fn calculate_overall_score(
    fwhm_score: f32,
    eccentricity_score: f32,
    background_score: f32,
    kron_score: f32,
    snr_score: f32,
    flag_score: f32,
    weights: &QualityWeights,
) -> f32

/// Create frame quality metrics for an image
pub fn create_frame_metrics(
    path: &Path,
    star_stats: StarStats,
    background: BackgroundMetrics,
) -> FrameQualityMetrics

/// Create frame quality metrics with custom weights
pub fn create_frame_metrics_with_weights(
    path: &Path,
    star_stats: StarStats,
    background: BackgroundMetrics,
    weights: QualityWeights,
) -> FrameQualityMetrics

Usage Examples

Detecting stars and calculating quality metrics

use astro_metrics::sep_detect;
use astro_metrics::quality_metrics;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Assume we have image data loaded from somewhere
    let image_data: Vec<f32> = vec![/* ... */];
    let width = 1024;
    let height = 768;
    
    // Detect stars and analyze background
    let (star_stats, background) = sep_detect::detect_stars_with_sep_background(
        &image_data, width, height, None)?;
    
    println!("Found {} stars", star_stats.count);
    println!("Median FWHM: {:.2} pixels", star_stats.median_fwhm);
    println!("Background uniformity: {:.3}", background.uniformity);
    
    // Calculate quality scores
    let scores = quality_metrics::calculate_quality_scores(&star_stats, &background);
    
    println!("FWHM score: {:.3}", scores.fwhm);
    println!("Eccentricity score: {:.3}", scores.eccentricity);
    println!("Background score: {:.3}", scores.background);
    println!("Overall quality score: {:.3}", scores.overall);
    
    // Create frame metrics
    let path = Path::new("/path/to/image.fits");
    let frame_metrics = quality_metrics::create_frame_metrics(
        path, star_stats, background);
    
    println!("Frame ID: {}", frame_metrics.frame_id);
    
    Ok(())
}

Using custom weights for quality scoring

use astro_metrics::quality_metrics::{self, QualityWeights};
use astro_metrics::sep_detect;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Assume we have image data loaded from somewhere
    let image_data: Vec<f32> = vec![/* ... */];
    let width = 1024;
    let height = 768;
    
    // Detect stars and analyze background
    let (star_stats, background) = sep_detect::detect_stars_with_sep_background(
        &image_data, width, height, None)?;
    
    // Create custom weights
    let weights = QualityWeights {
        fwhm: 0.5,             // Prioritize focus quality
        eccentricity: 0.2,
        background: 0.1,
        kron_radius: 0.1,
        snr: 0.05,
        flag: 0.05,
    };
    
    // Create frame metrics with custom weights
    let path = Path::new("/path/to/image.fits");
    let frame_metrics = quality_metrics::create_frame_metrics_with_weights(
        path, star_stats, background, weights);
    
    println!("Overall quality score: {:.3}", frame_metrics.scores.overall);
    
    Ok(())
}

Additional Documentation

For more detailed information about the quality metrics and how they're calculated, see the Quality Metrics Documentation.

License

This project is dual-licensed under the MIT License or the Apache License, Version 2.0.