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
  • How to cite
  • Supported GNSS Constellations
  • Key Features and Capabilities
  • Architecture
• Installation
  • Using Ginan with Docker
  • Precompiled binaries
  • Installation from Source
    • Tested Platforms
    • Prerequisites
    • Build Process using vcpkg + CMake presets (Recommanded)
    • Legacy: manual cmake + make instructions
  • Python Environment Setup
• Getting Started with the examples
  • Running Your First Example
  • Adding Ginan to PATH
• Additional Tools and Scripts
• Documentation
  • User Documentation
  • Developer Documentation
  • Generating Code Documentation
• Contributing
  • Reporting Issues
  • Contributing Code
  • Development Setup
• Support
  • Getting Help
• License
  • Third-Party Components
• 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.0.0 bash

# Verify installation
pea --help

# Run a basic example
cd /ginan/exampleConfigs
pea --config ppp_example.yaml

Ginan 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 the installation method that best fits your needs:

Recommended for most users - Get started quickly with a pre-configured environment:

# Run Ginan container with data volume mounting
docker run -it -v ${pwd}:/data gnssanalysis/ginan:v4.0.0 bash

This command:

• Mounts your current directory (${pwd}) to /data in the container
• Provides access to all Ginan tools and dependencies
• Opens an interactive bash shell

Prerequisites: Docker must be installed on your system.

Verify installation:

pea --help

Precompiled 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 (see the Build Process section) 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.

Compilers:

• GCC/G++ (recommended, tested and supported) or equivalent C/C++ compiler

Required Dependencies:

• CMake ≥ 3.0

• YAML ≥ 0.6

• Boost ≥ 1.75

• Eigen3 ≥ 3.4

• OpenBLAS (provides BLAS and LAPACK)

Optional Dependencies:

• Mongo C Driver ≥ 1.17.1

• Mongo C++ Driver ≥ 3.6.0 (= 3.7.0 for GCC 11+)

• MongoDB (for database features)

• netCDF4 (for tidal loading computation)

• Python ≥ 3.9

We recommend using vcpkg for dependency management together with the repository CMake presets.

1. Bootstrap and install vcpkg (from repository root):

# Clone/bootstrap vcpkg (if not present)
./vcpkg/bootstrap-vcpkg.sh 

# Install packages for your target triplet (example: Linux x86_64)
./vcpkg/vcpkg install --triplet x64-linux --x-install-root=./vcpkg_installed
# For macOS: use `arm64-osx` or `x64-osx`. For Windows cross builds (on linux) use `x64-mingw-static`.

2. Configure and build with a CMake preset (run from src):

cd src
# Choose the preset that matches your platform (examples: `release`, `macos-arm64-release`, `macos-x64-release`, `windows-cross-release`)
cmake --preset release
cmake --build --preset release

# Or build the preset directory directly (example for Linux):
cmake --build build/linux-Release --parallel $(nproc)

Note on loading / netCDF: the ocean-tide loading components currently have known problems when built from the vcpkg dependency set due to issues with the netcdf package in some vcpkg triplets. If you rely on tidal-loading features (the make_otl_blq target and related tools), either:

• Build those components from source using your system netcdf (install netcdf/netcdf-c via the OS package manager and use the legacy cmake/make flow), or
• Track the vcpkg netcdf fixes and retry when upstream provides a compatible package for your target triplet.

If you need help reproducing or a suggested workaround for your platform, open an issue with your OS/triplet and vcpkg versions.

Notes:

• The CI uses --x-install-root=./vcpkg_installed to install packages locally for reproducible builds.
• If you prefer not to use vcpkg, the legacy manual flow below remains supported.

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.md

Note: These scripts are maintained as best-effort and may require adjustments for your environment. If you are using the vcpkg + CMake presets workflow, follow the vcpkg steps in the Build Process section instead.

The older manual flow is still available for users who prefer it:

1. Create build directory:

mkdir -p src/build
cd src/build

2. Configure with CMake (legacy):

cmake ../

3. 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

4. Verify installation:

cd ../../exampleConfigs
../bin/pea --help

Expected output:

PEA starting... (main ginan-v4.0.0 from ...)
Options:
  -h [ --help ]     Help
  -q [ --quiet ]    Less output
  ...

5. Download example data:

cd ../inputData/data
./getData.sh
cd ../products  
./getProducts.sh

Ginan 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.txt

Congratulations! 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: None in configuration files
• Performance tip: For single-station PPP, limit cores to improve performance:

  OMP_NUM_THREADS=1 ../bin/pea --config ppp_example.yaml

1. Navigate to examples directory:

   cd exampleConfigs

2. Run basic PPP example:

   ../bin/pea --config ppp_example.yaml

3. Check outputs:

   The processing will create an directory named outputs/ppp_example/ or similar containing:

   • *.trace files with station processing details
   • Network*.trace with 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.yaml

Beyond 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.html

We 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Follow our coding standards
4. Submit a pull request with clear description

• Follow the source installation instructions above
• Review Docs/codingStandard.md for 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:

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.0.0 | GitHub Repository