Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

OceanSODA GeoZarr Conversion

ESA

In order to display zarr files you hvae to manually build the pyramids similar to a cog file. You also have to link all of the data together, so that I viauliser keeps track of the projections and crs metadata. A common specification to work on this is GeoZarr - https://geozarr.org/ . Which is a composition of other existing conventions. To create a valid geozarr file we will follow the example of eopf-zarr. To convert a zarr file to a geozarr you have to :

  • Converert the dataset zarr into a tree, that represents the data at different scales

  • Specify how the groups link to each other

  • Specify the projection and transformation information for every grouop

We will follow the eopf-geozarr tree structure so that we can use the new open layers visualisations. This structure has a nested data tree structure where a dataset such as measurement/reflectance is a group in the tree has spatial, multiscale and projection infomation. Then the different subgroups are scaled versions of an original dataset, and each subgroup has spatial and projection information. The highest resolution subgroup is basically the same as teh orignal zarr file. We will use the downloaded OceanSODA dfco2 zarr file as an example.

Loading...

This example uses the downloaded OceanSODA dfco2 zarr, all source variables use the lat/lon spatial dimensions, EPSG:4326, degree coordinates, spatial chunks up to 512 pixels, and pyramid factors [1, 2, 4, 8].

The output is an EOPF-style GeoZarr hierarchy :

/dfco2
/dfco2/0
/dfco2/1
/dfco2/2
/dfco2/3
[                                        ] | 0% Completed | 102.98 ms
/Users/dean/code/ocean_hackathon/.pixi/envs/default/lib/python3.13/site-packages/zarr/api/asynchronous.py:231: ZarrUserWarning: Consolidated metadata is currently not part in the Zarr format 3 specification. It may not be supported by other zarr implementations and may change in the future.
  warnings.warn(
[########################################] | 100% Completed | 7.20 ss

Open the source Zarr

The downloaded input store already has time, lat, lon, and the dfco2 data variable. We open it lazily with xarray, attach the known CRS at dataset level, find every variable that uses the spatial dimensions, and convert the encoded nodata value to NaN before downsampling. That way coarsen(...).mean() ignores nodata pixels for every spatial variable.

{'source': '../downloaded_data/dfco2.zarr', 'data_variables': ['dfco2'], 'spatial_data_variables': ['dfco2'], 'shape': [1440, 720], 'crs': 'EPSG:4326', 'bounds': [-180.0, -90.0, 180.0, 90.0], 'resolution': [0.25, 0.25], 'nodata_written': -9999.0}

Build the pyramid levels

The native dataset is level 0. Each following level halves the previous level in both spatial dimensions. Using Dataset.coarsen(...).mean() averages all spatial variables together and keeps their coordinate arrays aligned.

[{'level': 0, 'factor': 1, 'variables': ['dfco2'], 'shape': [1440, 720], 'bounds': [-180.0, -90.0, 180.0, 90.0], 'resolution': [0.25, 0.25]}, {'level': 1, 'factor': 2, 'variables': ['dfco2'], 'shape': [720, 360], 'bounds': [-180.0, -90.0, 180.0, 90.0], 'resolution': [0.5, 0.5]}, {'level': 2, 'factor': 4, 'variables': ['dfco2'], 'shape': [360, 180], 'bounds': [-180.0, -90.0, 180.0, 90.0], 'resolution': [1.0, 1.0]}, {'level': 3, 'factor': 8, 'variables': ['dfco2'], 'shape': [180, 90], 'bounds': [-180.0, -90.0, 180.0, 90.0], 'resolution': [2.0, 2.0]}]

Write the GeoZarr hierarchy

Each pyramid level is written as its own Zarr group under /dfco2. The whole xarray Dataset is written at each level, so all source variables travel together with lat, lon, and spatial_ref metadata.

Most of the spatial metadata comes directly from rioxarray: rio.transform(), rio.bounds(), and the xarray dimension sizes.

[{'path': 'dfco2/0', 'factor': 1, 'variables': ['dfco2', 'spatial_ref'], 'shape': [720, 1440], 'transform': [0.25, 0.0, -180.0, 0.0, 0.25, -90.0], 'bbox': [-180.0, -90.0, 180.0, 90.0]}, {'path': 'dfco2/1', 'factor': 2, 'variables': ['dfco2', 'spatial_ref'], 'shape': [360, 720], 'transform': [0.5, 0.0, -180.0, 0.0, 0.5, -90.0], 'bbox': [-180.0, -90.0, 180.0, 90.0]}, {'path': 'dfco2/2', 'factor': 4, 'variables': ['dfco2', 'spatial_ref'], 'shape': [180, 360], 'transform': [1.0, 0.0, -180.0, 0.0, 1.0, -90.0], 'bbox': [-180.0, -90.0, 180.0, 90.0]}, {'path': 'dfco2/3', 'factor': 8, 'variables': ['dfco2', 'spatial_ref'], 'shape': [90, 180], 'transform': [2.0, 0.0, -180.0, 0.0, 2.0, -90.0], 'bbox': [-180.0, -90.0, 180.0, 90.0]}]

Add parent multiscale metadata

The parent /dfco2 group links the resolution groups together. It stores the GeoZarr conventions, the multiscale layout, the source file path, the source data variable names, and the CRS/spatial metadata shared by the pyramid.

{'zarr_conventions': [{'uuid': 'd35379db-88df-4056-af3a-620245f8e347', 'schema_url': 'https://raw.githubusercontent.com/zarr-conventions/multiscales/refs/tags/v1/schema.json', 'spec_url': 'https://github.com/zarr-conventions/multiscales/blob/v1/README.md', 'name': 'multiscales', 'description': 'Multiscale layout of zarr datasets'}, {'uuid': '689b58e2-cf7b-45e0-9fff-9cfc0883d6b4', 'schema_url': 'https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json', 'spec_url': 'https://github.com/zarr-conventions/spatial/blob/v1/README.md', 'name': 'spatial:', 'description': 'Spatial coordinate information'}, {'uuid': 'f17cb550-5864-4468-aeb7-f3180cfb622f', 'schema_url': 'https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json', 'spec_url': 'https://github.com/zarr-experimental/geo-proj/blob/v1/README.md', 'name': 'proj:', 'description': 'Coordinate reference system information for geospatial data'}], 'multiscales': {'layout': [{'asset': '0', 'spatial:shape': [720, 1440], 'spatial:transform': [0.25, 0.0, -180.0, 0.0, 0.25, -90.0]}, {'asset': '1', 'spatial:shape': [360, 720], 'spatial:transform': [0.5, 0.0, -180.0, 0.0, 0.5, -90.0], 'derived_from': '0', 'transform': {'scale': [2.0, 2.0], 'translation': [0.0, 0.0]}}, {'asset': '2', 'spatial:shape': [180, 360], 'spatial:transform': [1.0, 0.0, -180.0, 0.0, 1.0, -90.0], 'derived_from': '1', 'transform': {'scale': [2.0, 2.0], 'translation': [0.0, 0.0]}}, {'asset': '3', 'spatial:shape': [90, 180], 'spatial:transform': [2.0, 0.0, -180.0, 0.0, 2.0, -90.0], 'derived_from': '2', 'transform': {'scale': [2.0, 2.0], 'translation': [0.0, 0.0]}}], 'resampling_method': 'average'}, 'title': 'dfco2 GeoZarr pyramid', 'source_file': '../downloaded_data/dfco2.zarr', 'data_variables': ['dfco2'], 'spatial:dimensions': ['lat', 'lon'], 'spatial:bbox': [-180.0, -90.0, 180.0, 90.0], 'spatial:transform_type': 'affine', 'spatial:registration': 'pixel', 'proj:code': 'EPSG:4326'}

Validate using the geozarr_toolkit

GeoZarr multiscale group: /dfco2
Detected conventions: ['spatial', 'proj', 'multiscales']

Parent multiscale group validation:
  [PASS] spatial
  [PASS] proj
  [PASS] multiscales
  [PASS] zarr_conventions

Resolution group validation:

/dfco2/0
  detected: ['spatial', 'proj']
  [PASS] spatial
  [PASS] proj
  [PASS] zarr_conventions

/dfco2/1
  detected: ['spatial', 'proj']
  [PASS] spatial
  [PASS] proj
  [PASS] zarr_conventions

/dfco2/2
  detected: ['spatial', 'proj']
  [PASS] spatial
  [PASS] proj
  [PASS] zarr_conventions

/dfco2/3
  detected: ['spatial', 'proj']
  [PASS] spatial
  [PASS] proj
  [PASS] zarr_conventions
/Users/dean/code/ocean_hackathon/.pixi/envs/default/lib/python3.13/site-packages/zarr/api/asynchronous.py:231: ZarrUserWarning: Consolidated metadata is currently not part in the Zarr format 3 specification. It may not be supported by other zarr implementations and may change in the future.
  warnings.warn(
<Group file://oceansoda_dfco2_geozarr.zarr>
Loading...

Visualising GeoZarr data

To actually visualise the data you need a viewer that reads geozarr datasets such as open-layers 10.8 or above. And you need to serve the files through http or s3.

So, youll need:

1. Upload the data to an s3 server, or simulate an http server locally using python.

2. Create an html file that creates the open layers Geozar layer viewer that points to the file.

You can see the example visualiser for the javascript code needed: https://sunnydean.github.io/ocean_cubes_vis/ .

Next steps.

The code and data in this tutorial were examples. The OceanSoda project used them to create a library (https://github.com/lukegre/geozarr-pyramid-maker/tree/main) that tranformed their datasets into geozarr faster and with defaults suitable for global ocean datasets. Then the data can be visualised either by:

  1. The viewer in their library : https://lukegre.github.io/geozarr-pyramid-maker/viewer/

  2. Through open-layers: https://sunnydean.github.io/ocean_cubes_vis/?cube=https://s3.waw4-1.cloudferro.com/EarthCODE/OSCAssets/ocean-soda/OceanSODA_ETHZv2.r2026.GCB-fgco2-1982_2025-pyramid.zarr&variable=sfco2

  3. Through gridlook - https://gridlook.pages.dev/#https://s3.waw4-1.cloudferro.com/EarthCODE/OSCAssets/ocean-soda/OceanSODA_ETHZv2.r2026.GCB-fgco2-1982_2025-pyramid.zarr

  4. Others