ushow - Unstructured Data Viewer

The ushow command uses X11 to display data: usow_example

The uterm command displays data in the terminal using ASCII or UTF characters. uterm

A fast, ncview‑inspired visualization tool for structured and unstructured geoscientific data.

Features

Multiple formats: Supports netCDF, zarr, GRIB, and MITgcm binary (MDS)
Unified data handling: Treats all data as collections of points with lon/lat coordinates
Fast visualization: KDTree-based nearest-neighbor interpolation to regular grid
X11/Xaw interface: Works over SSH with X forwarding, dark/light theme
Terminal quick-look mode: Separate uterm binary with raw terminal interaction (no X is needed)
Animation support: Step through time dimensions
Multiple colormaps: viridis, hot, grayscale, plus the full cmocean set

Building

Requirements:

NetCDF-C library
eccodes for GRIB support (can be build without)
X11 development libraries (libX11, libXt, libXaw, libXmu, libXext, libSM, libICE)
C compiler (gcc or clang)

macOS (Homebrew + XQuartz)

Install dependencies:

brew install netcdf

For optional Zarr support:

brew install c-blosc lz4

For optional GRIB support:

brew install eccodes

For optional YAC interpolation support (professional-grade interpolation methods):

brew install open-mpi autoconf automake libtool

Then build YAXT and YAC from source (see YAC Interpolation below).

Install XQuartz for X11 support. After installation, the X11 libraries will be in /opt/X11.

Build:

make                  # Without zarr/grib support
make WITH_ZARR=1      # With zarr support
make WITH_GRIB=1      # With grib support
make WITH_YAC=1       # With YAC interpolation support
make uterm            # Build terminal viewer only

The Makefile auto-detects XQuartz at /opt/X11.

Linux (Debian/Ubuntu)

Install dependencies:

sudo apt-get install libnetcdf-dev libx11-dev libxt-dev libxaw7-dev libxmu-dev libxext-dev

For optional Zarr support:

sudo apt-get install libblosc-dev liblz4-dev

For optional GRIB support:

sudo apt-get install libeccodes-dev

For optional YAC interpolation support:

sudo apt-get install libopenmpi-dev autoconf automake libtool

Then build YAXT and YAC from source (see YAC Interpolation below).

Build:

make                  # Without zarr/grib support
make WITH_ZARR=1      # With zarr support
make WITH_GRIB=1      # With grib support
make WITH_YAC=1       # With YAC interpolation support
make uterm            # Build terminal viewer only

DKRZ Levante

On Levante, the Makefile automatically uses the DKRZ spack-installed libraries:

NetCDF-C from /sw/spack-levante/netcdf-c-4.8.1-qk24yp
X11 libraries from /sw/spack-levante/libx*
c-blosc and lz4 for Zarr support
eccodes for GRIB support

For basic builds (without YAC), no modules need to be loaded:

make                  # Without zarr/grib support
make WITH_ZARR=1      # With zarr support (uses system blosc/lz4)
make WITH_GRIB=1      # With grib support (uses system eccodes)

For YAC support, load the OpenMPI module (provides mpicc) and build YAXT/YAC first (see YAC Interpolation):

module load openmpi/4.1.2-gcc-11.2.0
make WITH_YAC=1       # With YAC interpolation support

Full build with all optional features:

module load openmpi/4.1.2-gcc-11.2.0
make WITH_GRIB=1 WITH_YAC=1 WITH_ZARR=1

The binary will have the library paths embedded (via rpath), so it runs without setting LD_LIBRARY_PATH.

YAC Interpolation

YAC (Yet Another Coupler) provides professional-grade interpolation methods beyond the built-in nearest-neighbor. It requires building two libraries from source: YAXT and YAC.

On DKRZ Levante, load the OpenMPI module first:

module load openmpi/4.1.2-gcc-11.2.0

1. Build YAXT

Get YAXT source from https://swprojects.dkrz.de/redmine/projects/yaxt (or git clone https://gitlab.dkrz.de/dkrz-sw/yaxt.git).

cd /path/to/yaxt
scripts/reconfigure
mkdir build && cd build
../configure \
  MPI_LAUNCH="mpirun --map-by socket:OVERSUBSCRIBE" \
  --prefix=$HOME/local/yaxt \
  --disable-shared \
  CC=mpicc FC=mpif90
make -j4
make install

On macOS, a cosmetic date: illegal time format warning during scripts/reconfigure can be ignored.

2. Build YAC

Get YAC source from https://gitlab.dkrz.de/dkrz-sw/yac (version 3.14.0 or later).

cd /path/to/yac
./autogen.sh
./configure \
  --prefix=$HOME/local/yac \
  --with-yaxt-root=$HOME/local/yaxt \
  --disable-mci --disable-utils --disable-examples \
  --disable-tools --disable-fortran-bindings \
  CC=mpicc
make -j4
make install

On macOS, if configure fails with a shell error, prefix the command with CONFIG_SHELL=/bin/bash /bin/bash.

3. Build ushow with YAC

make clean
make WITH_YAC=1                              # Auto-detects at ~/local/yac
make WITH_YAC=1 YAC_PREFIX=/custom/path/yac  # Custom install location

The Makefile uses pkg-config to find YAC, with a fallback to YAC_PREFIX (default: $HOME/local/yac).

AWI Albedo

On Albedo, dependencies are provided via environment modules and spack. First load spack and the NetCDF module:

module load spack
module load netcdf-c/4.8.1-gcc12.1.0

Load the X11 development libraries from spack:

spack load /eub564f /gyimrqa /dp6g46v /aioyu3n /mxnurir /l6kzj5s /x75vrux

Basic build:

make

For optional Zarr support, load c-blosc and lz4 (c-blosc may need to be installed into your home directory first with spack install c-blosc%gcc@12.1.0):

spack load c-blosc%gcc@12.1.0
spack load /ahjcumd   # lz4

For optional GRIB support, load eccodes:

spack load /fi5kc7g   # eccodes 2.34.0

Build with Zarr and GRIB support (explicit paths needed because the Makefile's auto-detection does not cover Albedo):

make WITH_ZARR=1 WITH_GRIB=1 \
  ZARR_CFLAGS="-DHAVE_ZARR -I$HOME/.spack/sw/c-blosc/1.21.5-rrsl7wt/include -I/albedo/soft/sw/spack-sw/lz4/1.9.3-ahjcumd/include" \
  ZARR_LIBS="-L$HOME/.spack/sw/c-blosc/1.21.5-rrsl7wt/lib64 -L/albedo/soft/sw/spack-sw/lz4/1.9.3-ahjcumd/lib -lblosc -llz4 -Wl,-rpath,$HOME/.spack/sw/c-blosc/1.21.5-rrsl7wt/lib64 -Wl,-rpath,/albedo/soft/sw/spack-sw/lz4/1.9.3-ahjcumd/lib"

The binary will have library paths embedded via rpath, so no LD_LIBRARY_PATH is needed at runtime.

Custom Library Paths

If your libraries are in non-standard locations, you can override the detection:

# Custom nc-config location
make NC_CONFIG=/path/to/nc-config

# Custom X11 prefix (libraries in $X11_PREFIX/lib, headers in $X11_PREFIX/include)
make X11_PREFIX=/path/to/x11

# Both
make NC_CONFIG=/path/to/nc-config X11_PREFIX=/path/to/x11

Verifying the Build

After building, verify all libraries are found:

ldd ./ushow          # Linux
otool -L ./ushow     # macOS

No libraries should show as "not found".

Usage

./ushow [options] <data_file.nc|data.zarr|data.grib|mitgcm_dir> [file2 ...]

Options:
  -m, --mesh <file>      Mesh file with coordinates (for unstructured data)
  -r, --resolution <deg> Target grid resolution in degrees (default: 1.0)
  -i, --influence <m>    Influence radius in meters (default: 80000)
  -d, --delay <ms>       Animation frame delay in milliseconds (default: 200)
  -p, --polygon-only     Skip regridding, use polygon mode only (faster)
  --box W,E,S,N          Regional box (e.g. --box -10,30,35,70 for Europe)
  --polar <pole>         Polar LAEA projection (north or south)
  --cutoff <deg>         Cutoff latitude for polar view (default: 60)
  --light                Use light theme (default: dark)
  --yac                  Use YAC interpolation with default method (avg_arith)
  --yac-method <method>  Use YAC interpolation with specific method;
                         click the method button in the GUI to cycle methods at runtime
  --yac-3d               Fractional fill-value masking for 3D variables
  -v, --version          Show version
  -h, --help             Show help message

Terminal quick-look mode:

./uterm [options] <data_file.nc|data.zarr|data.grib> [file2 ...]

Options (uterm):
  -m, --mesh <file>      Mesh file with coordinates
  -r, --resolution <deg> Target grid resolution in degrees (default: 1.0)
  -i, --influence <m>    Influence radius in meters (default: 80000)
  -d, --delay <ms>       Animation frame delay in milliseconds (default: 200)
  --chars <ramp>     ASCII ramp (default: " .:-=+*#%@")
  --render <mode>    Render mode: ascii | half | braille
  --color            Force ANSI color output
  --no-color         Disable ANSI color output
  --box W,E,S,N      Regional box (e.g. --box -10,30,35,70)
  --polar <pole>     Polar LAEA projection (north or south)
  --cutoff <deg>     Cutoff latitude for polar view (default: 60)
  --yac              Use YAC interpolation (default: avg_arith)
  --yac-method <m>   Use YAC interpolation method (requires WITH_YAC=1)
  --yac-3d           Fractional fill-value masking for 3D variables
  -v, --version          Show version
  -h, --help             Show help

Examples

FESOM unstructured data with separate mesh file:

./ushow temp.fesom.1964.nc -m fesom.mesh.diag.nc

Standard NetCDF with embedded coordinates:

./ushow sst.nc

Higher resolution display:

./ushow data.nc -r 0.5  # 0.5 degree grid (720x360)

Multi-file time concatenation (NetCDF):

./ushow "temp.fesom.*.nc" -m mesh.nc   # Glob pattern
./ushow file1.nc file2.nc -m mesh.nc   # Explicit files

Zarr store (requires `make WITH_ZARR=1

Ushow

Install / Use

README