brahe 1.4.0

Brahe is a modern satellite dynamics library for research and engineering applications designed to be easy-to-learn, high-performance, and quick-to-deploy. The north-star of the development is enabling users to solve meaningful problems and answer questions quickly, easily, and correctly.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

/*!
 * GCAT (General Catalog of Artificial Space Objects) module.
 *
 * Provides access to Jonathan McDowell's GCAT catalogs:
 * - **SATCAT** (`satcat.tsv`) - Object catalog with physical/orbital properties
 * - **PSATCAT** (`psatcat.tsv`) - Payload-specific metadata
 *
 * Data is downloaded from `https://planet4589.org/space/gcat/tsv/cat/`
 * with 24-hour file-based caching by default.
 */

pub mod catalog;
pub mod fetch;
pub mod parser;
pub mod records;

pub use catalog::{GCATPsatcat, GCATSatcat};
pub use records::{GCATPsatcatRecord, GCATSatcatRecord};

use crate::utils::BraheError;

/// Default base URL for GCAT TSV files.
const DEFAULT_BASE_URL: &str = "https://planet4589.org/space/gcat/tsv/cat";

/// Default cache max age in seconds (24 hours).
const DEFAULT_CACHE_MAX_AGE: f64 = 86400.0;

/// Download and parse the GCAT SATCAT catalog.
///
/// Fetches the SATCAT TSV file from GCAT with file-based caching.
/// Returns a `GCATSatcat` container with search and filter methods.
///
/// # Arguments
///
/// * `cache_max_age` - Maximum cache age in seconds. Defaults to 86400 (24 hours).
///   Pass `Some(0.0)` to force a fresh download.
///
/// # Returns
///
/// * `Result<GCATSatcat, BraheError>` - Parsed SATCAT catalog container
///
/// # Examples
/// ```no_run
/// use brahe::datasets::gcat::get_satcat;
/// let satcat = get_satcat(None).unwrap();  // default 24h cache
/// println!("Loaded {} records", satcat.len());
/// ```
pub fn get_satcat(cache_max_age: Option<f64>) -> Result<GCATSatcat, BraheError> {
    let max_age = cache_max_age.unwrap_or(DEFAULT_CACHE_MAX_AGE);
    let url = format!("{}/satcat.tsv", DEFAULT_BASE_URL);
    let data = fetch::fetch_with_cache(&url, "satcat.tsv", max_age)?;
    let records = parser::parse_satcat_tsv(&data)?;
    Ok(GCATSatcat::new(records))
}

/// Download and parse the GCAT PSATCAT catalog.
///
/// Fetches the PSATCAT TSV file from GCAT with file-based caching.
/// Returns a `GCATPsatcat` container with search and filter methods.
///
/// # Arguments
///
/// * `cache_max_age` - Maximum cache age in seconds. Defaults to 86400 (24 hours).
///   Pass `Some(0.0)` to force a fresh download.
///
/// # Returns
///
/// * `Result<GCATPsatcat, BraheError>` - Parsed PSATCAT catalog container
///
/// # Examples
/// ```no_run
/// use brahe::datasets::gcat::get_psatcat;
/// let psatcat = get_psatcat(None).unwrap();
/// println!("Loaded {} records", psatcat.len());
/// ```
pub fn get_psatcat(cache_max_age: Option<f64>) -> Result<GCATPsatcat, BraheError> {
    let max_age = cache_max_age.unwrap_or(DEFAULT_CACHE_MAX_AGE);
    let url = format!("{}/psatcat.tsv", DEFAULT_BASE_URL);
    let data = fetch::fetch_with_cache(&url, "psatcat.tsv", max_age)?;
    let records = parser::parse_psatcat_tsv(&data)?;
    Ok(GCATPsatcat::new(records))
}