grdimage¶
Project and plot grids or images
Synopsis¶
gmt grdimage grd_z | img | grd_r grd_g grd_b [ -Aout_img[=driver] ] [ -B[p|s]parameters ] [ -Ccpt ] [ -D[r] ] [ -E[i|dpi] ] -Jparameters [ -Gcolor[+b|+f] ] [ -I[intensfile|intensity|modifiers] ] [ -M ] [ -N ] [ -Q ] [ -Rwest/east/south/north[/zmin/zmax][+r][+uunit] ] [ -U[stamp] ] [ -V[level] ] [ -X[a|c|f|r][xshift[u]] ] [ -Y[a|c|f|r][yshift[u]] ] [ -fflags ] [ -nflags ] [ -pflags ] [ -ttransp ] [ --PAR=value ]
Note: No space is allowed between the option flag and the associated arguments.
Description¶
grdimage reads one 2-D grid file and produces a gray-shaded (or colored) map by plotting rectangles centered on each grid node and assigning them a gray-shade (or color) based on the z-value. Alternatively, grdimage reads three 2-D grid files with the red, green, and blue components directly (all must be in the 0-255 range). Optionally, illumination may be added by providing a file with intensities in the (-1,+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. A third alternative is available when GMT is build with GDAL support. Pass img which can be an image file (geo-referenced or not). In this case the images 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.
Required Arguments¶
- grd_z | img | grd_r grd_g grd_b
- 2-D gridded data set (or red, green, blue grids) or image to be imaged (See GRID FILE FORMATS below.)
- -Jparameters (more …)
- Select map projection.
Optional Arguments¶
- -Aout_img[=driver]
- Save an image in a raster format instead of PostScript. Use extension .ppm for a Portable Pixel Map format. For GDAL-aware versions there are more choices: Append out_img to select the image file name and extension. If the extension is one of .bmp, .gif, .jpg, .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 +c<options> 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 PROJ4 syntax, otherwise a plain tiff file is produced. (2) Any vector elements will be lost.
- -B[p|s]parameters (more …)
- Set map boundary frame and axes attributes.
- -C[cpt |master[+izinc] |color1,color2[,color3,…]]
- Name of the CPT (for grd_z only). Alternatively, supply the name of a GMT color master dynamic CPT [turbo, but geo for @earth_relief and srtm for @srtm_relief data] to automatically determine a continuous CPT from the grid’s z-range; you may round up/down the z-range by adding +izinc. Yet another option is to specify -Ccolor1,color2[,color3,…] to build a linear continuous CPT from those colors automatically. In this case color1 etc can be a r/g/b triplet, a color name, or an HTML hexadecimal color (e.g. #aabbcc ). If no argument is given to -C then under modern mode we select the current CPT.
- -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[intensfile|intensity|modifiers]
- Gives the name of a grid file with intensities in the (-1,+1) range, or a constant intensity to apply everywhere (affects the ambient light). Alternatively, derive an intensity grid from the input data grid grd_z via a call to grdgradient; append +aazimuth and +nargs to specify azimuth and intensity arguments for that module or just give +d to select the default arguments (+a-45+nt1). If you want a more specific intensity scenario then run grdgradient separately first. [Default is no illumination].
- -M
- Force conversion to monochrome image using the (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
- Make grid nodes with z = NaN transparent, using the color-masking feature in PostScript Level 3 (the PS device must support PS Level 3).
- -Rxmin/xmax/ymin/ymax[+r][+uunit] (more …)
- Specify the region of interest.
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].
- -U[label][+c][+jjust][+odx/dy] (more …)
- Draw GMT time stamp logo on plot.
- -V[level] (more …)
- Select verbosity level [c].
-X[a|c|f|r][xshift[u]]
- -Y[a|c|f|r][yshift[u]] (more …)
- Shift plot origin.
- -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.
- -t[transp] (more …)
- Set transparency level in percent.
- -^ or just -
- Print a short message about the syntax of the command, then exits (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 exits.
- -? or no arguments
- Print a complete usage (help) message, including the explanation of all options, then exits.
- --PAR=value
- Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.
Grid File Formats¶
By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF file format. However, GMT is able to produce grid files in many other commonly used grid file formats and also facilitates so called “packing” of grids, writing out floating point data as 1- or 2-byte integers. (more …)
Global Relief Datasets¶
By using grids named @earth_relief_res we download global relief grids from the GMT server. These grids are saved in your ~/.gmt/server directory while any individual SRTM tile is stored in your ~/.gmt/server/srtm3 or ~/.gmt/server/srtm1 directory. Files are only downloaded once and are later accessed from ~/.gmt. You can clear your data via gmt clear data.
| Dataset | Resolution | Size | Description |
|---|---|---|---|
| earth_relief_01s | 1 arc sec | 41 Gb | 1 arc second global relief (SRTM1S) |
| earth_relief_03s | 3 arc sec | 6.8 Gb | 3 arc second global relief (SRTM3S) |
| earth_relief_15s | 15 arc sec | 2.6 Gb | 15 arc second global relief (SRTM15+V2) |
| earth_relief_30s | 30 arc sec | 765 Mb | 30 arc second global relief (SRTM15+V2 @ 0.9 km) |
| earth_relief_01m | 1 arc min | 214 Mb | 1 arc minute global relief (SRTM15+V2 @ 1.9 km) |
| earth_relief_02m | 2 arc min | 58 Mb | 2 arc minute global relief (SRTM15+V2 @ 3.7 km) |
| earth_relief_03m | 3 arc min | 27 Mb | 3 arc minute global relief (SRTM15+V2 @ 5.6 km) |
| earth_relief_04m | 4 arc min | 16 Mb | 4 arc minute global relief (SRTM15+V2 @ 7.5 km) |
| earth_relief_05m | 5 arc min | 10 Mb | 5 arc minute global relief (SRTM15+V2 @ 9 km) |
| earth_relief_06m | 6 arc min | 7.3 Mb | 6 arc minute global relief (SRTM15+V2 @ 10 km) |
| earth_relief_10m | 10 arc min | 2.8 Mb | 10 arc minute global relief (SRTM15+V2 @ 18 km) |
| earth_relief_15m | 20 arc min | 1.3 Mb | 15 arc minute global relief (SRTM15+V2 @ 28 km) |
| earth_relief_20m | 20 arc min | 759 Kb | 20 arc minute global relief (SRTM15+V2 @ 37 km) |
| earth_relief_30m | 30 arc min | 363 Kb | 30 arc minute global relief (SRTM15+V2 @ 55 km) |
| earth_relief_01d | 1 arc deg | 106 Kb | 1 arc degree global relief (SRTM15+V2 @ 111 km) |
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 grdview -Ts instead.
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).
Image formats recognized¶
We automatically recognize image formats via their magic bytes. For formats that could contain either an image of 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.
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
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 an false color plot from the three grid files red.nc, green.nc, and blue.nc, with linear scaling at 10 inch/x-unit, tickmarks every 5 units:
gmt grdimage red.nc green.nc blue.nc -Jx10i -B5 -pdf rgbimage
When GDAL support is built in: 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