You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.Rmd
+41-7Lines changed: 41 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -23,46 +23,80 @@ The goal of vaster is to provide grid logic without complication added by data a
23
23
24
24
## Installation
25
25
26
+
Install vaster from CRAN with
27
+
28
+
```r
29
+
install.packages("vaster")
30
+
```
31
+
26
32
You can install the development version of vaster from [GitHub](https://github.com/) with:
27
33
28
34
```r
29
35
# install.packages("devtools")
30
36
devtools::install_github("hypertidy/vaster")
31
37
```
32
38
39
+
## Grid logic
33
40
41
+
Here are four numbers, that represent two positions in the plane.
42
+
43
+
On their own they are very unlikely to align on a raster grid, but they provide a starting point for a "region of interest". Notice in this picture that the underlying discretization and the position of these points is unrelated, and can be arbitrary - but they are related in terms of describing *approximately* the same region. If we make our grid window too small we will miss part of the world that the points are in, you can see that we want to "snap out" at least one grid cell to the left and down, to the right and up.
34
44
35
-
See?
36
45
37
46
```{r vaster}
38
47
library(vaster)
39
48
set.seed(1)
40
49
x <- c(sort(runif(2, -20, 160)), sort(runif(2, -80, 10)))
41
50
names(x) <- c("xmin", "xmax", "ymin", "ymax")
42
51
print(x)
52
+
plot(matrix(x, ncol = 2))
53
+
grid()
54
+
55
+
```
56
+
57
+
This is where vaster comes in, tools to relate arbitrary point locations to an underlying grid.
58
+
59
+
60
+
vaster consists of a set of low-level functions for this relationship between point locations and grid elements.
61
+
62
+
The `vcrop()` function is a high-level function that uses these underlying tools. Imagine a grid that is 120x60 and includes the whole world in longlat, this is described by dimension (120x60) and by extent (-180, 180, -90, 90). With `vcrop()` we get exactly the right snapping for our points, identifying the exact extent we need to "snap out" that little bit as mentioned above. The discretization can be completely arbitrary, as it can be in geospatial packages.
63
+
64
+
```{r vaster1}
43
65
## all we need is a extent and dimension, we want to align to that grid
abline(v = v$extent[1:2], h = v$extent[3:4], lwd = 2)
48
70
abline(v = g_along(v$extent[1:2], v$dimension[1]), h = g_along(v$extent[3:4], v$dimension[2]), col = "grey")
49
71
72
+
73
+
50
74
## these points were used to crop the existing grid, they don't define its alignment
51
75
points(x[1:2], x[3:4], pch = "+")
52
76
```
53
77
54
-
All of the helper functions from the raster package are included, and every function is one of dimension, extent (when needed) in that order.
78
+
That is the core of vaster - this is *raster logic* that exists in geospatial libraries and packages, but it has use on its own without any imagery, or grid data, or files or anything else.
79
+
vaster was originally based on the abstract cell functions of the old [raster](https://CRAN.R-project.org/package=raster), which relied on its internal format - these are now superseded by the [terra](https://CRAN.R-project.org/package=terra) package - but we don't want to rely on its new format, or be subject to future changes so vaster has the logic separated from other tooling.
80
+
81
+
Most functions in vaster include arguments that 'dimension', and 'extent' (when needed) in that order.
82
+
83
+
We use the concept of "extent" which is xmin,xmax,ymin,ymax which is exactly the same as the concept of "bounding box (bbox)" which is xmin,ymin,xmax,ymax: the same thing in a different order.
84
+
85
+
## Another example
55
86
56
87
A grid of the world in 9x5 degree squares, we only need the dimension and extent to get the corners in x, y.
57
88
89
+
With `plot_extent()` we have a very simple way to plot a rectangular region with one argument.
90
+
58
91
```{r world}
59
92
ex <- c(-180, 180, -90, 90)
60
93
dm <- c(40, 36)
61
94
62
-
plot_extent(ex)
95
+
plot_extent(ex, lwd = 5, border = "firebrick")
63
96
abline(v = x_corner(dm, ex), h = y_corner(dm, ex))
64
97
```
65
98
99
+
With `x_corner()`, `y_corner()`, `x_centre()`, and `y_centre()` we need only those six numbers, extent and dimension to get the corner and cell centre positions.
We only get the margins from x_corner/x_centre so we go to a cell based function.
108
+
We only get the margins from x_corner/x_centre so we go to a cell based function, `xy_from_cell()` returns any centre position indexed by its cell number (cell numbers are 1-based and traverse from topleft to the right, then down by row - this is the same as in raster/terra and is the orientation used by most geospatial tools).
Other functions return cells, here we have another kind of "snap" operation, which cell does the point fall it (or which cell centre is it closest to).
0 commit comments