apsis-rs/crates/network/apsis-coverage/src/lib.rs

//! Ground coverage analysis.
//!
//! A satellite covers the part of the Earth's surface from which it can be
//! seen above a minimum elevation angle. That part is a circle, called the
//! footprint, whose size depends on the satellite altitude and on the
//! elevation mask. This crate computes the footprint geometry, tests whether
//! a ground point lies inside a footprint, and measures how much of a region
//! is covered.
//!
//! The spherical model in [`geometry`](self) treats the Earth as a sphere.
//! That is accurate enough for constellation design, where the quantities
//! wanted are the footprint radius to a few parts in ten thousand and the
//! number of satellites in view. The exact line-of-sight test in
//! [`line_of_sight`] uses the actual positions, so it accounts for the
//! flattening and for a ground point above the ellipsoid.
//!
//! The geometry of the satellite, the ground point, and the centre of the
//! Earth is a triangle. Its three angles are the elevation at the ground
//! point, the nadir angle at the satellite, and the central angle at the
//! centre, and they sum to a right angle:
//!
//! ```text
//! elevation + nadir + central = 90 degrees
//! ```
//!
//! Source: the relations used here are the standard satellite geometry, as
//! given for example in Vallado, D. A., *Fundamentals of Astrodynamics and
//! Applications*, 4th edition, microcosm Press, 2013, section 5.3.
//!
//! ```
//! use apsis_coverage::{footprint_central_angle, slant_range};
//!
//! // A satellite at 550 km altitude sees to about fifteen degrees of
//! // central angle at a ten degree elevation mask, which is a footprint
//! // radius of some 1665 km along the surface.
//! let central = footprint_central_angle(6_928.137, 6_378.137, 10.0_f64.to_radians())
//!     .expect("valid geometry");
//! assert!((central.to_degrees() - 14.96).abs() < 0.01);
//!
//! let range = slant_range(6_928.137, 6_378.137, 10.0_f64.to_radians())
//!     .expect("valid geometry");
//! assert!((range - 1_815.65).abs() < 0.01);
//! ```
//!
//! 地é<C2B0>¢è¦†ç›–分æž<C3A6>。
//!
//! å<>«æ˜Ÿè¦†ç›–地表上能在最å°<C3A5>仰角以上看到它的那部分。那部分是一个圆，称为覆盖区，
//! 其大å°<C3A5>å<EFBFBD>–决于å<C5BD>«æ˜Ÿé«˜åº¦ä¸Žä»°è§’é<E28099>®è”½ã€‚本 crate 计算覆盖区几何ã€<C3A3>判定æŸ<C3A6>地é<C2B0>¢ç‚¹æ˜¯å<C2AF>¦è<C2A6>½åœ¨
//! 覆盖区内，并度é‡<C3A9>æŸ<C3A6>区域被覆盖的比例。
//!
//! [`geometry`](self) 中的ç<E2809E>ƒé<C692>¢æ¨¡åž‹æŠŠåœ°ç<C2B0>ƒå½“作一个ç<C2AA>ƒã€‚对星座设计已足够准确，那里
//! 所è¦<C3A8>çš„é‡<C3A9>是覆盖区å<C2BA>Šå¾„到万分之几以å<C2A5>Šå<C5A0>¯è§<C3A8>å<EFBFBD>«æ˜Ÿæ•°ã€‚[`line_of_sight`] 中的精确视线
//! 判定使用实际ä½<C3A4>置，故它计入了æ‰<C3A6>率以å<C2A5>Šé«˜äºŽæ¤­ç<C2AD>ƒçš„地é<C2B0>¢ç‚¹ã€‚
//!
//! å<>«æ˜Ÿã€<C3A3>地é<C2B0>¢ç‚¹ä¸Žåœ°å¿ƒæž„æˆ<C3A6>的几何是一个三角形。其三个角是地é<C2B0>¢ç‚¹å¤„的仰角ã€<C3A3>å<EFBFBD>«æ˜Ÿå¤„çš„
//! 天底角，以å<C2A5>Šåœ°å¿ƒå¤„的中心角，它们相加为直角：
//!
//! ```text
//! elevation + nadir + central = 90 degrees
//! ```
//!
//! 出处：此处所用的关系是标准的å<E2809E>«æ˜Ÿå‡ ä½•ï¼Œä¾‹å¦‚è§<C3A8> Vallado, D. A.，*Fundamentals of
//! Astrodynamics and Applications*，第 4 版，microcosm Press，2013，第 5.3 节。

#![forbid(unsafe_code)]
#![deny(missing_docs)]

mod footprint;
mod geometry;
mod visibility;

pub use footprint::{
    Footprint, central_angle_between, footprint, footprint_area, footprint_central_angle,
    footprint_edge_elevation, footprint_fraction, point_in_footprint,
};
pub use geometry::{earth_central_angle, elevation_from_central_angle, nadir_angle, slant_range};
pub use visibility::{
    GroundPoint, Sensor, SubSatellitePoint, central_angle_to_station, elevation_angle,
    line_of_sight, local_up, sub_satellite_point, visible_from, visible_from_geodetic,
};

pub use apsis_geodesy::{Ellipsoid, Geodetic, WGS84};
pub use apsis_math::Vec3;