### Run setup tests

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Execute setup tests to create local datasets, which can be deployed via the CLI.

```sh
uv run pytest --setup
```

--------------------------------

### Start xpublish-tiles Server

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/examples/maplibre/README.md

Run this command to start the xpublish-tiles server with specified dataset and group.

```bash
uv run xpublish-tiles --dataset=earthmover-public/gfs --group=solar
```

--------------------------------

### List Tilesets Response Example

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Example JSON response structure for the GET /tiles/ endpoint, showing tileset metadata and available links.

```json
{
  "tilesets": [
    {
      "title": "Air Temperature",
      "dataType": "map",
      "crs": "http://www.opengis.net/gml/srs/epsg.xml#3857",
      "tileMatrixSetURI": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
      "links": [
        {
          "href": "/tiles/WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}?variables=air",
          "rel": "item",
          "type": "image/png",
          "templated": true
        },
        {
          "href": "/tiles/WebMercatorQuad/tilejson.json?variables=air",
          "rel": "describedBy",
          "type": "application/json"
        }
      ],
      "layers": [
        {
          "id": "air",
          "title": "Air Temperature",
          "dataType": "map",
          "crs": {...},
          "dimensions": [
            {
              "name": "time",
              "type": "temporal",
              "extent": ["2013-01-01T00:00:00", "2014-12-31T23:00:00"],
              "default": "2013-01-01T00:00:00"
            },
            ...
          ],
          "minTileMatrix": "0",
          "maxTileMatrix": "14",
          "style": {
            "id": "raster/default",
            "title": "Raster - Default"
          },
          "links": [
            {
              "href": "/tiles/WebMercatorQuad/tilejson.json?variables=air",
              "rel": "describedBy"
            },
            {
              "href": "/tiles/legend?variables=air&style=raster/viridis&colorscalerange=280,300",
              "rel": "ogc-rel:legend"
            }
          ]
        }
      ]
    },
    ...
  ],
  "links": [...]
}
```

--------------------------------

### CLI Execution Examples

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Various command-line examples for serving different dataset types, configuring ports, and running performance benchmarks.

```sh
# Serve synthetic global dataset on default port 8080
xpublish-tiles

# Serve air temperature tutorial dataset on port 9000
xpublish-tiles --port 9000 --dataset air

# Serve built-in test datasets
xpublish-tiles --dataset hrrr
xpublish-tiles --dataset para
xpublish-tiles --dataset eu3035_hires

# Load xarray tutorial datasets
xpublish-tiles --dataset xarray://rasm
xpublish-tiles --dataset xarray://ersstv5

# Serve locally stored datasets (first create them with `uv run pytest --setup`)
xpublish-tiles --dataset local://ifs
xpublish-tiles --dataset local://para_hires

# Serve icechunk data from custom path
xpublish-tiles --dataset icechunk:///path/to/my/repo --group my_dataset

# Serve standard Zarr store
xpublish-tiles --dataset zarr:///path/to/data.zarr

# Serve Zarr store with a specific group
xpublish-tiles --dataset zarr:///path/to/data.zarr --group subgroup

# Serve local Zarr store using zarr+file protocol
xpublish-tiles --dataset zarr+file:///path/to/data.zarr

# Serve local NetCDF file
xpublish-tiles --dataset netcdf+file:///path/to/data.nc

# Serve NetCDF file with a specific group
xpublish-tiles --dataset netcdf+file:///path/to/data.nc --group subgroup

# Serve Icechunk repository
xpublish-tiles --dataset icechunk:///path/to/icechunk/repo --group my_dataset

# Serve Arraylake dataset with specific branch and group
xpublish-tiles --dataset earthmover-public/aifs-outputs --branch main --group 2025-04-01/12z

# Run benchmark with a specific dataset
xpublish-tiles --dataset local://para_hires --spy

# Run benchmark with custom concurrency and against Arraylake production
xpublish-tiles --dataset para --spy --concurrency 20 --where arraylake-prod

# Run benchmark suite for all local datasets (creates tabulated results)
xpublish-tiles --bench-suite

# Run benchmark suite for all local datasets and compare with titiler
xpublish-tiles --bench-suite --titiler

# Enable debug logging
xpublish-tiles --dataset hrrr --log-level debug
```

--------------------------------

### Skip Setup Tests

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/tests/README.md

Run tests without performing the setup phase by omitting the --setup flag. This will skip all dataset creation tests.

```bash
# Skip setup tests (default behavior)
uv run pytest tests/test_arraylake.py --where=local  # All tests skipped
```

--------------------------------

### Example Requests for Raster Tile Endpoint

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Various HTTP GET requests demonstrating how to fetch tiles with custom styles, dimensions, color scaling, and output formats.

```http
# Basic tile with default style
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature

# Custom color range
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&colorscalerange=280,300

# Custom colormap
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&style=raster/custom&colormap={"0":"#FF0000","255":"#0000FF"}

# With dimension selection
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&time=2020-01-15T12:00:00

# Nearest time
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&time=nearest::2020-01-15T06:00:00

# Out-of-range colors
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&colorscalerange=280,300&abovemaxcolor=red&belowmincolor=transparent

# High DPI tile (512×512)
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&width=512&height=512

# JPEG output
GET /tiles/WebMercatorQuad/4/4/14?variables=temperature&f=jpeg

# Render errors as image
GET /tiles/WebMercatorQuad/4/4/14?variables=bad_var&render_errors=true
```

--------------------------------

### Handle BenchmarkImportError

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Example of catching the benchmark import error to provide installation instructions to the user.

```python
from xpublish_tiles.lib import BenchmarkImportError

try:
    run_benchmark(dataset)
except BenchmarkImportError:
    # Suggest installation
    print("Please install xpublish-tiles[testing] to use benchmarks")
```

--------------------------------

### TileJSON Response Example

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Example JSON response for the GET /tiles/{tileMatrixSetId}/tilejson.json endpoint, conforming to the TileJSON 3.0.0 specification.

```json
{
  "tilejson": "3.0.0",
  "name": "Air Temperature",
  "description": "...",
  "tiles": [
    "http://localhost:8080/tiles/WebMercatorQuad/{z}/{y}/{x}?variables=air&style=raster/viridis&colorscalerange=280,300"
  ],
  "minzoom": 0,
  "maxzoom": 14,
  "bounds": [-180, -85.051129, 180, 85.051129],
  "center": [0, 0, 2],
  "attribution": "...",
  "legend": "http://localhost:8080/tiles/legend?variables=air&style=raster/viridis&colorscalerange=280,300"
}
```

--------------------------------

### GET /tiles/

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Lists all available tilesets.

```APIDOC
## GET /tiles/

### Description
Lists all available tilesets accessible through the service.

### Method
GET

### Endpoint
/tiles/
```

--------------------------------

### CubedSphere Example Dataset Structure

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-grids.md

Example dimensions and coordinate structure for a CubedSphere dataset.

```xarray
Dimensions: {face: 6, y: 48, x: 48}
Coordinates:
  corner_lons (face, y, x, ...) float32 ...
  corner_lats (face, y, x, ...) float32 ...
Data variables:
  temperature (face, y, x) float32 ...
```

--------------------------------

### Configure Dataset Creation Tests

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/tests/README.md

Use these arguments to configure the dataset creation tests. Specify the storage backend and whether to enable setup tests.

```bash
# Required arguments
--where {local,arraylake}    # Storage backend
--setup                      # Enable dataset creation tests

# Optional arguments
--prefix PATH                # Custom storage path (has defaults)
```

--------------------------------

### GET /tiles/tileMatrixSets

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Lists all available tile matrix sets.

```APIDOC
## GET /tiles/tileMatrixSets

### Description
Retrieves a list of all available tile matrix sets defined in the service.

### Method
GET

### Endpoint
/tiles/tileMatrixSets
```

--------------------------------

### Example Requests for /tiles/legend

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Common request patterns for retrieving legends in different formats and configurations.

```text
# Vertical PNG legend
GET /tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=280,300

# Horizontal JPEG legend
GET /tiles/legend?variables=temperature&vertical=false&f=jpeg&width=600&height=80

# JSON legend data for client-side rendering
GET /tiles/legend?variables=temperature&f=json&colorscalerange=280,300

# Custom colors
GET /tiles/legend?variables=temperature&background_color=%23F0F0F0&text_color=black

# Categorical legend
GET /tiles/legend?variables=land_cover&style=raster/tab10
```

--------------------------------

### Example tile URL

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

A sample URL structure for requesting tiles from the server, where 4/4/14 represents {z}/{y}/{x} coordinates.

```text
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=2t&style=raster/viridis&colorscalerange=280,300&width=256&height=256&valid_time=2025-04-03T06:00:00
```

--------------------------------

### GET /tiles/conformance

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Retrieves the OGC API conformance information for the service.

```APIDOC
## GET /tiles/conformance

### Description
Returns the OGC API conformance classes supported by the service.

### Method
GET

### Endpoint
/tiles/conformance
```

--------------------------------

### Validate style query parameters

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-validators.md

Examples demonstrating successful parsing and error handling for various style inputs.

```python
validate_style("raster/viridis")      # → ("raster", "viridis")
validate_style("polygons/default")    # → ("polygons", "default")
validate_style(None)                  # → None
validate_style("invalid")             # → ValueError: format incorrect
validate_style("raster/nonexistent")  # → ValueError: variant not supported
```

--------------------------------

### Validate Overview Selection Strategy Usage Examples

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-validators.md

Demonstrates how the validator handles valid string inputs, None, and invalid strategy names.

```python
validate_overview_selection_strategy("nearest")   # → OverviewSelectionStrategy.NEAREST
validate_overview_selection_strategy("COARSER")   # → OverviewSelectionStrategy.COARSER
validate_overview_selection_strategy(None)        # → None
validate_overview_selection_strategy("invalid")   # → ValueError
```

--------------------------------

### Render error image usage example

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Demonstrates generating a 256x256 PNG error tile.

```python
from xpublish_tiles.render import render_error_image
from xpublish_tiles.types import ImageFormat

buffer = render_error_image(
    "Variable not found", 
    width=256, 
    height=256, 
    format=ImageFormat.PNG
)
# buffer now contains a 256x256 PNG with error message
```

--------------------------------

### Example Usage of validate_image_format

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-validators.md

Demonstrates how to use validate_image_format with various inputs including MIME types, shorthand, and invalid formats.

```python
validate_image_format("image/png")    # → ImageFormat.PNG
validate_image_format("jpeg")         # → ImageFormat.JPEG
validate_image_format(None)           # → None
validate_image_format("gif")          # → ValueError
```

--------------------------------

### GET /tiles/{tms}/{z}/{y}/{x}

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Renders a specific map tile.

```APIDOC
## GET /tiles/{tms}/{z}/{y}/{x}

### Description
Generates and returns a rendered map tile for the specified coordinates and tile matrix set.

### Method
GET

### Endpoint
/tiles/{tms}/{z}/{y}/{x}

### Parameters
#### Path Parameters
- **tms** (string) - Required - The tile matrix set identifier.
- **z** (integer) - Required - The zoom level.
- **y** (integer) - Required - The Y coordinate.
- **x** (integer) - Required - The X coordinate.
```

--------------------------------

### GET /tiles/legend

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Renders or describes the legend for a tileset.

```APIDOC
## GET /tiles/legend

### Description
Returns the legend information or a rendered legend image for the tileset.

### Method
GET

### Endpoint
/tiles/legend
```

--------------------------------

### Retrieve variable legends

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Examples of requesting legends with various styling parameters and output formats.

```http
# Vertical, transparent background
http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=280,300

# Horizontal
http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=280,300&vertical=false

# Map overlay: half-opaque dark panel with white text
http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=280,300&background_color=%2300000080&text_color=white

# JSON color stops (build your own legend client-side)
http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=280,300&f=application/json
```

--------------------------------

### Access Configuration Values

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Retrieve configuration values using standard dictionary-like access or the get method.

```python
value = config.get("option_name")
value = config["option_name"]  # dict-like access
```

--------------------------------

### GET /tiles/tileMatrixSets/{id}

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Retrieves the definition of a specific tile matrix set.

```APIDOC
## GET /tiles/tileMatrixSets/{id}

### Description
Returns the definition for a specific tile matrix set identified by the provided ID.

### Method
GET

### Endpoint
/tiles/tileMatrixSets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the tile matrix set.
```

--------------------------------

### Perform dimension selection

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Examples of using selection methods like nearest, ffill, and exact match for dimension filtering.

```bash
# Select nearest time to 2000-01-01T04:00
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=temperature&time=nearest::2000-01-01T04:00

# Exact match (implicit)
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=temperature&time=2000-01-01T00:00

# Forward fill for missing timestep
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=temperature&time=ffill::2000-01-01T03:30

# Multiple dimension selections with different methods
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?time=nearest::2000-01-01T04:00&pressure_level=500

# Using timedelta selections
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=temperature&time=nearest::2000-01-01T04:00&step=pad::3h
```

--------------------------------

### Configure Out-of-Range Colors via URL

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Example URL parameter usage for controlling rendering of values outside the colorscalerange.

```text
http://localhost:8080/tiles/WebMercatorQuad/4/4/14?variables=temperature&colorscalerange=280,300&abovemaxcolor=red&belowmincolor=transparent
```

--------------------------------

### JSON Response Formats

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Example JSON structures returned by the endpoint for continuous and discrete data types.

```json
{
  "type": "continuous",
  "label": "Temperature [K]",
  "units": "K",
  "variant": "viridis",
  "colorscalerange": [280, 300],
  "stops": [
    {"value": 280.0, "color": "#440154ff"},
    {"value": 290.0, "color": "#31688ef"},
    {"value": 300.0, "color": "#35b779ff"},
    ...
  ],
  "abovemaxcolor": "red",
  "belowmincolor": "transparent"
}
```

```json
{
  "type": "discrete",
  "label": "Land Cover",
  "units": null,
  "items": [
    {"value": 1, "label": "Broadleaf_Woodland", "color": "#FF0000"},
    {"value": 2, "label": "Coniferous_Woodland", "color": "#006600"},
    ...
  ]
}
```

--------------------------------

### Define Categorical Data Attributes

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Example of setting flag_values, flag_meanings, and flag_colors attributes for categorical data.

```text
land_cover:flag_values = 1, 2, 3, 4, 5, 6;
land_cover:flag_meanings = "Broadleaf_Woodland Coniferous_Woodland Arable_and_Horticulture Improved_Grassland Rough_Grassland Neutral_Grassland" ;
land_cover:flag_colors = "#FF0000 #006600 #732600 #00FF00 #FAAA00 #7FE57F" ;
```

--------------------------------

### Dimension Selection DSL

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Syntax and usage examples for selecting non-X/Y dimensions in API requests.

```APIDOC
## Dimension Selection Syntax

### Description
Non-X/Y dimensions can be selected using a DSL that supports selection methods. The syntax is `{dimension}={method}::{value}` or `{dimension}={value}` for exact matches.

### Methods
- `nearest`: Select nearest coordinate value
- `pad` / `ffill`: Forward fill (previous valid value)
- `backfill` / `bfill`: Backward fill (next valid value)
- `exact`: Exact match (default)

### Examples
- Exact time: `?time=2020-01-01T12:00:00`
- Nearest time: `?time=nearest::2020-01-01T12:30:00`
- Forward fill: `?time=ffill::2020-01-01T12:30:00`
- Multiple dimensions: `?time=nearest::2020-01-01&pressure_level=500`
```

--------------------------------

### Example Usage of validate_legend_format

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-validators.md

Demonstrates how to use validate_legend_format with various inputs including MIME types, shorthand, and invalid formats.

```python
validate_legend_format("image/png")        # → LegendFormat.PNG
validate_legend_format("json")             # → LegendFormat.JSON
validate_legend_format(None)               # → None
validate_legend_format("image/webp")       # → ValueError
```

--------------------------------

### Dimension Selection Query Parameters

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Examples of using the dimension selection DSL to filter data by time, pressure, and other dimensions via URL query parameters.

```text
# Exact time (default)
?time=2020-01-01T12:00:00

# Nearest time
?time=nearest::2020-01-01T12:30:00

# Forward fill for missing timestep
?time=ffill::2020-01-01T12:30:00

# Exact pressure level
?pressure_level=500

# Multiple dimensions
?time=nearest::2020-01-01&pressure_level=500

# TimeDelta selections
?time=nearest::2020-01-01T04:00&step=pad::3h
```

--------------------------------

### GET /tiles/{tileMatrixSetId}/{z}/{y}/{x}

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Render a raster tile at the specified zoom level, row, and column from a tile matrix set.

```APIDOC
## GET /tiles/{tileMatrixSetId}/{z}/{y}/{x}

### Description
Render a raster tile at the specified zoom/row/column.

### Method
GET

### Endpoint
/tiles/{tileMatrixSetId}/{z}/{y}/{x}

### Parameters
#### Path Parameters
- **tileMatrixSetId** (string) - Required - ID of the tile matrix set
- **z** (int) - Required - Zoom level (0 = world, increases toward more detail)
- **y** (int) - Required - Tile row (0 = north for most TMS)
- **x** (int) - Required - Tile column (0 = west)

#### Query Parameters
- **variables** (list[string]) - Required - Variable names to render (comma-separated or repeated). Raster style supports 1 variable.
- **style** (string) - Optional - Style and variant (style/variant). Default: raster/default
- **colorscalerange** (string) - Optional - Min,max values for color scaling (e.g., 280,300). Default: Auto-detected
- **colormap** (string) - Optional - Custom colormap as JSON: {"0": "#FF0000", "255": "#0000FF"} (requires style=raster/custom)
- **abovemaxcolor** (string) - Optional - Color for values above max: extend, transparent, hex (#RRGGBB), or named color. Default: extend
- **belowmincolor** (string) - Optional - Color for values below min: same as abovemaxcolor. Default: extend
- **width** (int) - Optional - Tile width in pixels (must be multiple of 256). Default: 256
- **height** (int) - Optional - Tile height in pixels (must be multiple of 256). Default: 256
- **f** (string) - Optional - Output format: image/png or image/jpeg (or shorthand: png, jpeg). Default: image/png
- **render_errors** (bool) - Optional - Render errors as image tiles instead of HTTP errors. Default: false
- **overview_selection_strategy** (string) - Optional - How to select multiscale overview: nearest, coarser, or finer. Default: Server config
- **{dimension}** (string) - Optional - Select value along non-X/Y dimensions (e.g., time=2020-01-01). Default: Auto-reduced

### Response
#### Success Response (200)
- **image** (binary) - PNG or JPEG image (256x256 by default)
```

--------------------------------

### Map Initialization with Mercator Projection

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/examples/maplibre/tiles-projected.html

Initializes a MapLibre GL JS map with a specified style, zoom level, center coordinates, and importantly, configures it to use the mercator projection. This setup is crucial for displaying projected tile sources correctly.

```javascript
const map = new maplibregl.Map({
  container: "map",
  style: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
  zoom: 5,
  center: [12, 60],
  projection: {
    name: "mercator",
    // center: [262.5-360, 38.5],
    // parallels: [38.5, 38.5]
  },
});
```

--------------------------------

### Handle TileTooBigError in Pipeline

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Example of catching TileTooBigError to return an HTTP 413 Payload Too Large response.

```python
from xpublish_tiles.lib import TileTooBigError

try:
    image = await pipeline(dataset, variable, query_params)
except TileTooBigError as e:
    # Return HTTP 413 Payload Too Large
    # Message: "Tile request would require loading X bytes; max is Y bytes"
    return error_response(413, str(e))
```

--------------------------------

### Handle GridDetectionError in Pipeline

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Example of catching GridDetectionError to return an HTTP 422 Unprocessable Entity response.

```python
from xpublish_tiles.lib import GridDetectionError

try:
    grid = guess_grid_system(dataset["temperature"])
except GridDetectionError as e:
    # Return HTTP 422 Unprocessable Entity
    # Message: "Cannot detect grid system for 'temperature': {reason}"
    return error_response(422, str(e))
```

--------------------------------

### Get Tile Matrix Set Definition

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Returns the full definition of a specific tile matrix set identified by its ID.

```json
{
  "id": "WebMercatorQuad",
  "title": "Web Mercator Quadtree",
  "crs": {...},
  "tileMatrices": [
    {
      "id": "0",
      "scaleDenominator": 559082264.0287179,
      "topLeftCorner": [-20037508.34, 20037508.34],
      "tileWidth": 256,
      "tileHeight": 256,
      "matrixWidth": 1,
      "matrixHeight": 1
    },
    ...
  ]
}
```

--------------------------------

### GET /tiles/{TileMatrixSet}/{z}/{x}/{y}

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Retrieves a tile image. When render_errors is set to true, the API returns an image tile containing the error message instead of a standard HTTP error response.

```APIDOC
## GET /tiles/{TileMatrixSet}/{z}/{x}/{y}

### Description
Retrieves a map tile. If an error occurs and `render_errors=true` is provided, the response is a PNG image displaying the error message.

### Query Parameters
- **render_errors** (boolean) - Optional - When set to true, errors are returned as image tiles with a red background and white text.
- **variables** (string) - Optional - The variables to be rendered in the tile.
```

--------------------------------

### Create Datasets Locally

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/tests/README.md

Run this command to create sample datasets in the local filesystem using the default prefix. Ensure the 'local' backend is specified.

```bash
# Create datasets locally (default prefix)
uv run pytest tests/test_arraylake.py --where=local --setup
```

--------------------------------

### Create Datasets in Arraylake

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/tests/README.md

Execute this command to create sample datasets in Arraylake cloud storage using the default prefix. The 'arraylake' backend must be specified.

```bash
# Create datasets in Arraylake (default prefix)
uv run pytest tests/test_arraylake.py --where=arraylake --setup
```

--------------------------------

### Configure via Environment Variables

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Set configuration parameters as environment variables before launching the server.

```bash
export XPUBLISH_TILES_NUM_THREADS=16
export XPUBLISH_TILES_MAX_RENDERABLE_SIZE=2147483648  # 2 GiB
export XPUBLISH_TILES_ASYNC_LOAD=false
xpublish-tiles --dataset air
```

--------------------------------

### Create Datasets with Custom Prefix

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/tests/README.md

Use this command to create sample datasets with a custom storage path. Specify the desired prefix using the --prefix argument along with the storage backend.

```bash
# Use custom prefix
uv run pytest tests/test_arraylake.py --where=local --prefix=/tmp/my-data --setup
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

The standard command structure for invoking the xpublish-tiles server.

```sh
uv run xpublish-tiles [OPTIONS]
```

--------------------------------

### Initialize Configuration Object

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Initialize the global configuration object for the xpublish_tiles namespace.

```python
from xpublish_tiles.config import config

config = donfig.Config("xpublish_tiles", defaults=[{...}], paths=[])
```

--------------------------------

### Sync development environment

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Synchronize the project environment using the uv package manager.

```sh
uv sync
```

--------------------------------

### Configure via YAML File

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Define settings in a YAML file and point to it using the DONFIG_PATH environment variable.

```yaml
# xpublish_tiles.yml
num_threads: 16
transform_chunk_size: 2048
max_renderable_size: 2147483648
async_load: false
```

```bash
export DONFIG_PATH=/path/to/xpublish_tiles.yml
xpublish-tiles --dataset air
```

--------------------------------

### GET /tiles/{tms}/tilejson.json

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Retrieves TileJSON metadata for a specific tileset.

```APIDOC
## GET /tiles/{tms}/tilejson.json

### Description
Returns the TileJSON metadata for the specified tile matrix set.

### Method
GET

### Endpoint
/tiles/{tms}/tilejson.json

### Parameters
#### Path Parameters
- **tms** (string) - Required - The tile matrix set identifier.
```

--------------------------------

### Initialize MapLibre Map and Add Raster Tile Layer

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/examples/maplibre/tiles.html

Sets up a MapLibre map instance and adds a raster tile layer using a TileJSON URL. Includes error handling for tile server reachability and event listeners for map interactions.

```javascript
const SERVER_URL = "http://localhost:8080";
const TILEJSON_URL = `${SERVER_URL}/tiles/WebMercatorQuad/tilejson.json?variables=RH&lev=45&colorscalerange=0%2C1&style=polygons%2Fdefault&width=512&height=512&f=png&render_errors=false`;

(async () => {
  try {
    const resp = await fetch(`${SERVER_URL}/tiles/`);
    if (!resp.ok) {
      throw new Error(`HTTP ${resp.status}`);
    }
  } catch (err) {
    document.body.innerHTML = `<pre style="padding:1em;color:#b00">Tile server not reachable at ${SERVER_URL}/tiles/ (${err.message})</pre>`;
    return;
  }

  const map = new maplibregl.Map({
    container: "map",
    style: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
    zoom: 2,
    center: [-71.0367, 42.3739],
  });

  let globeEnabled = true;
  map.on("style.load", () => {
    map.setProjection({ type: globeEnabled ? "globe" : "mercator" });
  });

  map.on("load", () => {
    map.addSource("tiles-test-source", {
      type: "raster",
      // use the tiles option to specify a raster tile source URL
      // https://docs.mapbox.com/style-spec/reference/sources/
      url: TILEJSON_URL,
      tileSize: 512,
    });

    map.addLayer({
      id: "tiles-test-layer",
      type: "raster",
      source: "tiles-test-source",
      paint: {
        "raster-opacity": 0.75,
      },
    },
    // 'building'
    // Place layer under labels, roads and buildings.
    );

    map.showTileBoundaries = false;

    // Fly to data center using tilejson bbox & minzoom
    document.getElementById("fly-to-center").addEventListener("click", async () => {
      const resp = await fetch(TILEJSON_URL);
      const tj = await resp.json();
      if (tj.bounds) {
        const [west, south, east, north] = tj.bounds;
        map.fitBounds([[west, south], [east, north]], { padding: 40 });
      }
    });

    // Toggle globe projection
    const globeToggle = document.getElementById("globe-toggle");
    globeToggle.addEventListener("click", () => {
      globeEnabled = !globeEnabled;
      map.setProjection({ type: globeEnabled ? "globe" : "mercator" });
      globeToggle.textContent = globeEnabled ? "Disable Globe" : "Enable Globe";
    });

    // Toggle tile boundaries functionality
    const tileBoundariesToggle = document.getElementById("tile-boundaries-toggle");
    tileBoundariesToggle.addEventListener("click", () => {
      map.showTileBoundaries = !map.showTileBoundaries;
      tileBoundariesToggle.textContent = map.showTileBoundaries ? "Hide Tile Boundaries" : "Show Tile Boundaries";
    });
  });

  map.on("style.load", function () {
    map.on("click", function (e) {
      var coordinates = e.lngLat;
      new maplibregl.Popup()
        .setLngLat(coordinates)
        .setHTML("you clicked here: <br/>" + coordinates)
        .addTo(map);
    });
  })();
})();
```

--------------------------------

### Run xpublish-tiles benchmarks

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Execute performance tests against local datasets or remote servers using the --spy flag.

```sh
# Run benchmark with a specific dataset (starts server automatically)
xpublish-tiles --dataset local://para_hires --spy

# Run benchmark against existing localhost server
xpublish-tiles --dataset para --spy --where local-booth

# Run benchmark against Arraylake production server with custom concurrency
xpublish-tiles --dataset para --spy --where arraylake-prod --concurrency 8

# Run benchmark suite for all local datasets
xpublish-tiles --bench-suite
```

--------------------------------

### Handle VariableNotFoundError in Pipeline

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Example of catching VariableNotFoundError to return an HTTP 422 Unprocessable Entity response.

```python
from xpublish_tiles.lib import VariableNotFoundError

try:
    image = await pipeline(dataset, ["nonexistent_var"], query_params)
except VariableNotFoundError as e:
    # Return HTTP 422 Unprocessable Entity
    # Message: "Variable 'nonexistent_var' not found in dataset"
    return error_response(422, str(e))
```

--------------------------------

### Register Renderer via Entry Points

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Add the renderer to the project's entry points in pyproject.toml to enable detection by the xpublish-tiles system.

```toml
[project.entry-points."xpublish_tiles.renderers"]
my_style = "mypackage.render:MyCustomRenderer"
```

--------------------------------

### List Supported Tile Matrix Sets

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Retrieves a list of all supported tile matrix sets with summary information.

```json
{
  "tileMatrixSets": [
    {
      "id": "WebMercatorQuad",
      "title": "Web Mercator Quadtree",
      "uri": "http://www.opengis.net/def/tilematrixset/OGC/1.0/WebMercatorQuad",
      "crs": {
        "type": "CRS84",
        "href": "http://www.opengis.net/gml/srs/epsg.xml#3857"
      },
      "links": [
        {
          "href": "/tiles/tileMatrixSets/WebMercatorQuad",
          "rel": "self",
          "type": "application/json"
        }
      ]
    },
    ...
  ]
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/README.md

Visual representation of the documentation file hierarchy.

```text
output/
├── README.md                             (This file)
├── api-reference-core-types.md           (Enums, dataclasses, type aliases)
├── api-reference-configuration.md        (Config options, env vars, tuning)
├── api-reference-validators.md           (Query param validation)
├── api-reference-rendering.md            (Renderer interface, registry, built-ins)
├── api-reference-grids.md                (Grid systems, detection, indexing)
├── api-reference-errors.md               (Exception classes, error handling)
└── endpoints.md                          (HTTP API endpoints, request/response)
```

--------------------------------

### Accessing Renderers via RenderRegistry

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Demonstrates retrieving a specific renderer by ID or listing all available renderers.

```python
from xpublish_tiles.render import RenderRegistry

# Get a specific renderer
RasterRenderer = RenderRegistry.get("raster")

# Get all renderers
all_renderers = RenderRegistry.all()
# → {"raster": DatashaderRasterRenderer, "polygons": PolygonsRenderer}
```

--------------------------------

### Run tests

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Execute the standard test suite using pytest.

```sh
uv run pytest tests
```

--------------------------------

### DatashaderRasterRenderer entry point configuration

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Registers the raster renderer via project entry points.

```toml
[project.entry-points."xpublish_tiles.renderers"]
raster = "xpublish_tiles.render.raster:DatashaderRasterRenderer"
```

--------------------------------

### PolygonsRenderer entry point configuration

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Registers the polygon renderer via project entry points.

```toml
[project.entry-points."xpublish_tiles.renderers"]
polygons = "xpublish_tiles.render.polygons:PolygonsRenderer"
```

--------------------------------

### Define OverviewSelectionStrategy enumeration

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-core-types.md

Strategy for selecting which multiscale overview to use when rendering a tile.

```python
class OverviewSelectionStrategy(enum.StrEnum):
    NEAREST = "nearest"
    COARSER = "coarser"
    FINER = "finer"
```

--------------------------------

### Configure via Python Code

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Access and modify configuration settings programmatically using the config object.

```python
from xpublish_tiles.config import config

# Get a value
num_threads = config.get("num_threads")

# Set a value (before any grid detection or rendering)
config.set({"num_threads": 16, "max_renderable_size": 2147483648})
```

--------------------------------

### Run type checker

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/README.md

Execute the type checking process for the codebase.

```sh
uv run ty check
```

--------------------------------

### Implement the Renderer base class

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Subclasses must implement the abstract methods defined in the Renderer base class to handle tile rendering and style metadata.

```python
class Renderer(ABC):
    @abstractmethod
    def render(
        self,
        *,
        contexts: dict[str, RenderContext],
        buffer: io.BytesIO,
        width: int,
        height: int,
        variant: str,
        colorscalerange: tuple[Number, Number] | None = None,
        format: ImageFormat = ImageFormat.PNG,
        context_logger=None,
        colormap: dict[str, str] | None = None,
        abovemaxcolor: str | None = None,
        belowmincolor: str | None = None,
    ):
        pass
    
    @abstractmethod
    def render_error(
        self,
        *,
        buffer: io.BytesIO,
        width: int,
        height: int,
        message: str,
        format: ImageFormat = ImageFormat.PNG,
        cmap: str = "",
        colorscalerange: tuple[Number, Number] | None = None,
        **kwargs,
    ):
        pass
    
    def render_legend(self, *, ...): ...
    def legend_data(self, *, ...): ...
    
    @staticmethod
    @abstractmethod
    def style_id() -> str: ...
    
    @staticmethod
    @abstractmethod
    def supported_variants() -> list[str]: ...
    
    @staticmethod
    @abstractmethod
    def default_variant() -> str: ...
    
    @classmethod
    def describe_style(cls, variant: str) -> dict[str, str]: ...
```

--------------------------------

### Implement a Custom Renderer Class

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Extend DatashaderRenderer and implement the render method to define custom tile generation logic. Ensure the class is decorated with @register_renderer for automatic discovery.

```python
from xpublish_tiles.render import Renderer, register_renderer, DatashaderRenderer
from xpublish_tiles.types import ImageFormat, DataType
import io
from PIL import Image

@register_renderer
class MyCustomRenderer(DatashaderRenderer):
    """Custom renderer for specialized use cases."""
    
    @staticmethod
    def style_id() -> str:
        return "my_style"
    
    @staticmethod
    def default_variant() -> str:
        return "gray"
    
    def render(
        self,
        *,
        contexts: dict[str, RenderContext],
        buffer: io.BytesIO,
        width: int,
        height: int,
        variant: str,
        colorscalerange=None,
        format: ImageFormat = ImageFormat.PNG,
        context_logger=None,
        colormap=None,
        abovemaxcolor=None,
        belowmincolor=None,
    ):
        # Use parent's _prepare_render helper
        result = self._prepare_render(
            contexts, 
            buffer=buffer, 
            width=width, 
            height=height, 
            variant=variant, 
            format=format, 
            context_logger=context_logger
        )
        if result is None:
            return  # Empty tile already written
        
        context, cvs, variant = result
        
        # Your custom rendering logic here
        # e.g., cvs.quadmesh(...), shade_mesh(...), etc.
        
        img.save(buffer, format=str(format))
```

--------------------------------

### Define default_pad

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-configuration.md

Set the pixel padding for bbox selections to prevent edge transparency.

```text
default_pad: int
```

--------------------------------

### Retrieve OGC API Conformance

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/endpoints.md

Returns the conformance classes implemented by the server. Use this to verify OGC API compliance.

```json
{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/tileset",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/tilesets-list"
  ]
}
```

--------------------------------

### Renderer

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Abstract base class for implementing custom renderers in xpublish-tiles.

```APIDOC
## Renderer

### Description
Abstract base class for all renderers. Subclasses must implement the required abstract methods to handle tile rendering, error rendering, and style identification.

### Required Methods
- **render** - Render tile(s) from render contexts into a buffer.
- **render_error** - Render an error message as an image tile.
- **style_id** - Return the style identifier (e.g., "raster", "polygons").
- **supported_variants** - Return list of supported colormap/variant names.
- **default_variant** - Return the default variant name when none is specified.

### Optional Methods
- **render_legend** - Render a legend/colorbar image.
- **legend_data** - Return legend as JSON-serializable dict of color stops.
- **describe_style** - Return metadata about a style/variant combination.
```

--------------------------------

### Initialize MapLibre GL JS Map

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/examples/maplibre/tiles-categorical.html

Initializes a new MapLibre GL JS map instance with specified container, style, zoom, center, and projection settings. The map is configured to use the mercator projection.

```javascript
const map = new maplibregl.Map({
  container: "map",
  style: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
  zoom: 5,
  center: [-54, -5],
  projection: {
    name: "mercator",
    <!-- center: [262.5-360, 38.5],
    parallels: [38.5, 38.5] -->
  },
});
```

--------------------------------

### Perform spatial selection with sel()

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-grids.md

Executes spatial selection on a grid using a bounding box and data array.

```python
slicers = grid.sel(bbox, da=data_array)
```

--------------------------------

### Configure Async Load Timeout

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-errors.md

Adjust or disable the async data loading timeout via the configuration object.

```python
from xpublish_tiles.config import config

# Increase timeout for large selections
config.set({"async_load_timeout_per_tile": 60})

# Disable timeout
config.set({"async_load_timeout_per_tile": None})
```

--------------------------------

### describe_style

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-rendering.md

Returns style metadata for a given variant.

```APIDOC
## describe_style(variant)

### Description
Returns style metadata for the specified variant.

### Parameters
- **variant** (str) - Required - The variant name to describe.

### Returns
- **dict[str, str]** - A dictionary containing style metadata (e.g., id, title, description).
```

--------------------------------

### Initialize Map and Add TileJSON Source

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/examples/maplibre/tilejson.html

Initializes a MapLibre GL JS map and adds a raster layer using a TileJSON URL. The Mapbox GL JS library automatically fetches and parses the TileJSON to add the source.

```javascript
const map = new maplibregl.Map({ container: "map", style: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json", zoom: 2, center: [-71.0367, 42.3739], });
map.on("load", () => {
  // Add source using TileJSON URL directly - Mapbox JS will fetch and parse it automatically
  map.addSource("tilejson-source", {
    type: "raster",
    url: "http://localhost:8080/tiles/WebMercatorQuad/tilejson.json?variables=gust&style=raster/viridis&colorscalerange=0,30&width=512&height=512",
    tileSize: 512,
  });
  // Add layer
  map.addLayer({
    id: "tilejson-layer",
    type: "raster",
    source: "tilejson-source",
    paint: {
      "raster-opacity": 0.5,
    },
  },
  // 'building'
  // Place layer under labels, roads and buildings.
  );
});
```

--------------------------------

### grid.sel()

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-grids.md

Performs spatial selection on a grid system based on a bounding box and data array.

```APIDOC
## grid.sel(bbox, da)

### Description
Performs spatial selection on a grid system. Returns a dictionary mapping dimension names to lists of index objects (slices, array indices, or special indexer objects).

### Parameters
- **bbox** (object) - Required - The bounding box for spatial selection.
- **da** (DataArray) - Required - The data array to perform selection against.

### Return Type
- **Slicers** (dict[str, list[Slicer]]) - A mapping of dimension names to lists of index objects.
```

--------------------------------

### Define PopulatedRenderContext

Source: https://github.com/earth-mover/xpublish-tiles/blob/main/_autodocs/api-reference-core-types.md

Complete context containing all information required for rendering a tile, including patches and grid metadata.

```python
@dataclass
class PopulatedRenderContext(RenderContext):
    grid: GridSystem
    datatype: DataType
    bbox: OutputBBox
    patches: list[Patch] = field(default_factory=list)
    da: xr.DataArray | None = None
    cell_rings: np.ndarray | None = None
```