diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index a67d70a3afa..e02eb03d310 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -318,14 +318,23 @@ def grdcontour(self, grid, **kwargs): @fmt_docstring @use_alias( - R="region", - J="projection", - W="pen", + A="img_out", B="frame", - I="shading", 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", + n="interpolation", p="perspective", t="transparency", x="cores", @@ -333,9 +342,35 @@ def grdcontour(self, grid, **kwargs): @kwargs_to_strings(R="sequence", p="sequence") def grdimage(self, grid, **kwargs): """ - Project grids or images and plot them on maps. - - Takes a grid file name or an xarray.DataArray object as input. + 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 `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* + 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 *dpi* 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 + *interpolation* option. + + The *region* option can be used to select a map region larger or + smaller than that implied by the extent of the grid. Full option list at :gmt-docs:`grdimage.html` @@ -344,8 +379,82 @@ def grdimage(self, grid, **kwargs): Parameters ---------- grid : str or xarray.DataArray - The file name of the input grid or the grid loaded as a 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 + :gmt-docs:`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 **+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 PROJ syntax, otherwise a plain tiff file + is produced. (2) Any vector elements will be lost. + {B} + {CPT} + 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 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]. + shading : str + ``[intensfile|intensity|modifiers]``. + Give 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 via a call to `grdgradient`; append **+a**\\ *azimuth*, + **+n**\\ *args*, and **+m**\\ *ambient* 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 `grdgradient` + separately first. If we should derive intensities from another file + than grid, specify the file with suitable modifiers [Default is no + illumination]. + {J} + 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). + {R} + {V} {XY} + {n} {p} {t} {x}