Add page on WOZ (#9)

maxrjones · web-flow · commit be0f5ee2da82 · 2025-03-10T17:53:05.000-04:00
diff --git a/README.md b/README.md
@@ -6,65 +6,7 @@ This repository contains in-progress work towards GeoZarr examples. If useful, t
 [Cloud Optimized Geospatial Formats Guide](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide) or the [GeoZarr spec](https://github.com/zarr-developers/geozarr-spec)
 repository.
 
-## Goals
-
-- Demonstrate how to write GeoZarr compliant data.
-    - Provide a demonstration of writing only the MUST include metadata (most importantly grid_mapping).
-    - Provide a demonstration of writing data with a WebMercatorQuad TMS.
-    - Provide a demonstration of writing data with a Custom TMS that maps to simple downsampled version of the raw data, without any change in extent or CRS.
-    - Provide a demonstration of storing raw data in NetCDF and overviews in native Zarr, with a virtual GeoZarr compliant entrypoint.
-- Demonstrate how to read GeoZarr compliant data.
-    - Provide a demonstration of reading in GeoZarr data with only MUST include metadata.
-    - Provide a demonstration of reading in GeoZarr data with raw data and overviews in "native" zarr.
-    - Provide a demonstration of reading in GeoZarr data with raw data in archival formats and overviews in "native" zarr via a single virtual GeoZarr compliant entrypoint.
-- Demonstrate how to work with GeoZarr data in Xarray using the prototypes for flexible coordinates and the xproj extension.
-    - Demonstrate whether the GeoZarr v0.4 and flexible coordinates solve the limitations highlighted in https://discourse.pangeo.io/t/example-which-highlights-the-limitations-of-netcdf-style-coordinates-for-large-geospatial-rasters/4140.
-- Demonstrate how GeoZarr would need to be adapted for Zarr specification v3.
-
-## Feedback cadence
-
-We will provide progress and solicit community feedback during the following events:
-
-- March 05, 2025 GeoZarr Monthly Community Meeting
-- March 05, 2025 Pangeo Community Meeting
-- April 02, 2025 GeoZarr Monthly Community Meeting
-- April 02, 2025 Pangeo Community Meeting
-- April 02, 2025 posts on Pangeo and CNG forums
-- EGU 2025 Conference
-- CNG 2025 Conference
-
-## FAQ
-
-### What's the status of GeoZarr?
-
-GeoZarr is currently being developed as a [Open Geospatial Consortium Standard](https://www.ogc.org/announcement/ogc-forms-new-geozarr-standards-working-group-to-establish-a-zarr-encoding-for-geospatial-data/).
-There is a [GeoZarr Standards Working Group](https://portal.ogc.org/index.php?m=public&orderby=default&tab=7) that meets once a month. We now have
-experimental prototypes of [all](https://github.com/pydata/xarray/pull/9543) [of](https://github.com/zarr-developers/VirtualiZarr/pull/271) [the](https://xproj.readthedocs.io/en/latest/usage.html)
-[pieces](https://zarr.dev/blog/zarr-python-3-release/) to move GeoZarr out of a discussion phase and into a demonstration phase. This repository stems from the hope that building demonstrations will lead to
-adoption, iteration, and formalization of a stable GeoZarr specification.
-
-### How does Zarr Specification V3 spec influence GeoZarr?
-
-The GeoZarr spec is designed for Zarr specification version 2. This repository will demonstrate how the differences between Zarr format 2 and Zarr format 3 would
-influence GeoZarr. My expectation is that there is not much difference in the metadata requirements between the two formats. However, best practices will likely be impacted by new features available
-in Zarr specification version 3 (e.g., sharding).
-
-### How does the release of Zarr-Python 3 influence GeoZarr?
-
-The Zarr-Python 3 release will help GeoZarr users through its increased performance, modernized codebase, and support for extensions. But, it only really interacts with the GeoZarr spec in-so-far
-as Zarr-Python 3 supports Zarr specification V3 (see prior question on "How does Zarr Specification V3 spec influence GeoZarr").
-
-### What is the relationship between GeoZarr and Web-Optimized-Zarr?
-
-Web-Optimized Zarr (WOZ) right now is just an idea. I hope that the term WOZ will promote the use of overviews in GeoZarr (which are optional in the core spec) and familiarize practitioners with the concept of storing full-resolution "archival" versions in other file formats and reduced resolution versions in "native" zarr. GeoZarr would allow a single "web-optimized" entrypoint to both via virtualization. A prototype will part of this repository.
-
-Depending on initial experimentation, WOZ may involve additional restrictions on top of the GeoZarr spec such as a minimum and maximum chunk size, sharding requirements for V3 data, compression requirements, encoding requirements around, for example, fill values, and rendering metadata (e.g., min and max values).
-
-## References
-
-- [GeoZarr validator](https://github.com/briannapagan/geozarr-validator) by [@briannapagan](https://github.com/briannapagan) [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/)
-- [GeoZarr spec](https://github.com/zarr-developers/geozarr-spec) [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/)
-- Quarto configuration based on [Cloud Native Geospatial Formats Guide](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide) and [Tile Benchmarking](https://developmentseed.org/tile-benchmarking/).
+More information is available in the [GeoZarr examples website](https://developmentseed.org/geozarr-examples/).
 
 ## License
 
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -15,8 +15,12 @@ website:
     contents:
       - href: index.qmd
         text: Home
-      - href: diagram.qmd
+      - href: spec-diagram.qmd
         text: Visual explainer
+      - href: web-optimized-zarr.qmd
+        text: Web-optimized Zarr (WOZ)
+      - href: woz-diagram.qmd
+        text: Visual WOZ comparison
       - href: slides.qmd
         text: Slides
       - section: Pre-requisites
diff --git a/docs/index.qmd b/docs/index.qmd
@@ -58,9 +58,7 @@ as Zarr-Python 3 supports Zarr specification V3 (see prior question on "How does
 
 ### What is the relationship between GeoZarr and Web-Optimized-Zarr?
 
-Web-Optimized Zarr (WOZ) right now is just an idea. I hope that the term WOZ will promote the use of overviews in GeoZarr (which are optional in the core spec) and familiarize practitioners with the concept of storing full-resolution "archival" versions in other file formats and reduced resolution versions in "native" zarr. GeoZarr would allow a single "web-optimized" entrypoint to both via virtualization. A prototype will part of this repository.
-
-Depending on initial experimentation, WOZ may involve additional restrictions on top of the GeoZarr spec such as a minimum and maximum chunk size, sharding requirements for V3 data, compression requirements, encoding requirements around, for example, fill values, and rendering metadata (e.g., min and max values).
+Please see the [web-optimized Zarr overview page](web-optimized-zarr.qmd).
 
 ## References/Acknowledgements
 
diff --git a/docs/spec-diagram.qmd b/docs/spec-diagram.qmd
@@ -1,2 +1 @@
-
 <iframe src="https://link.excalidraw.com/readonly/22k271SZdWUXq2hKxPZA" width="100%" height="100%" style="border: none;"></iframe>
diff --git a/docs/web-optimized-zarr.qmd b/docs/web-optimized-zarr.qmd
@@ -0,0 +1,20 @@
+# Web-optimized Zarr
+
+Web-optimized zarr provides a set of additional recommendations on top of the GeoZarr specification for optimal browser-based analysis and visualization. The specific recommendations are still
+under development. We anticipate the following to be included as web-optimized Zarr recommendations:
+
+1. The WOZ MUST be chunked in either the spatial or temporal dimensions. The WOZ guide will include a reference to a separate document for recommended chunking schemes and compression algorithms for different use-cases, which will be updated as browsers and infrastructures change.
+2. The dimension order for 2-dimensional data MUST be (y, x) (or the equivalent spatial dimension names) for maximum interoperability.
+3. The dimension order for 3-dimensional data MUST be (time, y, x) (or the equivalent spatial dimension names) for maximum interoperability.
+4. The WOZ MUST include multi-scales.
+5. The WOZ may contain full-resolution "archival" versions in other file formats and reduced resolution versions in "native" zarr.
+
+The following criteria may be included after further evaluation:
+
+1. The multi-scales must align with a well-known TMS.
+2. The WOZ should include sharding to allow clients to request smaller individual chunks or larger shards.
+3. The multi-scales should contain rendering metadata (e.g., min and max values and preferred color mapping representations).
+
+These recommendations will be expanded or updated after additional experimentation.
+
+For a graphical depiction of how WOZ compares to GeoZarr, please see [the excalidraw diagram](woz-diagram.qmd).
diff --git a/docs/woz-diagram.qmd b/docs/woz-diagram.qmd
@@ -0,0 +1 @@
+<iframe src="https://link.excalidraw.com/readonly/zNFS3VCbHRF6f1e3T53E" width="100%" height="100%" style="border: none;"></iframe>

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1 @@`
`1`		`-`
`2`	`1`	`<iframe src="https://link.excalidraw.com/readonly/22k271SZdWUXq2hKxPZA" width="100%" height="100%" style="border: none;"></iframe>`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+<iframe src="https://link.excalidraw.com/readonly/zNFS3VCbHRF6f1e3T53E" width="100%" height="100%" style="border: none;"></iframe>`