|
| 1 | +# mosaic |
| 2 | + |
| 3 | +```julia |
| 4 | +I = mosaic(lon, lat; pt_radius=6371007.0, provider="", zoom::Int=0, cache::String="", |
| 5 | + mapwidth=15, dpi=96, verbose::Int=0, kw...) |
| 6 | +``` |
| 7 | + |
| 8 | +*keywords: GMT, Julia, tiles image* |
| 9 | + |
| 10 | +Get image tiles from a web map tiles provider for given longitude, latitude coordinates. |
| 11 | + |
| 12 | +### Arguments |
| 13 | +- `lon` & `lat`: |
| 14 | + - `lon, lat` two scalars with the coordinates of region of interest center. To completly define |
| 15 | + the image area see the `neighbors` or `mosaic` option below. |
| 16 | + - `lon, lat` are two elements vector or matrix with the region's ``[lon_min, lon_max], [lat_min, lat_max]``. |
| 17 | + - Instead of two arguments, pass just one containing a GMTdataset obtained with the ``geocoder`` function. |
| 18 | + Example: ``mosaic(D, ...)`` or, if the search with ``geocoder`` was sufficiently generic (see its docs), |
| 19 | + ``mosaic(D, bbox=true)`` to use the BoundingBox returned by the query. `bbox` supports `bb`, `BB` or |
| 20 | + `BoundingBox` as aliases. |
| 21 | + |
| 22 | +- `pt_radius`: The planetary radius. Defaults to Earth's WGS84 authalic radius (6371007 m). |
| 23 | + |
| 24 | +- `provider`: Tile provider name. Currently available options are (but for more details see the docs of the |
| 25 | + `getprovider` function, *i.e.* ``? getprovider``): |
| 26 | + - "Bing" (the default), "OSM", "Esri" or a custom provider. |
| 27 | + - A `Provider` type from the ``TileProviders.jl`` package. You must consult the documentation of that package |
| 28 | + for more details on how to choose a *provider*. |
| 29 | + |
| 30 | +- `zoom`: Zoom level (0 for automatic). A number between 0 and ~19. The maximum is provider and area dependent. |
| 31 | + If `zoom=0`, the zoom level is computed automatically based on the `mapwidth` and `dpi` options. |
| 32 | + |
| 33 | +- `cache`: Full name of the the cache directory where to save the downloaded tiles. If empty, a cache |
| 34 | + directory is created in the system's TMP directory. If `cache="gmt"` the cache directory is created in |
| 35 | + ``~/.gmt/cache_tileserver``. NOTE: this normally is neeaded only for the first time you run this function when, |
| 36 | + if `cache!=""`, the cache dir location is saved in the ``~./gmt/tiles_cache_dir.txt`` file and used in |
| 37 | + subsequent calls. |
| 38 | + |
| 39 | +- `mapwidth`: Map width in cm. Used together with the `dpi` option to automatically compute the zoom level. |
| 40 | + |
| 41 | +- `dpi`: Dots per inch. Used together with the `mapwidth` option to automatically compute the zoom level. |
| 42 | + |
| 43 | +- `verbose`: Verbosity level. A number between 0 and 2. Print out info while downloading the image files. |
| 44 | + Silent when geting files from local cache unless `verbose=2`, where it prints out info about the files |
| 45 | + found in the cache. |
| 46 | + |
| 47 | +### kwargs (kw...) |
| 48 | +- `neighbors` or `mosaic`: When `lon` and `lat` are scalars, this option specifies the number of neighbors |
| 49 | + of the tile containing the query point to download. Normally this should be an odd number, but it can take the |
| 50 | + form of a matrix and the number of tiles is then determined by the number of rows and columns. |
| 51 | + |
| 52 | +- `merc` or `mercator`: Return tiled image in Mercator coordinates. The default is to project it back |
| 53 | + to geographical coordinates. |
| 54 | + |
| 55 | +- `loose` or `loose_bounds`: By default we return an image with the limits requested in the `lon` and |
| 56 | + `lat` arguments. This option makes it return an image with the limits that are determined by those of |
| 57 | + the tiles that intersect the requested region. Note that this does not work for point queries. |
| 58 | + |
| 59 | +- `quadonly`: Return only the quadtree string. A string or a matrix of strings when number of tiles > 1. |
| 60 | + Other from the quadtree string this option return also the `decimal_adress, lon, lat, x, y` that are: |
| 61 | + the XYZ tiles coordinates, the longitude, latitude , mercator X and Y coordinates in meters of first tile. |
| 62 | + |
| 63 | +Returns |
| 64 | +------- |
| 65 | +- `I`: A \myreflink{GMTimage} element or the output of the `quadonly` option explained above. |
| 66 | + |
| 67 | +Examples |
| 68 | +-------- |
| 69 | + |
| 70 | +- Make a figure with OpenStreetMap over Iberia maintaining the original spherical Mercator projection. |
| 71 | + |
| 72 | +\begin{examplefig}{} |
| 73 | +```julia |
| 74 | +using GMT |
| 75 | + |
| 76 | +I = mosaic([-9.5, 3.3], [36.0, 43.8], provider=:OSM, zoom=7, merc=true) |
| 77 | +viz(I) |
| 78 | +``` |
| 79 | +\end{examplefig} |
| 80 | + |
| 81 | + |
| 82 | +- Make a figure of the Big Island of Hawaii using the default Bing images. In this case |
| 83 | +we use the ``geocoder`` function to give us the map limits |
| 84 | + |
| 85 | +\begin{examplefig}{} |
| 86 | +```julia |
| 87 | +using GMT |
| 88 | + |
| 89 | +# Get the geographical limits of the Big Island in Hawaii |
| 90 | +D = geocoder("Hawaii, Island"); |
| 91 | + |
| 92 | +# Get the image tiles of the Big Island in Hawaii using the Bing provider and automatic zoom level |
| 93 | +I = mosaic(D, bbox=true); |
| 94 | + |
| 95 | +viz(I) |
| 96 | +``` |
| 97 | +\end{examplefig} |
| 98 | + |
| 99 | + |
| 100 | +See Also |
| 101 | +-------- |
| 102 | + |
| 103 | +\myreflink{geocoder} |
0 commit comments