7. Utility Scripts

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

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

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

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

7.6.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

7.6.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, 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 polar2grid.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:

polar2grid.sh viirs_sdr gtiff --grid-configs /home/p2g/my_grids.conf -g my_grid_name -f <path_to_files>

7.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-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 ...]

7.6.1. Positional Arguments

input_tiff

Input geotiff(s) to process

7.6.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

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

--coastlines-width

Width of coastline lines

Default: 1.0

7.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’]

--rivers-width

Width of rivers lines

Default: 1.0

7.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”

--grid-width

Width of grid lines

Default: 1.0

7.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’]

--borders-width

Width of border lines

Default: 1.0

7.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 or minimum value of the data otherwise.

--colorbar-max

Maximum data value of the colorbar. Defaults to ‘max_in’ of input metadata or maximum 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

7.3. Add Colormap

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

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

7.6.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.

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

[rescale:amsr2_btemp_36.5h]
data_kind=toa_brightness_temperature
instrument=amsr2
product_name=btemp_36.5h
method=palettize
min_in=180
max_in=280
colormap=$POLAR2GRID_HOME/colormaps/amsr2_36h.cmap
alpha=False

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

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

7.6. Python Proj

Convert latitude/longitude coordinates to X/Y values.

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

7.6.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)

7.6.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