Extend

comp_other_pkgs.md

@@ -29,3 +29,24 @@
  [MB-system](https://www.mbari.org/products/research-software/mb-system/) software from swath-bathymetry
  data processing.
 
+## Comparison with other packages
+
+- Q - Does GMT.jl offer the same functionality of other packages in Julia?
+- A - Yes.
+
+The list is long, non exaustive, but we are not going to do a comparison here and, besides, for many cases
+the overlap is only partial. And why is there such a overlap with other packages? Well, GMT (the C lib)
+already existed before most of them.
+
+- [ArchGDAL](https://github.com/yeesian/ArchGDAL.jl)
+- [FITSIO](https://github.com/JuliaAstro/FITSIO.jl)
+- [GADM](https://github.com/JuliaGeo/GADM.jl)
+- [GeoJSON](https://github.com/JuliaGeo/GeoJSON.jl)
+- [Geodesy](https://github.com/JuliaGeo/Geodesy.jl)
+- [HDF5](https://github.com/JuliaIO/HDF5.jl)
+- [Interpolations](https://github.com/JuliaMath/Interpolations.jl)
+- [LibGEOS](https://github.com/JuliaGeo/LibGEOS.jl)
+- [NetCDF](https://github.com/JuliaGeo/NetCDF.jl)
+- [Proj](https://github.com/JuliaGeo/Proj.jl)
+- [Rasters](https://github.com/rafaqz/Rasters.jl)
+- [Shapefile](https://github.com/JuliaGeo/Shapefile.jl)

documentation/all_docs_ref/all_refs.md

@@ -44,10 +44,20 @@
 Note: module names ending with a **\*** mean that they have not yet been ported to GMT.jl and
 its use requires resorting to the \myreflink{Monolithic} mode.
 
+## Utility functions*
+
+| | | | | | | | | | |
+|:-----|:----|:----|:----|:----|:----|:----|:----|:----|:----|
+| \myreflink{blendimg!} | \myreflink{cubeplot} | \myreflink{lelandshade} | \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{graticules} | \myreflink{orbits} | \myreflink{plotgrid!} | \myreflink{slicecube} | \myreflink{worldrectgrid} |
+| \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} | | | | | | | |
+
 ## Utility functions
 
 {{ generate_tablerefs utilfuns}}
 
+Note: This table contains links to the manuals that were automatically generated from the docstrings.
+Idealy, they should all be converted to individual man pages and moved to table above.
+
 ## GDAL utility functions
 
 {{ generate_tablerefs gdalfuns}}

documentation/modules/grd2cpt.md

@@ -135,8 +135,6 @@ Optional Arguments
 
 \textinput{common_opts/opt_h}
 
-\textinput{common_opts/opt_o}
-
 \textinput{common_opts/explain_transparency}
 
 Color Hinges

documentation/modules/makecpt.md

@@ -10,7 +10,7 @@ or
 makecpt(name::Symbol; kwargs...)
 ```
 
-Make static color palette tables (CPTs).
+Make static color palette tables (CPTs) from master CPTs.
 
 Description
 -----------
@@ -32,7 +32,7 @@ the master CPT. When there is no `COLOR_MODEL` entry in the master CPT, the `COL
 file or on the command line will be used.
 
 The second form is a quick way of generating CPT objects for use in the ``imshow`` function. Here `name` (as a symbol)
-is the name of any of the GM default paletts. It can also be the name of CPT file lieving in current directory. With it,
+is the name of any of the GM default palettes. It can also be the name of CPT file living in current directory. With it,
 you don't specify the `color=cptname` as it is already implied by the fact that first argin is a symbol. As mentioned,
 its primary usage is to quickly show a CPT with the ``imshow`` command. *e.g* ``imshow(:gray)``
 
@@ -247,6 +247,11 @@ of the listed cpt names as an output filename; hence the my_gebco.cpt in the exa
 a name, e.g., rainbow.cpt, then **makecpt** will read that file first and not look for the master CPT in the shared
 GMT directory.
 
+See Also
+--------
+
+\myreflink{grd2cpt}
+
 References
 ----------
 

documentation/utilfuns.txt

@@ -1,13 +1,9 @@
 append2fig
-blendimg!
 cart2pol
 cart2sph
-coastlinesproj
 colorzones!
 cpt4dcw
 crop
-cubeslice
-cubeplot
 date2doy
 delrows!
 df2ds
@@ -16,7 +12,6 @@ gadm
 geodetic2enu
 getbyattrib
 gmtread
-graticules
 gridit
 gunique
 hlines
@@ -36,16 +31,13 @@ mat2ds
 mat2grid
 mat2img
 ODE2ds
-orbits
 pcolor
-plotgrid!
 plotyy
 pol2cart
 polygonlevels
 rasterzones!
 regiongeog
 rescale
-slicecube
 sph2cart
 stackgrids
 streamlines
@@ -59,7 +51,4 @@ vlines
 wmsinfo
 wmsread
 wmstest
-worldrectangular
-worldrectgrid
-xyzw2cube
 yeardecimal

documentation/utilities.md

@@ -0,0 +1,3 @@
+# Utilities
+
+{{list_folder utilities}}

documentation/utilities/blendimg.md

@@ -0,0 +1,25 @@
+# blendimg!
+
+```julia
+blendimg!(img1::GMTimage, img2::GMTimage; new=false, transparency=0.5)
+```
+
+Blend the RGB `color` \myreflink{GMTimage} with the `shade` intensity image (normally obtained with
+\myreflink{gdaldem}). The `new` argument determines if we return a new RGB image or update the `color` argument.
+
+Or, blend two 2D UInt8 or 2 RGB images using transparency. 
+
+The blending method is the one explained in https://gis.stackexchange.com/questions/255537/merging-hillshade-dem-data-into-color-relief-single-geotiff-with-qgis-and-gdal/255574#255574
+
+- `img1`, `img2`: A RGB (GMTimage{UInt8, 3}) or an indexed images (GMTimage{UInt8, 2}).
+ If `img1` is RGB and `img2` is not, than transparency is ignored. However, if `img1` and `img2`
+ are of the same type (both RGB or both indexed), that the `transparency` determines the
+ relative weight of each of them.
+
+- `transparency` The default value, 0.5, gives equal weight to both images. 0.75 will make
+ `img2` weight 3/4 of the total sum, and so forth.
+
+- `new` If true returns a new GMTimage object, otherwise it changes the `img1` content.
+
+Returns ``nothing`` if `new` option has not been used or a \myreflink{GMTimage}, either RGB or indexed
+depending on the options used.

documentation/utilities/coastlinesproj.md

@@ -0,0 +1,39 @@
+# coastlinesproj
+
+```julia
+cl = coastlinesproj(proj="?", res="crude", coastlines=nothing)
+```
+
+Extract the coastlines from GMT's GSHHG database and project them using PROJ (NOT the GMT projection machinery).
+This allows the use of many of the PROJ projections that are not available from pure GMT.
+
+- `proj`: A proj4 string describing the projection (Mandatory).
+
+- `res`: The GSHHG coastline resolution. Available options are: `crude`, `low`, `intermediate`, `high` and `full`
+
+- `coastlines`: In alternative to the `res` option, one may pass a GMTdataset with coastlines
+ previously loaded (with \myreflink{gmtread}) from another source.
+
+- `limits`: If not empty it must be a 2 elements array with lon_min, lon_max that is used to ask for
+ coastlines that expand more than 360 degrees (\myreflink{worldrectangular} uses this).
+
+
+Returns
+-------
+
+A Vector of \myreflink{GMTdataset} containing the projected (or not) world GSHHG coastlines at resolution `res`.
+
+
+Example
+-------
+
+```julia
+using GMT
+cl = coastlinesproj(proj="+proj=ob_tran +o_proj=moll +o_lon_p=40 +o_lat_p=50 +lon_0=60");
+```
+
+See Also
+--------
+
+\myreflink{graticules}, \myreflink{plotgrid!}, \myreflink{worldrectangular}, \myreflink{worldrectgrid}, \myreflink{worldrectcoast},
+\myreflink{Best rectangular world map projection}

documentation/utilities/cubeplot.md

@@ -0,0 +1,40 @@
+# cubeplot
+
+```julia
+cubeplot(img1::Union{GMTimage, String}, img12::Union{GMTimage, String}="", img1e3::Union{GMTimage, String}="";
+ back::Bool=false, show=false, notop::Bool=false, kw...)
+```
+
+Plot images on the sides of a cube. Those images can be provided as file names, or \myreflink{GMTimage} objects.
+
+- `img1,2,3`: File names or GMTimages of the images to be plotted on the three cube sides. Of those three, only
+ `img1` is mandatory, case in which it will be repeated in the thre visible sides of the cube. If `img1` and
+ `img2`, this second image is plotted on the two vertical sides. When the three images are provided, the first
+ goes to top (or bottom if `back=true`) the second to the *xz* and third to *yz* planes. 
+
+- `back`: Boolean that defaults to false, meaning that images are printed on the front sides of the cube. If `false`,
+ the images are printed in the back sides. Use this option when wanting to plot on the walls of a 3D lines/scatter
+ or grid views. The default is to print on the front facades.
+
+- `notop`: If true, do not plot the top side (implies `back=false`)
+
+- `show`: If `true`, finish and display the figure.
+
+The `kw...` keyword/value options may be used to pass:
+
+- `region`: The limits extents that will be used to annotate the *x,y,z* axes. It uses the same syntax as all
+ other modules that accept this option (*e.g.* \myreflink{coast}). It defaults to "0/9/0/9/0/9"
+
+- `figsize`: Select the horizontal size(s). Defaults to 15x15 cm.
+
+- `zsize`: Sets the size of *z* axis in cm. The default is 15.
+
+- `view`: The view point. Default is `(135,30)`. WARNING: only azimute views from the 4rth quadrant are implemented.
+
+- `transparency`: Sets the image's transparency level in the [0,1] or [0 100] intervals. Default is opaque.
+
+
+See Also
+--------
+
+\myreflink{slicecube}, \myreflink{xyzw2cube}

documentation/utilities/graticules.md

@@ -0,0 +1,50 @@
+# graticules
+
+```julia
+grat = graticules(D, width=(30,20), grid=nothing, annot_x=nothing)
+
+or
+
+grat = graticules(; proj="projection", width=(30,20), pm=0, grid=nothing, annot_x=nothing)
+```
+
+Create a projected graticule \myreflink{GMTdataset} with meridians and parallels at `width` intervals.
+
+- `D`: A \myreflink{GMTdataset} (or vector of them) holding the projection info. Instead of GMTdataset type, this
+ argument may also be a referenced grid or image type.
+
+- `proj`: Alternatively pass a proj4 string or Symbol describing the projection
+
+- `pm`: The projection prime meridian (Default is 0 or whatever is in D.proj4).
+
+- `width`: A scalar or two elements array/tuple with increments in longitude and latitude. If scalar, width_x = width_y.
+
+- `grid`: Instead of using the `width` argument, that generates an automatic set of graticules, one may pass
+ a two elements Vector{Vector{Real}} with the meridians (grid[1]) and parallels (grid[2]) to create.
+
+- `annot_x`: By default, all meridians are annotated when `grat` is used in the \myreflink{plotgrid!} function, but
+ depending on the projection and the `latlim` argument used in \myreflink{worldrectangular} we may have the longitude
+ labels overlap close to the prime meridian. To minimize that pass a vector of longitudes to be annotated.
+ *e.g.* ` annot_x=[-180,-150,0,150,180]` will annotate only those longitudes.
+
+Returns
+-------
+
+A Vector of \myreflink{GMTdataset} containing the projected meridians and parallels. `grat[i]` attributes store
+information about that element lon,lat. 
+
+Example
+-------
+
+\begin{examplefig}{}
+```julia
+using GMT
+grat = graticules(proj="+proj=ob_tran +o_proj=moll +o_lon_p=40 +o_lat_p=50 +lon_0=60");
+```
+\end{examplefig}
+
+See Also
+--------
+
+\myreflink{coastlinesproj}, \myreflink{plotgrid!}, \myreflink{worldrectangular}, \myreflink{worldrectgrid}, \myreflink{worldrectcoast},
+\myreflink{Best rectangular world map projection}

documentation/utilities/lelandshade.md

@@ -0,0 +1,74 @@
+# lelandshade
+
+**WARNING**, for some yet unknown reason this is working only on Windows
+
+```julia
+[I = ] lelandshade(G::GMTgrid; detail=1.0, contrast=2.0, intensity=false, zfactor=3, transparency=0.6,
+ show=false, color=false, opts=String[], cmap="", kw...)
+```
+
+Compute a grayscale or color shaded illumination image using the thechnique developed by [Leland Brown's "texture shading"](http:https://www.textureshading.com/Home.html) 
+
+Returns a \myreflink{GMTimage} object (8 or 16 bits depending on the `intensity` option) if `show == false`,
+or nothing otherwise.
+
+- `G`: A \myreflink{GMTgrid} or a grid file name from which to compute the Leland texture illumination image.
+
+- `detail` is the amount of texture detail. Lower values of detail retain more elevation information,
+ giving more sense of the overall, large structures and elevation trends in the terrain, at the expense
+ of fine texture detail. Higher detail enhances the texture but gives an overall "flatter" general appearance,
+ with elevation changes and large structure less apparent (default = 1.0).
+
+- `contrast` is a parameter called “vertical enhancement.” Higher numbers increase contrast in the midtones,
+ but may lose detail in the lightest and darkest features. Lower numbers highlight only the sharpest ridges
+ and deepest canyons but reduce contrast overall (default = 2.0).
+
+- `intensity | uint16` controls if output is a UInt16 or a UInt8 image (the default). Note that the original code
+ writes only UInt16 images but if we want to combine this with the hillshade computed with \myreflink{gdaldem},
+ a UInt8 image is more handy.
+
+- `zfactor`: A terrain amplification factor used in \myreflink{gdaldem} when computing the "hillshade" (default = 3)
+
+- `transparency`: The transparency of the texture image computed with the Leland algorithm when blended with
+ hillshade computed with \myreflink{gdaldem}. The default value, 0.5, gives equal weight to both images. A value of
+ 0.75 will make the texture image weight 3/4 of the total sum, and so forth (default = 0.6).
+
+- `color`: Boolean that selects if the output is a color or a grayscale image (the default). For color images
+ we create a default linear color map (via a call to \myreflink{makecpt}), but this can be overruled with the `cmap` option.
+
+- `equalize`: For color images one may select to histogram equalize the colors (via a call to \myreflink{grd2cpt}).
+ This option alone (as well as `cmap`) also sets `color=true`.
+
+- `opts`: A (optional) string vector with \myreflink{gdaldem} dedicated options (see its man mage). Use this to fine tune
+ the "hillshade" part of the final image.
+
+- `cmap`: When doing color images and don't want the default cmap, pass a color map (cpt) name (file or master
+ cpt name) or \myreflink{GMTcpt}. This also sets `color=true`.
+
+- `colorbar`: Boolean, used only when `show=true`, to add a colorbar on the right side of the image.
+
+- `show`: Boolean that if set to `true` will show the result immediately. If `false`, a \myreflink{GMTimage} object
+ is returned.
+
+- `kw`: The keword/value pairs that can be used to pass arguments to \myreflink{makecpt}, \myreflink{grd2cpt}
+ and \myreflink{gdaldem}.
+
+
+Examples
+--------
+
+To make a texture shaded from a SRTM1 arc sec grid that will be downloaded from the GMT server and uses
+the defaults indicated above, do (it may take a little while):
+
+\begin{examplefig}{}
+```julia
+using GMT
+lelandshade(gmtread("@earth_relief_01s", region=(-114,-113,35,36)), color=true, colorbar=true, show=true)
+```
+\end{examplefig}
+
+
+See Also
+--------
+
+\myreflink{gdaldem}, \myreflink{makecpt}, \myreflink{grd2cpt},