# Grid Fundamentals & Concepts

    library(vaster)

## What is vaster?

The vaster package provides pure raster grid logic without requiring actual raster data. It separates the abstract mathematical operations of raster grids—dimension, extent, cell indexing, coordinate transformations—from data formats and file I/O.

This is useful when you need to:

- Pre-compute grid operations before reading or writing data
- Work with virtual grids and mosaics
- Perform format-agnostic grid calculations
- Build higher-level geospatial tools

## The Virtual Grid Model

A raster grid in vaster is defined by just two components:

1. Dimension: the number of columns and rows `c(ncol, nrow)`
2. Extent: the bounding box `c(xmin, xmax, ymin, ymax)`

    ## a 10x5 grid covering [0, 100] x [0, 50]
    dimension <- c(10, 5)
    extent <- c(0, 100, 0, 50)

From these two pieces of information, all grid properties can be derived:

    n_cell(dimension)
    #> [1] 50
    x_res(dimension, extent)
    #> [1] 10
    y_res(dimension, extent)
    #> [1] 10

There is no data, no file format, no CRS—just the logical grid structure. This matches how GDAL and other tools internally represent grids.

## Cell Numbering Convention

Cells are numbered from 1, starting at the top-left corner and proceeding row-wise (left-to-right, top-to-bottom). This matches the convention used by the `raster` and `terra` packages.

    ## cell numbers for a 4x3 grid
    dimension <- c(4, 3)
    extent <- c(0, 4, 0, 3)

    ## total cells
    n_cell(dimension)
    #> [1] 12

    ## cell 1 is top-left
    xy_from_cell(dimension, extent, 1)
    #>      [,1] [,2]
    #> [1,]  0.5  2.5

    ## cell 4 is top-right
    xy_from_cell(dimension, extent, 4)
    #>      [,1] [,2]
    #> [1,]  3.5  2.5

    ## cell 12 is bottom-right
    xy_from_cell(dimension, extent, 12)
    #>      [,1] [,2]
    #> [1,]  3.5  0.5

The cell centre coordinates reflect this ordering:

    ## all cell centres
    cells <- seq_len(n_cell(dimension))
    xy_from_cell(dimension, extent, cells)
    #>       [,1] [,2]
    #>  [1,]  0.5  2.5
    #>  [2,]  1.5  2.5
    #>  [3,]  2.5  2.5
    #>  [4,]  3.5  2.5
    #>  [5,]  0.5  1.5
    #>  [6,]  1.5  1.5
    #>  [7,]  2.5  1.5
    #>  [8,]  3.5  1.5
    #>  [9,]  0.5  0.5
    #> [10,]  1.5  0.5
    #> [11,]  2.5  0.5
    #> [12,]  3.5  0.5

## Resolution and Origin

Resolution is the cell size in x and y directions:

    dimension <- c(10, 5)
    extent <- c(0, 100, 0, 50)

    x_res(dimension, extent)
    #> [1] 10
    y_res(dimension, extent)
    #> [1] 10

The origin is the point where cell boundaries align. By default, vaster uses the bottom-left corner of the extent:

    origin(dimension, extent)
    #> [1] 0 0

Understanding the origin is important for aligning multiple grids—covered in detail in `vignette("extent-alignment")`.

## Extent Properties

Extract individual extent components, dimension is obviously irrelevant for extent components but is included for consistency with other functions.

    extent <- c(-180, 180, -90, 90)

    x_min(c(1, 1), extent)
    #> [1] -180
    x_max(c(1, 1), extent)
    #> [1] 180
    y_min(c(1, 1), extent)
    #> [1] -90
    y_max(c(1, 1), extent)
    #> [1] 90

    xlim(c(1, 1), extent)
    #> [1] -180  180
    ylim(c(1, 1), extent)
    #> [1] -90  90

## Coordinate Arrays

Generate coordinate vectors for all columns or rows:

    dimension <- c(4, 3)
    extent <- c(0, 4, 0, 3)

    ## x coordinates of cell centres (one per column)
    x_centre(dimension, extent)
    #> [1] 0.5 1.5 2.5 3.5

    ## y coordinates of cell centres (one per row)
    y_centre(dimension, extent)
    #> [1] 0.5 1.5 2.5

    ## x coordinates of cell corners/edges (ncol + 1 values)
    x_corner(dimension, extent)
    #> [1] 0 1 2 3 4

    ## y coordinates of cell corners/edges (nrow + 1 values)
    y_corner(dimension, extent)
    #> [1] 0 1 2 3

For a full matrix of all cell centre coordinates:

    xy(dimension, extent)
    #>         x   y
    #>  [1,] 0.5 2.5
    #>  [2,] 1.5 2.5
    #>  [3,] 2.5 2.5
    #>  [4,] 3.5 2.5
    #>  [5,] 0.5 1.5
    #>  [6,] 1.5 1.5
    #>  [7,] 2.5 1.5
    #>  [8,] 3.5 1.5
    #>  [9,] 0.5 0.5
    #> [10,] 1.5 0.5
    #> [11,] 2.5 0.5
    #> [12,] 3.5 0.5

## Comparison with raster/terra

The vaster approach differs from `raster` and `terra` in that there is no object to create or manage. Grid operations are pure functions:

    ## terra approach
    library(terra)
    r <- rast(ncol = 10, nrow = 5, xmin = 0, xmax = 100, ymin = 0, ymax = 50)
    res(r)
    ncell(r)
    xyFromCell(r, 1)

    ## vaster approach
    dimension <- c(10, 5)
    extent <- c(0, 100, 0, 50)
    c(x_res(dimension, extent), y_res(dimension, extent))
    n_cell(dimension)
    xy_from_cell(dimension, extent, 1)

This functional approach is useful when you need to perform many grid calculations without the overhead of object creation, or when working in contexts where raster packages aren’t available.

## Next Steps

- `vignette("cell-operations")`: Converting between cells, coordinates, and row/col indices
- `vignette("extent-alignment")`: Aligning and cropping extents to grids
- `vignette("gdal-interop")`: Working with GDAL geotransforms and RasterIO