13. Custom Grids

Geo2Grid provides a set of grids to suit most use cases, but sometimes these grids are not enough. This is why Geo2Grid allows users to create their own custom grids.

Grids can be static, meaning the grid definition specifies the projection, pixel size, origin, and grid size. Grids can also be dynamic, meaning that only some grid defining parameters are specified. An example of a dynamic grid is the WGS84 Dynamic Fit grid. This grid does not have an origin or grid size specified, which tells the remapping components of Geo2Grid to calculate these values from the data.

13.1. Adding your own grid

If you wish to add your own grids as a replacement for or in addition to the provided set you’ll have to make your own grid configuration file. The instructions below describe how to create your own configuration file and how it can be provided to geo2grid.sh:

  1. Create a text file named something ending in “.yaml” (ex. “my_grids.yaml”). Open it for editing. The package includes a grid_configs directory where user configuration files can be stored.

  2. Add an entry to this file for each grid you would like to add Geo2Grid. Follow the Grid Configuration File Format section below. The grid file is in the YAML text format.

  3. Call the geo2grid.sh script and add the command line option --grid-configs grids.conf <your-file.yaml>. The builtin grids in Geo2Grid are included when “grids.conf” is provided. If you would like only your grids and not the Geo2Grid provided grids don’t include the “grids.conf” in the command line option.

Geo2Grid also includes a simple script that can generate the required YAML text when provided with general information about the grid you wish to create. See the Defining Your Own Grids (Grid Configuration Helper) section.

Note

Configuration files are loaded in the order specified. If a grid name is used more than once, the last one loaded is used.

13.2. Grid Configuration File Format

Note

The legacy “.conf” format is still supported for backwards compatibility, but should not be used for new grid definition files.

Example Grid Configuration File: grid_example.yaml

Grid configuration files follow the format used by the Satpy and Pyresample Python libraries in their areas.yaml files and are in the YAML text format. Comments can be added by prefixing lines with a # character. There is an example file provided in the Geo2Grid bundle at:

$GEO2GRID_HOME/grid_configs/grid_example.yaml

Grids can be dynamic or static. Dynamic grids have some amount of information unspecified that will be filled in later at runtime using the provided input geolocation data. The most common case for a dynamic grid is specifying only “resolution”, but not “shape” or any extent information. If enough information is provided in the definition then a static grid is created which will always be in the same location at the same resolution, but will process faster as the other grid parameters don’t need to be computed.

If you are unfamiliar with projections, try the Defining Your Own Grids (Grid Configuration Helper) script. One example of a grid is shown below.

my_211e:
  description: 'My LCC grid'
  projection:
    proj: lcc
    lat_1: 25
    lat_0: 25
    lon_0: -95
    R: 6371200
    units: m
    no_defs: null
    type: crs
  shape:
    height: 5120
    width: 5120
  resolution:
    dy: 1015.9
    dx: 1015.9
  upper_left_extent:
    x: -122.9485839789149
    y: 59.86281930852158
    units: degrees

This static grid is named my_211e and has the following parameters:

  1. description: Optional human-readable description of the grid. This is not currently used by Geo2Grid.

  2. projection: PROJ.4 parameters of the projection of the grid. Can also be specified as a string. Or as an EPSG code integer. In addition to the example grids file linked above, for more information on possible parameters see the PROJ documentation.

  3. shape: Number of pixels in each dimension.

  4. resolution: Resolution of each pixel in projection units (usually meters). This can also be specified in degrees by adding a units: degrees in this section.

  5. upper_left_extent: Location of the upper-left corner of the upper-left pixel of the grid. By default this is in projection units (usually meters), but is specified in degrees here with the extra units: parameter. Note this differs from the legacy .conf format which used the center of the upper-left pixel.

See the example grids file linked above for more examples and other available parameters like center or area_extent.