### Start xpublish-tiles Server

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

Start the xpublish-tiles server using the CLI. Examples include default startup, specifying a dataset and port, using a local dataset with debug logging, and running a benchmark.

```bash
# Default (global synthetic dataset on port 8080)
xpublish-tiles

# Specific dataset and port
xpublish-tiles --dataset air --port 9000

# With local dataset
xpublish-tiles --dataset local://para_hires --log-level debug

# Run benchmark
xpublish-tiles --dataset para --spy --concurrency 20
```

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

### 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
```

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

### Run Setup Tests with uv and pytest

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

Run setup tests, which create local datasets deployable via the CLI, using uv and pytest.

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

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

### Example Usage of Render Registry

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

Demonstrates how to instantiate and use the RenderRegistry to get available colormaps and their metadata. Requires importing RenderRegistry and DatashaderRenderer.

```python
from xpublish_tiles.render import RenderRegistry, DatashaderRenderer

# Get the raster renderer
Raster = RenderRegistry.get("raster")

# Check available variants
variants = Raster.supported_variants()
print(f"Available colormaps: {variants}")

# Get metadata for a variant
meta = Raster.describe_style("viridis")
print(f"{meta['title']}: {meta['description']}")
```

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

### 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
```

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

### Install Testing Dependencies for Benchmarking

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

Install optional testing dependencies to enable benchmarking features. This is required if you encounter BenchmarkImportError.

```bash
pip install xpublish-tiles[testing]
```

```bash
pip install xpublish-tiles[complete]
```

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

### Detailed Renderer Implementation Example

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

A comprehensive example demonstrating the implementation of a custom renderer, including `render`, `render_error`, `style_id`, `supported_variants`, and `default_variant` methods.

```python
from xpublish_tiles.render import Renderer, register_renderer
import io

@register_renderer
class MyRenderer(Renderer):
    def render(
        self, *, contexts, buffer, width, height, variant, 
        colorscalerange=None, format=None, **kwargs
    ):
        # Render logic here
        from PIL import Image
        img = Image.new("RGBA", (width, height), (255, 0, 0, 255))
        img.save(buffer, format=str(format))
    
    def render_error(
        self, *, buffer, width, height, message, format=None, **kwargs
    ):
        # Error rendering logic
        pass
    
    @staticmethod
    def style_id() -> str:
        return "myrenderer"
    
    @staticmethod
    def supported_variants() -> list[str]:
        return ["variant1", "variant2"]
    
    @staticmethod
    def default_variant() -> str:
        return "variant1"
```

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

### Example Tile URL

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

This example demonstrates how to construct a URL to request a tile from the Xpublish Tiles API. It includes common parameters for specifying variables, style, color range, and dimensions.

```http
http://localhost:8080/tiles/WebMercatorQuad/4/10/6
  ?variables=temperature
  &style=raster/viridis
  &colorscalerange=250,310
  &width=256
  &height=256
```

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

### Instantiating ResolutionLevel

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

Example of how to create an instance of the ResolutionLevel dataclass with a dataset, path, and pixel size.

```python
from xpublish_tiles.multiscale import ResolutionLevel

level = ResolutionLevel(
    path="2x/2x",
    dataset=coarse_ds,
    pixel_size=4000.0
)
```

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

### Custom Renderer Implementation Example

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

Example of how to define and register a custom renderer by inheriting from `Renderer` and applying the `@register_renderer` decorator.

```python
from xpublish_tiles.render import register_renderer, Renderer

@register_renderer
class CustomRenderer(Renderer):
    @staticmethod
    def style_id() -> str:
        return "custom"
    
    def render(self, **kwargs):
        # Implementation
        pass
```

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

### Tile Request with All Styling Options

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

This example demonstrates how to apply all available styling options for a tile request, including custom dimensions and color mapping.

```bash
curl "http://localhost:8080/tiles/WebMercatorQuad/4/10/5?variables=temperature&style=raster/plasma&colorscalerange=250,310&width=512&height=512&abovemaxcolor=red&belowmincolor=transparent"
```

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

### TileJSON Endpoint Request Example

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

Example GET request for the TileJSON endpoint, specifying the tile matrix set ID and other parameters.

```http
GET /tiles/WebMercatorQuad/tilejson?variables=temperature&style=raster/viridis&colorscalerange=250,310
```

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

### Serve Built-in Test Datasets

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

Examples of serving different built-in test datasets like 'hrrr', 'para', and 'eu3035_hires'.

```bash
xpublish-tiles --dataset hrrr
```

```bash
xpublish-tiles --dataset para
```

```bash
xpublish-tiles --dataset eu3035_hires
```

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

### 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)
```

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

### Run Benchmark Suite

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

Executes the full benchmark suite. Requires initial dataset setup. Can optionally compare performance against titiler.

```bash
# Setup datasets first (one-time)
uv run pytest --setup

# Run full benchmark suite
xpublish-tiles --bench-suite

# Compare with titiler
xpublish-tiles --bench-suite --titiler
```

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

### Legend Endpoint Request Example

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

Example GET request for the legend endpoint, specifying variables, style, and color scale range.

```http
GET /tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310
```

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

### Serve Default Synthetic Global Dataset

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

Starts the xpublish-tiles server with default settings, typically serving on http://localhost:8080/.

```bash
xpublish-tiles
# Serves on http://localhost:8080/
```

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

### Serve Local Datasets

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

Serves local datasets using the 'local://' prefix. Requires initial setup using 'uv run pytest --setup'.

```bash
# Create local test datasets (one-time setup)
uv run pytest --setup

# Serve local dataset
xpublish-tiles --dataset local://ifs
xpublish-tiles --dataset local://para_hires
```

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

### Basic CLI Command

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

The fundamental command to start the xpublish-tiles server. It serves a default global dataset on the default port.

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

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

### Accessing and Modifying Configuration in Python

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

Demonstrates how to get, check, and set configuration values programmatically using the `config` object.

```python
from xpublish_tiles.config import config

# Get a single setting
max_size = config.get("max_renderable_size")
timeout = config.get("async_load_timeout_per_tile")

# Get with default if missing
threads = config.get("num_threads", default=8)

# Check if setting exists
if "custom_setting" in config:
    value = config["custom_setting"]

# Update at runtime
config.set({"num_threads": 16})

# Get all settings as dict
all_settings = dict(config)
```

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

### ContinuousData Usage Examples

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

Examples of defining continuous data. The first defines temperature data with explicit valid min/max bounds. The second shows unbounded data, which requires a colorscalerange to be specified at render time.

```python
from xpublish_tiles.types import ContinuousData

# Define continuous temperature data
temperature = ContinuousData(
    valid_min=250.0,
    valid_max=310.0
)

# No explicit bounds (requires colorscalerange at render time)
unbounded = ContinuousData(valid_min=None, valid_max=None)
```

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

### Usage Example for RenderRegistry

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

Demonstrates how to use the RenderRegistry to retrieve specific renderers by their style ID and to list all available renderers. Shows how to access supported variants for each renderer.

```python
from xpublish_tiles.render import RenderRegistry

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

# List all available renderers
all_renderers = RenderRegistry.all()
for style_id, renderer_cls in all_renderers.items():
    print(f"{style_id}: {renderer_cls.supported_variants()}")
```

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

### Example Tile Request with cURL

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

Shows a complete cURL command to request a tile with specified variables, style, color range, and format.

```bash
curl "http://localhost:8080/tiles/WebMercatorQuad/3/4/2?variables=temperature&style=raster/viridis&colorscalerange=250,310&format=png"
```

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

### Dimension Selection Examples

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

Illustrates various methods for selecting dimensions such as time and level, including exact matches, nearest values, and fill methods.

```http
?time=2000-01-01                           # Exact match
?time=nearest::2000-01-01T04:00            # Nearest value
?level=500&time=ffill::2000-01-01T03:30    # Forward fill
?step=pad::3h                              # Pad method with timedelta
```

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

### Serve Global Dataset

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

Starts the server to serve the synthetic global dataset on the default port 8080.

```sh
xpublish-tiles
```

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

### Dimension Selection DSL Examples

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

Demonstrates various ways to select dimensions using the DSL, including exact matches and different filling methods like nearest, forward fill, and backward fill.

```text
time=2000-01-01              # Exact match
time=nearest::2000-01-01     # Nearest value
level=ffill::500             # Forward fill
step=bfill::3h               # Backward fill
```

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

### Run Benchmark Against Existing Localhost Server

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

Tests performance against an already running localhost tile server without starting a new one. Requires the --spy flag for benchmarking.

```sh
xpublish-tiles --dataset para --spy --where local-booth
```

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

### Complete Zoom Calculation Example

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

Demonstrates how to calculate the minimum and maximum zoom levels for a given dataset and tile map service. This is useful for configuring TileJSON metadata.

```python
from xpublish_tiles.tiles_lib import get_min_zoom, get_max_zoom
from xpublish_tiles.grids import guess_grid_system
import morecantile
import xarray as xr

# Load data
ds = xr.open_dataset("global_model_output.nc")
ds.attrs["_xpublish_id"] = "global_model_v1"

# Setup
variable = "temperature"
da = ds[variable]
grid = guess_grid_system(da)
tms = morecantile.tms.get("WebMercatorQuad")

# Calculate zoom range
min_zoom = get_min_zoom(
    grid, tms, da,
    style="raster",
    xpublish_id=ds.attrs["_xpublish_id"]
)
max_zoom = get_max_zoom(grid, tms)

print(f"Zoom range: {min_zoom} to {max_zoom}")
# Example output: Zoom range: 2 to 12

# Use in TileJSON
tilejson = {
    "tilejson": "3.0.0",
    "name": f"{variable}",
    "minzoom": min_zoom,
    "maxzoom": max_zoom,
    "tiles": [
        f"https://server/tiles/WebMercatorQuad/{{z}}/{{y}}/{{x}}"
        f"?variables={variable}&style=raster/viridis"
    ]
}
```

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

### Compare Benchmarks with Titiler

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

Enable the --titiler flag to compare benchmark results against the titiler tool. This is an optional feature and requires titiler to be installed.

```bash
xpublish-tiles --bench-suite --titiler
```

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

### Example Tile URL Request

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

Illustrates the structure of a tile URL request, including coordinates, variables, style, colorscale, and dimensions. This format is used for accessing tile data.

```http
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
```

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

### Run Single Benchmark

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

Executes a single benchmark test for a specified dataset. The --spy flag starts the server for benchmarking. Custom concurrency levels and data sources (like 'arraylake-prod') can be specified.

```bash
# Benchmark with specific dataset (starts server)
xpublish-tiles --dataset local://para_hires --spy

# With custom concurrency
xpublish-tiles --dataset para --spy --concurrency 20

# Against Arraylake production
xpublish-tiles --dataset para --spy --where arraylake-prod --concurrency 8
```

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

### Serve Local Icechunk Datasets

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

Serves local datasets stored as Icechunk repositories. Datasets must be created first using `uv run pytest --setup`.

```sh
xpublish-tiles --dataset local://ifs
xpublish-tiles --dataset local://para_hires
```

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

### Set Environment Variables for xpublish-tiles

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

Configure xpublish-tiles options by setting environment variables. Ensure variables are uppercase with underscores. Examples include setting thread pool size, disabling async loading, and adjusting cache sizes.

```bash
# Set thread pool size
export XPUBLISH_TILES_NUM_THREADS=16

# Disable async loading
export XPUBLISH_TILES_ASYNC_LOAD=false

# Set max renderable size to 2 GB
export XPUBLISH_TILES_MAX_RENDERABLE_SIZE=2147483648

# Disable async load timeout
export XPUBLISH_TILES_ASYNC_LOAD_TIMEOUT_PER_TILE=null

# Disable concurrent load limit
export XPUBLISH_TILES_NUM_CONCURRENT_DATA_LOADS=null

# Set grid cache size (before import!)
export XPUBLISH_TILES_GRID_CACHE_MAX_SIZE=32
```

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

### Run Benchmark with Specific Dataset and Spy Mode

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

Use the --spy flag to run benchmark requests with a specified dataset for performance testing. This starts the server, runs warm-up requests, and makes concurrent tile requests.

```bash
xpublish-tiles --dataset para --spy
```

```bash
xpublish-tiles --dataset local://para_hires --spy
```

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

### Run Benchmark Suite for All Local Datasets

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

Execute the --bench-suite command to run benchmarks across all configured local datasets and tabulate the results. Ensure pytest is set up with `uv run pytest --setup`.

```bash
xpublish-tiles --bench-suite
```

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

### 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
```

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

### List Available Tile Matrix Sets

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

Get a list of all available tile matrix sets (coordinate systems) supported by the TilesPlugin. This is useful for understanding the available projections for tile requests.

```http
GET /tiles/tileMatrixSets
```

```json
{
  "tileMatrixSets": [
    {
      "id": "WebMercatorQuad",
      "title": "Web Mercator",
      "description": "Popular web mapping projection"
    },
    ...
  ]
}
```

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

### Curl Examples for Legend Endpoint

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

Demonstrates various ways to request legend data using curl, including PNG, horizontal orientation, custom colors, and JSON output.

```bash
# Vertical PNG legend (default)
curl "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310"
```

```bash
# Horizontal legend with custom colors
curl "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310&vertical=false&background_color=white&text_color=black"
```

```bash
# JSON legend (for client-side rendering)
curl "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310&f=application/json"
```

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

### 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
```

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

### Rectilinear Grid Example

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

Represents a regular grid with orthogonal 1D coordinates. This example shows how to create an xarray Dataset and initialize a Rectilinear grid.

```python
class Rectilinear(GridSystem2D):
    """Grid with 1D orthogonal coordinates. 
    
    Signature: lat[lat], lon[lon]
    
    Example
    -------
    >>> import xarray as xr
    >>> import numpy as np
    >>> lat = np.linspace(-90, 90, 181)
    >>> lon = np.linspace(-180, 180, 361)
    >>> ds = xr.Dataset(
    ...     data_vars={"temp": (("lat", "lon"), np.random.rand(181, 361))},
    ...     coords={"lat": lat, "lon": lon}
    ... )
    >>> grid = Rectilinear(crs=..., bbox=..., X="lon", Y="lat", ...)
    """
```

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

### MissingParameterError JSON Response Example

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

Example JSON response for a MissingParameterError, occurring when 'colorscalerange' is required but not provided for continuous data lacking 'valid_min'/'valid_max' attributes.

```json
{
  "detail": "`colorscalerange` must be specified when array does not have 
            valid_min and valid_max attributes specified."
}
```

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

### 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
```

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

### Development Configuration (Laptop)

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

Set environment variables for development on a laptop, balancing performance with resource constraints.

```bash
export XPUBLISH_TILES_NUM_THREADS=4
export XPUBLISH_TILES_MAX_RENDERABLE_SIZE=536870912  # 512 MB
export XPUBLISH_TILES_NUM_CONCURRENT_DATA_LOADS=2
```

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

### AsyncLoadTimeoutError JSON Response Example

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

Example JSON response for an AsyncLoadTimeoutError, indicating that asynchronous data loading exceeded the configured timeout. It suggests increasing the timeout setting.

```json
{
  "detail": "Data loading timed out after 20 seconds. 
            Try increasing XPUBLISH_TILES_ASYNC_LOAD_TIMEOUT_PER_TILE."
}
```

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

### DiscreteData Usage Example

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

Example of defining discrete land cover classification data with values, meanings, and colors. Ensure lengths of values, meanings, and colors (if provided) are consistent.

```python
from xpublish_tiles.types import DiscreteData

# Define land cover classification
land_cover = DiscreteData(
    values=[1, 2, 3, 4, 5, 6],
    meanings=[
        "Broadleaf_Woodland",
        "Coniferous_Woodland",
        "Arable_and_Horticulture",
        "Improved_Grassland",
        "Rough_Grassland",
        "Neutral_Grassland"
    ],
    colors=["#FF0000", "#006600", "#732600", "#00FF00", "#FAAA00", "#7FE57F"]
)
```

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

### Load Xarray Tutorial Datasets

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

Loads and serves datasets using the 'xarray://' prefix, such as 'rasm' and 'ersstv5'.

```bash
xpublish-tiles --dataset xarray://rasm
```

```bash
xpublish-tiles --dataset xarray://ersstv5
```

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

### IndexingError JSON Response Example

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

Illustrates the JSON response for an IndexingError, which occurs when a dimension selector value does not exist or coordinates are non-monotonic. This example shows a 'time' dimension error.

```json
{
  "detail": "Cannot index dimension 'time' with value '2000-06-15'. 
            Available values: ['2000-01-01', '2000-12-31']. 
            Try method='nearest' (e.g., time=nearest::2000-06-15)"
}
```

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

### Categorical Colormap Example (Python Dict)

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

Example of defining a categorical colormap using a Python dictionary. Keys represent specific data values (e.g., flag values) and values are hex color strings. This is suitable for discrete data classification.

```python
# For land cover: flag_values = [1, 2, 3, 4, 5, 6]
categorical = {
    "1": "#FF0000",   # Red
    "2": "#006600",   # Dark green
    "3": "#732600",   # Brown
    "4": "#00FF00",   # Bright green
    "5": "#FAAA00",   # Orange
    "6": "#7FE57F"    # Light green
}

```

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

### Serve Air Temperature Tutorial Dataset on Custom Port

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

Serves the 'air' dataset on port 9000. Useful for running multiple instances or avoiding port conflicts.

```bash
xpublish-tiles --port 9000 --dataset air
# Serves on http://localhost:9000/
```

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

### Continuous Colormap Example (Python Dict)

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

Example of defining a continuous colormap using a Python dictionary. Keys represent palette indices (0-255) and values are hex color strings. This dictionary can be converted to a JSON string for use in HTTP query parameters.

```python
import json

# Python dict
continuous = {
    "0": "#440154",    # Dark purple (min value)
    "64": "#31688e",   # Blue
    "128": "#35b779",  # Green
    "192": "#fde724",  # Yellow (approaching max)
    "255": "#fde724"   # Yellow (max value)
}

# As JSON string for HTTP query param
colormap_json = json.dumps(continuous)
# Pass as: ?colormap={"0":"#440154",...}

```

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

### Basic and Parameterized Tile Requests

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

Demonstrates basic tile retrieval and how to specify rendering variables, styles, and color scales.

```http
GET /tiles/WebMercatorQuad/3/4/2
GET /tiles/WebMercatorQuad/3/4/2?variables=temperature&style=raster/viridis&colorscalerange=250,310
```

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

### Get Specific Dataset Metadata

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

Retrieves metadata for a specific dataset, including links to its tilesets and styles.

```APIDOC
## GET /tiles/{datasetId}

### Description
Get metadata for a specific dataset.

### Method
GET

### Endpoint
/tiles/{datasetId}

### Parameters
#### Path Parameters
- **datasetId** (string) - Required - The ID of the dataset to retrieve.
```

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

### Get Default Colormap Variant

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

Retrieves the name of the default colormap. This is useful if no specific colormap is chosen.

```python
@staticmethod
def default_variant() -> str:
    """Return default colormap variant.
    
    Returns
    -------
    str
        "viridis"
    """
    pass
```

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

### Get TileJSON

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

Retrieves TileJSON metadata for a specified tile matrix set, compatible with Maplibre/Mapbox clients.

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

### Description
Gets TileJSON for Maplibre/Mapbox.

### Method
GET

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

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

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

### Get Specific Tile Matrix Set

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

Retrieves metadata for a specific tile matrix set by its ID.

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

### Description
Gets specific tile matrix set metadata.

### Method
GET

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

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the tile matrix set to retrieve.
```

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

### Initialize Configuration Object

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

Instantiate the global configuration object using `donfig.Config`. This should be done early in the application lifecycle. Settings can be provided via defaults and file paths.

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

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

### Creating and Using QueryParams

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

Demonstrates how to instantiate the QueryParams dataclass with specific rendering parameters and retrieve the associated renderer. Ensure necessary types like CRS and BBox are imported.

```python
from xpublish_tiles.types import QueryParams, ImageFormat
from pyproj import CRS
from xpublish_tiles.bbox import BBox

params = QueryParams(
    variables=["temperature"],
    crs=CRS.from_epsg(3857),
    bbox=BBox(west=-180, south=-85, east=180, north=85),
    selectors={"time": "2000-01-01", "level": 500},
    style="raster",
    width=256,
    height=256,
    variant="viridis",
    format=ImageFormat.PNG,
    colorscalerange=(250, 310)
)

renderer = params.get_renderer()
```

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

### Get Legend

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

Retrieves the legend for a given style and color scale, useful for visualizing data ranges.

```APIDOC
## GET /tiles/legend

### Description
Retrieves the legend image for the specified style and color scale.

### Method
GET

### Endpoint
/tiles/legend

### Parameters
#### Query Parameters
- **variables** (string) - Required - Comma-separated list of variables for which to generate the legend.
- **style** (string) - Required - The rendering style to apply (e.g., `raster/viridis`).
- **colorscalerange** (string) - Required - The range for the color scale (e.g., `250,310`).

### Request Example
```bash
curl "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310"
```

### Response
#### Success Response (200)
Returns the legend image data.
```

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

### TileJSON Endpoint

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

Get TileJSON metadata for a tileset, compatible with Mapbox/Maplibre. Includes parameters for styling and data selection.

```APIDOC
## GET /tiles/{tileMatrixSetId}/tilejson

### Description
Get TileJSON metadata for a tileset (compatible with Mapbox/Maplibre).

### Method
GET

### Endpoint
/tiles/{tileMatrixSetId}/tilejson

### Parameters
#### Query Parameters
- **variables** (string) - Required - Variable name
- **style** (string) - Required - Style: `{renderer}/{variant}`
- **colorscalerange** (string) - Optional - Comma-separated min,max

### Response
#### Success Response (200)
- **Content-Type**: `application/json`

#### Response Example
```json
{
  "tilejson": "3.0.0",
  "name": "air - WebMercatorQuad",
  "description": "Tiles for air",
  "version": "1.0.0",
  "attribution": "Generated by xpublish-tiles",
  "scheme": "xyz",
  "tiles": [
    "http://localhost:8080/tiles/WebMercatorQuad/{z}/{y}/{x}?variables=temperature&style=raster/viridis&colorscalerange=250,310"
  ],
  "minzoom": 0,
  "maxzoom": 18,
  "bounds": [-180, -90, 180, 90],
  "center": [0, 0, 2],
  "legend": "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310",
  "links": []
}
```
```

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

### Serve Dataset from Arraylake/Icechunk with Specific Branch

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

When serving datasets from sources like Arraylake or Icechunk, use the --branch option to specify a particular branch. The default branch is 'main'.

```bash
xpublish-tiles --dataset earthmover-public/aifs-outputs --branch main
```

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

### Instantiating NullRenderContext

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

Demonstrates how to create an instance of `NullRenderContext` to represent an empty tile.

```python
from xpublish_tiles.types import NullRenderContext

# Represents an empty tile (no data in bounding box)
empty_tile = NullRenderContext()
```

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

### TileJSON Metadata Response

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

Example JSON response for the TileJSON endpoint, providing metadata for tile services compatible with Mapbox/Maplibre.

```json
{
  "tilejson": "3.0.0",
  "name": "air - WebMercatorQuad",
  "description": "Tiles for air",
  "version": "1.0.0",
  "attribution": "Generated by xpublish-tiles",
  "scheme": "xyz",
  "tiles": [
    "http://localhost:8080/tiles/WebMercatorQuad/{z}/{y}/{x}?variables=temperature&style=raster/viridis&colorscalerange=250,310"
  ],
  "minzoom": 0,
  "maxzoom": 18,
  "bounds": [-180, -90, 180, 90],
  "center": [0, 0, 2],
  "legend": "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310",
  "links": []
}
```

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

### Get Specific Tileset Metadata

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

Retrieves metadata for a specific tileset, defined by a dataset and tile matrix set combination.

```APIDOC
## GET /tiles/{datasetId}/tilesets/{tileMatrixSetId}

### Description
Get metadata for a specific tileset (dataset + TMS combination).

### Method
GET

### Endpoint
/tiles/{datasetId}/tilesets/{tileMatrixSetId}

### Parameters
#### Path Parameters
- **datasetId** (string) - Required - The ID of the dataset.
- **tileMatrixSetId** (string) - Required - The ID of the tile matrix set.
```

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

### Grid System Integration in Rendering Pipeline

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

Illustrates the steps involved in integrating grid systems into the rendering pipeline, from initial detection and selection to index assignment and final rendering.

```python
# 1. Grid Detection: guess_grid_system(da) → GridSystem
# 2. Selection: grid.sel(bbox) → Slicers
# 3. Index Assignment: grid.assign_index(ds) → xr.Dataset with index coords
# 4. Cell Extraction: grid.cell_corners() → np.ndarray of rings (for polygon rendering)
# 5. Rendering: Datashader uses grids to rasterize/mesh render
```

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

### Serve Local Zarr Store using zarr+file

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

Serves a local Zarr store using the `zarr+file://` protocol. This is an alternative syntax for local Zarr stores.

```sh
xpublish-tiles --dataset zarr+file:///path/to/data.zarr
```

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

### Get Legend Data

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

Retrieves legend data as a JSON-serializable dictionary. Useful for displaying color scales and associated metadata.

```python
def legend_data(
    self,
    *,
    variant: str,
    datatype: DataType,
    colorscalerange: tuple[float, float] | None = None,
    colormap: dict[str, str] | None = None,
    abovemaxcolor: str | None = None,
    belowmincolor: str | None = None,
    label: str | None = None,
    units: str | None = None,
    stops: int = 256,
) -> dict:
    """Return legend as JSON data.
    
    Parameters
    ----------
    variant : str
        Colormap variant
    datatype : DataType
        Data type
    colorscalerange : tuple[float, float] | None
        (min, max) for continuous data
    colormap : dict[str, str] | None
        Custom colormap
    abovemaxcolor : str | None
        Out-of-range high color
    belowmincolor : str | None
        Out-of-range low color
    label : str | None
        Axis label
    units : str | None
        Data units
    stops : int
        Number of color stops for continuous data
    
    Returns
    -------
    dict
        JSON-serializable legend data with "type", "label", "units", 
        and either "stops" (continuous) or "items" (discrete)
    """
    pass
```

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

### Get Tile Legend

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

Retrieve the legend for a specific tile request, including variables, style, and color scale range.

```bash
# Get legend
curl "http://localhost:8080/tiles/legend?variables=temperature&style=raster/viridis&colorscalerange=250,310"
```

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

### 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);
    });
  })();
})();
```

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

### Creating and Optimizing PopulatedRenderContext

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

Demonstrates how to instantiate a PopulatedRenderContext with necessary parameters and optionally optimize it for rendering performance by rewriting curvilinear grids to rectilinear.

```python
from xpublish_tiles.types import PopulatedRenderContext, ContinuousData

# Assume grid_system, patch1, patch2, and data_array are defined elsewhere
# Example placeholders:
class MockGridSystem: pass
class MockPatch: 
    def __init__(self, ugrid_indexer=None, hp_indexer=None):
        self.ugrid_indexer = ugrid_indexer
        self.hp_indexer = hp_indexer
class MockDataArray: pass
class MockBBox: 
    def __init__(self, west, south, east, north):
        self.west = west
        self.south = south
        self.east = east
        self.north = north

grid_system = MockGridSystem()
patch1 = MockPatch()
patch2 = MockPatch()
data_array = MockDataArray()

context = PopulatedRenderContext(
    grid=grid_system,
    datatype=ContinuousData(valid_min=250, valid_max=310),
    bbox=MockBBox(west=-180, south=-85, east=180, north=85),
    patches=[patch1, patch2],
    da=data_array
)

# Optionally optimize for rendering
# Assuming a logger object is available
class MockLogger: 
    def info(self, msg):
        print(f"INFO: {msg}")

logger = MockLogger()
optimized = context.maybe_rewrite_to_rectilinear(width=256, height=256, logger=logger)

print("Context created and optionally optimized.")

```

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

### Basic Tile Request

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

Use this command to fetch a basic tile from the server. Specify the tile matrix set, zoom level, column, row, and desired variables.

```bash
curl "http://localhost:8080/tiles/WebMercatorQuad/3/4/2?variables=2t&style=raster/viridis&colorscalerange=280,300"
```

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

### Discrete Legend JSON Response

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

Example JSON response for a discrete data legend, listing items with their values, labels, and colors.

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

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

### Serve Built-in Datasets

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

The --dataset option allows serving pre-defined datasets. Multiple dataset names can be specified to serve them individually.

```bash
xpublish-tiles --dataset global
```

```bash
xpublish-tiles --dataset air
```

```bash
xpublish-tiles --dataset local://para_hires
```

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

### Continuous Legend JSON Response

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

Example JSON response for a continuous data legend, detailing color stops and scale information.

```json
{
  "type": "continuous",
  "label": "Temperature [K]",
  "units": "K",
  "variant": "viridis",
  "colorscalerange": [250, 310],
  "abovemaxcolor": "extend",
  "belowmincolor": "extend",
  "stops": [
    {"value": 250.0, "color": "#440154"},
    {"value": 260.5, "color": "#440154"},
    ...
    {"value": 310.0, "color": "#fde724"}
  ]
}
```

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

### Request a Tile with Custom Options

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

Request a tile with custom rendering options, including image dimensions, above/below max color settings, and specific variables and styles.

```bash
# With custom options
curl "http://localhost:8080/tiles/WebMercatorQuad/4/8/4?variables=temp&style=raster/plasma&width=512&height=512&abovemaxcolor=red&belowmincolor=transparent"
```

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

### Configure Environment Variables

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

Set environment variables to configure xpublish-tiles, such as the number of threads, async load timeouts, and maximum renderable size. Grid cache size can also be configured before importing.

```bash
# Environment variables (XPUBLISH_TILES_<KEY>=value)
export XPUBLISH_TILES_NUM_THREADS=16
export XPUBLISH_TILES_ASYNC_LOAD_TIMEOUT_PER_TILE=30
export XPUBLISH_TILES_MAX_RENDERABLE_SIZE=2147483648

# Before importing (for grid cache)
export XPUBLISH_TILES_GRID_CACHE_MAX_SIZE=32
```

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

### Legend Generation - Horizontal Colorbar

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

Generates a horizontal colorbar legend for the 'temperature' variable. This example specifies 'vertical=false' to orient the colorbar horizontally.

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

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

### Get All Registered Renderers

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

Returns a dictionary containing all currently registered renderers. The dictionary maps style IDs to their corresponding renderer classes.

```python
@classmethod
def all(cls) -> dict[str, type[Renderer]]:
    """Get all registered renderers.
    
    Returns
    -------
    dict[str, type[Renderer]]
        Mapping of style IDs to renderer classes
    """
```

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

### Basic xpublish-tiles Command

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

This is the basic command structure for running xpublish-tiles. No specific options are provided, so it will use default settings.

```bash
xpublish-tiles [OPTIONS]
```

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

### Get Tile

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

Retrieves a map tile based on the tile matrix set, zoom level, and coordinates, with various query parameters for customization.

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

### Description
Retrieves a map tile. This is the main endpoint for fetching tile data.

### Method
GET

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

### Parameters
#### Path Parameters
- **tms** (string) - Required - The tile matrix set identifier.
- **z** (int) - Required - The zoom level.
- **y** (int) - Required - The y-coordinate of the tile.
- **x** (int) - Required - The x-coordinate of the tile.

#### Query Parameters
- **variables** (string) - Required - Comma-separated list of variables to include (e.g., `temperature` or `temp,humidity`).
- **style** (string) - Required - The style to apply to the tile (e.g., `raster/viridis`, `polygons/default`).
- **colorscalerange** (string) - Optional - The range for the color scale (e.g., `250,310`).
- **colormap** (JSON) - Optional - A JSON object defining the colormap.
- **abovemaxcolor** (string) - Optional - Color for values above the maximum (e.g., `red`, `#FF0000`, `transparent`, `extend`).
- **belowmincolor** (string) - Optional - Color for values below the minimum (e.g., `red`, `#FF0000`, `transparent`, `extend`).
- **width** (int) - Optional - The width of the tile in pixels (default: 256).
- **height** (int) - Optional - The height of the tile in pixels (default: 256).
- **format** (string) - Optional - The image format (e.g., `image/png`, `image/jpeg`, `png`, `jpeg`).
- **{dimension}** (string) - Optional - Dimension-specific parameters (e.g., `time=2000-01-01` or `time=nearest::2000-01-01T04:00`).

### Request Example
```
http://localhost:8080/tiles/WebMercatorQuad/4/10/6?variables=temperature&style=raster/viridis&colorscalerange=250,310&width=256&height=256
```
```