8. Utility Scripts

The following are scripts that can be used to aid in the creation of customized Geo2Grid products. All utility scripts are stored in the bin directory:

$GEO2GRID_HOME/bin/<script>.sh ...

For simplicity, the sections below will specify the script directly, but note the scripts exist in the bin directory above.

8.1. Defining Your Own Grids (Grid Configuration Helper)

This script is meant to help those unfamiliar with PROJ.4 and projections in general. By providing a few grid parameters this script will provide a grid configuration line that can be added to a user’s custom grid configuration. Based on a center longitude and latitude, the script will choose an appropriate projection.

usage: p2g_grid_helper.sh [-h] [-p PROJ_STR]
                          grid_name center_longitude center_latitude
                          pixel_size_x pixel_size_y grid_width grid_height

8.6.1. Positional Arguments


Unique grid name


Decimal longitude value for center of grid (-180 to 180)


Decimal latitude value for center of grid (-90 to 90)


Size of each pixel in the X direction in grid units, meters for default projections.


Size of each pixel in the Y direction in grid units, meters for default projections.


Grid width in number of pixels


Grid height in number of pixels

8.6.2. Named Arguments


PROJ.4 projection string to override the default


p2g_grid_helper.sh my_grid_name -150.1 56.3 250 -250 1000 1000
# Will result in:
my_grid_name, proj4, +proj=lcc +datum=WGS84 +ellps=WGS84 +lat_0=56.30000 +lat_1=56.30000 +lon_0=-150.10000 +units=m +no_defs, 1000, 1000, 250.00000, -250.00000, -152.17946deg, 57.40550deg

The above example creates a proj4 text grid line named ‘my_grid_name’ defined to be at 250m resolution, 1000 pixels width and height, and centered at -150.1 degrees longitude and 56.3 degrees latitude. The projection is a lambert conic conformal projection which was chosen based on the center longitude and latitude.

Once this text line has been output, it can be added to a text file and referenced in the geo2grid.sh command line. For instance, if I save the output text grid line to a file named /home/user/my_grids.conf, I can create a GeoTIFF from satellite data by executing a command like this:

geo2grid.sh -r abi_l1b -w geotiff --grid-configs /home/user/my_grids.conf -g my_grid_name -f <path_to_files>

8.2. Add Overlays (Borders, Coastlines, Grids Lines, Rivers)

Add overlays to a GeoTIFF file and save as a PNG file.

usage: add_coastlines.sh [-h] [--add-coastlines]
                         [--coastlines-resolution {c,l,i,h,f}]
                         [--coastlines-level {1,2,3,4,5,6}]
                         [--coastlines-outline [COASTLINES_OUTLINE [COASTLINES_OUTLINE ...]]]
                         [--coastlines-fill [COASTLINES_FILL [COASTLINES_FILL ...]]]
                         [--coastlines-width COASTLINES_WIDTH] [--add-rivers]
                         [--rivers-resolution {c,l,i,h,f}]
                         [--rivers-level {0,1,2,3,4,5,6,7,8,9,10}]
                         [--rivers-outline [RIVERS_OUTLINE [RIVERS_OUTLINE ...]]]
                         [--rivers-width RIVERS_WIDTH] [--add-grid]
                         [--grid-no-text] [--grid-text-size GRID_TEXT_SIZE]
                         [--grid-font GRID_FONT]
                         [--grid-fill [GRID_FILL [GRID_FILL ...]]]
                         [--grid-outline [GRID_OUTLINE [GRID_OUTLINE ...]]]
                         [--grid-minor-outline [GRID_MINOR_OUTLINE [GRID_MINOR_OUTLINE ...]]]
                         [--grid-D GRID_D GRID_D] [--grid-d GRID_D GRID_D]
                         [--grid-lon-placement {tl,lr,lc,cc}]
                         [--grid-lat-placement {tl,lr,lc,cc}]
                         [--grid-width GRID_WIDTH] [--add-borders]
                         [--borders-resolution {c,l,i,h,f}]
                         [--borders-level {1,2,3}]
                         [--borders-outline [BORDERS_OUTLINE [BORDERS_OUTLINE ...]]]
                         [--borders-width BORDERS_WIDTH] [--add-colorbar]
                         [--colorbar-width COLORBAR_WIDTH]
                         [--colorbar-height COLORBAR_HEIGHT]
                         [--colorbar-tick-marks COLORBAR_TICK_MARKS]
                         [--colorbar-text-size COLORBAR_TEXT_SIZE]
                         [--colorbar-text-color [COLORBAR_TEXT_COLOR [COLORBAR_TEXT_COLOR ...]]]
                         [--colorbar-font COLORBAR_FONT]
                         [--colorbar-align {left,top,right,bottom}]
                         [--colorbar-vertical] [--colorbar-no-ticks]
                         [--colorbar-min COLORBAR_MIN]
                         [--colorbar-max COLORBAR_MAX]
                         [--colorbar-units COLORBAR_UNITS]
                         [--colorbar-title COLORBAR_TITLE]
                         [--shapes-dir SHAPES_DIR]
                         [-o OUTPUT_FILENAME [OUTPUT_FILENAME ...]] [-v]
                         input_tiff [input_tiff ...]

8.6.1. Positional Arguments


Input geotiff(s) to process

8.6.2. Named Arguments


Specify alternative directory for coastline shape files (default: GSHSS_DATA_ROOT)

-o, --output

Specify the output filename (default replace ‘.tif’ with ‘.png’)

-v, --verbose

each occurrence increases verbosity 1 level through ERROR-WARNING-INFO-DEBUG (default INFO)

Default: 0

8.2.3. coastlines


Add coastlines


Possible choices: c, l, i, h, f

Resolution of coastlines to add (crude, low, intermediate, high, full)

Default: “i”


Possible choices: 1, 2, 3, 4, 5, 6

Level of detail from the selected resolution dataset

Default: 4


Color of coastline lines (color name or 3 RGB integers)

Default: [‘yellow’]


Color of land


Width of coastline lines

Default: 1.0

8.2.4. rivers


Add rivers grid


Possible choices: c, l, i, h, f

Resolution of rivers to add (crude, low, intermediate, high, full)

Default: “c”


Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Level of detail for river lines

Default: 5


Color of river lines (color name or 3 RGB integers)

Default: [‘blue’]


Width of rivers lines

Default: 1.0

8.2.5. grid


Add lat/lon grid


Add labels to lat/lon grid


Lat/lon grid text font size

Default: 32


Path to TTF font (package provided or custom path)

Default: “Vera.ttf”


Color of grid text (color name or 3 RGB integers)

Default: [‘cyan’]


Color of grid lines (color name or 3 RGB integers)

Default: [‘cyan’]


Color of tick lines (color name or 3 RGB integers)

Default: [‘cyan’]


Degrees between grid lines (lon, lat)

Default: (10.0, 10.0)


Degrees between tick lines (lon, lat)

Default: (2.0, 2.0)


Possible choices: tl, lr, lc, cc

Longitude label placement

Default: “tb”


Possible choices: tl, lr, lc, cc

Latitude label placement

Default: “lr”


Width of grid lines

Default: 1.0

8.2.6. borders


Add country and/or region borders


Possible choices: c, l, i, h, f

Resolution of borders to add (crude, low, intermediate, high, full)

Default: “i”


Possible choices: 1, 2, 3

Level of detail for border lines

Default: 2


Color of border lines (color name or 3 RGB integers)

Default: [‘white’]


Width of border lines

Default: 1.0

8.2.7. colorbar


Add colorbar on top of image


Number of pixels wide


Number of pixels high


Extend colorbar to full width/height of the image


Tick interval in data units

Default: 5.0


Tick label font size

Default: 32


Color of tick text (color name or 3 RGB integers)

Default: [‘black’]


Path to TTF font (package provided or custom path)

Default: “Vera.ttf”


Possible choices: left, top, right, bottom

Which direction to align colorbar (see –colorbar-vertical)

Default: “bottom”


Position the colorbar vertically


Don’t include ticks and tick labels on colorbar


Minimum data value of the colorbar. Defaults to ‘min_in’ of input metadata or minimum value of the data otherwise.


Maximum data value of the colorbar. Defaults to ‘max_in’ of input metadata or maximum value of the data otherwise.


Units marker to include in the colorbar text


Title shown with the colorbar


add_coastlines.sh --add-coastlines --add-rivers --rivers-resolution=h --add-grid GOES-16_ABI_RadF_true_color_20181112_063034_GOES-East.tif
add_coastlines.sh --add-coastlines --add-borders --borders-resolution=h --borders-outline='red' --add-grid GOES-16_ABI_RadF_natural_color_20181112_183034_GOES-East.tif -o abi_natural_color_coastlines.png

8.3. Add Colormap

Add a GeoTIFF colortable to an existing single-band GeoTIFF.

usage: add_colormap.sh [-h] ct_file geotiffs [geotiffs ...]

8.6.1. Positional Arguments


Color table file to apply (CSV of (int, R, G, B, A)


Geotiff files to apply the color table to

Colormap files are comma-separated ‘integer,R,G,B,A’ text files.

A basic greyscale example for an 8-bit GeoTIFF would be:


Where the represents the lines in between, meaning every input GeoTIFF value has a corresponding RGBA value specified. The first value is the input GeoTIFF value, followed by R (red), G (green), B (blue), and A (alpha).

This script will also linearly interpolate between two values. So the above colormap file could also be written in just two lines:


Often times you may want to have the 0 value as a transparent ‘fill’ value and continue the colormap after that. This can be done by doing the following:

# 0 is a fill value
# 1 starts at bright red
# and we end with black at the end


Not all image viewers will obey the transparent (alpha) settings

Blank lines are allowed as well as spaces between line elements.

Note this script is no longer needed as of Geo2Grid 2.3 where colormaps can be specified directly in rescaling configuration files. For example:


8.4. GeoTIFF to KMZ Conversion

The gtiff2kmz.sh script converts a single GeoTIFF file into a Google Earth compatible Keyhole Markup language Zipped (KMZ) file. It is a wrapper around the GDAL tool gdal2tiles.py. The script can be executed with:

gtiff2kmz.sh input.tif [output.kmz]

Where output.kmz is an optional parameter specifying the name of the output KMZ file. If it isn’t specified it defaults to the input filename with the extension changed to .kmz.


gtiff2kmz.sh GOES-16_ABI_RadC_natural_color_20181219_174215_GOES-East.tif

8.5. Overlay GeoTIFF Images

The overlay.sh script can be used to overlay one image (ex. VIIRS EDR Active Fires) on top of another image (ex. VIIRS Adaptive DNB or True Color). This script uses GDAL’s gdal_merge.py utility underneath, but converts everything to RGBA format first for better consistency in output images.

usage: overlay.sh background.tif foreground.tif out.tif

Example: The following example shows how you would overlay the VIIRS Active Fire AFMOD resolution Fire Confidence Percentage GeoTIFF image on top of a VIIRS Day/Night Band GeoTIFF image.

overlay.sh noaa20_viirs_dynamic_dnb_20191120_151043_wgs84_fit.tif noaa20_viirs_confidence_pct_20191120_151043_wgs84_fit.tif afmod_overlay_confidence_cat.tif

8. Convert GeoTIFFs to MP4 Video

The gtiff2mp4.sh script converts a series of GeoTIFF files in to a single MP4 video file. This script uses default video creation settings to support most video players. If an image is too large for the video creation they will be automatically scaled to a smaller size.

gtiff2mp4.sh out.mp4 in1.tif in2.tif ...

This will create a MP4 video file called out.mp4 with 24 images (frames) per second.


gtiff2mp4.sh my_natural_color_animation.mp4  *natural_color*.tif

8. Remap GOES GeoTIFFs

The projection of the GOES-East and GOES-West satellites uses special parameters that are not always supported by older visualization tools. While new versions of GDAL and PROJ.4 libraries can often fix these issues, this is not always an option. Geo2Grid provides the reproject_goes.sh script to remap GOES GeoTIFFs to a nearly identical projection that is more compatible with older visualization tools. The script can be called by executing:

reproject_goes.sh in1.tif in2.tif in3.tif

The script will take the original name and add a -y to the end. So in the above example the results would be in1-y.tif, in2-y.tif, and in3-y.tif. The y refers to the sweep angle axis projection parameter that differs between the input geotiff (x) and the output geotiff (y).

8.6. Python Proj

Convert latitude/longitude coordinates to X/Y values.

usage: p2g_proj.sh [-h] [-i] proj4_str lon_point lat_point

8.6.1. Positional Arguments


PROJ.4 projection string (in quotes)


Longitude of the point to be converted (single value only)


Latitude of the point to be converted (single value only)

8.6.2. Named Arguments

-i, --inverse

Convert X/Y values to latitude/longitude coordinates


p2g_proj.sh "+proj=lcc +datum=NAD83 +ellps=GRS80 +lat_1=25 +lon_0=-95" -105.23 38.5
# Will result in:
-878781.238459 4482504.91307