Develop (#29)

* improve readme
* Rename schedule to tracker feature
  * improve MJD UTC calculations (scheduling process)
* fix example
* docs and api need some improvements
* rename rcvr to 'hardware'
* API upgrade:

   * provide Read parser
   * propose flate2 option for gzip compressed files

* Library update
* New CRC and buffering capabilities
* Add more tests
* Take CRC into account in parsing from now on
* Update docs
* Introducing CommonViewCalendar
* Enhancement of the CommonViewPeriod  (#30)
* CommonViewPeriod::first_track_offset_nanos() returns zero if it is not a bipm_common_view_period
* CommonViewPeriod::next_period_start() adds a return value to indicate whether the next CommonViewPeriod is `t0`

---------

Signed-off-by: Guillaume W. Bres <[email protected]>
Co-authored-by: vicalloy <[email protected]>

Author: gwbres

README.md

@@ -8,18 +8,26 @@ Rust package to parse and generate CGGTTS data.
 [![crates.io](https://docs.rs/cggtts/badge.svg)](https://docs.rs/cggtts/)
 [![crates.io](https://img.shields.io/crates/d/cggtts.svg)](https://crates.io/crates/cggtts)    
 
-CGGTTS is a file format designed to describe the state of a local clock with respect to spacecraft that belong
-to GNSS constellation, ie., a GNSS timescale.  
+CGGTTS is a file format designed to describe the state of a local clock with respect to clocks
+onboard spacecrafts that belong to a GNSS constellation (ie., a GNSS timescale).  
 Exchanging CGGTTS files allows direct clock comparison between two remote sites, by comparing how the clock behaves
-with respect to a specific spacecraft (ie., on board clock).  
-This is called the _common view_ time transfer technique. Although it is more accurate to say CGGTTS is just the comparison method,
-what you do from the final results is up to end application. Usually, the final end goal is to have the B site track the A site
-and replicate the remote clock. It is for example, one option to generate a UTC replica.
+with respect to the spacecraft (more specifically, its onboard clock), which is technically
+a constant observed from both sites.  
+
+Exchanging CGGTTS files allows a posteriori _common view_ time transfer.   
+Although it is more accurate to say CGGTTS just offers the comparison method,
+what you do from the final results is up to the application.
+
+One typical application of common view time transfer by means of CGGTTS files exchange,
+is to have a track a reference site from a remote site. CGGTTS files exchange is also used
+when creating local copies of UTC or potentially in designing UTC itself.  
 
 CGGTTS is specified by the Bureau International des Poids & des Mesures (BIPM):
 [CGGTTS 2E specifications](https://www.bipm.org/documents/20126/52718503/G1-2015.pdf/f49995a3-970b-a6a5-9124-cc0568f85450)
 
-This library only supports revision **2E**, and will _reject_ other revisions.
+## File Revisions
+
+This library only supports revision **2E** (latest) and will _reject_ other revisions.
 
 ## Set of tools
 
@@ -58,4 +66,4 @@ A built in API allows accurate system delay description as defined in CGGTTS.
 
 ## CGGTTS-CLI
 
-[A command line application](gnss_cli/README.md) is developed to process one or two CGGTTS file for clock comparison.
+[A command line application](gnss-cli/README.md) is developed to process one or two CGGTTS file for clock comparison.

cggtts-cli/src/main.rs

@@ -109,18 +109,18 @@ pub fn main() {
 
     if cli.identification() {
         for p in pool {
-            info!("STATION          \"{}\"", p.station);
+            info!("STATION          \"{}\"", p.header.station);
             info!("NUMBER OF TRACKS  {}", p.tracks.len());
             info!(
                 "CODES            {:?}",
-                p.tracks()
+                p.tracks_iter()
                     .map(|trk| trk.frc.clone())
                     .unique()
                     .collect::<Vec<_>>()
             );
             info!(
                 "SV               {:?}",
-                p.tracks()
+                p.tracks_iter()
                     .map(|trk| trk.sv.to_string())
                     .unique()
                     .collect::<Vec<_>>()

cggtts-cli/src/processing.rs

@@ -13,28 +13,28 @@ use crate::plot::{
 };
 
 pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
-    let sv: Vec<_> = cggtts.tracks().map(|trk| trk.sv).unique().collect();
+    let sv: Vec<_> = cggtts.tracks_iter().map(|trk| trk.sv).unique().collect();
     let codes: Vec<_> = cggtts
-        .tracks()
+        .tracks_iter()
         .map(|trk| trk.frc.clone())
         .unique()
         .collect();
 
     //REFSV/SRSV analysis
     ctx.add_timedomain_2y_plot(
-        &format!("{} REFSV/SRSV", cggtts.station),
+        &format!("{} REFSV/SRSV", cggtts.header.station),
         "REFSV [s]",
         "SRSV [s/s]",
     );
     for sv in &sv {
         for code in &codes {
             let epochs: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| if trk.sv == *sv { Some(trk.epoch) } else { None })
                 .collect();
 
             let refsv: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.refsv)
@@ -45,7 +45,7 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
                 .collect();
 
             let srsv: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.srsv)
@@ -76,19 +76,19 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
 
     //REFSYS/SRSYS analysis
     ctx.add_timedomain_2y_plot(
-        &format!("{} REFSYS/SRSYS", cggtts.station),
+        &format!("{} REFSYS/SRSYS", cggtts.header.station),
         "REFSYS [s]",
         "SRSYS [s/s]",
     );
     for sv in &sv {
         for code in &codes {
             let epochs: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| if trk.sv == *sv { Some(trk.epoch) } else { None })
                 .collect();
 
             let refsys: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.refsys)
@@ -99,7 +99,7 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
                 .collect();
 
             let srsys: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.srsys)
@@ -130,19 +130,19 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
 
     //TROPO
     ctx.add_timedomain_2y_plot(
-        &format!("{} MDTR/SMDT", cggtts.station),
+        &format!("{} MDTR/SMDT", cggtts.header.station),
         "MDTR [s]",
         "SMDT [s/s]",
     );
     for sv in &sv {
         for code in &codes {
             let epochs: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| if trk.sv == *sv { Some(trk.epoch) } else { None })
                 .collect();
 
             let mdtr: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.mdtr)
@@ -153,7 +153,7 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
                 .collect();
 
             let smdt: Vec<_> = cggtts
-                .tracks()
+                .tracks_iter()
                 .filter_map(|trk| {
                     if trk.sv == *sv {
                         Some(trk.data.smdt)
@@ -185,28 +185,28 @@ pub fn single_clock(cggtts: &CGGTTS, ctx: &mut PlotContext) {
 
 pub fn clock_comparison(workspace: &Path, pool: &Vec<CGGTTS>, ctx: &mut PlotContext) {
     let ref_clock = &pool[0];
-    info!("{} is considered reference clock", ref_clock.station);
+    info!("{} is considered reference clock", ref_clock.header.station);
 
-    let ref_sv: Vec<_> = ref_clock.tracks().map(|trk| trk.sv).unique().collect();
+    let ref_sv: Vec<_> = ref_clock.tracks_iter().map(|trk| trk.sv).unique().collect();
     let ref_codes: Vec<_> = ref_clock
-        .tracks()
+        .tracks_iter()
         .map(|trk| trk.frc.clone())
         .unique()
         .collect();
     let refsys: HashMap<Epoch, f64> = ref_clock
-        .tracks()
+        .tracks_iter()
         .map(|trk| (trk.epoch, trk.data.refsys))
         .collect();
 
     for i in 1..pool.len() {
         ctx.add_timedomain_plot(
-            &format!("{}-{}", ref_clock.station, pool[i].station),
+            &format!("{}-{}", ref_clock.header.station, pool[i].header.station),
             "Delta [s]",
         );
         for sv in &ref_sv {
             for code in &ref_codes {
                 let x_err: Vec<_> = ref_clock
-                    .tracks()
+                    .tracks_iter()
                     .filter_map(|trk| {
                         if trk.sv == *sv && &trk.frc == code {
                             if refsys.get(&trk.epoch).is_some() {
@@ -220,7 +220,7 @@ pub fn clock_comparison(workspace: &Path, pool: &Vec<CGGTTS>, ctx: &mut PlotCont
                     })
                     .collect();
                 let t_err: Vec<_> = ref_clock
-                    .tracks()
+                    .tracks_iter()
                     .filter_map(|trk| {
                         if trk.sv == *sv && &trk.frc == code {
                             refsys
@@ -243,31 +243,31 @@ pub fn clock_comparison(workspace: &Path, pool: &Vec<CGGTTS>, ctx: &mut PlotCont
         }
     }
 
-    let mut fd = File::create(workspace.join(&pool[0].station))
+    let mut fd = File::create(workspace.join(&pool[0].header.station))
         .expect("failed to create textfile: permission denied");
 
     writeln!(fd, "t, CLOCK(A), CLOCK(B), SV, (elev[°], azi[°]) @REF, (elev[°], azi[°]) @CLOCK, SIGNAL, CLOCK(A) - CLOCK(B) [s]")
         .expect("failed to generate textfile");
 
-    for trk in ref_clock.tracks() {
+    for trk in ref_clock.tracks_iter() {
         let ref_t = trk.epoch;
         let ref_sv = trk.sv;
-        let (ref_elev, ref_azim) = (trk.elevation, trk.azimuth);
+        let (ref_elev, ref_azim) = (trk.elevation_deg, trk.azimuth_deg);
         let ref_frc = &trk.frc;
         for i in 1..pool.len() {
             let track = pool[i]
-                .tracks()
+                .tracks_iter()
                 .filter(|trk| trk.epoch == ref_t && trk.sv == ref_sv && trk.frc == *ref_frc)
                 .reduce(|trk, _| trk);
             if let Some(b_trk) = track {
-                let (b_elev, b_azim) = (b_trk.elevation, b_trk.azimuth);
+                let (b_elev, b_azim) = (b_trk.elevation_deg, b_trk.azimuth_deg);
                 let dt = b_trk.data.refsys - trk.data.refsys;
                 writeln!(
                     fd,
                     "{:?}, {}, {}, {}, ({:.2E}, {:.2E}), ({:.2E}, {:.2E}), {}, {:.3E}",
                     ref_t,
-                    pool[i].station,
-                    pool[0].station,
+                    pool[i].header.station,
+                    pool[0].header.station,
                     ref_sv,
                     ref_elev,
                     ref_azim,

cggtts/Cargo.toml

@@ -3,31 +3,43 @@ name = "cggtts"
 version = "4.1.7"
 license = "MIT OR Apache-2.0"
 authors = ["Guillaume W. Bres <[email protected]>"]
-description = "Package to analyze and create CGGTTS data"
+description = "CGGTTS files parsing and production"
 homepage = "https://github.com/gwbres/cggtts"
-keywords = ["positionning","bipm","gnss","timing","satellites"]
+keywords = ["navigation", "gnss", "timing", "space"]
 categories = ["science","parsing"]
 edition = "2018"
 readme = "../README.md"
 
 [features]
-default = [] # no features by default
+default = []
 
-# unlock the Track Scheduling and data production helpers
-scheduler = ["polyfit-rs"]
+# unlock gzip file native support
+flate2 = ["dep:flate2"]
+
+# unlock serdes operations
+serde = [
+    "dep:serde", 
+    "hifitime/serde",
+    "gnss-rs/serde",
+]
+
+# unlock helper to fit several measurements during 
+# a CommonViewPeriod, following BIPM recommendations.
+polyfit-rs = ["dep:polyfit-rs"]
 
 [dependencies]
 thiserror = "2"
 scan_fmt = "0.1.3"
 strum = "0.26"
 itertools = "0.13"
 strum_macros = "0.26"
+flate2 = { version = "1", optional = true }
 serde = { version = "1.0", optional = true, features = ["derive"] }
 
-hifitime = { version = "4.0", features = ["serde", "std"] }
+hifitime = { version = "4.0", features = ["std"] }
 
-# gnss-rs = { version = "2.2.4", features = ["serde"] }
-gnss-rs = { git = "https://github.com/rtk-rs/gnss", branch = "main", features = ["serde"] }
+# gnss-rs = "2.2.4"
+gnss-rs = { git = "https://github.com/rtk-rs/gnss", branch = "main" }
 
 # track scheduling
 polyfit-rs = { version = "0.2", optional = true }

cggtts/README.md

@@ -24,15 +24,55 @@ Add "cggtts" to your Cargo.toml
 cggtts = "4"
 ```
 
-Use CGGTTS to parse local files
+## Crate features
+
+`CGGTTS` supports several features:
+
+- `serde` will unlock the serdes operation
+of many internal structures.
+- `flate2` will unlock native support
+of gzip compressed files.
+- `polyfit-rs` will unlock one fitting helper
+that help fit observation according to the BIPM track
+fitting method
+
+## Parsing
+
+Parse a local CGGTTS file:
 
 ```rust
 use cggtts::prelude::CGGTTS;
 
-let cggtts = CGGTTS::from_file("../data/dual/GZGTR560.258");
-assert!(cggtts.is_ok());
+let path = format!(
+    "{}/../data/dual/GZGTR560.258",
+    env!("CARGO_MANIFEST_DIR"),
+);
 
-let cggtts = cggtts.unwrap();
-assert_eq!(cggtts.station, "LAB");
+let cggtts = CGGTTS::from_file("../data/dual/GZGTR560.258")
+    .unwrap();
+
+assert_eq!(cggtts.header.station, "LAB");
 assert_eq!(cggtts.tracks.len(), 2097);
 ```
+
+Refer to online API for more examples and further information
+about [CGGTTS].
+
+## Formatting
+
+Parse, modify, dump, parse back then verify:
+
+```rust
+use cggtts::prelude::CGGTTS;
+
+let cggtts = CGGTTS::from_file("../data/dual/GZGTR560.258")
+    .unwrap();
+
+cggtts.to_file("/tmp/test.txt")
+    .unwrap();
+
+let parsed = CGGTTS::from_file("/tmp/test.txt")
+    .unwrap();
+
+assert_eq!(parsed.tracks.len(), cggtts.tracks.len());
+```