pygmt.Figure.grdimage

Figure.grdimage(grid, *, img_out=None, frame=None, cmap=None, img_in=None, dpi=None, bit_color=None, shading=None, projection=None, monochrome=None, no_clip=None, nan_transparent=None, region=None, timestamp=None, verbose=None, xshift=None, yshift=None, interpolation=None, panel=None, coltypes=None, perspective=None, transparency=None, cores=None, **kwargs)

Project and plot grids or images.

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,+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 pygmt.grdgradient and, optionally, modified by grdmath or grdhisteq. If GMT is built with GDAL support, grid can be an image file (geo-referenced or not). In this case the image can optionally be illuminated with the file provided via the shading parameter. 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 dpi parameter. 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 interpolation parameter.

The region parameter can be used to select a map region larger or smaller than that implied by the extent of the grid.

Full parameter list at https://docs.generic-mapping-tools.org/latest/grdimage.html

Aliases:

  • A = img_out

  • B = frame

  • C = cmap

  • D = img_in

  • E = dpi

  • G = bit_color

  • I = shading

  • J = projection

  • M = monochrome

  • N = no_clip

  • Q = nan_transparent

  • R = region

  • U = timestamp

  • V = verbose

  • X = xshift

  • Y = yshift

  • c = panel

  • f = coltypes

  • n = interpolation

  • p = perspective

  • t = transparency

  • x = cores

Parameters

  • grid (str or xarray.DataArray) – The file name or a DataArray containing the input 2-D gridded data set or image to be plotted (See GRID FILE FORMATS at https://docs.generic-mapping-tools.org/latest/grdimage.html#grid-file-formats).

  • img_out (str) – out_img[=driver]. Save an image in a raster format instead of PostScript. Use extension .ppm for a Portable Pixel Map format which is the only raster format GMT can natively write. For GMT installations configured with GDAL support 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 +cargs string where args is a list of one or more concatenated number of GDAL -co arguments. 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.

  • frame (bool or str or list) – Set map boundary frame and axes attributes.

  • cmap (str) – File name of a CPT file or a series of comma-separated colors (e.g., color1,color2,color3) to build a linear continuous CPT from those colors automatically.

  • img_in (str) – [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 img_in, which specifies that the grid is in fact an image file to be read via GDAL. Append r to assign the region specified by region to the image. For example, if you have used region='d' then the image will be assigned a global domain. This mode allows you to project a raw image (an image without referencing coordinates).

  • dpi (int) – [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.

  • bit_color (str) – color[+b|f]. This parameter only applies when a resulting 1-bit image otherwise would consist of only two colors: black (0) and white (255). If so, this parameter 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 is +f].

  • shading (str or xarray.DataArray) – [intensfile|intensity|modifiers]. Give the name of a grid file or a DataArray 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 via a call to pygmt.grdgradient; append +aazimuth, +nargs, and +mambient to specify azimuth, intensity, and ambient arguments for that module, or just give +d to select the default arguments (+a-45+nt1+m0). If you want a more specific intensity scenario then run pygmt.grdgradient separately first. If we should derive intensities from another file than grid, specify the file with suitable modifiers [Default is no illumination]. Note: If the input data is an image then an intensfile or constant intensity must be provided.

  • projection (str) – Required if this is the first plot command. projcode[projparams/]width. Select map projection.

  • monochrome (bool) – Force conversion to monochrome image using the (television) YIQ transformation. Cannot be used with nan_transparent.

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

  • nan_transparent (bool) – Make grid nodes with z = NaN transparent, using the color-masking feature in PostScript Level 3 (the PS device must support PS Level 3).

  • region (str or list) – Required if this is the first plot command. xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • verbose (bool or str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorithms);

    • i - Informational messages (same as verbose=True)

    • c - Compatibility warnings

    • d - Debugging messages

  • xshift (str) – [a|c|f|r][xshift]. Shift plot origin in x-direction.

  • yshift (str) – [a|c|f|r][yshift]. Shift plot origin in y-direction. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#xy-full.

  • panel (bool or int or list) – [row,col|index]. Selects a specific subplot panel. Only allowed when in subplot mode. Use panel=True to advance to the next panel in the selected order. Instead of row,col you may also give a scalar value index which depends on the order you set via autolabel when the subplot was defined. Note: row, col, and index all start at 0.

  • coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#f-full.

  • interpolation (str) –

    [b|c|l|n][+a][+bBC][+c][+tthreshold]. Select interpolation mode for grids.

    • b to use B-spline smoothing.

    • c to use bicubic interpolation.

    • l to use bilinear interpolation.

    • n to use nearest-neighbor value (for example to plot

    categorical data).

    The following modifiers are supported:

    • +a to switch off antialiasing (where supported) [default uses antialiasing].

    • +b to override boundary conditions used, by appending g for geographic, p for periodic, or n for natural boundary conditions. For the latter two you may append x or y to specify just one direction, otherwise both are assumed.

    • +c to clip the interpolated grid to input z-min/z-max [default may exceed limits].

    • +t to control how close to nodes with NaNs the interpolation will go based on threshold. A threshold of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN. For example, 0.5 will interpolate about half way from a non-NaN value and 0.1 will go about 90% of the way [default is 0.5].

  • perspective (list or str) – [x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]. Select perspective view and set the azimuth and elevation angle of the viewpoint. Default is [180, 90]. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#perspective-full.

  • transparency (int or float) – Set transparency level, in [0-100] percent range. Default is 0, i.e., opaque. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

  • cores (bool or int) – [[-]n]. Limit the number of cores to be used in any OpenMP-enabled multi-threaded algorithms. By default we try to use all available cores. Set a number n to only use n cores (if too large it will be truncated to the maximum cores available). Finally, give a negative number -n to select (all - n) cores (or at least 1 if n equals or exceeds all).