Ginan is a powerful, open-source software toolkit for processing Global Navigation Satellite System (GNSS) observations for geodetic applications. Developed by Geoscience Australia, Ginan provides state-of-the-art capabilities for precise positioning, orbit determination, and atmospheric modeling.
If you use Ginan in a publication, please cite:
McClusky, Simon; Hammond, Aaron; Maj, Ronald; Allgeyer, Sébastien; Harima, Ken; Yeo, Mark; Du, Eugene; Riddell, Anna, "Precise Point Positioning with Ginan: Geoscience Australia’s Open-Source GNSS Analysis Centre Software," Proceedings of the ION 2024 Pacific PNT Meeting, Honolulu, Hawaii, April 2024, pp. 248-280. https://doi.org/10.33012/2024.19598
- Quick Start
- Overview
- Installation
- Getting Started with the examples
- Additional Tools and Scripts
- Documentation
- Contributing
- Support
- License
- Acknowledgements
The fastest way to get started with Ginan is using Docker:
# Pull and run the latest Ginan container
docker run -it -v "$(pwd):/data" gnssanalysis/ginan:v4.1.2 bash
# Verify installation
pea --help
# Run a basic example
cd /ginan/exampleConfigs
pea --config ppp_example.yamlGinan is a comprehensive processing package for GNSS observations in geodetic applications, supporting multiple satellite constellations and providing advanced analysis capabilities.
We currently support processing of:
- GPS - United States' Global Positioning System
- Galileo - European Union's Galileo system
- GLONASS - Russian GLONASS system*
- BeiDou - Chinese Navigation Satellite System*
- QZSS - Japanese Quasi-Zenith Satellite System*
*Development ongoing
Ginan provides the following advanced capabilities:
- Precise Orbit & Clock Determination (POD) of GNSS satellites
- Precise Point Positioning (PPP) for stations in network and individual modes
- Real-time corrections generation for PPP users
- Multi-frequency, multi-GNSS data analysis
- Atmospheric products including ionosphere and troposphere models
- Low Earth Orbiter orbit modeling capabilities
- Satellite Laser Ranging processing capabilites
- Support for wide range of users and receiver types
- User-friendly outputs accessible by non-experts
- Real-time and offline processing capabilities
- IGS products generation (final, rapid, ultra-rapid, and real-time)
- Ocean Tide Loading (OTL) displacement modeling
The software consists of three main components:
- Parameter Estimation Algorithm (PEA) - Core processing engine incorporating Precise Orbit Determination
- Analysis Scripts - Tools for data preparation, solution combination and analysis
- Visualization Tools - Python-based plotting and comparison utilities
Choose one of the paths below:
| Method | Best for | Notes |
|---|---|---|
| Docker | Most users, tutorials, reproducible runs | Includes Ginan and its runtime dependencies. |
| Precompiled binaries | Users who want a native executable without building | Available from GitHub Releases for Linux, macOS, and Windows. |
Source build with vcpkg |
Developers and users who need a custom build | Recommended source-build path. |
| Legacy/manual source build | Sites with system-managed dependencies | Best-effort support; use only when vcpkg is not suitable. |
Recommended for most users. Docker is the fastest way to run Ginan with a known-good environment.
Prerequisite: install Docker.
# Run Ginan container with data volume mounting on Linux/macOS
docker run -it -v "$(pwd):/data" gnssanalysis/ginan:v4.1.2 bash
# PowerShell equivalent on Windows
docker run -it -v "${PWD}:/data" gnssanalysis/ginan:v4.1.2 bashThe command mounts your current directory to /data in the container and opens an interactive shell with Ginan available.
Verify installation:
pea --helpPrecompiled binaries for Ginan and GinanUI are available on the project's GitHub Releases page: https://github.com/GeoscienceAustralia/ginan/releases
We publish builds for the following platforms:
- Linux (x86_64)
- macOS (arm64 and x86_64)
- Windows (x86_64)
These artifacts are provided for convenience and have been tested on our CI runners and a subset of target systems. They may not work on every configuration — if you encounter problems please try the Docker image or build from source, and open an issue on GitHub with your OS and steps to reproduce.
Note about Windows binaries: We have observed an output file-size limitation on Windows builds where RTS/output files appear limited at about 2.1 GB (roughly equivalent to a PPP processing of two stations over one day at 30 s resolution). If you require larger RTS outputs, run the processing on Linux/macOS (or in the Docker image) or build from source on a platform without this limitation. We plan to implement a permanent solution in a future release.
For developers and advanced users who need to modify the source code or require specific configurations.
| Platform | Tested Versions | Notes |
|---|---|---|
| Linux | Ubuntu 22.04, 24.04 | Primary development platform |
| macOS | 10.15+ (x86) | Limited testing |
| Windows | 10+ | Limited testing |
The recommended source build uses the repository's CMake presets and vcpkg manifest. This keeps dependency versions close to the CI/release builds.
Prerequisites:
- CMake 3.22 or newer
- A C/C++ compiler for your platform
- Git
vcpkg, installed or cloned as shown below
From the repository root:
export VCPKG_ROOT="$PWD/vcpkg"
export VCPKG_COMMIT="4c5ae6b55f3e3e39d291679f89822f496cf190ee"
git clone https://github.com/Microsoft/vcpkg.git "$VCPKG_ROOT"
git -C "$VCPKG_ROOT" fetch --depth 1 origin "$VCPKG_COMMIT"
git -C "$VCPKG_ROOT" checkout --detach "$VCPKG_COMMIT"
"$VCPKG_ROOT/bootstrap-vcpkg.sh" -disableMetricsIf you already have vcpkg installed elsewhere, set VCPKG_ROOT to that directory and skip the clone commands.
On Windows PowerShell:
$env:VCPKG_ROOT = "$PWD\vcpkg"
$env:VCPKG_COMMIT = "4c5ae6b55f3e3e39d291679f89822f496cf190ee"
git clone https://github.com/Microsoft/vcpkg.git $env:VCPKG_ROOT
git -C $env:VCPKG_ROOT fetch --depth 1 origin $env:VCPKG_COMMIT
git -C $env:VCPKG_ROOT checkout --detach $env:VCPKG_COMMIT
& "$env:VCPKG_ROOT\bootstrap-vcpkg.bat" -disableMetricsThen configure and build from src using the preset for your platform:
cd src
cmake --preset release
cmake --build --preset releaseCommon release presets:
| Platform | Configure/build preset |
|---|---|
| Linux x86_64 | release |
| macOS Apple silicon | macos-arm64-release |
| macOS Intel | macos-x64-release |
| Windows native | windows-release |
| Windows cross-compile from Linux | windows-cross-release |
For example, on Apple silicon:
cd src
cmake --preset macos-arm64-release
cmake --build --preset macos-arm64-releaseBuild outputs are written to the repository-level bin/ and lib/ directories.
Verify the build:
../bin/pea --helpThe CMake presets use platform-specific dependency install roots under ./vcpkg_installed/. If a configure step fails after changing triplets or branches, remove the relevant preset build directory under src/build/ and configure again.
OpenBLAS threading: Ginan can use OpenMP while OpenBLAS may also use worker threads. If you see warnings such as OpenBLAS Warning : Detect OpenMP Loop and this application may hang, set OPENBLAS_NUM_THREADS=1 so BLAS/LAPACK calls run single-threaded inside Ginan's OpenMP regions.
Use this path only if you need system-managed dependencies instead of vcpkg.
Pre-written installation scripts are available in scripts/installation/ for systems where you prefer distro-specific package installation instead of vcpkg:
# Ubuntu 24.04
./scripts/installation/ubuntu24.sh
# Ubuntu 22.04
./scripts/installation/ubuntu22.sh
# Ubuntu 20.04
./scripts/installation/ubuntu20.sh
# Fedora 38
./scripts/installation/fedora38.sh
# Generic instructions
cat scripts/installation/generic.mdThese scripts are maintained as best-effort and may require adjustments for your environment.
The older manual flow is still available for users who prefer it:
- Create build directory:
mkdir -p src/build
cd src/build- Configure with CMake (legacy):
cmake ../- Compile (legacy):
# Build everything (parallel compilation recommended)
make -j$(nproc)
# Build specific components
make pea -j$(nproc) # Core PEA executable
make make_otl_blq -j$(nproc) # Ocean tide loading
make interpolate_loading -j$(nproc) # Loading interpolation- Verify installation:
cd ../../exampleConfigs
../bin/pea --helpExpected output:
PEA starting... (main ginan-v4.1.2 from ...)
Options:
-h [ --help ] Help
-q [ --quiet ] Less output
...
- Download example data:
cd ../inputData/data
./getData.sh
cd ../products
./getProducts.shGinan uses Python for automation, post-processing, and visualization:
# Create virtual environment (recommended)
python3 -m venv ginan-env
source ginan-env/bin/activate
# Install Python dependencies
pip3 install -r scripts/requirements.txtCongratulations! Ginan is now ready to use. The examples in exampleConfigs/ provide a great starting point.
- Working directory: All examples must be run from the
exampleConfigs/directory due to relative paths - MongoDB: If MongoDB is not installed, set
mongo: enable: Nonein configuration files - Threading: Ginan can use OpenMP while OpenBLAS may also use its own worker threads. If you see warnings such as
OpenBLAS Warning : Detect OpenMP Loop and this application may hang, setOPENBLAS_NUM_THREADS=1so BLAS/LAPACK calls run single-threaded inside Ginan's OpenMP regions.GOTO_NUM_THREADS=1is also recognised by OpenBLAS-compatible builds. - Performance tip: For single-station PPP, limit OpenMP cores to improve performance:
OPENBLAS_NUM_THREADS=1 GOTO_NUM_THREADS=1 OMP_NUM_THREADS=1 ../bin/pea --config ppp_example.yaml
-
Navigate to examples directory:
cd exampleConfigs -
Run basic PPP example:
../bin/pea --config ppp_example.yaml
-
Check outputs:
The processing will create an directory named
outputs/ppp_example/or similar containing:*.tracefiles with station processing detailsNetwork*.tracewith Kalman filter results- Other auxiliary outputs as configured
For convenience, add Ginan binaries to your system PATH:
# Add to ~/.bashrc or ~/.zshrc
export PATH="/path/to/ginan/bin:$PATH"
# Then run from anywhere
pea --config /path/to/config.yamlBeyond the core PEA executable, Ginan includes comprehensive scripts for:
- Data downloading and preprocessing
- Output visualization and analysis
- Solution comparison and validation
- Performance monitoring and reporting
Ginan documentation is available in multiple formats:
- Online Manual: geoscienceaustralia.github.io/ginan
- Configuration Guide: Detailed parameter explanations and examples
- FAQ: Ginan FAQ
- Code Documentation: API Reference
Requirements: doxygen and graphviz
# Install dependencies (Ubuntu/Debian)
sudo apt install doxygen graphviz
# Generate documentation
cd src/build
cmake ../
make docs
# View documentation
open ../../Docs/codeDocs/index.htmlWe welcome contributions from the community! Here's how to get involved:
- Use GitHub Issues for bug reports
- Provide detailed reproduction steps and system information
- Check existing issues before creating new ones
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Follow our coding standards
- Submit a pull request with clear description
- Follow the source installation instructions above
- Review
Docs/codingStandard.mdfor guidelines - Run tests before submitting.
- Documentation: Check the online manual first
- Issues: Report bugs and feature requests on GitHub
- Discussions: Join community discussions on GitHub Discussions
Ginan is released under the Apache License 2.0. See LICENSE.md for details.
This software incorporates components from several open-source projects. See Acknowledgements below for detailed attribution.
Ginan incorporates code from several excellent open-source projects:
| Project | License | Purpose | Original Source |
|---|---|---|---|
| Magic Enum | MIT | Enhanced enum support | github.com/Neargye/magic_enums |
| EGM96 | zlib | Earth gravitational model | github.com/emericg/EGM96 |
| IERS2010 | Public Domain | Tidal displacement computation | github.com/xanthospap/iers2010 |
| JPL Ephemeris | GPL-3 | Planetary ephemeris | github.com/Bill-Gray/jpl_eph |
| NRLMSISE | Public Domain | Atmospheric modeling | github.com/c0d3runn3r/nrlmsise |
| RTKLIB | BSD-2-Clause | GNSS processing routines | github.com/tomojitakasu/RTKLIB |
| SLR | Public Domain | SLR input file managements | ilrs.gsfc.nasa.gov* |
| SOFA | SOFA License | Astronomical computations | iausofa.org |
All incorporated code has been preserved with appropriate modifications in the cpp/src/ directory structure, maintaining original licensing and attribution requirements.
Developed by Geoscience Australia | Version 4.1.2 | GitHub Repository