docs: bilingual comments for the access finder and pass summary

crates/network/apsis-access/src/finder.rs

@@ -11,6 +11,11 @@ use apsis_math::Vec3;
 /// in seconds from the caller's origin. The caller supplies a sequence of
 /// these, which decouples the finder from the propagation and the frame
 /// transformation.
+///
+/// 卫星轨迹的一个样本，按其被查找器消费的形式。
+///
+/// 位置在地固系中，单位为千米；时间以距调用方原点的秒数表示。调用方
+/// 提供这样的一串样本，使查找器与传播及坐标系变换解耦。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct OrbitSample {
     /// The time of the sample, in seconds from the caller's origin.
@@ -18,11 +23,15 @@ pub struct OrbitSample {
     /// 样本时刻，单位为自调用方原点起的秒数。
     pub seconds: f64,
     /// The satellite position in the Earth-fixed frame, in kilometers.
+    ///
+    /// 地固系中的卫星位置，单位为千米。
     pub position_ecef_km: Vec3,
 }
 
 impl OrbitSample {
     /// Creates a sample from a time and a position.
+    ///
+    /// 由时间与位置创建样本。
     pub const fn new(seconds: f64, position_ecef_km: Vec3) -> Self {
         Self {
             seconds,
@@ -31,6 +40,8 @@ impl OrbitSample {
     }
 
     /// Returns `true` when the sample is usable.
+    ///
+    /// 当该样本可用时返回 `true`。
     pub fn is_valid(&self) -> bool {
         self.seconds.is_finite() && self.position_ecef_km.is_finite()
     }
@@ -41,25 +52,43 @@ impl OrbitSample {
 /// The finder holds the station and the numerical settings of the search.
 /// The settings are separated from the search so that the same finder can be
 /// applied to many satellites.
+///
+/// 为一个地面站查找可见性窗口。
+///
+/// 查找器保存地面站与搜索的数值设置。设置与搜索分开，使同一个查找器可
+/// 应用于许多卫星。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct AccessFinder {
     /// The station and its elevation mask.
+    ///
+    /// 地面站及其仰角遮蔽。
     pub station: GroundPoint,
     /// The interval between samples of the satellite track, in seconds.
     ///
     /// A smaller step finds shorter passes but costs proportionally more
     /// evaluations. A step of one minute resolves any pass a low Earth
     /// satellite makes, since such a pass lasts several minutes.
+    ///
+    /// 卫星轨迹样本之间的间隔，单位为秒。
+    ///
+    /// 更小的步长能发现更短的过境，但求值次数成比例增加。一分钟的步长
+    /// 能分辨低轨卫星的任何过境，因为这样的过境持续数分钟。
     pub sample_step_seconds: f64,
     /// The tolerance on a crossing time, in seconds.
     ///
     /// The refinement of a rise or set continues until the interval
     /// containing the crossing is this narrow.
+    ///
+    /// 穿越时刻的容差，单位为秒。
+    ///
+    /// 对升起或降落的细化持续到包含该穿越的区间窄于该值为止。
     pub crossing_tolerance_seconds: f64,
 }
 
 impl AccessFinder {
     /// Returns `true` when the finder settings are usable.
+    ///
+    /// 当查找器设置可用时返回 `true`。
     pub fn is_valid(&self) -> bool {
         self.station.is_valid()
             && self.sample_step_seconds.is_finite()
@@ -71,6 +100,8 @@ impl AccessFinder {
 
     /// Validates the settings, returning the reason when they are not
     /// usable.
+    ///
+    /// 校验设置，不可用时返回原因。
     fn validate(&self) -> Result<(), AccessError> {
         if !self.station.is_valid() {
             return Err(AccessError::new(AccessErrorKind::InvalidStation));
@@ -93,6 +124,10 @@ impl AccessFinder {
     /// Returns the elevation of a sample, in radians.
     ///
     /// Returns `None` when the sample or the station is not usable.
+    ///
+    /// 返回某样本的仰角，单位为弧度。
+    ///
+    /// 样本或地面站不可用时返回 `None`。
     pub fn elevation_of(&self, sample: &OrbitSample) -> Option<f64> {
         if !sample.is_valid() {
             return None;
@@ -129,11 +164,34 @@ impl AccessFinder {
     /// checked rather than assumed, because the interpolation between two
     /// samples binary searches the sequence and a binary search over an
     /// unordered list returns a wrong index without failing.
+    ///
+    /// 在有序的样本序列中查找可见性窗口。
+    ///
+    /// 各样本必须按时间排序并覆盖所关注的区间。查找器假定仰角在样本
+    /// 之间连续，故步长必须短到卫星不会在一个步长内升起又降落。低轨
+    /// 卫星在十度遮蔽以上持续数分钟，故一分钟或更短的步长即满足。
+    ///
+    /// 穿越时刻通过在跨越该穿越的两个样本之间线性插值卫星位置求得。
+    /// 两样本之间的弦与真实弧的偏差为步长的二阶量，故十秒步长给出的
+    /// 穿越精度约为十分之一秒，一秒步长约为毫秒。当传播器可用且希望
+    /// 穿越达到完整容差时，用 [`AccessFinder::find_with`]。
+    ///
+    /// 在第一个样本处已进行中的过境，其升起时刻报告为第一个样本时间；
+    /// 在最后一个样本处仍在进行中的过境，其降落时刻报告为最后一个
+    /// 样本时间。该约定意味着过境被裁剪到所搜索的区间，而不外推超出
+    /// 它。
+    ///
+    /// 设置不可用、样本序列少于两项、某样本不可用，或序列未按时间
+    /// 递增排列时返回错误。次序是被检查而非假定的，因为两样本之间的
+    /// 插值会对序列做二分查找，而对无序列表的二分查找会返回错误的下标
+    /// 而不报错。
     pub fn find(&self, samples: &[OrbitSample]) -> Result<PassSummary, AccessError> {
         self.find_internal(samples, |seconds| {
             // Interpolate the position between the bracketing samples. The
             // order of the sequence is checked by `find_internal` before
             // this closure runs, and the step is the caller's to choose.
+            // 在夹逼的两个样本之间插值位置。序列的次序在该闭包运行前由
+            // `find_internal` 检查，步长由调用方选择。
             let index = match samples.binary_search_by(|sample| {
                 sample
                     .seconds
@@ -164,6 +222,11 @@ impl AccessFinder {
     /// The function must be defined over the whole interval and must be
     /// continuous, and the sample sequence must be ordered by time. The
     /// closure returns `None` when the position at that time is not usable.
+    ///
+    /// 在给定返回某时刻仰角的函数下运行搜索。
+    ///
+    /// 该函数必须定义在整个区间上且必须连续，样本序列必须按时间排序。
+    /// 当该时刻的位置不可用时，该闭包返回 `None`。
     fn find_internal<F>(
         &self,
         samples: &[OrbitSample],
@@ -185,10 +248,17 @@ impl AccessFinder {
         // crossing against the wrong pair of positions and report a pass that
         // never happened. Checking only the ends, as this once did, let that
         // through silently.
+        // 整个序列必须严格按时间递增，而不只是其两端。两样本之间的插值
+        // 会对该列表做二分查找，而对无序列表的二分查找会返回错误的下标
+        // 而不报错，故无序序列会针对错误的位置对细化穿越，并报告一个
+        // 从未发生过的过境。只检查两端（如本代码过去所做的）会使其无声
+        // 通过。
         for (index, pair) in samples.windows(2).enumerate() {
             // The test is written out rather than as `!(a < b)` so that it
             // also rejects a pair whose times are not finite, and so that a
             // reader can see that equality and disorder are both refused.
+            // 该测试是写开的而非写成 `!(a < b)`，使它也拒绝时间非有限的
+            // 点对，并使读者能看出相等与失序都被拒绝。
             let ordered = pair[0].seconds.is_finite()
                 && pair[1].seconds.is_finite()
                 && pair[0].seconds < pair[1].seconds;
@@ -229,6 +299,8 @@ impl AccessFinder {
         let mut rise: Option<f64> = None;
         // Track the highest elevation seen inside the current pass so that
         // the peak is known without a second pass over the samples.
+        // 跟踪当前过境内所见的最大仰角，使峰值无需再遍历一遍样本即可
+        // 得知。
         let mut peak = f64::NEG_INFINITY;
         let mut peak_seconds = first;
         let mut peak_position = samples[0].position_ecef_km;
@@ -240,6 +312,8 @@ impl AccessFinder {
                     rise = Some(if index == 0 {
                         // The pass was already open at the start of the
                         // window, so it is clipped to the first sample.
+                        // 该过境在窗口开始时就已打开，故被裁剪到第一个
+                        // 样本。
                         samples[0].seconds
                     } else {
                         self.refine_crossing(samples, index, true, &mut elevation_at)
@@ -266,6 +340,7 @@ impl AccessFinder {
 
         // A pass still open at the end of the sequence is clipped to the
         // last sample.
+        // 在序列末尾仍打开的过境被裁剪到最后一个样本。
         if let Some(rise_seconds) = rise {
             passes.push(Pass {
                 rise_seconds,
@@ -290,6 +365,14 @@ impl AccessFinder {
     /// increases through the mask; otherwise it is a set. The flag selects
     /// which side of the crossing is above the mask, which keeps the search
     /// bracket correct.
+    ///
+    /// 细化仰角穿越遮蔽的时刻。
+    ///
+    /// 该穿越位于下标 `index` 处的样本与其前一个之间，两者夹逼遮蔽。
+    /// 二分法把区间减半直到它窄于容差。
+    ///
+    /// 当 `rising` 为真时该穿越是升起，即仰角递增地穿过遮蔽；否则是
+    /// 降落。该标志选择穿越的哪一侧在遮蔽之上，从而保持搜索夹逼正确。
     fn refine_crossing<F>(
         &self,
         samples: &[OrbitSample],
@@ -306,6 +389,8 @@ impl AccessFinder {
 
         // The elevation difference from the mask, with the sign arranged so
         // that the function is negative at `low` and positive at `high`.
+        // 相对遮蔽的仰角差，其符号被安排为使该函数在 `low` 处为负、在
+        // `high` 处为正。
         let sign = if rising { 1.0 } else { -1.0 };
         let mut difference = |seconds: f64| {
             let elevation = elevation_at(seconds).unwrap_or(mask);
@@ -342,6 +427,13 @@ impl AccessFinder {
     ///
     /// Returns an error when the settings are not usable, when the interval
     /// is not ordered, or when the propagator fails at a sample.
+    ///
+    /// 在某个区间上查找可见性窗口，对每个样本调用一次传播器。
+    ///
+    /// 传播器接收以距搜索原点的秒数表示的时间，返回地固系中的卫星
+    /// 位置。这使查找器可适配任何轨道来源，而本 crate 不依赖于其一。
+    ///
+    /// 设置不可用、区间次序不对，或传播器在某样本处失败时返回错误。
     pub fn find_with<F>(
         &self,
         start_seconds: f64,
@@ -361,6 +453,7 @@ impl AccessFinder {
         }
 
         // Build the sample sequence, including the end point.
+        // 构建样本序列，包含端点。
         let step = self.sample_step_seconds;
         let count = ((end_seconds - start_seconds) / step).ceil() as usize + 1;
         let mut samples = Vec::with_capacity(count);
@@ -375,6 +468,8 @@ impl AccessFinder {
         // The loop above may append the end point twice when the interval is
         // an exact multiple of the step, so the last sample is replaced when
         // it duplicates the end.
+        // 当区间是步长的精确整数倍时，上面的循环可能把端点追加两次，故
+        // 当最后一个样本与端点重复时将其替换。
         if let Some(last) = samples.last_mut() {
             if last.seconds != end_seconds {
                 let position = propagator(end_seconds).ok_or_else(|| {
@@ -390,6 +485,8 @@ impl AccessFinder {
         // The refinement calls the propagator at each bisection point, so
         // the crossing is found to the tolerance rather than to the
         // accuracy of a chord between two samples.
+        // 细化在每个二分点调用传播器，故穿越是按容差求得，而非按两样本
+        // 之间弦的精度求得。
         let mut failure = None;
         let summary = self.find_internal(&samples, |seconds| match propagator(seconds) {
             Some(position) if position.is_finite() => elevation_angle(position, &self.station),

crates/network/apsis-access/src/pass.rs

@@ -8,34 +8,58 @@ use apsis_math::Vec3;
 /// Times are seconds from an origin chosen by the caller, so the same
 /// structure serves a search over a scenario clock and one over elapsed
 /// time.
+///
+/// 卫星高于某地面站仰角遮蔽的一个连续区间。
+///
+/// 时间是以距调用方所选原点的秒数表示，故同一结构既服务于按场景时钟的
+/// 搜索，也服务于按流逝时间的搜索。
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Pass {
     /// The time the satellite rises above the mask, in seconds from the
     /// caller's origin.
+    ///
+    /// 卫星升到遮蔽之上的时间，以距调用方原点的秒数表示。
     pub rise_seconds: f64,
     /// The time the satellite falls below the mask.
+    ///
+    /// 卫星降到遮蔽以下的时间。
     pub set_seconds: f64,
     /// The time of greatest elevation.
+    ///
+    /// 仰角最大时的时间。
     pub peak_seconds: f64,
     /// The greatest elevation during the pass, in radians.
+    ///
+    /// 该过境期间的最大仰角，单位为弧度。
     pub peak_elevation: f64,
     /// The elevation at which the satellite crossed the mask, in radians.
     ///
     /// This is the station's mask, recorded so that a pass carries the
     /// geometry it was found under.
+    ///
+    /// 卫星穿越遮蔽时的仰角，单位为弧度。
+    ///
+    /// 这是地面站的遮蔽，记录它是为了使过境携带其被发现时所依据的
+    /// 几何。
     pub mask_elevation: f64,
     /// The satellite position in the Earth-fixed frame at the peak, in
     /// kilometers.
+    ///
+    /// 峰值处地固系中的卫星位置，单位为千米。
     pub peak_position: Vec3,
 }
 
 impl Pass {
     /// Returns the duration of the pass, in seconds.
+    ///
+    /// 返回该过境的时长，单位为秒。
     pub fn duration(&self) -> f64 {
         self.set_seconds - self.rise_seconds
     }
 
     /// Returns the time from the rise to the peak, in seconds.
+    ///
+    /// 返回从升起到峰值的时间，单位为秒。
     pub fn rise_to_peak(&self) -> f64 {
         self.peak_seconds - self.rise_seconds
     }
@@ -46,6 +70,11 @@ impl Pass {
     /// The pass stores only the peak, so this helper reports the stored
     /// values at the three defining times and defers to the caller's
     /// elevation function otherwise.
+    ///
+    /// 返回过境内某时刻的仰角，当调用方能提供它时。
+    ///
+    /// 过境只保存峰值，故该辅助函数在三个界定时刻报告所存的值，其余
+    /// 情形交由调用方的仰角函数。
     pub fn contains(&self, seconds: f64) -> bool {
         seconds >= self.rise_seconds && seconds <= self.set_seconds
     }
@@ -54,22 +83,34 @@ impl Pass {
     ///
     /// This is the same as the peak elevation, named for readability at a
     /// call site that compares passes.
+    ///
+    /// 返回该过境的最大仰角，单位为弧度。
+    ///
+    /// 这与峰值仰角相同，其命名是为在比较过境的调用处更具可读性。
     pub fn maximum_elevation(&self) -> f64 {
         self.peak_elevation
     }
 }
 
 /// A summary of the access windows over an interval.
+///
+/// 某区间上可见性窗口的汇总。
 #[derive(Debug, Clone, PartialEq)]
 pub struct PassSummary {
     /// The passes, in time order.
+    ///
+    /// 按时序排列的各过境。
     pub passes: Vec<Pass>,
     /// The length of the interval searched, in seconds.
+    ///
+    /// 所搜索区间的长度，单位为秒。
     pub interval_seconds: f64,
 }
 
 impl PassSummary {
     /// Creates a summary from a list of passes and the interval length.
+    ///
+    /// 由过境列表与区间长度创建汇总。
     pub fn new(passes: Vec<Pass>, interval_seconds: f64) -> Self {
         Self {
             passes,
@@ -78,6 +119,8 @@ impl PassSummary {
     }
 
     /// Returns the number of passes.
+    ///
+    /// 返回过境的数量。
     pub fn count(&self) -> usize {
         self.passes.len()
     }
@@ -85,6 +128,10 @@ impl PassSummary {
     /// Returns the total access time, in seconds.
     ///
     /// The passes are disjoint, so the durations add.
+    ///
+    /// 返回总可见时间，单位为秒。
+    ///
+    /// 各过境互不相交，故时长相加。
     pub fn total_access_seconds(&self) -> f64 {
         self.passes.iter().map(Pass::duration).sum()
     }
@@ -93,6 +140,10 @@ impl PassSummary {
     /// accessible.
     ///
     /// Returns `None` when the interval length is not positive.
+    ///
+    /// 返回卫星可见所占该区间的比例。
+    ///
+    /// 区间长度非正时返回 `None`。
     pub fn access_fraction(&self) -> Option<f64> {
         if self.interval_seconds > 0.0 && self.interval_seconds.is_finite() {
             Some(self.total_access_seconds() / self.interval_seconds)
@@ -104,6 +155,10 @@ impl PassSummary {
     /// Returns the mean pass duration, in seconds.
     ///
     /// Returns `None` when there are no passes.
+    ///
+    /// 返回过境的平均时长，单位为秒。
+    ///
+    /// 没有过境时返回 `None`。
     pub fn mean_duration_seconds(&self) -> Option<f64> {
         if self.passes.is_empty() {
             return None;
@@ -112,6 +167,8 @@ impl PassSummary {
     }
 
     /// Returns the longest pass, if there is one.
+    ///
+    /// 返回最长的过境（若存在）。
     pub fn longest(&self) -> Option<&Pass> {
         self.passes.iter().max_by(|first, second| {
             first
@@ -122,6 +179,8 @@ impl PassSummary {
     }
 
     /// Returns the highest pass, if there is one.
+    ///
+    /// 返回仰角最高的过境（若存在）。
     pub fn highest(&self) -> Option<&Pass> {
         self.passes.iter().max_by(|first, second| {
             first
@@ -135,6 +194,10 @@ impl PassSummary {
     ///
     /// Returns `None` when either index is out of range or the two indices
     /// are not consecutive and increasing.
+    ///
+    /// 返回两个相邻过境之间的间隙，单位为秒。
+    ///
+    /// 任一下标越界，或两个下标不相邻且递增时返回 `None`。
     pub fn gap_seconds(&self, first: usize, second: usize) -> Option<f64> {
         if second != first + 1 {
             return None;
@@ -148,6 +211,11 @@ impl PassSummary {
     ///
     /// This is the longest time a station waits between contacts.
     /// Returns `None` when there are fewer than two passes.
+    ///
+    /// 返回相邻过境之间的最大间隙，单位为秒。
+    ///
+    /// 这是一个地面站在两次通信之间等待的最长时间。过境少于两个时返回
+    /// `None`。
     pub fn longest_gap_seconds(&self) -> Option<f64> {
         if self.passes.len() < 2 {
             return None;