8. Utility Scripts

The following are scripts that can be used to aid in the 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.7.1. Positional Arguments

grid_name Unique grid name
center_longitude
 Decimal longitude value for center of grid (-180 to 180)
center_latitude
 Decimal latitude value for center of grid (-90 to 90)
pixel_size_x Size of each pixel in the X direction in grid units, meters for default projections.
pixel_size_y Size of each pixel in the Y direction in grid units, meters for default projections.
grid_width Grid width in number of pixels
grid_height Grid height in number of pixels

8.7.2. Named Arguments

-p PROJ.4 projection string to override the default

Example:

p2g_grid_helper.sh my_grid_name -150.1 56.3 250 -250 1000 1000
# Will result in:
my_grid_name, +proj=lcc +datum=WGS84 +ellps=WGS84 +lat_0=56.300 +lat_1=56.300 +lon_0=-150.100 +units=m +no_defs, 1000, 1000, 250.000, -250.000, -125000.000, 125000.000

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 ...]]]
                         [--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 ...]]]
                         [--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}] [--add-borders]
                         [--borders-resolution {c,l,i,h,f}]
                         [--borders-level {1,2,3}]
                         [--borders-outline [BORDERS_OUTLINE [BORDERS_OUTLINE ...]]]
                         [--add-colorbar] [--colorbar-width COLORBAR_WIDTH]
                         [--colorbar-height COLORBAR_HEIGHT]
                         [--colorbar-extend]
                         [--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.7.1. Positional Arguments

input_tiff Input geotiff(s) to process

8.7.2. Named Arguments

--shapes-dir 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
 Add coastlines
--coastlines-resolution
 

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

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

Default: “i”

--coastlines-level
 

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

Level of detail from the selected resolution dataset

Default: 4

--coastlines-outline
 

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

Default: [‘yellow’]

--coastlines-fill
 Color of land

8.2.4. rivers

--add-rivers Add rivers grid
--rivers-resolution
 

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

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

Default: “c”

--rivers-level

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

Level of detail for river lines

Default: 5

--rivers-outline
 

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

Default: [‘blue’]

8.2.5. grid

--add-grid Add lat/lon grid
--grid-no-text Add labels to lat/lon grid
--grid-text-size
 

Lat/lon grid text font size

Default: 32

--grid-font

Path to TTF font (package provided or custom path)

Default: “Vera.ttf”

--grid-fill

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

Default: [‘cyan’]

--grid-outline

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

Default: [‘cyan’]

--grid-minor-outline
 

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

Default: [‘cyan’]

--grid-D

Degrees between grid lines (lon, lat)

Default: (10.0, 10.0)

--grid-d

Degrees between tick lines (lon, lat)

Default: (2.0, 2.0)

--grid-lon-placement
 

Possible choices: tl, lr, lc, cc

Longitude label placement

Default: “tb”

--grid-lat-placement
 

Possible choices: tl, lr, lc, cc

Latitude label placement

Default: “lr”

8.2.6. borders

--add-borders Add country and/or region borders
--borders-resolution
 

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

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

Default: “i”

--borders-level
 

Possible choices: 1, 2, 3

Level of detail for border lines

Default: 2

--borders-outline
 

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

Default: [‘white’]

8.2.7. colorbar

--add-colorbar Add colorbar on top of image
--colorbar-width
 Number of pixels wide
--colorbar-height
 Number of pixels high
--colorbar-extend
 Extend colorbar to full width/height of the image
--colorbar-tick-marks
 

Tick interval in data units

Default: 5.0

--colorbar-text-size
 

Tick label font size

Default: 32

--colorbar-text-color
 

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

Default: [‘black’]

--colorbar-font
 

Path to TTF font (package provided or custom path)

Default: “Vera.ttf”

--colorbar-align
 

Possible choices: left, top, right, bottom

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

Default: “bottom”

--colorbar-vertical
 Position the colorbar vertically
--colorbar-no-ticks
 Don’t include ticks and tick labels on colorbar
--colorbar-min Minimum data value of the colorbar.Defaults to ‘min_in’ of input metadata orminimum value of the data otherwise.
--colorbar-max Maximum data value of the colorbar.Defaults to ‘max_in’ of input metadata ormaximum value of the data otherwise.
--colorbar-units
 Units marker to include in the colorbar text
--colorbar-title
 Title shown with the colorbar

Examples:

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.7.1. Positional Arguments

ct_file Color table file to apply (CSV of (int, R, G, B, A)
geotiffs 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:

0,0,0,0,255
1,1,1,1,255
...
254,254,254,254,255
255,255,255,255,255

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:

0,0,0,0,255
255,255,255,255,255

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
0,0,0,0,0
# 1 starts at bright red
1,255,0,0,255
# and we end with black at the end
255,0,0,0,255

Note

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

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

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.

Example:

gtiff2kmz.sh GOES-16_ABI_RadC_natural_color_20181219_174215_GOES-East.tif

8.5. 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 the 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.

Example:

gtiff2mp4.sh my_natural_color_animation.mp4  *natural_color*.tif

8.6. 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.7. Python Proj

Convert latitude/longitude coordinates to X/Y values.

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

8.7.1. Positional Arguments

proj4_str PROJ.4 projection string (in quotes)
lon_point Longitude of the point to be converted (single value only)
lat_point Latitude of the point to be converted (single value only)

8.7.2. Named Arguments

-i, --inverse Convert X/Y values to latitude/longitude coordinates

Example:

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