How do I start?

How do I start?#

This page provides an easy entry point on how to create and use your first Equi7Grid object with this python package. The Equi7Grid is a grid framework that is a definition for the full globe and organises the continental zones and tiling systems. These tiling systems share the same tiling concept and the same map projection functions, but differ in their projection parameters that are centred on the different continents. Specifically, for the Equi7Grid seven continental equidistant azimuthal projections are used.

Equi7Grid’s seven continental tiling schemes are named as following:

  • Africa (“AF”)

  • Antarctica (“AN”)

  • Asia (“AS”)

  • Europe (“EU”)

  • North America (“NA”)

  • Oceania (“OC”)

  • South America (“SA”).

By default, each continent is organised by consistent tiling system with three tiling levels:

  • T1 (100km tile size)

  • T3 (300km tile size)

  • T6 (600km tile size) Optionally, the user may define other tiling levels, as explained in pytileproj’s tiling system documentation.

Since the Equi7Grid was primilary defined for high-resolution raster data over land surfaces, a feature of the Equi7Grid realisation is that it considers local overlap with land and ocean. For instance, tile objects carry an attribute cover_land that indicates whether the tile covers land or ocean.

Initialisation#

Lets start with how to initialise a standard Equi7Grid object. The package offers the user-facing function get_standard_equi7grid to create an Equi7Grid instance from a given sampling. If you have a certain tile size in mind, and you want to know which samplings are compatible with it, you can use the allowed_samplings function. In the following example we want to check, what samplings fit into a 600km tile size (named “T6”).

from equi7grid import allowed_samplings

allowed_samplings(600_000)

[1,
 2,
 3,
 4,
 5,
 6,
 8,
 10,
 12,
 15,
 16,
 20,
 24,
 25,
 30,
 32,
 40,
 48,
 50,
 60,
 64,
 75,
 80,
 96,
 100,
 120,
 125,
 150,
 160,
 192,
 200,
 240,
 250,
 300,
 320,
 375,
 400,
 480,
 500,
 600,
 625,
 750,
 800,
 960,
 1000,
 1200,
 1250,
 1500,
 1600,
 1875,
 2000,
 2400,
 2500,
 3000,
 3125,
 3750,
 4000,
 4800,
 5000,
 6000,
 6250,
 7500,
 8000,
 9375,
 10000,
 12000,
 12500,
 15000,
 18750,
 20000,
 24000,
 25000,
 30000,
 37500,
 40000,
 50000,
 60000,
 75000,
 100000,
 120000,
 150000,
 200000,
 300000,
 600000]

We decide to pick 1km as our grid sampling and can now pass this onto get_standard_equi7grid.

from equi7grid import get_standard_equi7grid

e7grid = get_standard_equi7grid(1000)
e7grid

Equi7Grid 
--------- 
Equi7TilingSystem(AF)
Equi7TilingSystem(AN)
Equi7TilingSystem(AS)
Equi7TilingSystem(EU)
Equi7TilingSystem(NA)
Equi7TilingSystem(OC)
Equi7TilingSystem(SA)

You just created your first Equi7Grid instance! Note that this command sets the sampling of all standard tiling levels (“T1”, “T3”, and “T6”) to 1km. Please checkout the more detailed grid documention to learn how to initialise an Equi7Grid object in a different way or to define samplings per tiling level.

The e7grid object provides several global functions for retrieving coordinates and tiles across different continents. More details can be found in the respective documentation.

Tiling system#

As you can see in the printed output of the e7grid object, each Equi7Grid continent is represented by an Equi7TilingSystem object. You can simply access these instances via the given shortcut and print some basic details:

print(e7grid.AF)  # noqa: T201

Equi7TilingSystem 
-----------------
Name: 
AF
Projection: 
+proj=aeqd +lat_0=8.5 +lon_0=21.5 +x_0=5621452.02 +y_0=5990638.423 +datum=WGS84 +units=m +no_defs +type=crs
Tilings: 
{1: RegularTiling(T6, 1000.0), 2: RegularTiling(T3, 1000.0), 3: RegularTiling(T1, 1000.0)}

Inheriting from the Equi7Grid global definitions, the tiling system defines its own projection, projection zone, land zone, and overlays the projection extent with the hierarchy of pre-defined regular tilings. Similar to e7grid, it provides methods for retrieving coordinates and tiles on a continent level.

Tile#

The Equi7Tile is the last object and smallest unit in the EquiGrid system hierarchy. It is equipped with handy functions and comprises at a manageable size a well-defined set of pixels, representing a square in the projected space. It can be retrieved by executing the tile queries of the Equi7Grid and Equi7TilingSystem classes. All functions work in the same manner, with a cover_land flag to filter for tiles covering land and a generator object as a return value. As an example, you can retrieve all tiles accross all continents intersecting with the given geographical bounding box with get_tiles_in_geog_bbox.

e7tiles = list(
    e7grid.get_tiles_in_geog_bbox(bbox=(0, 30, 10, 40), tiling_id="T6", cover_land=True)
)
[e7tile.name for e7tile in e7tiles]

['AF_E030N084T6',
 'AF_E030N090T6',
 'AF_E036N084T6',
 'AF_E036N090T6',
 'AF_E042N084T6',
 'AF_E042N090T6',
 'EU_E036N006T6',
 'EU_E042N000T6',
 'EU_E042N006T6']

In other words, an Equi7Tile instance represents a raster covering a certain space in an Equi7Grid projection, with the sampling defined by the grid and a tile extent defined by tiling system.

e7tile = e7tiles[0]
print(e7tile)  # noqa: T201

Equi7Tile 
--------- 
Name: 
AF_E030N084T6 
Shape: 
(600, 600)
Projection: 
+proj=aeqd +lat_0=8.5 +lon_0=21.5 +x_0=5621452.02 +y_0=5990638.423 +datum=WGS84 +units=m +no_defs +type=crs
Geotransformation parameters: 
(3000000.0, 1000.0, 0.0, 9000000.0, 0.0, -1000.0)
Pixel origin: 
ll
Covers land: 
True

It provides several methods for interacting with world and pixel system coordinates, its raster boundary and extent, and its topological relation with other geometries. Please checkout the tile documentation, which explains all Equi7Tile properties and methods in detail.