270 lines
8.4 KiB
Rust
270 lines
8.4 KiB
Rust
//! Footprint geometry and coverage fractions.
|
|
//!
|
|
//! 覆盖区几何与覆盖比例。
|
|
|
|
use crate::geometry::{earth_central_angle, elevation_from_central_angle};
|
|
use apsis_math::Vec3;
|
|
use core::f64::consts::PI;
|
|
|
|
/// A circular ground footprint.
|
|
///
|
|
/// The footprint is the part of the Earth's surface from which a satellite
|
|
/// is visible above a given elevation mask. On a sphere it is an exact
|
|
/// circle, described here by the central angle from the sub-satellite point
|
|
/// and the radius of the body.
|
|
///
|
|
/// 圆形地面覆盖区。
|
|
///
|
|
/// 覆盖区是能在地平遮蔽以上看见某卫星的那部分地表。在球面上它是精确
|
|
/// 的圆，此处以自星下点的中心角和天体半径描述。
|
|
#[derive(Debug, Clone, Copy, PartialEq)]
|
|
pub struct Footprint {
|
|
/// The central half angle of the footprint, in radians.
|
|
///
|
|
/// This is the angle at the centre of the Earth from the sub-satellite
|
|
/// point to the edge of the footprint.
|
|
///
|
|
/// 覆盖区的中心半角，单位为弧度。
|
|
///
|
|
/// 这是在地心处自星下点到覆盖区边缘的角度。
|
|
pub central_angle: f64,
|
|
/// The radius of the body, in kilometers.
|
|
///
|
|
/// 天体的半径，单位为千米。
|
|
pub body_radius: f64,
|
|
}
|
|
|
|
impl Footprint {
|
|
/// Creates a footprint from its central angle and body radius.
|
|
///
|
|
/// 由其中心角与天体半径创建覆盖区。
|
|
#[must_use]
|
|
pub const fn new(central_angle: f64, body_radius: f64) -> Self {
|
|
Self {
|
|
central_angle,
|
|
body_radius,
|
|
}
|
|
}
|
|
|
|
/// Returns the footprint radius measured along the surface, in
|
|
/// kilometers.
|
|
///
|
|
/// 返回沿地表量得的覆盖区半径，单位为千米。
|
|
#[must_use]
|
|
pub fn surface_radius(&self) -> f64 {
|
|
self.central_angle * self.body_radius
|
|
}
|
|
|
|
/// Returns the area of the footprint, in square kilometers.
|
|
///
|
|
/// The area is the part of a sphere cut off by a cone,
|
|
///
|
|
/// <div>
|
|
/// $$
|
|
/// A = 2 \pi R^2 \left(1 - \cos(\text{central})\right)
|
|
/// $$
|
|
/// </div>
|
|
///
|
|
/// which is exact for a spherical body.
|
|
///
|
|
/// 返回覆盖区的面积，单位为平方千米。
|
|
///
|
|
/// 该面积是被圆锥截去的球面部分，
|
|
///
|
|
/// <div>
|
|
/// $$
|
|
/// A = 2 \pi R^2 \left(1 - \cos(\text{central})\right)
|
|
/// $$
|
|
/// </div>
|
|
///
|
|
/// 对球形天体这是精确的。
|
|
#[must_use]
|
|
pub fn area(&self) -> f64 {
|
|
2.0 * PI * self.body_radius * self.body_radius * (1.0 - self.central_angle.cos())
|
|
}
|
|
|
|
/// Returns the fraction of the whole sphere covered by the footprint.
|
|
///
|
|
/// The value is between zero and one half, because a footprint from a
|
|
/// point above the surface can never cover more than a hemisphere.
|
|
///
|
|
/// 返回覆盖区占整个球面的比例。
|
|
///
|
|
/// 该值介于零与二分之一之间，因为来自地表之上某点的覆盖区覆盖范围
|
|
/// 绝不会超过一个半球。
|
|
#[must_use]
|
|
pub fn fraction_of_surface(&self) -> f64 {
|
|
self.area() / (4.0 * PI * self.body_radius * self.body_radius)
|
|
}
|
|
|
|
/// Returns `true` when a ground point at the given central angle from
|
|
/// the sub-satellite point lies inside the footprint.
|
|
///
|
|
/// The comparison is inclusive, so a point exactly on the edge is
|
|
/// inside.
|
|
///
|
|
/// 当距星下点给定中心角的地面点位于覆盖区内时返回 `true`。
|
|
///
|
|
/// 比较是含端点的，故恰在边缘上的点算在内部。
|
|
#[must_use]
|
|
pub fn contains_central_angle(&self, central_angle: f64) -> bool {
|
|
central_angle.is_finite() && central_angle >= 0.0 && central_angle <= self.central_angle
|
|
}
|
|
}
|
|
|
|
/// Returns the central half angle of the footprint, in radians.
|
|
///
|
|
/// This is the largest central angle at which the satellite is still above
|
|
/// the elevation mask.
|
|
///
|
|
/// Returns `None` when the geometry is not usable.
|
|
///
|
|
/// 返回覆盖区的中心半角，单位为弧度。
|
|
///
|
|
/// 这是卫星仍高于仰角遮蔽时的最大中心角。
|
|
///
|
|
/// 几何不可用时返回 `None`。
|
|
#[must_use]
|
|
pub fn footprint_central_angle(
|
|
satellite_radius: f64,
|
|
body_radius: f64,
|
|
elevation_mask: f64,
|
|
) -> Option<f64> {
|
|
let central = earth_central_angle(satellite_radius, body_radius, elevation_mask)?;
|
|
if central.is_finite() && central >= 0.0 {
|
|
Some(central)
|
|
} else {
|
|
None
|
|
}
|
|
}
|
|
|
|
/// Returns the footprint for a satellite and an elevation mask.
|
|
///
|
|
/// Returns `None` when the geometry is not usable.
|
|
///
|
|
/// 返回卫星与仰角遮蔽所对应的覆盖区。
|
|
///
|
|
/// 几何不可用时返回 `None`。
|
|
#[must_use]
|
|
pub fn footprint(
|
|
satellite_radius: f64,
|
|
body_radius: f64,
|
|
elevation_mask: f64,
|
|
) -> Option<Footprint> {
|
|
Some(Footprint::new(
|
|
footprint_central_angle(satellite_radius, body_radius, elevation_mask)?,
|
|
body_radius,
|
|
))
|
|
}
|
|
|
|
/// Returns the area of a footprint, in square kilometers.
|
|
///
|
|
/// This is a free function form of [`Footprint::area`].
|
|
///
|
|
/// Returns `None` when the geometry is not usable.
|
|
///
|
|
/// 返回覆盖区的面积，单位为平方千米。
|
|
///
|
|
/// 这是 [`Footprint::area`] 的自由函数形式。
|
|
///
|
|
/// 几何不可用时返回 `None`。
|
|
#[must_use]
|
|
pub fn footprint_area(satellite_radius: f64, body_radius: f64, elevation_mask: f64) -> Option<f64> {
|
|
Some(footprint(satellite_radius, body_radius, elevation_mask)?.area())
|
|
}
|
|
|
|
/// Returns the fraction of the Earth's surface covered by a footprint.
|
|
///
|
|
/// Returns `None` when the geometry is not usable.
|
|
///
|
|
/// 返回覆盖区所占地球表面的比例。
|
|
///
|
|
/// 几何不可用时返回 `None`。
|
|
#[must_use]
|
|
pub fn footprint_fraction(
|
|
satellite_radius: f64,
|
|
body_radius: f64,
|
|
elevation_mask: f64,
|
|
) -> Option<f64> {
|
|
Some(footprint(satellite_radius, body_radius, elevation_mask)?.fraction_of_surface())
|
|
}
|
|
|
|
/// Returns the angle between two surface points, in radians.
|
|
///
|
|
/// The vectors must be positions relative to the centre of the body, in the
|
|
/// same frame. The angle is the central angle between them, as seen from the
|
|
/// centre.
|
|
///
|
|
/// Returns `None` when either vector has zero length or a non-finite
|
|
/// component.
|
|
///
|
|
/// 返回两个地表点之间的角度，单位为弧度。
|
|
///
|
|
/// 两矢量必须是相对天体中心、在同一坐标系中的位置。该角度是自中心看
|
|
/// 它们之间的中心角。
|
|
///
|
|
/// 任一矢量为零长或含非有限分量时返回 `None`。
|
|
#[must_use]
|
|
pub fn central_angle_between(first: Vec3, second: Vec3) -> Option<f64> {
|
|
if !first.is_finite() || !second.is_finite() {
|
|
return None;
|
|
}
|
|
let first_norm = first.norm();
|
|
let second_norm = second.norm();
|
|
if first_norm == 0.0 || second_norm == 0.0 {
|
|
return None;
|
|
}
|
|
Some(
|
|
(first.dot(second) / (first_norm * second_norm))
|
|
.clamp(-1.0, 1.0)
|
|
.acos(),
|
|
)
|
|
}
|
|
|
|
/// Returns `true` when a ground point lies inside a footprint.
|
|
///
|
|
/// The point and the sub-satellite point are positions relative to the
|
|
/// centre of the body, in kilometers. The footprint supplies the body radius
|
|
/// and the central half angle.
|
|
///
|
|
/// Returns `None` when either vector is degenerate or not finite.
|
|
///
|
|
/// 当某地面点位于某覆盖区内时返回 `true`。
|
|
///
|
|
/// 该点与星下点都是相对天体中心的位置，单位为千米。覆盖区提供天体半径
|
|
/// 与中心半角。
|
|
///
|
|
/// 任一矢量退化或非有限时返回 `None`。
|
|
#[must_use]
|
|
pub fn point_in_footprint(
|
|
footprint: &Footprint,
|
|
point: Vec3,
|
|
sub_satellite_point: Vec3,
|
|
) -> Option<bool> {
|
|
let central = central_angle_between(point, sub_satellite_point)?;
|
|
Some(footprint.contains_central_angle(central))
|
|
}
|
|
|
|
/// Returns the elevation at which a footprint edge is seen from the ground,
|
|
/// in radians.
|
|
///
|
|
/// This is the inverse of [`footprint_central_angle`], useful when a
|
|
/// footprint is known and the mask it corresponds to is wanted.
|
|
///
|
|
/// Returns `None` when the geometry is not usable.
|
|
///
|
|
/// 返回自地面看覆盖区边缘的仰角，单位为弧度。
|
|
///
|
|
/// 它是 [`footprint_central_angle`] 的逆，当已知覆盖区而想求它对应的遮蔽时
|
|
/// 有用。
|
|
///
|
|
/// 几何不可用时返回 `None`。
|
|
#[must_use]
|
|
pub fn footprint_edge_elevation(satellite_radius: f64, footprint: &Footprint) -> Option<f64> {
|
|
elevation_from_central_angle(
|
|
satellite_radius,
|
|
footprint.body_radius,
|
|
footprint.central_angle,
|
|
)
|
|
}
|