readme and fiddly bits

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ximage
 Title: Draw Images of Raster Data and Related Adornments
-Version: 0.0.0.9008
+Version: 0.0.0.9009
 Authors@R: 
     person("Michael D.", "Sumner", , "mdsumner@gmail.com", role = c("aut", "cre"))
 Description: Draw images easily and as if doing that was considered desirable or  
@@ -17,6 +17,6 @@ Roxygen: list(markdown = TRUE)
 Depends: 
     R (>= 2.10)
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.0
 Imports: 
     palr

NEWS.md

@@ -1,4 +1,4 @@
-# ximage dev
+# ximage 0.0
 
 * `ximage()` now handles `breaks` argument to go with `col` (for numeric input). 
 

R/xcontour.R

@@ -17,6 +17,7 @@
 #' #im <- whatarelief::imagery(extent = ex, projection = "+proj=nzmg +datum=WGS84")
 #' #ximage(im, add = TRUE, extent = ex)
 #' xcontour(v, add = TRUE, extent = ex, col = "white")
+#' xrect(ex, add = TRUE, border = "hotpink", lwd = 5)
 xcontour <- function(x, extent = NULL, ..., add = FALSE) {
   UseMethod("xcontour")
 }
@@ -36,7 +37,7 @@ xcontour.list <- function(x, extent = NULL, ..., add = FALSE) {
   if (all(c("geotransform", "cols", "rows", "driver") %in% names(x))) {
     ## smells like sf
     stop("no xcontour for sf")
-    ximage_sf_data(x, extent = extent, zlim = zlim, add = add, ..., xlab = xlab, ylab = ylab, col = col)
+    ximage_sf_data(x, extent = extent,  add = add, ...)
     return(invisible(x))
   }
    ## here validate that we have extent, dimension as attributes, otherwise just see if it's a matrix

R/ximage.R

@@ -59,7 +59,7 @@ flip_c <- function(x) {
 #' \enumerate{
 #'    \item Allow arrays with RGB/A.
 #'    \item Allow matrix with character (named colours, or hex) or raw (Byte) values
-#'    \Allow list output from vapour, a list with numeric values, hex character, or nativeRaster
+#'    \item Allow list output from vapour, a list with numeric values, hex character, or nativeRaster
 #'    \item Plot in 0,ncol 0,nrow by default
 #'    \item Override default with extent (xmin, xmax, ymin, ymax)
 #'
@@ -182,8 +182,10 @@ ximage.default <- function(x, extent = NULL, zlim = NULL, add = FALSE, ..., xlab
 
 
     #x <- .make_hex_matrix(x, cols = col )
-
-    if (!is.null(col)) {
+    ## politely ignore numeric arrays with 3 or 4 slices
+    dmx <- dim(x)
+    tt <- length(dmx %in% c(3, 4)) && is.numeric(x) && all(x >= 0, na.rm = TRUE)
+    if (!tt && !is.null(col)) {
 
       x <- matrix(palr::image_pal(x, col, breaks = breaks), dim(x)[1L], dim(x)[2L])
     } else {

R/xrect.R

@@ -17,7 +17,8 @@
 #' xrect(sort(runif(100)))
 #' xrect(runif(100), col = hcl.colors(25, alpha = seq(.2, .8, length.out = 25)))
 #'
-#' example(xcontour, ask = FALSE)
+#' #example(xcontour, ask = FALSE)
+#' ex <- c(0.2, 0.8, .2, .6)
 #' xrect(ex, add = TRUE, lwd = 5, lty = 2)
 xrect <- function(x, add = FALSE, ..., asp = 1L) {
   ## assuming cbind(xmin, xmax, ymin, ymax)

README.Rmd

@@ -21,23 +21,17 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/hypertidy/ximage/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/hypertidy/ximage/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-VERY VERY WIP
 
+The goal of ximage is to make something like 'image()' and 'rasterImage()' but without the missing functionality and useability. 
 
-The goal of ximage is to make something like 'image()' and 'rasterImage()' but without the acquired need for compatibility with WTAF. 
+ximage supports making images from
 
+- numeric, character, byte matrix
+- numeric array
+- nativeRaster
+- list returned from `vapour::gdal_raster_()` functions which include numeric, character, byte vectors or nativeRaster
 
-<!--
-
-## Installation
-
-You can install the development version of ximage from [GitHub](https://github.com/) with:
-
-``` r
-# install.packages("devtools")
-devtools::install_github("hypertidy/ximage")
-```
--->
+The orientation is in "raster-order", i.e. when you're looking at the picture it's topleft to topright, then scan lines down each row to the bottom (like western reading and `par(mfrow)` order). This matches the way that spatial data readers read imagery. 
 
 ## Example
 
@@ -57,9 +51,30 @@ ximage(logo_n, extent = c(10, 20, 20, 40), add = TRUE)
 ximage(topo, extent = c(40, 60, 80, 100), add = TRUE, col = hcl.colors(256))
 ```
 
+We can get imagery from the internet, and plot it very quickly. 
+
+```{r imagery}
+library(vapour)  ## quite a recent version, dev in January 2024
+virtual_earth <-  "<GDAL_WMS><Service name=\"VirtualEarth\"><ServerUrl>http://a${server_num}.ortho.tiles.virtualearth.net/tiles/a${quadkey}.jpeg?g=90</ServerUrl></Service><MaxConnections>4</MaxConnections><Cache/></GDAL_WMS>"
+par(mar = rep(0, 4))
+px <- dev.size("px")
+px[which.min(px)] <- 0
+
+## change lon_0 and lat_0 to anywhere you like
+im <- gdal_raster_nara(virtual_earth, target_ext = c(-1, 1, -1, 1) * 3e5, target_dim = px, target_crs = "+proj=laea +lon_0=147 +lat_0=-42")
 
+system.time(ximage(im, asp = 1))
+
+
+## crank up the size it's still fast
+px <- px * 4
+im <- gdal_raster_nara(virtual_earth, target_ext = c(-1, 1, -1, 1) * 3e5, target_dim = px, target_crs = "+proj=laea +lon_0=147 +lat_0=-42")
+
+system.time(ximage(im, asp = 1))
+
+```
 
 
-  ## Code of Conduct
+## Code of Conduct
 
   Please note that the ximage project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.

README.md

@@ -8,23 +8,21 @@
 [![R-CMD-check](https://github.com/hypertidy/ximage/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/hypertidy/ximage/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-VERY VERY WIP
-
 The goal of ximage is to make something like ‘image()’ and
-‘rasterImage()’ but without the acquired need for compatibility with
-WTAF.
-
-<!--
+‘rasterImage()’ but without the missing functionality and useability.
 
-## Installation
+ximage supports making images from
 
-You can install the development version of ximage from [GitHub](https://github.com/) with:
+- numeric, character, byte matrix
+- numeric array
+- nativeRaster
+- list returned from `vapour::gdal_raster_()` functions which include
+  numeric, character, byte vectors or nativeRaster
 
-``` r
-# install.packages("devtools")
-devtools::install_github("hypertidy/ximage")
-```
--->
+The orientation is in “raster-order”, i.e. when you’re looking at the
+picture it’s topleft to topright, then scan lines down each row to the
+bottom (like western reading and `par(mfrow)` order). This matches the
+way that spatial data readers read imagery.
 
 ## Example
 
@@ -38,6 +36,7 @@ ximage(topo)  ## plot in the index space of the matrix
 <img src="man/figures/README-example-1.png" width="100%" />
 
 ``` r
+
 ## or, plot in the geographic space (we happen to know this for this matrix)
 ximage(topo, extent = c(-180, 180, -90, 90), axes = F)
 axis(1); axis(2);box()
@@ -47,6 +46,8 @@ axis(1); axis(2);box()
 
 ``` r
 ximage(logo_a)  ## plot a RGB array
+#> Warning in matrix(palr::image_pal(x, col, breaks = breaks), dim(x)[1L], : data
+#> length differs from size of matrix: [30400 != 76 x 100]
 ## plot  a native raster over the other in a different window
 ximage(logo_n, extent = c(10, 20, 20, 40), add = TRUE)
 
@@ -55,6 +56,42 @@ ximage(topo, extent = c(40, 60, 80, 100), add = TRUE, col = hcl.colors(256))
 
 <img src="man/figures/README-example-3.png" width="100%" />
 
+We can get imagery from the internet, and plot it very quickly.
+
+``` r
+library(vapour)  ## quite a recent version, dev in January 2024
+virtual_earth <-  "<GDAL_WMS><Service name=\"VirtualEarth\"><ServerUrl>http://a${server_num}.ortho.tiles.virtualearth.net/tiles/a${quadkey}.jpeg?g=90</ServerUrl></Service><MaxConnections>4</MaxConnections><Cache/></GDAL_WMS>"
+par(mar = rep(0, 4))
+px <- dev.size("px")
+px[which.min(px)] <- 0
+
+## change lon_0 and lat_0 to anywhere you like
+im <- gdal_raster_nara(virtual_earth, target_ext = c(-1, 1, -1, 1) * 3e5, target_dim = px, target_crs = "+proj=laea +lon_0=147 +lat_0=-42")
+#> Byte
+#> 1
+
+system.time(ximage(im, asp = 1))
+```
+
+<img src="man/figures/README-imagery-1.png" width="100%" />
+
+    #>    user  system elapsed 
+    #>   0.006   0.000   0.006
+
+
+    ## crank up the size it's still fast
+    px <- px * 4
+    im <- gdal_raster_nara(virtual_earth, target_ext = c(-1, 1, -1, 1) * 3e5, target_dim = px, target_crs = "+proj=laea +lon_0=147 +lat_0=-42")
+    #> Byte
+    #> 1
+
+    system.time(ximage(im, asp = 1))
+
+<img src="man/figures/README-imagery-2.png" width="100%" />
+
+    #>    user  system elapsed 
+    #>   0.126   0.032   0.159
+
 ## Code of Conduct
 
 Please note that the ximage project is released with a [Contributor Code