Complete documentation of grdimage (#620)

* Document common aliases for grdimage

Add automatic docstrings for frame (B), cmap (C)
projection (J), region (R), timestamp (U), verbose (V),
and interpolation (n).
Also removed alias pen (W) that actually doesn't work.

* Alias dpi (E) for grdimage
* Copy grdimage long description from GMT manpage

Copied from https://docs.generic-mapping-tools.org/6.1/grdimage.html,
swapping out short command-line arguments for long aliases.

* Alias monochrome (M), no_clip (N) and nan_transparent (Q) for grdimage
* Alias img_out (A) and img_in (D) for grdimage
* Alias bit_color (G) for grdimage
* Remove mention of RGB grid inputs, following GMT 6.2.0 grdimage docs
* Document shading (I) for grdimage

Co-authored-by: Dongdong Tian <[email protected]>

Author: weiji14

pygmt/base_plotting.py

@@ -318,24 +318,59 @@ 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",
     )
     @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}