diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 934ef9494..7a741fdb5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,54 +1,58 @@ CONTRIBUTING ============ -First of all: Hello and welcome on board! - -Use `cargo fmt` prior submitting a pull request so the CI/CD does not fail on coding standards issues. - -This crate and ecosystem is part of the Georust community. -You can contact us to ask questions on our Discord channel, -see the [community portal](https://github.com/georust/geo) - -lib architecture -================ - -For each supported RINEX types, we have one folder. -The folder bears the name of such RINEX type. In that folder, -you can find a `record.rs` file where that particular files content is described. -It also contains its dedicated parsing methods. - -- src/lib.rs : main library, `Rinex` definitions -- src/constellation/mod.rs : GNSS constellations definition - - src/constellation/augmentation.rs : SBAS related definitions -- src/sv.rs : Satellite vehicule definitions -- src/observation/mod.rs : OBS RINEX entry point - - src/observation/record.rs : OBS RINEX specific record definitions -- src/navigation/mod.rs : NAV RINEX entry point - - src/navigation/record.rs : NAV RINEX specific generic record definitions - - src/navigation/ephemeris.rs : Ephemeris frames definition, parsing method and related calculations, like Kepler solving - - src/navigation/ionmessage.rs : new ION frame definition and parsing methods - - src/navigation/eopmessage.rs : new EOP frame definition and parsing methods -- src/meteo/mod.rs : Meteo RINEX entry point - - src/meteo/record.rs : specific record definitions, including parsing methods - - src/hatanaka/mod.rs : Compression / Decompression module - - src/qc/mod.rs : Quality Check module - - src/qc/analysis/sv.rs : Satellite Vehicle general analysis - - src/qc/analysis/obs.rs : OBS RINEX specific analysis +Hello and welcome on board :wave: + +Use the github portal to submit PR, all contributions are welcomed. +Don't forget to run a quick `cargo fmt` prior any submissions, so the CI/CD does not fail +on coding style "issues". + +This crate and ecosystem is part of the Georust community. +You can contact us on [Discord](https://discord.gg/Fp2aape). + +Crate architecture +================== + +For each supported RINEX types, we have one folder named after that format. +`src/navigation` is one of those. + +The module contains the record type definition. RINEX file contents vary a lot +depending on which type of RINEX we're talking about. +For complex RINEX formats like Navigation Data, that module will contain all possible inner types. + +Other important structures : +- `src/epoch/mod.rs`: the Epoch module basically provides +hifitime::Epoch parsing methods, because RINEX describes date in non standard formats. +Also, the `Flag` structure is used to mark Observations (valid or invalid). +- `src/constellation.rs` defines GNSS constellations +- `src/constellation/augmentation.rs` : preliminary SBAS support +- `src/sv.rs` defines a Satellite vehicle, which is associated to a constellation +- `src/observable.rs`: defines possible observations like raw phase +- `src/carrier.rs`: defines carrier signals in terms of frequency and bandwidth. +It also contains utilities to identify which GNSS signals we're dealing with, +from an `Observable`. +- `src/hatanaka/mod.rs`: the Hatanaka module contains the RINEX Compressor and Decompressor +- `src/antex/antenna.rs`: defines the index structure of ANTEX format NAV RINEX ========= -Abstraction for NAV files parsing is provided by the `navigation.json` descriptor. -This is how we describe all supported revisions and their data fields. +Orbit instantaneous parameters, broadcasted by GNSS vehicles, are presented in different +forms depending on the RINEX revision and the GNSS constellation. -Improving or updating NAV file parsing either means updating this database, -or improving the way we rely on it. This is handle +To solve that problem, we use a dictionary, in the form of `src/db/NAV/orbits.json`, +which describes all fields per RINEX revision and GNSS constellation. + +This file is processed at build time, by the build script and ends up as a static +pool we rely on when parsing a file. + +The dictionary is powerful enough to describe all revision, the default Navigation Message +is `LNAV`: Legacy NAV message, which can be omitted. Therefore, it is only declared +for modern Navigation messages. Introducing a new RINEX type ============================ -A good guideline would be to follow the src/meteo/mod.rs module, which is simple enough, -yet follows the basic principles previously explained. +`src/meteo/mod.rs` is the easiest format and can serve as a guideline to follow. -A more complex RINEX declination would be src/navigation, because the inner record entry -can have 3 or 4 different variations. +When introducing a new Navigation Data, the dictionary will most likely have to be updated (see previous paragraph). diff --git a/README.md b/README.md index 6e2a4ba56..19936016f 100644 --- a/README.md +++ b/README.md @@ -11,45 +11,78 @@ RINEX Rust tool suites to parse, analyze and process [RINEX Data](https://en.wikipedia.org/wiki/RINEX). +This RINEX toolsuite is part of the [GeoRust community](https://github.com/georust), +and we aim towards advanced geodesic and ionospheric analysis. + +## Advantages :rocket: + +- Fast +- Open sources +- Native Hatanaka decompression and compression +- Seamless .gzip decompression with `flate2` compilation feature +- RINEX V4 full support, that includes modern Navigation messages +- Meteo RINEX full support +- IONEX and Clock RINEX partial support, will be concluded soon +- File merging, splitting and pre processing +- Modern constellations like BeiDou, Galileo and IRNSS +- Supported time scales are GPST, BDT, GST, UTC +- Full support of Military codes : if you're working with such signals you can +at least run a -qc analysis, and possibly the position solver once it is merged +- Supports high precision RINEX (scaled phase data with micro cycle precision) +- RINEX post processing like SNR, DCB analysis, Broadcast ephemeris interpolation, +high precision orbit interpolation (SP3).. +- RINEX-qc : statistical analysis like "teqc", including on modern signals and SP3 high precision orbits +- An SPP/PPP position solver is under develoment: +checkout [this branch](https://github.com/georust/rinex/tree/solver) which +is kept up to date until merged + +## Known weaknesses :warning: + +- QZNSST is represented as GPST at the moment +- GLONASST and IRNSST are not supported : calculations (mostly orbits) will not be accurate +- Partial SBAS support : some features are not yet available +- The command line tool does not accept BINEX or other proprietary formats +- File production is not fully concluded to this day, some formats are still not correctly supported +(mostly NAV). + +## Architecture + * [`rinex`](rinex/) is the core library * [`rinex-cli`](rinex-cli/) is a command line application based on the core library. It can be used to process RINEX files and perform operations similar to `teqc`. The application is auto-generated for a few architectures, download it from the [release portal](https://github.com/gwbres/rinex/releases) -* [`rnx2crx`](rnx2crx/) is a RINEX compression program -* [`crx2rnx`](crx2rnx/) is a CRINEX decompression program (Compact RINEX to RINEX) +* [`rnx2crx`](rnx2crx/) is a RINEX compressor (RINEX to Compact RINEX) +* [`crx2rnx`](crx2rnx/) is a CRINEX decompresor (Compact RINEX to RINEX) +* [`rinex-qc`](rinex-qc/) is a library dedicated to RINEX files analysis +* [`qc-traits`](qc-traits/) declares Traits that are shared between `rinex` and `rinex-qc` * [`sinex`](sinex/) SNX dedicated core library -* [`ublox-rnx`](ublox-rnx/) is an application that connects to a `Ublox` -receiver and generates RINEX data quickly & easily. -It is the combination of the [ublox](https://github.com/lkolbly/ublox) -and [rinex](rinex/) crates. - -By default, all timestamps are in UTC with leap seconds correctly managed. - -This RINEX toolsuite is part of the [GeoRust community](https://github.com/georust), -and we aim towards advanced geodesic and ionospheric analysis. - -RINEX Standards -=============== - -| Type | Parser | Writer | CLI | UBX | Notes | -|----------------------------|-------------------|---------------------|----------------------|-------------------|------------------------- -| Navigation (NAV) | :heavy_check_mark:| Ephemeris :construction: V4 :construction: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Epoch iteration | -| Observation (OBS) | :heavy_check_mark:| :heavy_check_mark: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Epoch iteration | -| CRINEX (Compressed OBS) | :heavy_check_mark:| RNX2CRX1 :heavy_check_mark: RNX2CRX3 :construction: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Epoch iteration | -| Meteorological data (MET) | :heavy_check_mark:| :heavy_check_mark: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Epoch iteration | -| Clocks (CLK) | :heavy_check_mark:| :construction: | :construction: |:construction: | Epoch iteration | -| Antenna (ATX) | :heavy_check_mark:| :construction: | :construction: |:construction: | Sorted by `antex::Antenna` | -| Ionosphere Maps (IONEX) | :heavy_check_mark:| :construction: | :heavy_check_mark: :chart_with_upwards_trend: |:construction: | Epoch iteration | -| SINEX (SNX) | :construction: | :construction: | :heavy_minus_sign: |:construction: | SINEX are special RINEX, they are managed by a dedicated [core library](sinex/) | -| Troposphere (TRO) | :construction: | :construction: | :question: |:construction: | Troposphere are one possible SINEX declination | -| Bias (BIA) | :heavy_check_mark: | :construction: | :question: |:construction: | Bias solutions are one possible SINEX declination | +* [`ublox-rnx`](ublox-rnx/) is an application intended to generate RINEX Data +from raw uBlox GNSS receiver frames. This application is work in progress at the moment. + +RINEX formats & applications +============================ + +| Type | Parser | Writer | CLI | UBX | Content | Record browsing | +|----------------------------|-------------------|---------------------|----------------------|----------------------|--------------------------| ---------------------| +| Navigation (NAV) | :heavy_check_mark:| Ephemeris :construction: V4 :construction: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Orbit parameters, Ionospheric models.. | Epoch iteration | +| Observation (OBS) | :heavy_check_mark:| :heavy_check_mark: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Phase, Pseudo Range, Doppler, SSI | Epoch iteration | +| CRINEX (Compressed OBS) | :heavy_check_mark:| RNX2CRX1 :heavy_check_mark: RNX2CRX3 :construction: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | see OBS Data | Epoch iteration | +| Meteorological data (MET) | :heavy_check_mark:| :heavy_check_mark: | :heavy_check_mark: :chart_with_upwards_trend: | :construction: | Meteo sensors data (Temperature, Moisture..) | Epoch iteration | +| Clocks (CLK) | :heavy_check_mark:| :construction: | :construction: |:construction: | Clock comparison | Epoch iteration | +| Antenna (ATX) | :heavy_check_mark:| :construction: | :construction: |:construction: | Antenna calibration data | Sorted by `antex::Antenna` | +| Ionosphere Maps (IONEX) | :heavy_check_mark:| :construction: | :heavy_check_mark: :chart_with_upwards_trend: |:construction: | Ionosphere Electron density | Epoch iteration | +| SINEX (SNX) | :construction: | :construction: | :heavy_minus_sign: |:construction: | SINEX are special RINEX, they are managed by a dedicated [core library](sinex/) | Epoch iteration | +| Troposphere (TRO) | :construction: | :construction: | :question: |:construction: | Troposphere modeling | Epoch iteration | +| Bias (BIA) | :heavy_check_mark: | :construction: | :question: |:construction: | Bias estimates, like DCB.. | Epoch iteration | :heavy_check_mark: means all revisions supported -:construction: under development -__CLI__ + :chart_with_upwards_trend: means record analysis is supported by the CLI, [README](rinex-cli/README.md) +:construction: : Work in Progress +__CLI__ + :chart_with_upwards_trend: means the [cli app](rinex-cli/README.md) provides one or several visualizations + +The [cli app](rinex-cli/README.md) accepts more than RINEX input, for example SP3 (high precision orbits) are accepted. File formats ============ @@ -60,14 +93,10 @@ File formats | CRINEX | :heavy_minus_sign: | :heavy_check_mark: | | gzip compressed RINEX | Name must end with `.gz` | `--flate2` feature must be enabled | | gzip compressed CRINEX | Name must end with `.gz` | `--flate2` feature must be enabled | +| SP3 | :heavy_minus_sign: | `--flate2` feature must be enabled | :heavy_minus_sign: No restrictions: file names do not have to follow naming conventions. -## Known weaknesses :warning: - -- Glonass Time Scale is not known to this day. -We cannot parse and apply system time corrections from other time scales into the glonass time scale. - Benchmarking ============ @@ -84,6 +113,14 @@ processing/esbc00dnkr2021/mask:obs | 438.73 ms | processing/esbc00dnkr2021/mask:sv | 341.42 ms | processing/esbc00dnkr2021/smooth:hatch:l1c,l2c | 502.90 ms | +Special Thanks +============== + +RINEX relies heavily on the great libraries written by C. Rabotin, [check out his work](https://github.com/nyx-space). +Some features would not exist without the invaluable help of J. Lesouple, +check out his +[PhD manuscript (french)](http://perso.recherche.enac.fr/~julien.lesouple/fr/publication/thesis/THESIS.pdf?fbclid=IwAR3WlHm0eP7ygRzywbL07Ig-JawvsdCEdvz1umJJaRRXVO265J9cp931YyI) + Contributions ============= diff --git a/rinex-cli/README.md b/rinex-cli/README.md index ac15a8be4..1ad6bcc21 100644 --- a/rinex-cli/README.md +++ b/rinex-cli/README.md @@ -50,7 +50,7 @@ if you know how to operate the preprocessing toolkit ## Data analysis This tool can perform several data analysis. Feasible operations -are highly dependent on the context provided by the user. +are highly dependent on the context provided by the user. Refer to [this page](doc/file-combination.md) to understand what minimal context should be provided, for the analysis you want to perform. diff --git a/rinex-cli/doc/file-combination.md b/rinex-cli/doc/file-combination.md index 7f8f515a2..67d0dd2bb 100644 --- a/rinex-cli/doc/file-combination.md +++ b/rinex-cli/doc/file-combination.md @@ -7,9 +7,9 @@ you want to perform. ## Meteo RINEX analysis -To analyze a Meteo file, a primary file of this type should be passed -to `--fp` (or `-f`). In this case, you get a visualization -of all observations. An in depth statistical analysis is feasible with `--qc`. +To analyze a Meteo file, a primary file of this type should be passed to `--fp` (or `-f`). +In this case, you get a visualization of all observations. +An in depth statistical analysis is feasible with `--qc`. It does not make sense to stack other RINEX files to such analysis.