Add a tutorial on Remote grids

Author: joa-quim

Interoperability.md

@@ -144,7 +144,6 @@ the Rasters.jl package is able to keep some metadata (namely the time axis) and
 is not yet able to match.
 Here we will reproduce some of the examples from this Rasters.jl [docs](https://rafaqz.github.io/Rasters.jl/dev/#Examples-and-Plotting).
 
-\begin{examplefig}{}
 ```julia
 using GMT
 using Rasters, RasterDataSources, ArchGDAL
@@ -153,7 +152,10 @@ ENV["RASTERDATASOURCES_PATH"] = tempdir();
 A = Raster(WorldClim{BioClim}, 5);
 viz(A, colorbar=true)
 ```
-\end{examplefig}
+
+~~~
+<img src="/assets/world_clim_bio_clim.png" width=80% class="center"/>
+~~~
 
 \begin{examplefig}{}
 ```julia

_assets/world_clim_bio_clim.png

@@ -23,16 +23,18 @@ Parameters
 
 - `name`: The grid name. One of:
 
-  - `earth_age`, `earth_geoid`, `earth_mag`, `earth_gebco`, `earth_gebcosi`, `earth_mask`, `earth_dist`, `earth_faa`, `earth_edefl`, `earth_ndefl`, `earth_mss`, `earth_mdt`, `earth_relief`, `earth_synbath`, `earth_vgg`, `earth_wdmam`, `earth_day`, `earth_night`, 
+  - `earth_age`, `earth_geoid`, `earth_mag`, `earth_gebco`, `earth_gebcosi`, `earth_mask`, `earth_dist`, `earth_faa`, `earth_faaerror`, `earth_edefl`, `earth_ndefl`, `earth_mss`, `earth_mdt`, `earth_relief`, `earth_synbath`, `earth_vgg`, `earth_wdmam`, `earth_day`, `earth_night`, 
   - `mars_relief`, `mercury_relief`, `moon_relief`, `pluto_relief`, `venus_relief`.
 
 Keyword Arguments
 -----------------
 
 - `rest_p` or `res`: Grid resolution. One of "01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m" or higher
   for the grids that have finer resolution. Use the `info` option to inquiry all available resolutions of a grid.
+  The suffix ``d``, ``m``, and ``s`` stand for arc-degrees, arc-minutes, and arc-seconds, respectively.
 
-- `reg`: Grid registration. Choose between 'g'rid or 'p'ixel registration or leave blank modules picking the best one.
+- `reg`: Grid registration. Choose between 'g'rid or 'p'ixel registration or leave blank for modules to picking the indicated one.
+  By default, a gridline-registered grid is selected unless only the pixel-registered grid is available.
 
 - `info`: Print grid information (true) or just the full grid name (false). Cannot be used with the option `res`.
 
@@ -62,7 +64,7 @@ See a region over Oman of the "earth_relief" at "15s" resolution
 ```julia
 using GMT
 
-G = gmtread(remotegrid("earth_relief", res="15s"), region=(55,60,23,28))
+G = grdcut(remotegrid("earth_relief", res="15s"), region=(55,60,23,28))
 viz(G, proj=:guess, shade=true, coast=true, colorbar=true)
 ```
 \end{examplefig}

documentation/utilities/remotegrid.md

@@ -122,4 +122,15 @@
     ~~~</a>~~~
   @@
 
+  @@box
+    ~~~<a class="boxlink" href="remote_datasets/remote_datasets/">~~~
+    @@title Remote Grids@@
+    @@box-content
+      ~~~
+      <img src="/tutorials/remote_datasets/tilelogo.jpg">
+      ~~~
+    @@
+    ~~~</a>~~~
+  @@
+
 @@

tutorials.md

@@ -37,7 +37,7 @@ Load the gray scale image and show it:
 using GMT
 
 Iblend = gmtread("https://oceania.generic-mapping-tools.org/cache/wiberia_shade_blender.png");
-viz(Iblend, coast=true)
+viz(Iblend)
 ```
 \end{examplefig}
 

tutorials/blender_shading/blender_rt.md

@@ -0,0 +1,3 @@
+# GMT Remote Datasets
+
+{{list_folder_with_images remote_datasets}}

tutorials/remote_datasets.md

@@ -0,0 +1,31 @@
+# Seafloor Crustal Age
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_age.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _earth_age.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_age](https://www.generic-mapping-tools.org/remote-datasets/earth-age.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("age", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/age/age.md

@@ -0,0 +1,38 @@
+# NASA Earth Day/Night Images
+
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_daynight.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+We serve two NASA image products: The Blue and Black marble mosaics. We have filtered and down-ampled those as
+well at the same resolutions that are available for the Earth DEMs. However, all images are pixel-registered only.
+
+The available resolutions for this image are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the image(s) are loaded from that local directory.
+
+Refer to [earth_daynight](https://www.generic-mapping-tools.org/remote-datasets/earth-daynight.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+I = gmtread(remotegrid("day", res="6m"))
+viz(I)
+```
+
+or for the night images
+
+```julia
+I = gmtread(remotegrid("night", res="6m"))
+viz(I)
+```

tutorials/remote_datasets/age/tilelogo.jpg

@@ -0,0 +1,30 @@
+# GSHHG Earth Distace to Shoreline
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_dist.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _earth_dist.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_dist](https://www.generic-mapping-tools.org/remote-datasets/earth-dist.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("dist", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/daynight/daynight.md

@@ -0,0 +1,30 @@
+# IGPP Earth West-East Defections
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_edefl.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _earth_defl.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_edefl](https://www.generic-mapping-tools.org/remote-datasets/earth-edefl.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("edefl", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/daynight/tilelogo.jpg

@@ -0,0 +1,31 @@
+# IGPP Earth Free-Air Anomaly
+
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_faa.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _earth_faa.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_faa](https://www.generic-mapping-tools.org/remote-datasets/earth-faa.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("faa", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/dist/dist.md

@@ -0,0 +1,28 @@
+# IGPP Earth Free-Air Anomaly Error
+
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_faaerror.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+Refer to [earth_faaerror](https://www.generic-mapping-tools.org/remote-datasets/earth-faaerror.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("faaerror", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/dist/tilelogo.jpg

@@ -0,0 +1,43 @@
+# GEBCO Earth Relief
+
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_gebco.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+This grid only contains observed relief and inferred relief via altimetric gravity. You access these grids
+by specifying their names (`earth_gebco`, or just `gebco`, `gebcosi` and `synbath`) and resolution.
+
+The available resolutions for these group of grids are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s", "15s", "03s", "01s"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _geo.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_gebco](https://www.generic-mapping-tools.org/remote-datasets/earth-gebco.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Examples
+
+```julia
+G = gmtread(remotegrid("gebco", res="10m"))
+viz(G, shade=true)
+```
+
+Grids with resolutions higher than `06m` are tilled to avoid download the entire dataset, which can be **very** big,
+when only a sub-region is needed. For example, this downloads a sub-region of the `1m` (one arc-minute) and visualizes it.
+
+```julia
+G = grdcut(remotegrid("gebco", res="1m"), region=(0,10,40, 50))
+viz(G, shade=true)
+```
+

tutorials/remote_datasets/edefl/edefl.md

@@ -0,0 +1,29 @@
+# EGM2008 Earth Geoid
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_geoid.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+Load the EGM2008 Earth geoid dataset in various resolutions.
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+Refer to [earth_geoid](https://www.generic-mapping-tools.org/remote-datasets/earth-geoid.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("geoid", res="6m"))
+viz(G, shade=true)
+```

tutorials/remote_datasets/edefl/tilelogo.jpg

@@ -0,0 +1,33 @@
+# Earth Magnetic Anomaly Model (EMAG2)
+
+\begin{examplefig}{}
+```julia
+using GMT	# hide
+I = gdalread("https://github.com/GenericMappingTools/remote-datasets/blob/main/docs/_static/GMT_earth_mag.jpg?raw=true"); # hide
+viz(I) # hide
+```
+\end{examplefig}
+
+The US National Environmental Information Center Office of Geomatics provide EMAG2, the Earth Magnetic Anomaly Model
+at 2 arc-minute resolution based on satellite, ship, and airborne magnetic measurements. 
+
+The available resolutions for this grid are:
+- `"01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m"`. Where
+  the suffix `d`, `m` and `s` stand for arc-degrees, arc-minutes, and arc-seconds. See also the manual
+  of \myreflink{remotegrid} for information about the grid registrations.
+
+On first usage, the grids are downloaded to the user `./gmt/server/...` directory. On later usages,
+the grid(s) are loaded from that local directory.
+
+The default color palette table (CPT) for this dataset is _earth_mag.cpt_. It’s implicitly used when passing in the
+file name of the dataset to any grid plotting method if no CPT is explicitly specified.
+
+Refer to [earth_mag](https://www.generic-mapping-tools.org/remote-datasets/earth-mag.html) for more details
+about technical detail, available resolutions, sizes, version information and references.
+
+### Example
+
+```julia
+G = gmtread(remotegrid("mag", res="6m"))
+viz(G, shade=true)
+```