Expand grdview options to keywords.

docs/make.jl

@@ -46,6 +46,7 @@ makedocs(
             "coast.md",
             "grdcontour.md",
             "grdimage.md",
+            "grdview.md",
             "lines.md",
             "scatter.md",
             "scatter3.md",

docs/src/coast.md

@@ -103,7 +103,7 @@ Optional Arguments
    Select filling of "wet" areas. Append the shade, color, or pattern;  [Default is no fill].
 
 - **Td** or *rose* : *rose=([map=true, inside=true, norm=true, paper=true,] anchor=refpoint, width=width [,justify=code, fancy=level, labels=labels, offset=(dx,dy)])*\
-   Draws a map directional rose on the map at the location defined by the reference and anchor points: Give the reference point on the map for the rose using one of four coordinate systems: (1) Use *map=true* for map (user) coordinates, (2) use *inner=code* for setting *refpoint* via a 2-char justification code that refers to the (invisible) map domain rectangle, (3) use *norm=true* for normalized (0-1) coordinates, or (4) use *paper=true* for plot coordinates (inches, cm, etc.). You can offset the reference point with *offset=(dx,dy)* in the direction implied by *justify=code*. By default, the anchor point is assumed to be the center of the rose (MC), but this can be changed by using *justify=code* where *code* is a 2-char justification code (see `text` for list and explanation of codes). Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*, if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*. Use *width=width* to set the width of the rose in plot coordinates (in inches, cm, or points). Add *fancy=true* to get a "fancy" rose, and specify in *level* what you want drawn. The default [1 or *true*] draws the two principal E-W, N-S orientations, 2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW. Label the cardinal points W,E,S,N by adding *labels* and append your own four comma-separated string to override the default. Skip a specific label by leaving it blank. See `Placing-dir-map-roses` and **box** on how to place a panel behind the scale.
+   Draws a map directional rose on the map at the location defined by the reference and anchor points: Give the reference point on the map for the rose using one of four coordinate systems: (1) Use *map=true* for map (user) coordinates, (2) use ``inside=code`` for setting *refpoint* via a 2-char justification code that refers to the (invisible) map domain rectangle, (3) use *norm=true* for normalized (0-1) coordinates, or (4) use *paper=true* for plot coordinates (inches, cm, etc.). You can offset the reference point with *offset=(dx,dy)* in the direction implied by *justify=code*. By default, the anchor point is assumed to be the center of the rose (MC), but this can be changed by using *justify=code* where *code* is a 2-char justification code (see `text` for list and explanation of codes). Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*, if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*. Use *width=width* to set the width of the rose in plot coordinates (in inches, cm, or points). Add *fancy=true* to get a "fancy" rose, and specify in *level* what you want drawn. The default [1 or *true*] draws the two principal E-W, N-S orientations, 2 adds the two intermediate NW-SE and NE-SW orientations, while 3 adds the eight minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and ENE-WSW. Label the cardinal points W,E,S,N by adding *labels* and append your own four comma-separated string to override the default. Skip a specific label by leaving it blank. See `Placing-dir-map-roses` and **box** on how to place a panel behind the scale.
 
 - **Tm** or *compass* : *compass=([map=true, inside=true, norm=true, paper=true,] anchor=refpoint, width=width, [*dec=(dec, dlabel), justify=code, labels=labels, rose_primary=pen, rose_secondary=pen, offset=(dx,dy)])*\
    Draws a map magnetic rose on the map at the location defined by the reference and anchor points: Give the reference point on the map for the rose using one of four coordinate systems: (1) Use *map=true* for map (user) coordinates, (2) use *inner=code* for setting *refpoint* via a 2-char justification code that refers to the (invisible) map domain rectangle, (3) use *norm=true* for normalized (0-1) coordinates, or (4) use *paper=true* for plot coordinates (inches, cm, etc.). You can offset the reference point with *offset=(dx,dy)* in the direction implied by *justify=code*. By default, the anchor point is assumed to be the center of the rose (MC), but this can be changed by using *justify=code* where *code* is a 2-char justification code (see `text` for list and explanation of codes). Note: If **-Dj** is used then *justify* defaults to the same as *refpoint*, if **-DJ** is used then *justify* defaults to the mirror opposite of *refpoint*. Use **width=width** to set the width of the rose in plot coordinates (in inches, cm, or points). Use *dec=dec* to assign the magnetic declination or *dec=(dec, dlabel) to set *dlabel*, which is a label for the magnetic compass needle (use "-" as *dlabel* to bypass labeling). With *dec*, both directions to geographic and magnetic north are plotted [Default is geographic only]. If the north label is a star (**\***) as in *dec=(1,"W,E,S.*")* then a north star is plotted instead of the north label. Annotation and two levels of tick intervals for both geographic and magnetic directions default to 30/5/1 degrees; override these settings by appending *annot=(...,...,.)*, and enter six intervals to set both the geographic (first three) and magnetic (last three) intervals. Label the cardinal points W,E,S,N by adding *label=lab* where *lab* is your own four comma-separated string to override the default. Skip a specific label by leaving it blank. The *rose_primary=pen* and *rose_secondary=pen* modify the pens used to plot the outter and inner circles of the comapss. A number GMT default parameters control pens, fonts, and color. See `Placing-dir-map-roses` and **box** on how to place a panel behind the scale.

docs/src/grdcontour.md

@@ -22,7 +22,7 @@ Optional Arguments
 - **A** or *annot* : *annot=annot_int* **|** *annot=(int=annot_int, disable=true, single=true, labels=labelinfo)*\
   *annot_int* is annotation interval in data units; it is ignored if contour levels are given in a file.
   [Default is no annotations]. Use *annot=(disable=true,)* to disable all annotations implied by **cont**.
-  Alternatively do *annot=(single=true, int=val)* to plot *val* as a single contour. The optional *labelinfo* controls the specifics of the label formatting and consists of the following control arguments [`Label formatting`](@ref label_format_quot)
+  Alternatively do *annot=(single=true, int=val)* to plot *val* as a single contour. The optional *labelinfo* controls the specifics of the label formatting and consists of a named tuple with the following control arguments [`Label formatting`](@ref label_format_quot)
 
 - **B** or *axis* or *frame*\
   Set map boundary frame and axes attributes. More at [axis](@ref)

docs/src/grdimage.md

@@ -7,9 +7,23 @@ Project grids or images and plot them on maps
 Description
 -----------
 
-Reads one 2-D grid 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](@ref) and, optionally, modified by [grdhisteq](@ref). 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 **shade** 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.
+Reads one 2-D grid 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](@ref) and, optionally, modified by [grdhisteq](@ref). 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
+**shade** 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 **region** option can be used to select a map region larger or smaller than that implied by the extent of the grid. 
 
@@ -23,35 +37,68 @@ Optional Arguments
 ------------------
 
 - **-A** or *img_out* or *image_out* : *img_out=fname*\
-   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: Use *fname* 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.
+   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: Use *fname* 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** or *axis* or *frame*\
    Set map boundary frame and axes attributes. More at [axis](@ref)
 
 - **C** or *color* or *cmap* : *color=cpt*\
-   Where *cpt* is a *GMTcpt* type or a cpt file name (for *grd_z* only). Alternatively, supply the name of a GMT color master dynamic CPT [jet] to automatically determine a continuous CPT from the grid's z-range; you may round up/down the z-range by adding **+i***zinc*. Yet another option is to specify *color="color1,color2 [,color3 ,...]" or *color=((r1,g1,b1),(r2,g2,b2),...)* 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 ) (see [Setting color](@ref)). When not explicitly set, but a color map is needed, we will either use the current color map, if available (set by a previous call to *makecpt*), or the default *jet* color map.
+   Where *cpt* is a *GMTcpt* type or a cpt file name (for *grd_z* only). Alternatively, supply the name of
+   a GMT color master dynamic CPT [jet] to automatically determine a continuous CPT from the grid's z-range;
+   you may round up/down the z-range by adding **+i** *zinc*. Yet another option is to specify
+   *color="color1,color2 [,color3 ,...]" or *color=((r1,g1,b1),(r2,g2,b2),...)* 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 ) (see [Setting color](@ref)). When not explicitly set, but a
+   color map is needed, we will either use the current color map, if available (set by a previous call to
+   *makecpt*), or the default *jet* color map.
 
 - **coast** : *coast=true* **|** coast=(...)\
-   Call the [coast](@ref) module to overlay coastlines and/or countries. The short form *coast=true* just plots the coastlines
-   with a black, 0.5p thickness line. To access all options available in the *coast* module passe them in the named tuple (...).
+   Call the [coast](@ref) module to overlay coastlines and/or countries. The short form *coast=true* just
+   plots the coastlines with a black, 0.5p thickness line. To access all options available in the *coast*
+   module passe them in the named tuple (...).
 
 - **colorbar** : *colorbar=true* **|** colorbar=(...)\
-   Call the [colorbar](@ref) module to add a colorbar. The short form *colorbar=true* automatically adds a color bar on the right side of the image using the current color map stored in the global scope. To access all options available in the *colorbar* module passe them in the named tuple (...).
+   Call the [colorbar](@ref) module to add a colorbar. The short form *colorbar=true* automatically adds a
+   color bar on the right side of the image using the current color map stored in the global scope. To
+   access all options available in the *colorbar* module passe them in the named tuple (...).
 
 - **D** or *img_in* or *image_in* : *img_in=true* **|** *img_in=: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. Use *img_in=:r* to assign the region specified by **region** to the image. For example, if you have used **region***=global* then the image will be assigned a global domain. This mode allows you to project a raw image (an image without referencing coordinates).
+   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. Use *img_in=:r* to assign the region specified
+   by **region** to the image. For example, if you have used **region***=global* then the image will be assigned
+   a global domain. This mode allows you to project a raw image (an image without referencing coordinates).
 
 - **E** or *dpi* : *dpi=xx* **|** *dpi=:i*\
-   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 *dpi=:i* to use the PostScript image operator to interpolate the image at the device resolution.
+   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 *dpi=:i* to use the PostScript image operator to interpolate the image at the
+   device resolution.
 
 - **G** : *G="+b"* **|** *G="+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*. Use *G="+b"* to paint the background pixels (1) or *G="+f"* for the foreground pixels [Default].
-
-- **I** or *shade* or *intensity* : *shade=grid* **|** *shade=azim* **|** *shade=(azimuth=az, norm=params, default=true)*\
-   Gives the name of a grid 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`; use *shade=(azimuth=az,)* or *shade=(azimuth=az, norm=params)* to specify azimuth and intensity arguments for that module or just give *shade=(default=true,)* to select the default arguments (*azim=-45,nom=:t1)*. If you want a more specific intensity scenario then run grdgradient` separately first.
-
-- **Jz**
-   Set z-axis scaling; same syntax as **proj**
+   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*. Use *G="+b"* to paint the background pixels (1) or *G="+f"* for the foreground pixels
+   [Default].
+
+- **I** or *shade* or *intensity* : *shade=grid* **|** *shade=azim* **|** *shade=(azimuth=az, norm=params, auto=true)*\
+   Gives the name of a grid 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`; use ``shade=(azimuth=az,)`` or ``shade=(azimuth=az, norm=params)`` to specify azimuth
+   and intensity arguments for that module or just give ``shade=(auto=true,)`` to select the default arguments
+   (*azim=-45,nom=:t1)*. If you want a more specific intensity scenario then run grdgradient` separately first.
+
+- **Jz** or **JZ** or *zscale* or *zsize* : *zscale=scale* **|** *zsize=size*\
+   Set z-axis scaling or or z-axis size. ``zsize=size`` sets the size to the fixed value *size*
+   (for example *zsize=10* or *zsize=4i*). ``zscale=scale`` sets the vertical scale to UNIT/z-unit.
 
 - **M** or *monochrome* : *monochrome=true*\
     Force conversion to monochrome image using the (television) YIQ transformation. Cannot be used with **nan_alpha**.