MB-System Unix Manual Page

mbm_grdtiff

Section: MB-System 5.0 (1)
Updated: 28 November 2018
Index
 

NAME

mbm_grdtiff - Create an executable shellscript which will generate a TIFF image of gridded data in a GMT grd file.

 

VERSION

Version 5.0

 

SYNOPSIS

mbm_grdtiff -Ifile [-Amagnitude[/azimuth/elevation] -Gcolor_mode -H -Kintensity_file -Nnudge_x/nudge_y -Oroot -S[color/shade] -V -W[color_style[/palette[ncolors]] | cptfile] ]

Additional Options:
[-Dflipcolor/flipshade -MGSscalefactor -MGW -Q -Rw/e/s/n -X -Y -Zmin/max[/mode]]

 

DESCRIPTION

mbm_grdtiff is a macro to generate a shellscript which, when executed, will use the program mbgrdtiff to generate a geographically located TIFF image of gridded data. The primary purpose of this macro is to allow the simple, semi-automated production of a nice looking image with a few command line arguments. Several styles of images can be generated, including color fill and shaded relief maps. The available options mirror a subset of the options in mbm_grdplot, allowing users to easily generate equivalent Postscript plots and TIFF images of gridded data. The program mbgrdtiff recognizes the coordinate system used by mbgrid or mbmosaic to generate a grid file, and then embeds the projection and grid bounds information into the TIFF image in accordance with the GeoTIFF standard. A number of GIS software packages recognize the georeferencing information in GeoTIFF images. In particular, images generated by mbgrdtiff from grids created using mbgrid or mbmosaic can be loaded into the GRASS, ArcInfo, ArcView, and ArcGIS GIS packages as geographically located coverages. The mbgrid and mbmosaic manual pages each contain an appendix with a complete list of the projected coordinate systems that may used in grid generation. Some software packages (e.g. Winfrog) do not recognize the embedded coordinate system information, and install require a parallel "world" file to specify the bounds and resolution. The -MGW option causes a world file to be generated with a ".tfw" suffix.

 

MB-SYSTEM AUTHORSHIP

David W. Caress

  Monterey Bay Aquarium Research Institute
Dale N. Chayes

  Center for Coastal and Ocean Mapping

  University of New Hampshire
Christian do Santos Ferreira

  MARUM - Center for Marine Environmental Sciences

  University of Bremen

 

SIMPLE DESCRIPTION OF BASIC OPTIONS

-A
magnitude[/azimuth/elevation]
Sets the parameters which control the synthetic illumination of the gridded data (shaded relief). The value magnitude is an effective vertical exageration which modulates the intensity of the shading; typical values are in the 0.1 to 10 range. The value azimuth is the azimuth in degrees from north from which the data is illuminated. The value elevation is the elevation of the illumination in degrees from horizontal. Defaults: magnitude = 0.2; azimuth = 0.0; elevation = 30.0;
-C
contour_control
If -C is given alone, it causes unannotated contours to be drawn using a contour interval calculated from the data. The user may also use contour_control to specify the contour interval. See the COMPLETE DESCRIPTION OF OPTIONS section below for a more complete discussion.
-D
[flipcolor/flipshade]
Normally, the color or grayscale tables used for color maps run from cool colors (or dark grays) for low grid values to hot colors (or light grays) for high grid values. This option reverses the color table so that cool colors (dark grays) correspond to high values and hot colors (light grays) to low values. If -D is given alone, it applies to the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or using an intensity file (-K and -G3 options), then setting flipshade = 1 will cause the shading convention to be reversed (e.g. high intensities overlaid as light shading). Using -D0/1 will flip the shading convention but leave the default color convention.
-G
color_mode
Turns on color fill plot and sets the style of the plot.

        color_mode = 1: Color/gray fill.
        color_mode = 2: Color/gray fill shaded by
                        synthetic illumination.
        color_mode = 3: Color/gray fill shaded by
                        an intensity file. The -K
                        option must be used to specify
                        the intensity file.

        color_mode = 4: Color/gray fill of slope
                        magnitude.

        color_mode = 5: Color/gray fill shaded by
                        slope magnitude.
-H
This "help" flag cause the program to print out a description of its operation and then exit immediately.
-I
grdfile
Sets the name of the gridded data file to be plotted. Alternatively, grdfile may be a list of grid files (one filename on each line) to be plotted together.
-K
intensity_file
Sets the name of the gridded data file containing instensity values to be used for shading the map. Alternatively, grdfile may be a list of grid files (one filename on each line) to be used together. If a list of file is supplied, the intensity files must conform in order to the data grid files they will shade.
-N
nudge_x/nudge_y Specifies positional offset in meters of the output geotiff image relative to the input grid or mosaic.
-O
root
Sets the root used to construct the filename of the output shellscript (root.cmd) and names of files created when the shellscript is run. Normally the name of the input grid file or grid file list is used as the root.
-S
[color/shade]
This option enables effective histogram equalization of the color and/or shading of the gridded data. The equalization is not achieved by changing the data values, but rather by constructing the color or shading tables so that the boundaries in the tables encompass equal fractions of the datapoints. This serves to focus color or shading contrasts in value ranges corresponding to the bulk of the data values. If -S is given alone or with color = 1, it enables equalization of the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or using an intensity file (-K and -G3 options), then setting shade = 1 will cause the shading to be equalized. Using -S0/1 will equalize the shading without equalizing the color table.
-U
orientation
Normally the orientation of the plot (portrait or landscape) is selected automatically so as to maximize the plot scale. The -U option allows the user to set the plot orientation. If orientation = 1, a portrait plot will be produced; if orientation = 2, a landscape plot will be produced.
-V
Causes mbm_grdtiff to operate in "verbose" mode so that it outputs more information than usual.
-W
[color_style[/palette[ncolors]] | cptfile]
This option controls the color scheme used for color fill plots.

If color_style = 1 [default], then the color scheme used will be a continuous grading of colors. If color_style = 2, the color scheme will be a set of discrete color intervals. The color palette used is set using palette. Five palettes are available:
        palette = 1:    Haxby colors [default]

        palette = 2:    high Intensity colors

        palette = 3:    low Intensity colors

        palette = 4:    grayscale

        palette = 5:    uniform grayscale

A complete description of the color palettes is given in the COMPLETE DESCRIPTION OF OPTIONS section below.

The ncolors parameter sets the number of color values used in plotting, whether the colors are represented in a continuous color scale or a stepped, discrete color scale [default is 11].

If the option argument is the path to an existing GMT color palette (CPT) file, then that CPT file and its color scheme will be used for the plot

 

COMPLETE DESCRIPTION OF OPTIONS

-A
magnitude[/azimuth]
Sets the parameters which control the synthetic illumination of the gridded data (shaded relief). The value magnitude is an effective vertical exageration which modulates the intensity of the shading; typical values are in the 0.1 to 0.5 range. The value azimuth is the azimuth from which the data is illuminated. Defaults: magnitude = 0.2; azimuth = 0.0;
-D
[flipcolor/flipshade]
Normally, the color or grayscale tables used for color maps run from cool colors (or dark grays) for low grid values to hot colors (or light grays) for high grid values. This option reverses the color table so that cool colors (dark grays) correspond to high values and hot colors (light grays) to low values. If -D is given alone, it applies to the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or using an intensity file (-K and -G3 options), then setting flipshade = 1 will cause the shading convention to be reversed (e.g. high intensities overlaid as light shading). Using -D0/1 will flip the shading convention but leave the default color convention.
-G
color_mode
Turns on color fill plot and sets the style of the plot.

        color_mode = 1: Color/gray fill.
        color_mode = 2: Color/gray fill shaded by
                        synthetic illumination.
        color_mode = 3: Color/gray fill shaded by
                        an intensity file. The -K
                        option must be used to specify
                        the intensity file.

        color_mode = 4: Color/gray fill of slope
                        magnitude.

        color_mode = 5: Color/gray fill shaded by
                        slope magnitude.
See the mbgrdtiff and grdimage manual pages for information on shading with intensity files
-H
This "help" flag cause the program to print out a description of its operation and then exit immediately.
-I
grdfile
Sets the name of the gridded data file to be plotted. The data must be in a form acceptable to GMT version 3 programs (see the GMT Cookbook & Technical Reference). Alternatively, grdfile may be a list of grid files (one filename on each line) to be plotted together. This is useful when data from a region is broken up into several grid files rather than a single very large grid file.
-K
intensity_file
Sets the name of the gridded data file containing instensity values to be used for shading the map. Alternatively, grdfile may be a list of grid files (one filename on each line) to be used together. If a list of files is supplied, the intensity files must conform in order to the list of data grid files they will shade.
-M
A series of "miscellaneous" options are provided which are given as -M followed by a two character identifier, followed by any other parameters associated with that option. The -M options may be strung together separated by colons, e.g. "-MGQ100:GU:CA200/10", which is equivalent to "-MGQ -MGU -MCA200/10".
-MGD
gmtdef/value
Allows the user to set the GMT default values used as the plot is constructed. This command may be given repeatedly to set as many GMT defaults as required. For example, to set the basemap annotation font to Courier, use "-MGDANOT_FONT/Courier".
-MGS
scalefactor
The gridded data is multiplied by scalefactor. This option is most often used flip the sign of the data (scalefactor = -1). [Default no scaling]
-MGW
The -MGW option causes a "world" file to be generated parallel to the GeoTiff image with a ".tfw" suffix. Some software packages (e.g. Winfrog) do not recognize the coordinate information embedded in the GeoTiff file, and look for a world file.
-O
root
Sets the root used to construct the filename of the output shellscript (root.cmd) and names of files created when the shellscript is run. Normally the name of the input grid file or grid file list is used as the root.
-Q
Normally, the output plot generation shellscript includes lines which execute the program xv to display the TIFF image on the screen. This option causes those lines to be commented out so that executing the shellscript produces a TIFF image but does not attempt to display it on the screen.
-R
west/east/south/north
west, east, south, and north specify the Region of interest. To specify boundaries in degrees and minutes [and seconds], use the dd:mm[:ss] format. Append r if lower left and upper right map coordinates are given instead of wesn. You may ask for a larger w/e/s/n region to have more room between the image and the axes. A smaller region than specified in the grdfile will result in a subset of the grid [Default is region given by the grdfile].
-S
[color/shade]
This option enables effective histogram equalization of the color and/or shading of the gridded data. The equalization is not achieved by changing the data values, but rather by constructing the color or shading tables so that the boundaries in the tables encompass equal fractions of the datapoints. This serves to focus color or shading contrasts in value ranges corresponding to the bulk of the data values. If -S is given alone or with color = 1, it enables equalization of the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or using an intensity file (-K and -G3 options), then setting shade = 1 will cause the shading to be equalized. Using -S0/1 will equalize the shading without equalizing the color table.
-V
Causes mbm_grdtiff to operate in "verbose" mode so that it outputs more information than usual.
-W
[color_style[/palette[ncolors]] | cptfile]
This option controls the color scheme used for color fill plots.

If color_style = 1 [default], then the color scheme used will be a continuous grading of colors. If color_style = 2, the color scheme will be a set of discrete color intervals. The color palette used is set using palette. Seven palettes are available:
        palette = 1:    Haxby colors [default]

        palette = 2:    high Intensity colors

        palette = 3:    low Intensity colors

        palette = 4:    grayscale

        palette = 5:    uniform grayscale

        palette = 6:    uniform black

        palette = 7:    uniform white

The RGB definitions of the color palettes are:

color palette 1 - Haxby Color Table
  red:   255 255 255 255 240 205 138 106  50  40  37
  green: 255 186 161 189 236 255 236 235 190 127  57
  blue:  255 133  68  87 121 162 174 255 255 251 175

color palette 2 - High Intensity Colors
  red:   255 255 255 255 128   0   0   0   0 128 255
  green:   0  64 128 255 255 255 255 128   0   0   0
  blue:    0   0   0   0   0   0 255 255 255 255 255

color palette 3 - Low Intensity Colors
  red:   200 194 179 141  90   0   0   0   0  90 141
  green:   0  49  90 141 179 200 141  90   0   0   0
  blue:    0   0   0   0   0   0 141 179 200 179 141

color palette 4 - Grayscale
  red:   255 230 204 179 153 128 102  77  51  26   0
  green: 255 230 204 179 153 128 102  77  51  26   0
  blue:  255 230 204 179 153 128 102  77  51  26   0

color palette 5 - Uniform Grayscale
  red:   128 128 128 128 128 128 128 128 128 128 128
  green: 128 128 128 128 128 128 128 128 128 128 128
  blue:  128 128 128 128 128 128 128 128 128 128 128

color palette 6 - Uniform Black
  red:     0   0   0   0   0   0   0   0   0   0   0
  green:   0   0   0   0   0   0   0   0   0   0   0
  blue:    0   0   0   0   0   0   0   0   0   0   0

color palette 7 - Uniform White
  red:   255 255 255 255 255 255 255 255 255 255 255
  green: 255 255 255 255 255 255 255 255 255 255 255
  blue:  255 255 255 255 255 255 255 255 255 255 255

The Haxby colors have been adapted from a palette developed by Dr. William Haxby of the Lamont-Doherty Earth Observatory; this palette is pleasing to the eye and well suited for shading. The high intensity colors describe linear paths through RGB space from red to blue to green to purple; because the colors are high intensity they are not well suited to shading. The low intensity colors are similar to the high intensity, but muted and thus well suited to shading. The grayscale palette runs linearly from white to black and is commonly used for plots of sidescan and amplitude data. The uniform grayscale is useful for non-color shaded relief plots.

The ncolors parameter sets the number of color values used in plotting, whether the colors are represented in a continuous color scale or a stepped, discrete color scale [default is 11].

If the option argument is the path to an existing GMT color palette (CPT) file, then that CPT file and its color scheme will be used for the plot

-X
Normally, mbm_grdtiff creates an executable shellscript and then exits. This option will cause the shellscript to be executed in the background before mbm_grdtiff exits.
-Y
Normally, mbm_grdplot generates nicely rounded numbers for the boundaries of the color palette. Often, the resulting color bounds extend well outside the range of the gridded data. This option causes the minimum and maximum color boundaries to exactly conform to the minimum and maximum values of the grid, or, if the -Z option is used, the minimum and maximum values specified by the user.
-Z
min/max[/mode]
This option overrides the minimum and maximum values of the gridded data, affecting the color palette and the contour interval if those parameters are not specified by the user. By default (i.e. mode is omitted or equal to 0), the macro selects the color palette bounds so that they encompass min and max while using nicely rounded numbers. If mode is omitted or equal to 0, then the color palette will end near min and max whether it is linear stretched or histogram equalized. If mode = 1, then the color stretching calculations will be done using min and max, but then the first and last values in the color palette will be set to the actual minimum and maximum values.so that all the data are displayed.

 

EXAMPLES

Suppose we have obtained two GRD files, one containing gridded bathymetry (testbath.grd) and the other mosaiced amplitude (testamp.grd). In order to generate a color fill TIFF image, we use the -G1 option. Because the data has been gridded as bathymetry (positive down) rather than as topography (positive up), the default plot will have "hot" colors for deep regions and "cold" colors for shallow regions; this is the opposite of the convention we usually use. In order to fix the colors, we have to either rescale the data by multiplying the bathymetry by -1 (accomplished with -MGS-1), or flip the color palette (accomplished with -D). We use the latter approach:


        mbm_grdtiff -Itestbath.grd -G1 -D \

            -V -Obath_fill

In order to generate a grayscale plot of the amplitude mosaic, we use -G1 and -W1/4. We also use -D so that high amplitude amplitudes are shown as dark.


        mbm_grdtiff -Itestamp.grd -G1 -D -W1/4 \

            -V -Oamp_fill

Now consider generating a shaded relief view of the gridded bathymetry. We choose to illuminate the bathymetry from the northeast (azimuth of 45 degrees) and to use a shading magnitude of 0.4 (-A0.4/45). We also use the -X flag this so that the plot generation shellscript is executed immediately. Here is the command:


        mbm_grdtiff -Itestbath.grd \

            -G2 -A0.4/45 -D -X -V \

            -Obath_shade

Now, consider generating a plot of the bathymetry overlaid with the mosaiced amplitude. The amplitude overlay is specified using the -K option. We want the colors for the bathymetry to be chosen without histogram equalization, but we also want histogram equalization to be applied to the amplitude data used for shading. To do this, we use -S0/1, where the first number (0) specifies no histogram equalization of the color scale and the second number (1) causes histogram equalization of the shading amplitude data to be implemented. In order to maintain the convention that high amplitude amplitudes are black, we flip both the color palette (as in the previous example) and the shading scale with -D1/1. We could also flip the shading by specifying a negative shading magnitude (-A-0.4).


        mbm_grdtiff -Itestbath.grd \

            -G3 -Ktestamp.grd \

            -S0/1 -D1/1 -A0.4 -X -V \

            -Obath_amp

As an example, the contents of the plotting shellscript "bath_fill_tiff.cmd" are:


#! /bin/csh -f
#
# Shellscript to create TIFF image of data in grd file
# Created by macro mbm_grdtiff
#
# This shellscript created by following command line:
# mbm_grdtiff -Itestbath.grd -G1 -D -V -Obath_fill
#
# Define shell variables used in this script:
set TIFF_FILE = bath_fill.tif
set CPT_FILE = bath_fill.cpt
set MAP_REGION = -49.28/-49.13/12.05/12.2
#
# Save existing GMT defaults
echo Saving GMT defaults...
gmtdefaults -L > gmtdefaults$$
#
# Set new GMT defaults
echo Setting new GMT defaults...
gmtset COLOR_BACKGROUND 0/0/0
gmtset COLOR_FOREGROUND 255/255/255
gmtset COLOR_NAN 255/255/255
gmtset DEGREE_FORMAT 3
#
# Make color palette table file
echo Making color palette table file...
echo -5250 255 255 255 -5100 255 186 133 > $CPT_FILE
echo -5100 255 186 133 -4950 255 161 68 >> $CPT_FILE
echo -4950 255 161 68 -4800 255 189 87 >> $CPT_FILE
echo -4800 255 189 87 -4650 240 236 121 >> $CPT_FILE
echo -4650 240 236 121 -4500 205 255 162 >> $CPT_FILE
echo -4500 205 255 162 -4350 138 236 174 >> $CPT_FILE
echo -4350 138 236 174 -4200 106 235 255 >> $CPT_FILE
echo -4200 106 235 255 -4050 50 190 255 >> $CPT_FILE
echo -4050 50 190 255 -3900 40 127 251 >> $CPT_FILE
echo -3900 40 127 251 -3750 37 57 175 >> $CPT_FILE
#
# Define data files to be plotted:
set DATA_FILE = testbath.grd
set INTENSITY_FILE =
#
# Make tiff image
echo Running mbgrdtiff...
mbgrdtiff -I $DATA_FILE
       -O $TIFF_FILE
       -C $CPT_FILE
       -V

#
# Delete surplus files
echo Deleting surplus files...
/bin/rm -f $CPT_FILE
#
# Reset GMT default fonts
echo Resetting GMT fonts...
/bin/mv gmtdefaults$$ .gmtdefaults
#
# Run xv
echo Running xv in background...
xv bath_fill.tif &
#
# All done!
echo All done!

 

SEE ALSO

mbsystem(1), mbm_grdplot(1), mbgrid(1), mbmosaic(1), mbm_grid(1), mbgrdtiff(1), gmt(1)(1), grdimage(1)

 

BUGS

This macro either has too many options, or not enough options. You choose.


 

Index

NAME
VERSION
SYNOPSIS
DESCRIPTION
MB-SYSTEM AUTHORSHIP
SIMPLE DESCRIPTION OF BASIC OPTIONS
COMPLETE DESCRIPTION OF OPTIONS
EXAMPLES
SEE ALSO
BUGS


Last Updated: 28 November 2018