grdimage

Project and plot grids or images

Synopsis

gmt grdimage grid | image -Jparameters [ -Aout_img[=driver] ] [ -B[p|s]parameters ] [ -C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),…][+h[hinge]][+idz][+u|Uunit][+sfname] ] [ -D[r] ] [ -E[i|dpi] ] [ -Gcolor[+b|f] ] [ -I[file|intens|+aazimuth][+d][+mambient][+nargs] ] [ -M ] [ -N ] [ -Q[color][+i][+zvalue] ] [ -Rwest/east/south/north[/zmin/zmax][+r][+uunit] ] [ -T[+o[pen]][+s] ] [ -U[stamp] ] [ -V[level] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -fflags ] [ -nflags ] [ -pflags ] [ -ttransp ] [ -x[[-]n] ] [ --PAR=value ]

Description

grdimage reads a 2-D grid file and produces a gray-shaded (or colored) map by building a rectangular image and assigning pixels a gray-shade (or color) based on the z-value and the CPT file. Optionally, illumination may be added by providing a file with intensities in the ±1 range or instructions to derive intensities from the input data grid. Values outside this range will be clipped. Such intensity files can be created from the grid using grdgradient and, optionally, modified by grdmath or grdhisteq. Alternatively , pass image which can be an image file (geo-referenced or not). In this case the image can optionally be illuminated with the file provided via the -I option. Here, if image has no coordinates then those of the intensity file will be used.

When using map projections, the grid is first resampled on a new rectangular grid with the same dimensions. Higher resolution images can be obtained by using the -E option. To obtain the resampled value (and hence shade or color) of each map pixel, its location is inversely projected back onto the input grid after which a value is interpolated between the surrounding input grid values. By default bi-cubic interpolation is used. Aliasing is avoided by also forward projecting the input grid nodes. If two or more nodes are projected onto the same pixel, their average will dominate in the calculation of the pixel value. Interpolation and aliasing is controlled with the -n option.

The -R option can be used to select a map region larger or smaller than that implied by the extent of the grid. Finally, -A allows the creation of a direct output to a raster file instead of plotting via PostScript.

Required Arguments

grid | image

2-D gridded data set or image to be plotted (see Grid File Formats).

-Jparameters

Specify the projection. (See full description) (See cookbook summary) (See projections table).

Optional Arguments

-Aout_img[=driver]

Save an image in a raster format instead of PostScript. Append out_img to select the image file name and extension. If the extension is one of .bmp, .gif, .jp[e]g, .png, or .tif then no driver information is required. For other output formats you must append the required GDAL driver. The driver is the driver code name used by GDAL; see your GDAL installation’s documentation for available drivers. Append a +coptions string where options is a list of one or more concatenated number of GDAL -co options. For example, to write a GeoPDF with the TerraGo format use =PDF+cGEO_ENCODING=OGC_BP. Notes: (1) If a tiff file (.tif) is selected then we will write a GeoTiff image if the GMT projection syntax translates into a PROJ syntax, otherwise a plain tiff file is produced. (2) Any vector elements will be lost. Note: The -B option is not compatible with -A since no PostScript output is allowed.

-B[p|s]parameters

Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),…][+h[hinge]][+idz][+u|Uunit][+sfname]

Name of a master CPT, an input CPT file or a comma-separated list of colors from which to build a CPT. If no argument is given then under modern mode we select the current CPT, if it is available. Generally, the input can be many things:

  1. A standard GMT master CPT file, e.g., earth (see Of Colors and Color Legends) and can be either addressed by master or section/master (without any .cpt extension).

  2. File name of already custom-made cpt file (e.g, my_colors.cpt).

  3. Build a linear continuous CPT from color\(_1\),color\(_2\)[,color\(_3\),…] automatically, where z starts at 0 and is incremented by one for each color. In this case, color\(_i\) can be a r/g/b (e.g., 255/100/75), h-s-v triplet (e.g., 180-0.8-1), a c/m/y/k quadruple (e.g., 80/50/40/30), an HTML hexadecimal color (e.g. #aabbcc), or a color name. No spaces between commas are allowed.

A few modifiers pertains to hinges and units:

  • +h - If given a master CPT with soft hinges then you can enable the hinge at data value hinge [0], whereas for hard-hinge CPTs you can adjust the location of the hinge [0] but not disable it.

  • +i - Append increment dz to quantize the grid range [Default uses the exact grid range].

  • +s - Append fname to save the finalized CPT in a disk file. This is useful when the CPT is generated automatically, but if used, must be at the end of the -C option.

  • +u - For any other master CPT, you may convert their z-values from other distance Units to meter by appending the original unit code.

  • +U - Likewise, you may convert their z-values from meter to other Units by appending the desired unit code.

-D[r]

GMT will automatically detect standard image files (Geotiff, TIFF, JPG, PNG, GIF, etc.) and will read those via GDAL. For very obscure image formats you may need to explicitly set -D, which specifies that the grid is in fact an image file to be read via GDAL. Append r to assign the region specified by -R to the image. For example, if you have used -Rd then the image will be assigned a global domain. This mode allows you to project a raw image (an image without referencing coordinates).

-E[i|dpi]

Sets the resolution of the projected grid that will be created if a map projection other than Linear or Mercator was selected [100]. By default, the projected grid will be of the same size (rows and columns) as the input file. Specify i to use the PostScript image operator to interpolate the image at the device resolution.

-Gcolor[+b|f]

This option only applies when a resulting 1-bit image otherwise would consist of only two colors: black (0) and white (255). If so, this option will instead use the image as a transparent mask and paint the mask with the given color. Append +b to paint the background pixels (1) or +f for the foreground pixels [Default].

-I[file|intens|+aazimuth][+d][+mambient][+nargs]

Apply illumination for the input grid. Several methods are available:

  • Give the file name of a co-registered grid with intensities in the ±1 range.

  • Give a constant intens to apply everywhere (affects the ambient light).

Alternatively, derive intensities from the main input data grid via a call to grdgradient by appending +aazimuth, +nargs and +mambient for the arguments needed by that module, or just give +d to select the default [+a-45+nt1+m0]. For more specific intensity scenarios run grdgradient separately first. If we should derive intensities from another file than the main grid, specify that file as the file and add suitable modifiers [Default is no illumination]. Note: If the input grid actually is an image then file or constant intens must be provided since derivatives are not available.

-M

Force conversion to monochrome image using the (old-style television) YIQ transformation. Cannot be used with -Q.

-N

Do not clip the image at the map boundary (only relevant for non-rectangular maps).

-Q[color][+i][+zvalue]

Handle transparency or opacity for grids or images. There are four general schemes:

  • Grid - Plain -Q will turn grid nodes with NaN values transparent in the image, using the color-masking feature in PostScript Level 3 (the PS device must support PS Level 3). Use modifier +zvalue to specify another grid value than NaN. Each pixel is now either opaque color or fully transparent.

  • RGB image - Append a color to identify pixels that should be turned transparent [Default is white]. Each pixel is then either opaque or transparent in the output image.

  • RGBA image with two A values (0, 255) - True transparent image requires an alpha channel that is either 0 or 255. Default turns any pixel with alpha = 0 transparent.

  • RGBA image with variable transparency - If we have an alpha channel with variable transparency between 0 and 255 on a per pixel basis then the PostScript image operator cannot create true variable pixel transparency t. Instead, each r, g, and b pixel values are converted by \(r' = t R + (1-t) r\), where R (and G, B) is the transparent color at full transparency [Default is white]. If color is given then it becomes the R, B, G at full transparency. Such RGBA images will be approximated by n_columns times n_rows of tiny squares with variable color and transparency. If A reflects opacity instead of transparency then you can use modifier +i to invert these numbers first. See Limitations on transparency for more discussion. Note: The +i modifier is not available for grids.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See cookbook information).

For perspective view -p, optionally append /zmin/zmax. (more …) 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 grid file will result in a subset of the grid [Default is the region given by the grid file].

-T[+o[pen]][+s]

Plot a data grid without any interpolation. This involves converting each node-centered bin into a polygon which is then painted separately. Append +s to skip nodes with z = NaN. This option is suitable for categorical data where interpolating between values is meaningless and a categorical CPT has been provided via -C. Optionally, append +o to draw the tile outlines, and specify a custom pen if the default pen is not to your liking.

-U[label|+c][+jjustify][+odx[/dy]][+ttext]

Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-X[a|c|f|r][xshift]

Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

Shift plot origin. (See full description) (See cookbook information).

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more …)

Select interpolation mode for grids.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)

Select perspective view.

-ttransp[/transp2] (more …)

Set transparency level(s) in percent.

-x[[-]n] (more …)

Limit number of cores used in multi-threaded algorithms (OpenMP required).

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default unless stated otherwise], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

Imaging Grids With Nans

Be aware that if your input grid contains patches of NaNs, these patches can become larger as a consequence of the resampling that must take place with most map projections. Because grdimage uses the PostScript colorimage operator, for most non-linear projections we must resample your grid onto an equidistant rectangular lattice. If you find that the NaN areas are not treated adequately, consider (a) use a linear projection, or (b) use -T+s instead to plot graticule polygons.

Consequences of grid resampling

Except for Cartesian cases, we need to resample your geographic grid onto an equidistant projected grid. In doing so various algorithms come into play that projects data from one lattice to another while avoiding anti-aliasing, leading to possible distortions. One expected effect of resampling with splines is the tendency for the new resampled grid to slightly exceed the global min/max limits of the original grid. If this is coupled with tight CPT limits you may find that some map areas may show up with fore- or background color due to the resampling. In that case you have two options: (1) Modify your CPT to fit the resampled extrema (reported with -V) or (2) Impose clipping of resampled values so they do not exceed the input min/max values (add +c to your -n option). Note: If -n is not set and no CPT is given (or a master CPT is given or implied), we automatically set -nc+c.

Imaging Categorical Grids

Geographical categorical grids have values at the nodes that should not be interpolated (i.e., categories 4 and 5 should never be averaged to give a new category 4.5). However, imaging such grids using map projections requires a resampling onto an equidistant Cartesian lattice that usually will result in such blending. We do not know if a grid is categorical but if the CPT provided via -C is categorical we will override any -n setting you have chosen (perhaps implicitly) with -nn+a that turns on nearest neighbor gridding and turns off anti-aliasing. Alternatively, use -T instead to plot individual polygons centered on each node.

Imaging Categorical Images

If a 1-byte single layer image is given and the file has no color map then we will interpret the byte values as categories and a categorical CPT is required via -C. If no -C is given then we assume the image is a grayscale image with values in the 0-255 range.

Limitations on transparency

The PostScript imaging model does not support any form of transparency. However, Adobe added pdfMark which allows PostScript to specify transparency but only if activated when converting PostScript or EPS to PDF with Adobe Distiller or GhostScript. Each graphic (e.g., polygon, line, text, image) can have a specified transparency. Yet, for images this is very limited: We can choose a particular characteristic of the image to mean transparency, e.g, a specific r/g/b color or an alpha channel level (0-255). Thus, variable pixel-by-pixel transparency in a sophisticated RGBA image (color + transparency) cannot be see-through for more than a single color. Our approximation for plotting transparent RGBA images is to simulate the transparency effect on the color, but the image remains opaque (optionally apart from a single color via -Q). Since polygons can have separate transparencies then we may simulate the image by squares symbols that can have individualized color and transparency via (up to) 255 values in the alpha channel.

Image formats recognized

We automatically recognize image formats via their magic bytes. For formats that could contain either an image or a data set (e.g., geotiff) we determine which case it is and act accordingly. If your favorite image format is not automatically detected then please let us know its magic bytes so we can add it.

MacOS Preview Warning

Low-resolution raster-images appearing in PDF or PostScript files may look blurry when viewed with the Preview application under macOS. This happens because Preview decides to resample very coarse (low dpi) images instead of leaving them alone; we do not know of a simple way to turn this feature off. It is most noticeable in color bars for discrete CPTs (we now use -Np as the default setting for such CPTs) and very small grids plotted in either grdimage or grdview -Qi|c. However, if a raster format (such as JPG or PNG) is selected instead then here is no such blurring. Other PDF viewers (e.g., Adobe Acrobat) do not seem similarly affected.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

For a quick-and-dirty illuminated color map of the data in the remote file @AK_gulf_grav.nc, try:

gmt grdimage @AK_gulf_grav.nc -I+d -B -pdf quick

To gray-shade the file AK_gulf_grav.nc on a Lambert map at 1.5 cm/degree along the standard parallels 18 and 24, centered on (142W, 55N), try:

gmt begin alaska_gray
  gmt grd2cpt -Cgray @AK_gulf_grav.nc
  gmt grdimage @AK_gulf_grav.nc -Jl142W/55N/18/24/1.5c -B
gmt end show

To create an illuminated color plot of the gridded data set image.nc, using the intensities provided by the file intens.nc, and color levels in the file colors.cpt, with linear scaling at 10 inch/x-unit, tickmarks every 5 units:

gmt grdimage image.nc -Jx10i -Ccolors.cpt -Iintens.nc -B5 -pdf image

To create a sinusoidal projection of a remotely located Jessica Rabbit:

gmt grdimage -JI15c -Rd http://larryfire.files.wordpress.com/2009/07/untooned_jessicarabbit.jpg -pdf jess

Note on CPTs in Modern Mode

In modern mode, CPTs are rarely needed to be named explicitly. Instead, when a module that may create a CPT, such as grd2cpt and makecpt (or even grdimage when no color table is available), the behavior under modern mode is to write that CPT to a hidden file in the session directory. When a module requires a CPT (e.g., grdimage not given -C or plot given -C with no name) then we read this hidden CPT (if it exists). This file is called the current CPT. In fact, there are several levels of current CPTs that may all be different, and some may not be present. If you create a CPT within an inset operation then that CPT is only accessible during the inset plotting; it thus only has the inset as its scope. If you create a CPT while positioned into a specific subplot, then that CPT is likewise only accessible to that subplot. If, on the other hand, you make a CPT after subplot begin but before any plotting then that CPT is available to all the subplots (but can be locally overridden by a subplot-specific CPT mention above). Finally, each call to figure means you may have a figure-specific CPT, should you create them. If none exists then the session CPT is used. The rule gmt follows is to always get the CPT with the most restricted scope that is visible from where you are in the plotting hierarchy. If not found we go up the hierarchy to CPTs with broader scope, and if none is ultimately found (and the module, unlike grdimage, cannot create a CPT by itself), then you have likely made a scripting error. There are cases in modern mode when you must explicitly create a named CPT using the -H option. One such case is when making movies with movie since you will want to create the CPT once and have movie access it again and again. Since each movie frame is a separate session there is no cross-session sharing of current CPTs.

See Also

gmt, gmt.conf, grd2kml, grdcontour, grdview, grdgradient, grdhisteq