Pydantic Models

Pydantic models for GeoZarr conventions.

Spatial

geozarr_toolkit.Spatial

Bases: BaseModel

Spatial convention attributes for a Zarr group or array.

Attributes:

• dimensions (list[str]) –

  Names of spatial dimensions, e.g., ["Y", "X"] for 2D or ["Z", "Y", "X"] for 3D. Required field.

• bbox (list[float] | None) –

  Bounding box in coordinate space. For 2D: [xmin, ymin, xmax, ymax]. For 3D: [xmin, ymin, zmin, xmax, ymax, zmax].

• transform_type (str) –

  Type of transformation. Currently only "affine" is defined. Default: "affine".

• transform (list[float] | None) –

  Affine transformation coefficients [a, b, c, d, e, f] mapping array indices to coordinates: x = ai + bj + c, y = di + ej + f. Uses Rasterio/Affine library ordering.

• shape (list[int] | None) –

  Shape of spatial dimensions [height, width] for 2D or [depth, height, width] for 3D.

• registration (str) –

  Grid cell registration. "pixel" (default, PixelIsArea) means cell boundaries align with coordinates. "node" (PixelIsPoint) means cell centers align.

validate_dimensions_not_empty

validate_dimensions_not_empty() -> Spatial

Validate that dimensions list is not empty.

validate_registration

validate_registration() -> Spatial

Validate registration is either 'pixel' or 'node'.

validate_transform_length

validate_transform_length() -> Spatial

Validate that transform has exactly 6 coefficients for 2D affine.

geozarr_toolkit.SpatialConventionMetadata

Bases: ZarrConventionMetadata

Metadata for the spatial: convention in zarr_conventions array.

Proj Convention

geozarr_toolkit.Proj

Bases: BaseModel

Proj convention attributes for a Zarr group or array.

At least one of code, wkt2, or projjson must be provided.

Attributes:

• code (str | None) –

  Authority:Code identifier, e.g., "EPSG:4326", "EPSG:32633". Pattern: ^[A-Z]+:[0-9]+$

• wkt2 (str | None) –

  WKT2 (ISO 19162:2019) representation of the CRS.

• projjson (dict | None) –

  PROJJSON representation of the CRS following PROJ specification v0.7.

validate_at_least_one_crs

validate_at_least_one_crs() -> Proj

Validate that at least one CRS field is provided.

validate_code_format classmethod

validate_code_format(v: str | None) -> str | None

Validate that code matches the Authority:Code pattern.

validate_code_resolves

validate_code_resolves() -> Proj

Validate that the code resolves to a known CRS via pyproj.

geozarr_toolkit.ProjConventionMetadata

Bases: ZarrConventionMetadata

Metadata for the proj: convention in zarr_conventions array.

Multiscales Convention

geozarr_toolkit.Multiscales

Bases: BaseModel

Multiscales convention attributes for a Zarr group.

Note: This convention applies to groups only, not arrays.

Attributes:

• layout (tuple[ScaleLevel, ...]) –

  Array of scale level objects, each representing a resolution level in the pyramid.

• resampling_method (str | MISSING) –

  Default resampling method applied to all levels, e.g., "average". Can be overridden per-level.

validate_layout_not_empty classmethod

validate_layout_not_empty(
    value: tuple[ScaleLevel, ...],
) -> tuple[ScaleLevel, ...]

Validate that layout has at least one level.

geozarr_toolkit.MultiscalesConventionMetadata

Bases: ZarrConventionMetadata

Metadata for the multiscales convention in zarr_conventions array.

geozarr_toolkit.ScaleLevel

Bases: BaseModel

A single level in the multiscale pyramid.

Attributes:

• asset (str) –

  Path to the Zarr group/array for this level, e.g., "0", "level1", or "0/data" for nested structures. Relative paths only.

• derived_from (str | MISSING) –

  Path to the source level used to generate this level.

• transform (Transform | MISSING) –

  Transformation from this level to the source level. Required if derived_from is specified.

• resampling_method (str | MISSING) –

  Resampling method used for this level, e.g., "average", "nearest". Overrides the default resampling_method if specified.

geozarr_toolkit.Transform

Bases: BaseModel

Transformation between resolution levels.

Describes the coordinate transformation from a derived level back to its source level during resampling.

Attributes:

• scale (tuple[float, ...] | MISSING) –

  Scale factors per axis. Values > 1 indicate downsampling, values < 1 indicate upsampling.

• translation (tuple[float, ...] | MISSING) –

  Translation offsets per axis in coordinate space.

Base Convention

geozarr_toolkit.ZarrConventionMetadata

Bases: BaseModel

Base class for Zarr convention metadata.

At least one of uuid, schema_url, or spec_url must be provided to identify the convention.

ensure_identifiable

ensure_identifiable() -> Self

Ensure at least one identifier is provided.