RATILE v0

RATILE is a proposed raster tile data type for DuckDB extensions.

The goal of RATILE is to treat a georeferenced raster tile as a single value, similar in spirit to how GDAL models raster data as georeferencing metadata plus an array payload.

This document defines the initial RATILE v0 specification.

Status

This is a draft specification for the first version of the type.

Design Goal

RATILE is designed to store a single-band georeferenced raster tile as one typed value.

Each RATILE value contains:

• CRS
• GDAL-compatible affine transform
• Raster width and height
• Pixel data type
• NoData definition
• Pixel array payload

This means RATILE represents a raster tile as:

georeferencing + array

Non-Goals

RATILE v0 does not define:

• A table schema
• Spatial indexing strategy
• Auxiliary geometry columns
• Multi-band storage inside one RATILE value
• Compression codecs inside the tile payload

Those may be defined by higher-level table layouts or future versions.

Core Semantics

• One RATILE value represents one raster tile.
• RATILE v0 is single-band.
• The payload is stored in row-major order.
• The affine transform follows the GDAL geotransform model exactly.
• CRS is stored as a string and may vary between values.

Field Model

A RATILE v0 value consists of the following logical fields:

Field	Type	Description
crs	string	Coordinate reference system identifier or definition. Usually an authority string such as EPSG:4326, but arbitrary CRS strings are allowed.
transform	double[6]	GDAL geotransform coefficients.
width	unsigned integer	Tile width in pixels.
height	unsigned integer	Tile height in pixels.
dtype	enum	Pixel data type of the tile payload.
has_nodata	boolean	Whether the tile has a NoData value.
nodata_raw	bytes	NoData value stored in the same binary representation as dtype.
data	bytes	Pixel payload stored as packed row-major bytes.
compression	enum	Compression mode. In v0, this must be none.

CRS

The CRS is stored as a string for flexibility.

Examples:

• EPSG:4326
• EPSG:3857
• WKT
• PROJJSON

RATILE v0 does not require CRS normalization. Two CRS strings may be semantically equivalent while remaining textually different.

Transform

The transform field must follow the GDAL geotransform convention exactly:

GT(0) x-coordinate of the upper-left corner of the upper-left pixel
GT(1) w-e pixel resolution
GT(2) row rotation
GT(3) y-coordinate of the upper-left corner of the upper-left pixel
GT(4) column rotation
GT(5) n-s pixel resolution

This allows rotated or skewed tiles in addition to north-up rasters.

DType

dtype defines the binary interpretation of both data and nodata_raw.

Recommended initial set:

• uint8
• int8
• uint16
• int16
• uint32
• int32
• uint64
• int64
• float32
• float64

All multi-byte numeric values must use little-endian byte order.

NoData

If has_nodata = false, nodata_raw must be empty.

If has_nodata = true, nodata_raw must store the NoData value in the same binary representation as the tile dtype.

Examples:

• dtype = uint8, nodata = 255 -> nodata_raw is 1 byte
• dtype = int16, nodata = -9999 -> nodata_raw is 2 bytes in little-endian form
• dtype = float32, nodata = -3.4028235e+38 -> nodata_raw is 4 bytes

This avoids precision loss that may occur when normalizing NoData to double, and avoids parse overhead or ambiguity from string storage.

Data Payload

The data field stores the tile pixel array as a packed binary payload.

Rules:

• Storage order is row-major
• Payload is single-band
• Payload contains exactly width * height values
• Each value is encoded according to dtype
• Multi-byte values use little-endian byte order

Expected payload size:

width * height * sizeof(dtype)

Compression

RATILE v0 does not define internal payload compression.

Therefore:

• compression must be none
• data must contain the uncompressed packed array

This keeps the first version simple and avoids decode overhead in core tile operations.

Compression may be introduced in a future version.

Single-Band Scope

RATILE v0 stores exactly one band.

Multi-band rasters should be modeled outside the type, for example by:

• multiple RATILE values
• multiple columns
• a higher-level container type in a future version

This keeps the type semantics explicit and avoids coupling per-band metadata to a multi-band payload layout in the first version.

Derived Geometry

RATILE does not store geometry directly.

However, the spatial footprint of a tile can be derived deterministically from:

• crs
• transform
• width
• height

This enables higher-level systems to generate auxiliary geometry columns for filtering or indexing without changing the RATILE core type.

Summary

RATILE v0 is a minimal georeferenced raster tile type with the following properties:

• single-band
• GDAL-compatible transform
• flexible CRS string
• typed NoData stored as raw bytes
• row-major packed binary payload
• no internal compression in v0

The purpose of this design is to make a raster tile a first-class typed value while keeping the first version small, explicit, and implementation-friendly.