Ginan: GNSS Analysis Software Toolkit

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.

How to cite

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

Table of Contents

• 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

Quick Start

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.1 bash

# Verify installation
pea --help

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

Overview

Ginan is a comprehensive processing package for GNSS observations in geodetic applications, supporting multiple satellite constellations and providing advanced analysis capabilities.

Supported GNSS Constellations

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

Key Features and Capabilities

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

Architecture

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

Installation

Choose the installation method that best fits your needs:

Using Ginan with Docker

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

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.

Installation from Source

For developers and advanced users who need to modify the source code or require specific configurations.

Tested Platforms

| Platform | Tested Versions | Notes | |----------|-----------------|-------| | Linux | Ubuntu 22.04, 24.04 | Primary development platform | | macOS | 10.15+ (x86) | Limited testing | | Windows | 10+ | Limited testing|

Prerequisites

System Dependencies

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

Build Process using vcpkg + CMake presets (Recommanded)

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.

Legacy: manual cmake + make instructions

Quick Installation Scripts (legacy)

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

**No