Motivation
The guide currently covers each raster cloud-optimized format individually (COG, Zarr, Kerchunk, Cloud-Optimized HDF/NetCDF) and includes a Zarr + STAC cookbook on integration approaches; what is missing is a cross-cutting lens that explains, in neutral terms, what determines the theoretical floor of read latency for any of these formats, and how that floor shifts with layout, discovery, and codec choices. This proposal adds a top-level "Performance Fundamentals" page that gives readers a mental model of how the components of cloud-native raster architecture fit together, with the goal of alignment in cloud-native geospatial development: helping the community converge on which approaches are well-suited to which problem regions, by naming the constraints that actually move the optimum. The page does not advocate for any tool; it frames tools (lazycogs, VirtualiZarr + Icechunk, kerchunk, stackstac, odc-stac, async-geotiff) as instances of patterns, not as recommendations, since the optimal choice depends on what is being optimized for and which constraints are binding.
Where it goes
A new top-level page performance-fundamentals.qmd, sibling of overview.qmd and glossary.qmd, with sidebar position between Overview and the Formats section so readers encounter the lens before reading the raster format pages. Cross-links go from each raster format intro.qmd into the relevant section: COG intro links to the chunk granularity discussion (T_chunk floor), Zarr intro links to the discovery / precomputed-manifest discussion, Cloud-Optimized HDF/NetCDF intro links to the chunk granularity and codec sections, and the Zarr + STAC cookbook's data-consumers page links into the layout-scenarios section instead of duplicating it.
Page structure
The page is organized around a cost equation and three orthogonal axes that determine its terms.
1. The cost equation
Introduces T_total = T_catalog + T_header + T_chunk + T_decode for a cold sub-AOI read, and explains the parallel fan-out caveat (each term is set by the longest critical-path GET in its phase, not the sum). States explicitly when T_decode -> 0 is a fair assumption (cold S3 to compute, default codecs) and when it is not (heavy codecs like zstd-22, single-threaded decoders, same-region or VPC-endpoint bandwidth where the network term shrinks faster than the CPU term).
Anchor visual: reuse io_stack.svg, with cost-term annotations overlaid on each lane (discovery -> T_catalog, readers / formats -> T_header, filesystem -> T_chunk, codecs -> T_decode).
2. Layout, what the data looks like
Three reference layouts, walking through which terms dominate in each: harmonized swath (e.g. HLS-style MGRS-tiled scenes that share CRS and grid within a tile), non-harmonized swath (native sensor geometry across UTM zones, requiring reprojection), and single common grid (possibly with per-band time axes). Introduces chunk granularity (tile vs strip) as a format-induced floor that no tool can lift, since neither read path can manufacture sub-strip access out of a striped TIFF, and introduces cross-CRS unification as the constraint that puts T_warp on the read path or pushes a materialization step into ingest.
Anchor visual: new layout-comparison SVG (three side-by-side panels) to be drafted after direction is approved.
3. Discovery, how you find what you need
The T_catalog + T_header axis, with two patterns at opposite ends: pay-at-read (catalog query plus per-file index discovery on every cold session, e.g. STAC plus IFD reads via async-geotiff), and pay-at-ingest (precomputed manifest such as Icechunk or kerchunk that bakes index resolution into a single load, valid across sessions and language runtimes). Explains why this is not a tool-vs-tool question but a question about where in the data lifecycle index work happens, with trade-offs in both directions: manifest staleness on archive growth, ingest cost, non-Python client portability, fresh-process cold reads.
Anchor visual: new pay-at-read vs pay-at-ingest flow diagram.
4. Codec and filter, what you actually transfer and decode
The T_chunk + T_decode Pareto optimizations: stronger compression cuts the network term but raises the CPU term, and the reachable frontier is constrained by which codecs are available for the format. A non-COG TIFF can use JPEG, a Zarr can use zstd or blosc, a COG cannot use blosc; that format-conditional codec menu is what sets the achievable frontier, not the tool reading the data. Pre-filters (bitround, quantize, scale-offset, delta) push the frontier outward by reducing bytes-pulled with negligible decode cost, and are first-class for cloud-native geospatial workloads, not specialized scientific tooling.
Anchor visuals: reuse codec_ecosystem.svg, plus a new Pareto-frontier SVG plotting codec families on compression ratio vs decode time axes with format-availability shading.
5. Where the walls are
Physical and format-induced limits no tool can lift: RTT to object storage (~30 to 60 ms per cold S3 GET), strip granularity in non-tiled TIFFs (megabytes pulled for kilobytes wanted), connection-pool saturation at large N (the parallel fan-out assumption breaks), cross-CRS unification at the array level (cannot be virtualized; requires either read-time warp or ingest-time materialization), and single-threaded decode under the GIL. Each is framed as an invariant, not a tooling shortcoming, and this section is where the alignment goal pays off: separating physical limits from format-induced limits from tooling-induced limits is what lets the community discuss approaches without tribalism.
Anchor visual: new walls-map SVG.
6. Putting it together
For each combination of (layout, discovery, codec) constraints, where does the floor sit and which patterns fit it? This section names tools across the design space as instances of patterns, identifying regions where current tooling is well-matched and regions where it is not, with the intent of making the community design conversation concrete: instead of "which tool is best", the question becomes "which region of the design space is each tool optimized for, and which regions are underserved".
Anchor visual: new design-space map SVG.
SVG inventory
Reused (embedded inline above): io_stack.svg (section 1) and codec_ecosystem.svg (section 4). These are the two anchor visuals shared with this proposal so reviewers can see the visual style being proposed.
New, to be drafted after direction is approved: N1 cost-strip diagram with parallel fan-out (section 1); N2 three-layout comparison panel (section 2); N3 tile vs strip chunk granularity, same AOI overlaid (section 2); N4 pay-at-read vs pay-at-ingest flow (section 3); N5 codec Pareto frontier (section 4); N6 walls map (section 5); N7 design-space map (section 6). All new SVGs hand-authored in the style of io_stack.svg and codec_ecosystem.svg, no Mermaid or auto-generated diagrams.
Framing principles
Neutral voice: tools appear as instances of patterns, not as recommendations, and the cost equation is the artifact (tool comparisons are downstream of it). The three axes (layout, discovery, codec) are treated as orthogonal, not ranked, since a reader optimizing for cold-cache latency, a reader optimizing for ingestion budget, and a reader optimizing for non-Python clients land on different optima, and the page makes this explicit. The walls section is the rigor anchor: it names physical and format-induced limits explicitly so the community can agree on what is genuinely constrained vs what is open to design. The codec dimension is treated as co-equal with layout and discovery, not as a free implementation detail; the "decode is free" assumption is stated as a condition, not a baseline.
Out of scope
Vector formats (GeoParquet, FlatGeobuf, PMTiles) and point-cloud formats (COPC); benchmarks of specific tools (the page is about cost floors and what sets them, not measured tool performance); recommendations for archive producers about format choice (that belongs in the data-producers cookbook page); implementation details of any single tool (the page references tools by role, not by API).
This page covers cloud-optimized raster formats (COG, Zarr, Kerchunk, Cloud-Optimized HDF/NetCDF). Vector formats (GeoParquet, FlatGeobuf, PMTiles) and point-cloud formats (COPC) are out of scope; the cost equation introduced here generalizes to those domains, but the layout axes and walls discussion are raster-specific and would blur important distinctions if mixed in. A parallel page covering vector and point-cloud cost floors is a reasonable follow-up but not part of this proposal.
Credit
I was introduced to the speed of light concept by Ryan Abernathey and Tom Augspurger
Motivation
The guide currently covers each raster cloud-optimized format individually (COG, Zarr, Kerchunk, Cloud-Optimized HDF/NetCDF) and includes a Zarr + STAC cookbook on integration approaches; what is missing is a cross-cutting lens that explains, in neutral terms, what determines the theoretical floor of read latency for any of these formats, and how that floor shifts with layout, discovery, and codec choices. This proposal adds a top-level "Performance Fundamentals" page that gives readers a mental model of how the components of cloud-native raster architecture fit together, with the goal of alignment in cloud-native geospatial development: helping the community converge on which approaches are well-suited to which problem regions, by naming the constraints that actually move the optimum. The page does not advocate for any tool; it frames tools (lazycogs, VirtualiZarr + Icechunk, kerchunk, stackstac, odc-stac, async-geotiff) as instances of patterns, not as recommendations, since the optimal choice depends on what is being optimized for and which constraints are binding.
Where it goes
A new top-level page
performance-fundamentals.qmd, sibling ofoverview.qmdandglossary.qmd, with sidebar position between Overview and the Formats section so readers encounter the lens before reading the raster format pages. Cross-links go from each raster formatintro.qmdinto the relevant section: COG intro links to the chunk granularity discussion (T_chunkfloor), Zarr intro links to the discovery / precomputed-manifest discussion, Cloud-Optimized HDF/NetCDF intro links to the chunk granularity and codec sections, and the Zarr + STAC cookbook's data-consumers page links into the layout-scenarios section instead of duplicating it.Page structure
The page is organized around a cost equation and three orthogonal axes that determine its terms.
1. The cost equation
Introduces
T_total = T_catalog + T_header + T_chunk + T_decodefor a cold sub-AOI read, and explains the parallel fan-out caveat (each term is set by the longest critical-path GET in its phase, not the sum). States explicitly whenT_decode -> 0is a fair assumption (cold S3 to compute, default codecs) and when it is not (heavy codecs like zstd-22, single-threaded decoders, same-region or VPC-endpoint bandwidth where the network term shrinks faster than the CPU term).Anchor visual: reuse
io_stack.svg, with cost-term annotations overlaid on each lane (discovery ->T_catalog, readers / formats ->T_header, filesystem ->T_chunk, codecs ->T_decode).2. Layout, what the data looks like
Three reference layouts, walking through which terms dominate in each: harmonized swath (e.g. HLS-style MGRS-tiled scenes that share CRS and grid within a tile), non-harmonized swath (native sensor geometry across UTM zones, requiring reprojection), and single common grid (possibly with per-band time axes). Introduces chunk granularity (tile vs strip) as a format-induced floor that no tool can lift, since neither read path can manufacture sub-strip access out of a striped TIFF, and introduces cross-CRS unification as the constraint that puts
T_warpon the read path or pushes a materialization step into ingest.Anchor visual: new layout-comparison SVG (three side-by-side panels) to be drafted after direction is approved.
3. Discovery, how you find what you need
The
T_catalog + T_headeraxis, with two patterns at opposite ends: pay-at-read (catalog query plus per-file index discovery on every cold session, e.g. STAC plus IFD reads via async-geotiff), and pay-at-ingest (precomputed manifest such as Icechunk or kerchunk that bakes index resolution into a single load, valid across sessions and language runtimes). Explains why this is not a tool-vs-tool question but a question about where in the data lifecycle index work happens, with trade-offs in both directions: manifest staleness on archive growth, ingest cost, non-Python client portability, fresh-process cold reads.Anchor visual: new pay-at-read vs pay-at-ingest flow diagram.
4. Codec and filter, what you actually transfer and decode
The
T_chunk + T_decodePareto optimizations: stronger compression cuts the network term but raises the CPU term, and the reachable frontier is constrained by which codecs are available for the format. A non-COG TIFF can use JPEG, a Zarr can use zstd or blosc, a COG cannot use blosc; that format-conditional codec menu is what sets the achievable frontier, not the tool reading the data. Pre-filters (bitround, quantize, scale-offset, delta) push the frontier outward by reducing bytes-pulled with negligible decode cost, and are first-class for cloud-native geospatial workloads, not specialized scientific tooling.Anchor visuals: reuse
codec_ecosystem.svg, plus a new Pareto-frontier SVG plotting codec families on compression ratio vs decode time axes with format-availability shading.5. Where the walls are
Physical and format-induced limits no tool can lift: RTT to object storage (~30 to 60 ms per cold S3 GET), strip granularity in non-tiled TIFFs (megabytes pulled for kilobytes wanted), connection-pool saturation at large N (the parallel fan-out assumption breaks), cross-CRS unification at the array level (cannot be virtualized; requires either read-time warp or ingest-time materialization), and single-threaded decode under the GIL. Each is framed as an invariant, not a tooling shortcoming, and this section is where the alignment goal pays off: separating physical limits from format-induced limits from tooling-induced limits is what lets the community discuss approaches without tribalism.
Anchor visual: new walls-map SVG.
6. Putting it together
For each combination of (layout, discovery, codec) constraints, where does the floor sit and which patterns fit it? This section names tools across the design space as instances of patterns, identifying regions where current tooling is well-matched and regions where it is not, with the intent of making the community design conversation concrete: instead of "which tool is best", the question becomes "which region of the design space is each tool optimized for, and which regions are underserved".
Anchor visual: new design-space map SVG.
SVG inventory
Reused (embedded inline above):
io_stack.svg(section 1) andcodec_ecosystem.svg(section 4). These are the two anchor visuals shared with this proposal so reviewers can see the visual style being proposed.New, to be drafted after direction is approved: N1 cost-strip diagram with parallel fan-out (section 1); N2 three-layout comparison panel (section 2); N3 tile vs strip chunk granularity, same AOI overlaid (section 2); N4 pay-at-read vs pay-at-ingest flow (section 3); N5 codec Pareto frontier (section 4); N6 walls map (section 5); N7 design-space map (section 6). All new SVGs hand-authored in the style of
io_stack.svgandcodec_ecosystem.svg, no Mermaid or auto-generated diagrams.Framing principles
Neutral voice: tools appear as instances of patterns, not as recommendations, and the cost equation is the artifact (tool comparisons are downstream of it). The three axes (layout, discovery, codec) are treated as orthogonal, not ranked, since a reader optimizing for cold-cache latency, a reader optimizing for ingestion budget, and a reader optimizing for non-Python clients land on different optima, and the page makes this explicit. The walls section is the rigor anchor: it names physical and format-induced limits explicitly so the community can agree on what is genuinely constrained vs what is open to design. The codec dimension is treated as co-equal with layout and discovery, not as a free implementation detail; the "decode is free" assumption is stated as a condition, not a baseline.
Out of scope
Vector formats (GeoParquet, FlatGeobuf, PMTiles) and point-cloud formats (COPC); benchmarks of specific tools (the page is about cost floors and what sets them, not measured tool performance); recommendations for archive producers about format choice (that belongs in the data-producers cookbook page); implementation details of any single tool (the page references tools by role, not by API).
This page covers cloud-optimized raster formats (COG, Zarr, Kerchunk, Cloud-Optimized HDF/NetCDF). Vector formats (GeoParquet, FlatGeobuf, PMTiles) and point-cloud formats (COPC) are out of scope; the cost equation introduced here generalizes to those domains, but the layout axes and walls discussion are raster-specific and would blur important distinctions if mixed in. A parallel page covering vector and point-cloud cost floors is a reasonable follow-up but not part of this proposal.
Credit
I was introduced to the speed of light concept by Ryan Abernathey and Tom Augspurger