Add mosaic docs

joa-quim · joa-quim · commit 7d762b49b0f0 · 2023-11-22T17:27:16.000Z
diff --git a/_assets/common_opts/opt__j.md b/_assets/common_opts/opt__j.md
@@ -1,4 +1,4 @@
-- **j** or **spherical_dist** or **spherical** : -- *spherical=greatcirc* or *spherical=:flat* or *spherical=:ellipsoidal*\
+- **j** or **metric** or **spherical_dist** or **spherical** : -- *metric=greatcirc* or *spherical=:flat* or *spherical=:ellipsoidal*\
     Determine how spherical distances are calculated in modules that support this [Default is `spherical=:greatcirc`].
     GMT has different ways to compute distances on planetary bodies:
 
diff --git a/documentation/all_docs_ref/all_refs.md b/documentation/all_docs_ref/all_refs.md
@@ -46,10 +46,10 @@ its use requires resorting to the \myreflink{Monolithic} mode.
 |  |  |  |  |  |  |  |  |  |  |
 |:-----|:----|:----|:----|:----|:----|:----|:----|:----|:----|
 | \myreflink{ablines} | \myreflink{append2fig} | \myreflink{blendimg!} | \myreflink{colorzones!} | \myreflink{cpt4dcw} | \myreflink{crop} | \myreflink{cubeplot} | \myreflink{imagesc} | \myreflink{inwhichpolygon} | \myreflink{lelandshade} |
-| \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{gadm} | \myreflink{geodetic2enu} | \myreflink{info} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{getbyattrib} | \myreflink{gmtread} | \myreflink{gmtwrite} |
-| \myreflink{graticules} | \myreflink{gridit} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} | \myreflink{orbits} |
-| \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{rescale} | \myreflink{slicecube} | \myreflink{stackgrids} | \myreflink{theme} | \myreflink{wmsinfo} | \myreflink{wmsread} |
-| \myreflink{wmstest} | \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} |  |  |  |  |  |
+| \myreflink{coastlinesproj} | \myreflink{cubeslice} | \myreflink{gadm} | \myreflink{geocoder} | \myreflink{geodetic2enu} | \myreflink{info} | \myreflink{lelandshade} | \myreflink{linearfitxy} | \myreflink{getbyattrib} | \myreflink{gmtread} |
+| \myreflink{gmtwrite} | \myreflink{graticules} | \myreflink{gridit} | \myreflink{image_alpha!} | \myreflink{image_cpt!} | \myreflink{imshow} | \myreflink{ind2rgb} | \myreflink{mat2ds} | \myreflink{mat2grid} | \myreflink{mat2img} |
+| \myreflink{mosaic} | \myreflink{orbits} | \myreflink{pca} | \myreflink{plotgrid!} | \myreflink{polygonlevels} | \myreflink{rasterzones!} | \myreflink{rescale} | \myreflink{slicecube} | \myreflink{stackgrids} | \myreflink{theme} |
+| \myreflink{wmsinfo} | \myreflink{wmsread} | \myreflink{wmstest} | \myreflink{worldrectgrid} | \myreflink{worldrectcoast} | \myreflink{worldrectangular} | \myreflink{xyzw2cube} |  |  |  |
 
 ## Utility functions
 
diff --git a/documentation/modules/arrows.md b/documentation/modules/arrows.md
diff --git a/documentation/modules/filter1d.md b/documentation/modules/filter1d.md
@@ -93,7 +93,7 @@ Optional Arguments
     convolution. Enter *q_factor* between 0 and 1. If mean weight <
     *q_factor*, output is suppressed at this point [Default does not check Quality].
 
-- **S** or **symetry** : -- *symetry=factor*\
+- **S** or **symmetry** : -- *symmetry=factor*\
     Checks symmetry of data about window center. Enter a factor between
     0 and 1. If ( (abs(n_left - n_right)) / (n_left + n_right) ) >
     *factor*, then no output will be given at this point [Default does not check Symmetry].
diff --git a/documentation/modules/gmtconnect.md b/documentation/modules/gmtconnect.md
@@ -46,13 +46,13 @@ Optional Arguments
     segment header will be written and the segment headers of individual pieces will be written
     out as comments to make it possible to identify where the connected pieces came from.
 
-- **L** or **linkfile** : -- *linkfile=true* **|** *linkfile="file"*\
-    Writes link information to the specified file [gmtconnect_link.txt]. For each segment we
+- **L** or **links** or **linkfile** : -- *links=true* **|** *linkfile="file"*\
+    Writes link information to the specified file [gmtconnect_link.txt] (or return its contents). For each segment we
     write the original segment id, and for the beginning and end point of the segment we report the
     id of the nearest segment, whether it is the beginning (B) or end (E) point that is closest,
     and the distance between those points in units determined by **tolerance**.
 
-- **Q** or **list_file** : -- *list_file=true* **|** *list_file="template"*\
+- **Q** or **list** or **listfile** : -- *list=true* **|** *listfile="template"*\
     Used with **dump** to write a list file with the names of the individual output files.
     Optionally, append a filename template for the individual file names; this template
     **may** contain a C format specifier that can format an character (C or O for closed
diff --git a/documentation/modules/gmtconvert.md b/documentation/modules/gmtconvert.md
@@ -106,7 +106,7 @@ Optional Arguments
     combined with any other ordering scheme except **conn_method** (segmentation)
     and is applied at the end.
 
-- **Q** or **select_num** : -- *select_num=[**~**]\ *selection* *\
+- **Q** or **segments** : -- *segments=[**~**]\ *selection* *\
     Only write segments whose number is included in *selection* and skip
     all others. Cannot be used with |-S|. The *selection* syntax is
     *range*[,*range*,...] where each *range* of items is either a single
@@ -239,7 +239,7 @@ of records within each segment, try:
 To extract segments 20 to 40 in steps of 2, plus segment 0 in a file, try:
 
 ```julia
-    convert("lots_of_segments.txt", select_num="0,20:2:40")
+    convert("lots_of_segments.txt", segments="0,20:2:40")
 ```
 
 To extract the attribute ELEVATION from an ogr gmt file like this:
diff --git a/documentation/modules/gmtselect.md b/documentation/modules/gmtselect.md
@@ -64,7 +64,7 @@ Optional Arguments
     Pass all locations that are inside the valid data area of the *grid*R, which can be either a
     file name or an *in-memory* grid object. Nodes that are outside are either NaN or zero.
 
-- **I** or **reverse** or **revert** : -- *reverse=:c|f|l|r|s|z*\
+- **I** or **invert** or **reverse** : -- *invert=:c|f|l|r|s|z*\
     Reverses the sense of the test for each of the criteria specified:
 
     - **c** - select records NOT inside any point's circle of influence.
diff --git a/documentation/modules/histogram.md b/documentation/modules/histogram.md
@@ -41,7 +41,7 @@ Optional Arguments
 - **D** or **annot** or **annotate** or **count** : -- *annot=true* **|** *annot=(beneath=|font=|offset=|vertical=,)*\
    Annotate each bar with the count it represents. Add any of the following options: Use **annot=(beneath=true,)** to place the labels beneath the bars instead of above; use **annot=(font="font",)** to change to another font than the default annotation font; use **annot=(offset=val,)** to change the offset between bar and label [6p]; use **annot=(vertical=true,)** to rotate the labels from horizontal to vertical.
 
-- **E** or **width** : -- *width=val* **|** *width=(width=val, offset=val)*\ 
+- **E** or **width** : -- *width=val* **|** *width=(width=val, offset=val)*\
    Use an alternative histogram bar width than the default set via **bin**, and optionally shift all bars by an offset. Here width is either an alternative width in data units, or the user may append a valid plot dimension unit ("c|i|p") for a fixed dimension instead. Optionally, all bins may be shifted along the axis by offset. As for width, it may be given in data units of plot dimension units by appending the relevant unit.
 
 - **binmethod** or **BinMethod** : -- *binmethod=mthod*\
@@ -52,7 +52,7 @@ Optional Arguments
 
    For DateTime data: "**second**", "**minute**", "**hour**", "**day**", "**week**", "**month**" or "**year**" 
 
-- **F** or **center** : -- *center=true*\ 
+- **F** or **center** : -- *center=true*\
    Center bin on each value. [Default is left edge].
 
 - **full_histo** : -- *full_histo=true*\
diff --git a/documentation/utilities/geocoder.md b/documentation/utilities/geocoder.md
@@ -0,0 +1,55 @@
+# geocoder
+
+```julia
+D = geocoder(address::String; options=String[])
+```
+
+Get the geocoder info for a given address by calling the GDAL/OGR
+[geocoding functions](https://gdal.org/doxygen/ogr__geocoding_8h.html).
+
+### Arguments
+- `address`: The string to geocode.
+
+- `options`: These are the options passed to GDAL and in the form of a vector of strings. For example,
+  the default is equivalent to `options=["SERVICE", "OSM_NOMINATIM"]`.
+    - ``"CACHE_FILE"`` : Defaults to ``"ogr_geocode_cache.sqlite"`` (or otherwise ``"ogr_geocode_cache.csv"`` if the
+      SQLite driver isn't available). Might be any CSV, SQLite or PostgreSQL datasource.
+    - ``"READ_CACHE"`` : ``"TRUE"`` (default) or "FALSE"
+    - ``"WRITE_CACHE"`` : ``"TRUE"`` (default) or "FALSE"
+    - ``"SERVICE"``: ``"OSM_NOMINATIM"`` (default), ``"MAPQUEST_NOMINATIM"``, ``"YAHOO"``, ``"GEONAMES"``,
+        ``"BING"`` or other value.
+      Note: ``"YAHOO"`` is no longer available as a free service.
+    - ``"EMAIL"``: used by ``"OSM_NOMINATIM"``. Optional, but recommended.
+    - ``"USERNAME"``: used by ``"GEONAMES"``. Compulsory in that case.
+    - ``"KEY"``: used by BING. Compulsory in that case.
+    - ``"APPLICATION"``: used to set the User-Agent MIME header. Defaults to GDAL/OGR version string.
+    - ``"LANGUAGE"``: used to set the Accept-Language MIME header. Preferred language order for showing search results.
+    - ``"DELAY"``: minimum delay, in second, between 2 consecutive queries. Defaults to 1.0.
+    - ``"QUERY_TEMPLATE"``: URL template for GET requests. Must contain one and only one occurrence of %s in it.
+      If not specified, for ``["SERVICE", "OSM_NOMINATIM"]``, ``"MAPQUEST_NOMINATIM"``, ``"YAHOO"``, ``"GEONAMES"``
+      or ``"BING"``, the URL template is hard-coded.
+    - ``"REVERSE_QUERY_TEMPLATE"``: URL template for GET requests for reverse geocoding. Must contain one and only
+      one occurrence of {lon} and {lat} in it. If not specified, for ``["SERVICE", "OSM_NOMINATIM"]``,
+      ``"MAPQUEST_NOMINATIM"``, ``"YAHOO"``, ``"GEONAMES"`` or ``"BING"``, the URL template is hard-coded.
+
+
+Returns
+-------
+A \myreflink{GMTdataset} with the longitude, latitude, and full attribute dictionary returned by the geocoder for
+the input address. This dataset contains only one point but geocoding service resturns also a BoundingBox
+containing that point. When the `address` is very specific that BB is tiny arround the point, but when the
+query is general (for example,just the name of a city or even a country), the BB is large and may be very
+useful to use in the `mosaic` program. For that purpose, the returned BB is sored in the \myreflink{GMTdatset}
+``ds_bbox`` field.
+
+Examples
+--------
+
+```julia
+    geocoder("Paris, France")
+```
+
+See Also
+--------
+
+\myreflink{mosaic}
diff --git a/documentation/utilities/gridit.md b/documentation/utilities/gridit.md
@@ -4,7 +4,7 @@
 G = gridit(fname="", indata=nothing; method="surface", gdopts="", proj="", epsg=0, kw...)
 ```
 
-*keywords: GMT, Julia, gris interpolations, GDAL interpolate*
+*keywords: GMT, Julia, 2D interpolations, grid interpolations, GDAL interpolate*
 
 Wrapper function to interpolate scattered data into a grid.
 Interpolation methods may be those of GMT and GDAL (gdal_grid).
@@ -18,12 +18,12 @@ Interpolation methods may be those of GMT and GDAL (gdal_grid).
   "nearneighbor", "sphtriangulate", "greenspline". The arguments: "mean", "median", "mode", "std", "highest",
   "lowest" will compute those amounts inside each *rectangular* cell.
 
-     - Or (GDAL): "invdist", "invdistnn", "average", "nearest", "linear", "minimum", "maximum", "range",
-     "count", "average_distance", "average_distance_pts". See https://gdal.org/programs/gdal_grid.html#gdal-grid
+    - Or (GDAL): "invdist", "invdistnn", "average", "nearest", "linear", "minimum", "maximum", "range",
+      "count", "average_distance", "average_distance_pts". See https://gdal.org/programs/gdal_grid.html#gdal-grid
 
-     - Note that there is some overlap between the diverse methods. For example, the GMT's \myreflink{nearneighbor}
-     and GDAL's ``invdist`` apply the same algorithm (the Inverse Distance Weight) but they difer on how
-     to select the points to do the weighted average.
+    - Note that there is some overlap between the diverse methods. For example, the GMT's \myreflink{nearneighbor}
+      and GDAL's `invdist` apply the same algorithm (the Inverse Distance Weight) but they difer on how
+      to select the points to do the weighted average.
 
 - `gdopts`: List of options, in the form of a single string, accepted by the gdal_grid utility. This option
   only applies to the GDAL methods.
diff --git a/documentation/utilities/mosaic.md b/documentation/utilities/mosaic.md
@@ -0,0 +1,103 @@
+# mosaic
+
+```julia
+I = mosaic(lon, lat; pt_radius=6371007.0, provider="", zoom::Int=0, cache::String="",
+           mapwidth=15, dpi=96, verbose::Int=0, kw...)
+```
+
+*keywords: GMT, Julia, tiles image*
+
+Get image tiles from a web map tiles provider for given longitude, latitude coordinates.
+
+### Arguments
+- `lon` & `lat`:
+  - `lon, lat` two scalars with the coordinates of region of interest center. To completly define
+    the image area see the `neighbors` or `mosaic` option below.
+  - `lon, lat` are two elements vector or matrix with the region's ``[lon_min, lon_max], [lat_min, lat_max]``.
+  - Instead of two arguments, pass just one containing a GMTdataset obtained with the ``geocoder`` function.
+    Example: ``mosaic(D, ...)`` or, if the search with ``geocoder`` was sufficiently generic (see its docs),
+    ``mosaic(D, bbox=true)`` to use the BoundingBox returned by the query. `bbox` supports `bb`, `BB` or
+    `BoundingBox` as aliases.
+
+- `pt_radius`: The planetary radius. Defaults to Earth's WGS84 authalic radius (6371007 m).
+
+- `provider`: Tile provider name. Currently available options are (but for more details see the docs of the
+  `getprovider` function, *i.e.* ``? getprovider``):
+  - "Bing" (the default), "OSM", "Esri" or a custom provider.
+  - A `Provider` type from the ``TileProviders.jl`` package. You must consult the documentation of that package
+    for more details on how to choose a *provider*.
+
+- `zoom`: Zoom level (0 for automatic). A number between 0 and ~19. The maximum is provider and area dependent.
+  If `zoom=0`, the zoom level is computed automatically based on the `mapwidth` and `dpi` options.
+
+- `cache`: Full name of the the cache directory where to save the downloaded tiles. If empty, a cache
+  directory is created in the system's TMP directory. If `cache="gmt"` the cache directory is created in
+  ``~/.gmt/cache_tileserver``. NOTE: this normally is neeaded only for the first time you run this function when,
+  if `cache!=""`, the cache dir location is saved in the ``~./gmt/tiles_cache_dir.txt`` file and used in
+  subsequent calls.
+
+- `mapwidth`: Map width in cm. Used together with the `dpi` option to automatically compute the zoom level.
+
+- `dpi`: Dots per inch. Used together with the `mapwidth` option to automatically compute the zoom level.
+
+- `verbose`: Verbosity level. A number between 0 and 2. Print out info while downloading the image files.
+  Silent when geting files from local cache unless `verbose=2`, where it prints out info about the files
+  found in the cache.
+
+### kwargs (kw...)
+- `neighbors` or `mosaic`: When `lon` and `lat` are scalars, this option specifies the number of neighbors
+  of the tile containing the query point to download. Normally this should be an odd number, but it can take the
+  form of a matrix and the number of tiles is then determined by the number of rows and columns.
+
+- `merc` or `mercator`: Return tiled image in Mercator coordinates. The default is to project it back
+  to geographical coordinates.
+
+- `loose` or `loose_bounds`: By default we return an image with the limits requested in the `lon` and
+  `lat` arguments. This option makes it return an image with the limits that are determined by those of
+  the tiles that intersect the requested region. Note that this does not work for point queries.
+
+- `quadonly`: Return only the quadtree string. A string or a matrix of strings when number of tiles > 1.
+  Other from the quadtree string this option return also the `decimal_adress, lon, lat, x, y` that are:
+  the XYZ tiles coordinates, the longitude, latitude , mercator X and Y coordinates in meters of first tile.
+
+Returns
+-------
+- `I`: A \myreflink{GMTimage} element or the output of the `quadonly` option explained above.
+
+Examples
+--------
+
+- Make a figure with OpenStreetMap over Iberia maintaining the original spherical Mercator projection.
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+I = mosaic([-9.5, 3.3], [36.0, 43.8], provider=:OSM, zoom=7, merc=true)
+viz(I)
+```
+\end{examplefig}
+
+
+- Make a figure of the Big Island of Hawaii using the default Bing images. In this case
+we use the ``geocoder`` function to give us the map limits
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+# Get the geographical limits of the Big Island in Hawaii
+D = geocoder("Hawaii, Island");
+
+# Get the image tiles of the Big Island in Hawaii using the Bing provider and automatic zoom level
+I = mosaic(D, bbox=true);
+
+viz(I)
+```
+\end{examplefig}
+
+
+See Also
+--------
+
+\myreflink{geocoder}
diff --git a/documentation/utilities/rasterzones.md b/documentation/utilities/rasterzones.md
@@ -4,7 +4,7 @@
 rasterzones!(GI::GItype, shapes::Vector{GMTdataset}, fun::Function)
 ```
 
-*keywords: GMT, Julia, zonal statistical*
+*keywords: GMT, Julia, zonal statistics*
 
 Apply a unidimensional function `fun` to to the elements of the grid or image `GI` that lies inside the polygons
 of the \myreflink{GMTdataset} `shapes`. The `GI` array is modified in place.
diff --git a/gallery/ex25.md b/gallery/ex25.md
@@ -61,8 +61,8 @@ coast!(shore=:thinnest, area=500)
 # Place an explanatory legend below
 legend!(pos=(anchor=:BC, width=10), box=(pen=:thick,), yshift=-1.0, par=(:FONT_ANNOT_PRIMARY,7),
     text_record(["N 3"
-    string("S 0.3 s 0.25 red  0.25p 0.5 Terrestrial Antipodes [", land.data[1], " %]", )
-    string("S 0.3 s 0.25 blue 0.25p 0.5 Oceanic Antipodes [", ocean.data[1], " %]", )
-    string("S 0.3 s 0.25 gray 0.25p 0.5 Mixed Antipodes [", mixed.data[1], " %]", )]), show=true)
+    string("S 0.3 s 0.25 red  0.25p 0.5 Terrestrial Antipodes [", round(Int, land.data[1]), " %]", )
+    string("S 0.3 s 0.25 blue 0.25p 0.5 Oceanic Antipodes [", round(Int, ocean.data[1]), " %]", )
+    string("S 0.3 s 0.25 gray 0.25p 0.5 Mixed Antipodes [", round(Int, mixed.data[1]), " %]", )]), show=true)
 ```
 \end{examplefig}
diff --git a/gallery/ex40.md b/gallery/ex40.md
diff --git a/index.md b/index.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-- j or spherical_dist or spherical : -- spherical=greatcirc or spherical=:flat or spherical=:ellipsoidal\`
	`1`	`+- j or metric or spherical_dist or spherical : -- metric=greatcirc or spherical=:flat or spherical=:ellipsoidal\`
`2`	`2`	Determine how spherical distances are calculated in modules that support this [Default is `spherical=:greatcirc`].
`3`	`3`	`GMT has different ways to compute distances on planetary bodies:`
`4`	`4`