MB-System Unix Manual Page: mbm_grdtiff

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

##

    mbm_grdtiff
    Section:  MB-System 5.0  (1)
    Updated:  26 October 2009
    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
    -Oroot -S[color/shade]
    -V
    -W[color_style[/pallette[ncolors]] | cptfile] ]

    Additional Options:

    [-Dflipcolor/flipshade
    -MGSscalefactor -Q -Rw/e/s/n
    -X -Y -Zmin/max]

    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.

    AUTHORSHIP

    David W. Caress (caress@mbari.org)

      Monterey Bay Aquarium Research Institute

    Dale N. Chayes (dale@ldeo.columbia.edu)

      Lamont-Doherty Earth Observatory

    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.
    -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[/pallette[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
    pallette used is set using pallette. Five pallettes
    are available:

            pallette = 1:   Haxby colors [default]

            pallette = 2:   high Intensity colors

            pallette = 3:   low Intensity colors

            pallette = 4:   grayscale

            pallette = 5:   uniform grayscale

    A complete description of the color pallettes 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 pallette (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]
    -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[/pallette[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
    pallette used is set using pallette. Seven pallettes
    are available:

            pallette = 1:   Haxby colors [default]

            pallette = 2:   high Intensity colors

            pallette = 3:   low Intensity colors

            pallette = 4:   grayscale

            pallette = 5:   uniform grayscale

            pallette = 6:   uniform black

            pallette = 7:   uniform white

    The RGB definitions of the color pallettes are:

    color pallette 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 pallette 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 pallette 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 pallette 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 pallette 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 pallette 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 pallette 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 pallette
    developed by Dr. William Haxby of the Lamont-Doherty
    Earth Observatory; this pallette 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 pallette 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 pallette (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_grdtiff generates nicely rounded numbers
    for the boundaries of the color pallette. Often, the resulting
    color bounds extend well outside the range of the gridded data.
    This option causes
    the color boundaries to be uniformly distributed between the
    minimum and maximum values of the grid.
    -Z

    min/max

    This option overrides the minimum and maximum values of
    the gridded data, affecting the color pallette and the
    contour interval if those parameters are not specified
    by the user.

    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
    pallette (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 pallette (as in the previous example) and the
    shading scale with -D1/1. We could also flip the shading
    by specifing 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 pallette table file

    echo Making color pallette 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(l), mbm_grdplot(l), mbgrid(l), mbmosaic(l),
    mbm_grid(l), mbgrdtiff(l), gmt(l)(l), grdimage(l)

    BUGS

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

     Index

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

Last Updated: 26 October 2009

Return to list of MB-System manual pages...

Back to MB-System Home Page...