GeoBox Model

Probably the main abstraction in odc.geo is a GeoBox. It defines a geo-registered bounded image plane. Image width and height, CRS and an affine matrix fully define geo-registered pixel plane. From this, one can compute footprint on the surface of the earth for the whole or part of the image.

Affine matrix defines linear mapping from pixel coordinates \(X_p\) to the world \(X_w\). In the most generic form affine matrix has 6 independent parameters:

\begin{eqnarray*} X_w &=& A X_p \\ \begin{pmatrix}x_w \\ y_w \\ 1\end{pmatrix} &=& \begin{pmatrix} a & b & c \\ d & e & f \\ 0 & 0 & 1 \end{pmatrix} \begin{pmatrix}x_p \\ y_p \\ 1\end{pmatrix} \end{eqnarray*}

However most data sources use square pixels aligned to \(x_w\), \(y_w\) world coordinates with image \(y_p\) axis flipped to match image coordinate convention. This form looks like this:

\begin{equation} \begin{pmatrix}x_w \\ y_w \\ 1\end{pmatrix} = \begin{pmatrix} s & 0 & t_x \\ 0 & -s & t_y \\ 0 & 0 & 1 \end{pmatrix} \begin{pmatrix}x_p \\ y_p \\ 1\end{pmatrix} \end{equation}

Image coordinate system we use is the same as used by GDAL: point \((0, 0)\) is a top left corner of the top left pixel of the image. The center of the top-left pixel is at \((0.5, 0.5)\). Valid range of pixel coordinates spans \(x_p \in [0, width], y_p \in [0, height]\).

from odc.geo.geobox import GeoBox
GeoBox.from_bbox(
   (-2_000_000, -5_000_000,
   2_250_000, -1_000_000),
   "epsg:3577", resolution=1000)

GeoBox

Dimensions

4,250x4,000

EPSG

3577

Resolution

1000m

Cell

500px

WKT

PROJCRS["GDA94 / Australian Albers",
    BASEGEOGCRS["GDA94",
        DATUM["Geocentric Datum of Australia 1994",
            ELLIPSOID["GRS 1980",6378137,298.257222101,
                LENGTHUNIT["metre",1]]],
        PRIMEM["Greenwich",0,
            ANGLEUNIT["degree",0.0174532925199433]],
        ID["EPSG",4283]],
    CONVERSION["Australian Albers",
        METHOD["Albers Equal Area",
            ID["EPSG",9822]],
        PARAMETER["Latitude of false origin",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8821]],
        PARAMETER["Longitude of false origin",132,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8822]],
        PARAMETER["Latitude of 1st standard parallel",-18,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8823]],
        PARAMETER["Latitude of 2nd standard parallel",-36,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8824]],
        PARAMETER["Easting at false origin",0,
            LENGTHUNIT["metre",1],
            ID["EPSG",8826]],
        PARAMETER["Northing at false origin",0,
            LENGTHUNIT["metre",1],
            ID["EPSG",8827]]],
    CS[Cartesian,2],
        AXIS["(E)",east,
            ORDER[1],
            LENGTHUNIT["metre",1]],
        AXIS["(N)",north,
            ORDER[2],
            LENGTHUNIT["metre",1]],
    USAGE[
        SCOPE["Statistical analysis."],
        AREA["Australia - Australian Capital Territory; New South Wales; Northern Territory; Queensland; South Australia; Tasmania; Western Australia; Victoria."],
        BBOX[-43.7,112.85,-9.86,153.69]],
    ID["EPSG",3577]]

In the sample above we have constructed a GeoBox in the Australia Albers projection with 1km pixels. It describes an image plane 4,250 pixels wide by 4,000 pixels tall. Mapping from pixel coordinates to the world coordinates in EPSG:3577 is defined by the affine matrix listed below:

\begin{equation} \begin{pmatrix}x_w \\ y_w \\ 1\end{pmatrix} = \begin{pmatrix} 1000 & 0 & -2,000,000 \\ 0 & -1000 & -1,000,000 \\ 0 & 0 & 1 \end{pmatrix} \begin{pmatrix}x_p \\ y_p \\ 1\end{pmatrix} \end{equation}

Here \(1000\) is a size of the pixel in meters, and \((-2,000,000, -1,000,000)\) is the location of the top left corner of the top left pixel (point \((0, 0)\) in the pixel coordinate system). Top left corner is marked by a circle on the map above.