Add mosaics tutorial.

documentation/modules/earthregions.md

@@ -122,3 +122,8 @@ viz(G, shade=true, coast=true, cmap=:earth)
 ```
 \end{examplefig}
 
+
+See Also
+--------
+
+\myreflink{coast}, \myreflink{mosaic}

documentation/modules/histogram.md

@@ -28,6 +28,7 @@ Optional Arguments
    When input is a GMTimage of UInt16 type this option will compute the histogram as well as good
    bounds to use in contrast enhancement, which will be plotted as two vertical lines.
 
+\textinput{common_opts/opt_B}
 
 - **bg** or **background** : -- *bg=imagename* **|** *bg=funname|img|grd* **|** *bg=(..., colormap)*\
    Fills the plotting canvas with a backround image. That image may come from a file (*e.g.* **bg="cute.png"**) or
@@ -66,6 +67,7 @@ Optional Arguments
 - **I** or **inquire** or **bins** : -- *inquire=:all* **|** *inquire=:no_zero* **|** *inquire=:bins*\
    Inquire about min/max x and y after binning. The *xmin xmax ymin ymax* is output; no plotting is done. Use **inquire=:no_zero** to output a table of the resulting x,y data instead. **inquire=:all** will output all x,y bin data even when y == 0. **inquire=:bins** outputs the binned array (the histogram).
 
+\textinput{common_opts/opt_J}
 
 - **L** or **out_range** : --  *out_range=:first* **|** *out_range=:last* **|** *out_range=:both*\
    The modifiers specify the handling of extreme values that fall outside the range set by **bin**. By default these values are ignored. Use **out_range=:both** to let these values be included in the first or last bins. To only include extreme values below first bin into the first bin, use **out_range=:first**, and to only include extreme values above the last bin into that last bin, use **out_range=:last**.
@@ -83,6 +85,7 @@ Optional Arguments
 - **Q** or **cumulative** : -- *cumulative=true **|** cumulative="r"*\
    Draw a cumulative histogram. Append **r** to instead compute the reverse cumulative histogram.
 
+\textinput{common_opts/opt_R}
 
 - **S** or **stairs** : -- *stairs=true*\
    Draws a stairs-step diagram which does not include the internal bars of the default histogram. Uses *pen*.
@@ -104,7 +107,15 @@ Optional Arguments
 - **getauto** or **getthresholds** : -- *getthresholds=true*\
    Get the automatically determined thresholds to use in contrast enhancement. No plotting is done.
 
+\textinput{common_opts/opt_U}
 
+\textinput{common_opts/opt_V}
+
+\textinput{common_opts/opt_pen}
+
+\textinput{common_opts/opt_X}
+
+\textinput{common_opts/opt_Y}
 
 - **Z** or **kind** : -- *kind=type* **|** *kind=(counts=, | freq=, | frequency=, | log_count=, | log_freq=, | log10_count=, | log10_freq=, weights=)*\
    Choose between 6 types of histograms:

documentation/utilities/mosaic.md

@@ -43,7 +43,9 @@ Get image tiles from a web map tiles provider for given longitude, latitude coor
     projection, and it doesn't need to be in geographic coordinates. Coordinates in other reference systems
     will be converted to geogs.
   - Finaly, all of the above options can be skipped if the keyword `region` is used. Note that this option is
-    the same as in, for example, the \myreflink{coast} module.
+    the same as in, for example, the \myreflink{coast} module. And that means we can use it with
+    \myreflink{earthregions} arguments. _e.g._  ``region="IT"`` is a valid option and will get the tiles
+    needed to build an image of Italy.
 
 - `pt_radius`: The planetary radius. Defaults to Earth's WGS84 authalic radius (6371007 m).
 

tutorials.md

@@ -89,4 +89,15 @@
     ~~~</a>~~~
   @@
 
+  @@box
+    ~~~<a class="boxlink" href="mosaics/mosaic/">~~~
+    @@title Images mosaic@@
+    @@box-content
+      ~~~
+      <img src="/tutorials/mosaics/tilelogo.jpg">
+      ~~~
+    @@
+    ~~~</a>~~~
+  @@
+
 @@

tutorials/mosaics.md

@@ -0,0 +1,3 @@
+# Mosaicing from Web tiles servers
+
+{{list_folder_with_images mosaics}}

tutorials/mosaics/mosaic.md

@@ -0,0 +1,128 @@
+# Mosaicing from Web tiles servers
+
+The \myreflink{mosaic} function let us download map tiles from Web Map Tiles servers given a BoundingBox limits
+in geographical coordinates. The function has many use options and we will show here the result of using
+some of them. By default it downloads images from the Bing servers but data from OpenStreetMap, Google, ESRI, 
+Nimbo and other providers can be accessed as well.
+
+To start with we create an image over Iberia using only default values. _i.,e._ Bing images and image resolution
+(that is, the zoom level) computed automatically for that area.
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+I = mosaic([-10, 3.5], [36.0, 44])
+viz(I)
+```
+\end{examplefig}
+
+If we want instead a map from OpenStreetMap, we need to specify that via the `provider` option. To know more
+about the `provider` usage, see the manual of the ``getprovider`` function (e.,g._ type ``? getprovider``
+in the Julia command window.)
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+I = mosaic([-10, 3.5], [36.0, 44], provider=:OSM)
+viz(I)
+```
+\end{examplefig}
+
+A question that will often arise is: _but what if I want to control the resolution, what zoom level should I choose?_.
+Well, the answer is use trial an error or help yourself a bit and make a figures with the tiles limits. For that we
+use the `mesh` option and plot the tiles limits only.
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+D = mosaic([-10, 3.5], [36.0, 44], mesh=true)
+viz(D, coast=true)
+```
+\end{examplefig}
+
+Typing `D[1].comment` shows that the default zoom level for that area is 8
+
+```julia
+julia> D[1].comment
+1-element Vector{String}:
+ "Zoom level = 8"`
+```
+
+So, if we want a twice resolution map we would do (for the first example). Mind you that each increase of one unit
+in the zoom level duplicates the resolution and multiply by 4 the number of download tiles.
+
+```julia
+I = mosaic([-10, 3.5], [36.0, 44], zoom=9)
+viz(I)
+```
+
+So, we saw how to make maps over large areas, but when it comes to smaller areas it becomes more (or much more)
+cumbersome to find the apropriate map limits. That is when the \myreflink{geocoder} function comes into our resque.
+Basically, it takes as input an adress and return a \myreflink{GMTdataset} with information on that place, and in
+particular its coordinates and BoundingBox.
+
+The syntax is very simple. Just give an address that it understands. It can be a general address like:
+
+```julia
+D = geocoder("Hawaii Island, USA")
+
+Attribute table
+┌────────────┬──────────────┬────────┬────────────────┬────────────┬───────┬────────────────────┬──────────────┬────────┬──────────┬───────
+│        lat │ country_code │   type │ ISO3166-2-lvl4 │ place_rank │ class │         importance │          lon │  state │ osm_type │ addr ⋯
+├────────────┼──────────────┼────────┼────────────────┼────────────┼───────┼────────────────────┼──────────────┼────────┼──────────┼───────
+│ 19.5895548 │           us │ island │          US-HI │         17 │ place │ 0.5331294636028157 │ -155.4486983 │ Hawaii │ relation │      ⋯
+└────────────┴──────────────┴────────┴────────────────┴────────────┴───────┴────────────────────┴──────────────┴────────┴──────────┴───────
+                                                                                                                          8 columns omitted
+BoundingBox: [-155.4486983, -155.4486983, 19.5895548, 19.5895548]
+Global BoundingBox: [-156.0618813, -154.806698, 18.9106939, 20.2685021]
+PROJ: +proj=longlat +datum=WGS84 +units=m +no_defs
+
+1×2 GMTdataset{Float64, 2}
+ Row │      Lon      Lat
+─────┼───────────────────
+   1 │ -155.449  19.5896
+```
+
+Since this still represents a somewhat large area we will use the reported BoundingBox via the `bbox` option. So, to create
+an image of the Big Island, Hawaii we do:
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+D = geocoder("Hawaii Island, USA");
+I = mosaic(D, bbox=true);
+viz(I)
+```
+\end{examplefig}
+
+But when it comes to image real small areas the BoundingBox trick no longer works because it normally is ... too small.
+We must than use the alternative, which is to specify the number of neighbor tiles arround the obtained address. And here
+we must specify the zoom level manually.
+
+Example of a high resolution map over the S. Peters Piazza, Vatican.
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+D = geocoder("Piazza San Pietro, Vatican");
+I = mosaic(D, zoom=19, neighbors=7);
+viz(I)
+```
+\end{examplefig}
+
+But not all small and beautifull places are geocoded. To see the lovely _Fish Island_ in Croatia, we still have to provide
+the central coordinates (or the right BoundingBox).
+
+\begin{examplefig}{}
+```julia
+using GMT
+
+I = mosaic(13.71862, 44.939234, zoom=18, provider=:Google, neighbors=[7,5]);
+viz(I, proj=:guess)
+```
+\end{examplefig}