7. Utility Scripts

The following are scripts that can be used to aid in the the creation of customized Polar2Grid products.

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
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
Options:
-p PROJ.4 projection string to override the default

Example:

$POLAR2GRID_HOME/bin/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 text grid line named 'my_grid_name' at a 250m resolution, 1000 pixels wide 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 any Polar2Grid command line. For instance, if I save the output text grid line to a the /home/p2g/my_grids.txt, I can create a VIIRS GeoTIFF by executing a command like this:

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

7.2. Add Overlays (Borders, Coastlines, Grids Lines)

Convert a GeoTIFF to PNG and add coastlines and borders

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-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 ...]]]
                         [--shapes-dir SHAPES_DIR]
                         [-o OUTPUT_FILENAME [OUTPUT_FILENAME ...]] [-v]
                         input_tiff [input_tiff ...]
Positional arguments:
input_tiff Input geotiff(s) to process
Options:
--add-coastlines=False
 Add coastlines
--coastlines-resolution=i
 

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

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

--coastlines-level=4
 

Level of detail from the selected resolution dataset

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

--coastlines-outline=['yellow']
 Color of coastline lines (color name or 3 RGB integers)
--coastlines-fill
 Color of land
--add-rivers=False
 Add rivers grid
--rivers-resolution=c
 

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

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

--rivers-level=5
 

Level of detail for river lines

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

--rivers-outline=['blue']
 Color of river lines (color name or 3 RGB integers)
--add-grid=False
 Add lat/lon grid
--grid-text=False
 Add labels to lat/lon grid
--grid-text-size=32
 Lat/lon grid text font size
--grid-font=Vera.ttf
 Path to TTF font (polar2grid provided or custom path)
--grid-fill=['cyan']
 Color of grid text (color name or 3 RGB integers)
--grid-outline=['cyan']
 Color of grid lines (color name or 3 RGB integers)
--grid-minor-outline=['cyan']
 Color of tick lines (color name or 3 RGB integers)
--grid-D=(10.0, 10.0)
 Degrees between grid lines (lon, lat)
--grid-d=(2.0, 2.0)
 Degrees between tick lines (lon, lat)
--grid-lon-placement=tb
 

Longitude label placement

Possible choices: tl, lr, lc, cc

--grid-lat-placement=lr
 

Latitude label placement

Possible choices: tl, lr, lc, cc

--add-borders=False
 Add country and/or region borders
--borders-resolution=i
 

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

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

--borders-level=2
 

Level of detail for border lines

Possible choices: 1, 2, 3

--borders-outline=['white']
 Color of border lines (color name or 3 RGB integers)
--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=0, --verbose=0
 each occurrence increases verbosity 1 level through ERROR-WARNING-INFO-DEBUG (default INFO)

Example:

add_coastlines.sh --add-coastlines --add-borders gcom-w1_amsr2_btemp_89.0ah_20160719_190300_lcc_fit.tif
add_coastlines.sh --add-coastlines --add-borders --borders-resolution=h --borders-outline='red' --add-grid npp_viirs_true_color_20170305_193251_lcc_fit.tif -o myfile.png

7.3. Add Colormap

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

usage: add_colormap.sh [-h] ct_file geotiffs [geotiffs ...]
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.

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:

$POLAR2GRID_HOME/bin/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 npp_viirs_true_color_20161210_193100_wgs84_fit.tif

7.5. Python Proj

Convert lon/lat points to X/Y values

usage: p2g_proj.sh [-h] [-i] proj4_str lon_point lat_point
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)
Options:
-i=False, --inverse=False
 Convert X/Y values to lon/lat

Example:

$POLAR2GRID_HOME/bin/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