README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

<!-- badges: start -->

[![CRAN status](https://www.r-pkg.org/badges/version/ceramic)](https://CRAN.R-project.org/package=ceramic)
[![R-CMD-check](https://github.com/hypertidy/ceramic/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/hypertidy/ceramic/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

```{r setup, include = FALSE}

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%", 
  dev = "png"
  #, dev.args = list( jpeg = list(quality =50))
)
options(warn = -1)
```
# ceramic

The goal of ceramic is to obtain web map tiles. Use a spatial object to define the region of interest. 




```{r extent1}
library(ceramic)
roi <- ext(100, 160, -50, 10)
im <- cc_location(roi)

plotRGB(im)
```

The terra package is always loaded by ceramic, so we can assume the use of its functions, ceramic accepts a wider range of inputs than terra does however. 

We can use  wk, geos, terra, raster, sp, sf, or stars objects, or an input lon,lat point
and a buffer (in metres) to define an extent. This provides a very easy way to
obtain imagery or elevation data for any almost any region using our own data.

```{r extent2, fig.width=8, fig.height=10}
sql <- "SELECT shapeGroup FROM geoBoundariesCGAZ_ADM0 WHERE shapeGroup IN ('BOL')"
dsn <- "/vsizip//vsicurl/https://github.com/wmgeolab/geoBoundaries/raw/main/releaseData/CGAZ/geoBoundariesCGAZ_ADM0.zip"
bol <- vect(dsn, query = sql)

im <- cc_location(bol)
plotRGB(im)
```

Even if the data uses a map projection it will be converted into a region to match the Mercator extents used by Mapbox image servers. 

```{r warn, include = FALSE}
options(warn = -1)
```

```{r nz-spData, include = FALSE}
data("nz", package = "spData")

library(sf)
im_nz2 <- cc_location(nz)
plotRGB(im_nz2)
plot(st_transform(nz, crs(im_nz2))[0], add = TRUE, col = rainbow(nrow(nz), alpha = 0.5))
```

There are basic heuristics to decide if data is projected or just in "longitude,latitude" in the usual way. 

Raster elevation data is also available. 

```{r}
north <- nz[nz$Island == "North", ]
dem_nz <- cc_elevation(north, type = "elevation-tiles-prod" )


## plot elevation data for NZ north
dem_nz[!dem_nz > 0] <- NA

plot(dem_nz, col = grey.colors(128))
plot(st_transform(st_cast(north, "MULTILINESTRING")["Name"], terra::crs(dem_nz)), add = TRUE, lwd = 5)

```

## I thought you said *tiles*?

Indeed, here's a function called `read_tiles()`, it shares the same interface as `get_tiles()`. 


```{r read-tiles}
read_tiles()
```


Note that, the `cc_location()` and `cc_elevation()` functions no longer use tiles, they read directly from the internet using GDAL and are not related to the tile download facilities. 

But, they used to run `get_tiles()` behind the scenes. The separation is still a little unfinished, but I want ceramic to have separation of loading data from the internet with downloading tiles. 

This function and its counterparts `get_tiles_zoom()`, `get_tiles_dim()` and `get_tiles_buffer()` will *only download files*. 

```{r tiles}
tile_summ <- get_tiles_zoom(north, zoom = 8)
length(tile_summ$files)
str(tile_summ$tiles)

(tile_rect <- tiles_to_polygon(ceramic_tiles(zoom = 8)))

```

This is really for expert use when you want to control the downloaded tile files yourself directly. 


## Providers

The default map provider is [Mapbox](https://www.mapbox.com/), but ceramic is written for general usage and also provides access to the [joerd AWS tiles](https://github.com/tilezen/joerd/) via the `type = "elevation-tiles-prod"` argument. 

```{r}
pt <- cbind(175.6082, -37.994)
nz_z12 <- cc_location(pt, buffer  = 100000,  type = "elevation-tiles-prod")
```

```{r, eval=FALSE, include = FALSE}
north_carolina <- sf::read_sf(system.file("gpkg/nc.gpkg", package = "sf", mustWork = TRUE))
nc_image <- cc_location(north_carolina)

rowan_dem <- cc_elevation(dplyr::filter(north_carolina, NAME == "Rowan"))
rowan_dem
```


## Installation

Install ceramic from CRAN with: 

```R
install.packages("ceramic")
```

You can install the development version of ceramic from  Github. 

```R
## install.packages("remotes")
remotes::install_github("hypertidy/ceramic")
```

Set your mapbox API key with 

```R
Sys.setenv(MAPBOX_API_KEY = "<yourkey>")
```




## Example

This complete example gets tiled imagery that we can use as real data.

The code here

-   generates a bounding box in longitude-latitude
- reads the raster data using GDAL

then we look at the actual tiles involved, 

-   uses [slippymath](https://CRAN.r-project.org/package=slippymath) to
    find sensible tiles for the region
-   downloads them to a local cache
-   summarizes the tiles as a spatial (wk) object


```{r example01}
library(ceramic)
## a point in longlat, and a buffer with in metres
pt <- cbind(136, -34)
im <- cc_location(pt, buffer = c(1e6, 5e5), type = "mapbox.satellite")
op <- par(bg = "black")
plotRGB(im)

## get the approximately matching tiles (zoom is magic here, it's all wrapped - needs thought)

tileset <- get_tiles(pt, buffer = c(1e6, 5e5))
tiles <- ceramic_tiles(zoom = tileset$tiles$zoom, type = "mapbox.satellite")
plot(tiles_to_polygon(tiles), add = TRUE, border = "white")



middle <- function(x, y) {
  x + (y - x)/2
}
text(middle(tiles$xmin, tiles$xmax), middle(tiles$ymin, tiles$ymax), lab = sprintf("[%i,%i]", tiles$tile_x, tiles$tile_y), 
     col = "yellow")
     
par(op)
```


## Tasmap maps


```{r tasmap}
library(ceramic)
library(terra)
template <- rast(ext(527358, 527880, 5252204, 5252704), res = .3, crs = "EPSG:32755")
ortho <- cc_location(template, type = "tasmap_orthophoto")

plot(ortho)

plot(cc_location(template, type = "tasmap_street"))

plot(cc_location(template, type = "tasmap_tasmapraster"))

plot(cc_location(template, type = "tasmap_hillshade"))

plot(cc_location(template, type = "tasmap_hillshadegrey"))
plot(cc_location(template, type = "tasmap_esgismapbookpublic"))  ## nope
plot(cc_location(template, type = "tasmap_topographic"))


plot(cc_location(template, type = "tasmap_tasmap25k"))  ## also 100k, 250k, 500k
 
```



```{r smash,include=FALSE}
quantize_figs <- function(dir = "man/figures") {
  f <- fs::dir_ls(dir, regexp = "png$")
  for (i in seq_along(f)) {
    tf <- tempfile(fileext = ".png")
    im <- magick::image_read(f[i])
    magick::image_write(magick::image_quantize(im), tf)
    
    ## I don't know how to properly unlink the original pointer, this just a guess (not sure it matters)
    rm(im)
    fs::file_delete(f[i])
    fs::file_move(tf, f[i])
  }
} 
quantize_figs()
```



---

Please note that the 'ceramic' project is released with a [Contributor Code of Conduct](https://github.com/hypertidy/ceramic/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.