Copernicus Viewer

A Rust GUI application to explore and visualize EOPF Zarr products.

Features

• Open EOPF Zarr stores (.zarr directories, .zarr.zip archives, or s3:// URIs on AWS S3)
• Open Sentinel-3 SAFE products (.SEN3 directories) when built with the safe feature
• Browse the product hierarchy (groups and variables) in a tree view
• Inspect metadata with an xarray-inspired representation (DataTree / Group / DataArray with attributes)
• Product attributes tree for root metadata (nested STAC / EOPF attributes, foldable like the hierarchy)
• Statistics and data preview tables in the inspector for loaded array subsets
• Async plot loading with progress bar for large arrays
• Geo-referenced plotting: coordinate arrays, CRS, and axis extent labels on heatmaps
• CF flag variables with flag_meanings and flag_values / flag_masks (bitmask plots per flag)
• Coverage map in the inspector — adaptive Plate Carrée view (zooms to regional tiles, global view for wide footprints) with Natural Earth coastlines
• Product comparison (Tools → Comparison) — compare a reference and a new product (structure, variable data, CF flags) with user-defined thresholds and a pass/fail report; same logic via the compare_products example
• S3 product download — copy an open S3-hosted product to a local .zarr directory (File → Download product…, hierarchy ⬇ icon, or right-click on the product name)

Quick start

This walkthrough opens a reference and a new EOPF product side by side (the screenshots below use Sentinel-3 SLSTR LST data). Pass your own .zarr paths:

cargo run -- /path/to/reference.zarr /path/to/new.zarr

Both products appear in the Hierarchy panel. Select measurements/lst to inspect metadata, view the coverage map, and plot the land-surface temperature heatmap:

Configure S3 bucket credentials from File → Configure S3…:

Open Tools → Comparison, pick the reference and new product, then run the check. The report lists structure, variable, and flag differences — here four auxiliary variables differ while 64 measurement variables pass:

The same comparison logic is available from the CLI:

cargo run --example compare_products -- /path/to/reference.zarr /path/to/new.zarr

To regenerate the README screenshots (maintainers):

COPERNICUS_VIEWER_CAPTURE_DEMO=docs/screenshots cargo run -- \
  /path/to/reference.zarr /path/to/new.zarr

For further details, see the tutorial.

Requirements

• Rust 1.75+
• GPU support for the GUI (wgpu on Linux desktop, macOS, and Windows; Glow/OpenGL on WSL2 — see WSL2 graphics)

Sentinel-3 SAFE (optional safe feature)

The safe Cargo feature enables .SEN3 support via NetCDF. It is on by default for local development.

GitHub Releases ship two variants per platform: a Zarr-only binary and a -safe binary built with netcdf-static (no NetCDF install required for end users).

On Linux, system development builds need:

sudo apt install libnetcdf-dev

Without libnetcdf-dev, use static linking:

cargo build --features netcdf-static

WSL2 / Linux system packages

On WSLg (default on recent WSL2), the app uses Wayland automatically — no extra packages needed.

If you use X11 forwarding to an external X server (VcXsrv, X410, …), install:

sudo apt install libxkbcommon-x11-0 libgl1-mesa-dri

Runtime for the GTK file dialog (optional build): libgtk-3-0.

Opening products: File → Open Zarr… opens an in-app browser for local .zarr directories, .zarr.zip archives, and (when built with safe) .SEN3 SAFE directories — click or double-click a product, or paste a path and press Open. Use S3 in that dialog to browse configured buckets and prefixes on object storage (see S3 object storage). You can also paste an s3://bucket/path/product.zarr URI directly. Use System picker… for the native file chooser on local paths; it automatically uses a folder picker for .zarr paths and a file picker for .zip paths. You can open several products at once; each appears as a top-level entry in the Hierarchy panel. Close one with ✕ next to its name or File → Close product. Opening a product reads hierarchy metadata only; array values are loaded when you select a variable to plot.

If the native dialog is empty or opens twice on WSL, rebuild with the GTK backend:

sudo apt install libgtk-3-dev
cargo build --no-default-features --features dialog-gtk
cargo run --no-default-features --features dialog-gtk

WSL2 graphics

The app picks a renderer from your WSL environment (override with COPERNICUS_VIEWER_GL):

On WSLg (WAYLAND_DISPLAY set), the default is Glow with GPU acceleration. Mesa llvmpipe is not compatible with WSLg/Wayland.

On WSL over X11 (VcXsrv, X410, …), the default is Glow with Mesa llvmpipe software rendering, which is much more stable than ZINK/EGL when resizing windows. Vsync is disabled on this path; the app sets LIBGL_ALWAYS_SOFTWARE=1 and related Mesa env vars automatically.

# Force Mesa llvmpipe + Glow (X11 only; on WSLg falls back to GPU Glow with a warning)
COPERNICUS_VIEWER_GL=software cargo run

# GPU: Glow on WSL, wgpu elsewhere
COPERNICUS_VIEWER_GL=hardware cargo run

# Force wgpu everywhere (expert — may fail on WSL with EGL/ZINK errors)
COPERNICUS_VIEWER_GL=wgpu cargo run

# Explicit auto-detection (same as unset)
COPERNICUS_VIEWER_GL=auto cargo run

native is an alias for wgpu.

Install

Rust (crates.io)

cargo install copernicus_viewer
copernicus_viewer

Requires a Rust toolchain and GPU support (same as Requirements).

Prebuilt binaries (GitHub Releases)

Download the archive for your platform from GitHub Releases, extract it, and run:

• copernicus_viewer-{version}-{target}.tar.gz / .zip — Zarr-only (no .SEN3 support)
• copernicus_viewer-{version}-{target}-safe.tar.gz / .zip — Zarr + Sentinel-3 SAFE (self-contained NetCDF)

# Linux / macOS
./copernicus_viewer /path/to/product.zarr

# Windows
copernicus_viewer.exe C:\path\to\product.zarr

Verify downloads with the SHA256SUMS.txt file attached to each release.

Build & Run

# Optional: generate a local sample product for testing
cargo run --example create_sample_zarr

Formatting and linting

cargo fmt --all
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked

CI runs cargo fmt --check, Clippy (-D warnings), and tests on every push and pull request.

Optional pre-commit hooks run cargo fmt and Clippy before each commit:

pip install pre-commit   # or: brew install pre-commit
pre-commit install
pre-commit run --all-files   # verify without committing

# Compare two products from the CLI (reference vs new)
cargo run --example compare_products -- reference.zarr new.zarr

cargo run

Use File → Open Zarr… to load additional EOPF products. Pass one or more paths on the command line:

cargo run -- /path/to/product_a.zarr /path/to/product_b.zarr
cargo run -- s3://my-eopf-bucket/eopf/products/S03OLCEFR_202309.zarr

S3 object storage

Remote EOPF Zarr directory stores on AWS S3 (including custom endpoints) can be opened with an s3:// URI from the command line or by pasting the URI in File → Open Zarr…. You can also browse remote products in that dialog: click S3 to list buckets from your config file, then navigate prefixes and double-click a .zarr product to open it. Use Local to return to filesystem browsing. The in-app directory listing for local paths is unchanged.

Credentials

Credentials are resolved in this order (bucket name from the URI selects the INI section):

1. Config file from COPERNICUS_VIEWER_S3_CONFIG or S3_CONFIG (if set)
2. Default config at %APPDATA%\cp-rs\s3.conf (Windows) or ~/.config/cp-rs/s3.conf (Unix)
3. S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINT, S3_REGION
4. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL, AWS_REGION

INI format (rclone-style), one section per bucket:

[my-eopf-bucket]
type = s3
access_key_id = AKID
secret_access_key = SKEY
region = eu-west-1
endpoint = https://s3.example.com

Nested paths are resolved to the Zarr product root automatically (same as local paths), e.g. s3://bucket/path/product.zarr/measurements/lst opens s3://bucket/path/product.zarr.

.zarr.zip archives on S3 are not supported in this version.

Downloading S3 products

When an S3 product is open, download it to your local filesystem as a .zarr directory:

• File → Download product… (enabled when the selected product is on S3)
• ⬇ next to the product name in the Hierarchy panel
• Right-click the product name → Download product…

Choose a parent folder in the native dialog; the product is saved as <folder>/<product-name>.zarr with the same Zarr layout as on S3. Progress appears in the status bar. The download fails if that destination folder already exists.

The library API download_s3_product is also available for scripts and automation.

Releasing (maintainers)

1. Bump version in Cargo.toml and commit.
2. Create and push an annotated tag: git tag -a v0.2.0 -m "v0.2.0" && git push origin v0.2.0
3. Ensure the repository secret CARGO_REGISTRY_TOKEN is set (crates.io token).

The release workflow runs tests, builds binaries for Linux, Windows, and macOS (x86_64 + arm64), attaches them to a GitHub Release, publishes to crates.io, and updates CHANGELOG.md from git history using git-cliff.

Preview unreleased changes locally (set GITHUB_TOKEN for PR metadata from the GitHub API):

cargo install git-cliff --locked
export GITHUB_TOKEN=ghp_...   # optional; `gh auth token` works too
git cliff --config cliff.toml --unreleased

To include linked issues in the changelog, reference them in commit or PR descriptions (Fixes #123, Closes #456, or #789). git-cliff does not query the GitHub Issues API for all closed issues in a release — only PR metadata (via the API) and issue numbers mentioned in commit text (via link_parsers in cliff.toml).

Regenerate the full changelog:

git cliff --config cliff.toml --output CHANGELOG.md

For the first crates.io publish, create an API token at crates.io/settings/tokens, add it as a GitHub secret, then either push a tag or run locally:

cargo publish

EOPF Zarr structure

EOPF products follow the standard Zarr hierarchy described in PSFD §4.4:

• Root .zattrs — product-level metadata (STAC attributes)
• .zmetadata — consolidated metadata
• Group directories (measurements, quality, conditions, …) with .zgroup
• Variable leaf directories with .zarray, .zattrs, and chunk files

Sample data is available from the EOPF Sentinel Zarr Samples Service.

Coastline data: Natural Earth 110m land (public domain).

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT)

at your option.