
Create a SpatRaster
rast.Rd
Methods to create a SpatRaster. These objects can be created from scratch, from a filename, or from another object.
A SpatRaster represents a spatially referenced surface divided into three dimensional cells (rows, columns, and layers).
When a SpatRaster is created from a file, it does not load the cell (pixel) values into memory (RAM). It only reads the parameters that describe the geometry of the SpatRaster, such as the number of rows and columns and the coordinate reference system. The actual values will be read when needed.
Usage
# S4 method for character
rast(x, subds=0, lyrs=NULL, drivers=NULL, opts=NULL, win=NULL, snap="near", vsi=FALSE)
# S4 method for missing
rast(x, nrows=180, ncols=360, nlyrs=1, xmin=-180, xmax=180,
ymin=-90, ymax=90, crs, extent, resolution, vals, names, time, units)
# S4 method for SpatRaster
rast(x, nlyrs=nlyr(x), names, vals, keeptime=TRUE, keepunits=FALSE, props=FALSE)
# S4 method for matrix
rast(x, type="", crs="", digits=6, extent=NULL)
# S4 method for data.frame
rast(x, type="xyz", crs="", digits=6, extent=NULL)
# S4 method for array
rast(x, crs="", extent=NULL)
# S4 method for list
rast(x, warn=TRUE)
# S4 method for SpatRasterDataset
rast(x)
# S4 method for SpatVector
rast(x, ...)
# S4 method for SpatExtent
rast(x, ...)
Arguments
- x
filename (character), missing, SpatRaster, SpatRasterDataset, SpatExtent, SpatVector, matrix, array, list of SpatRaster objects. For other types it will be attempted to create a SpatRaster via (`as(x, "SpatRaster")`
- subds
positive integer or character to select a sub-dataset. If zero or "", all sub-datasets are returned (if possible)
- lyrs
positive integer or character to select a subset of layers (a.k.a. "bands")
- drivers
character. GDAL drivers to consider
- opts
character. GDAL dataset open options
- win
SpatExtent to set a
window
(area of interest)- snap
character. One of "near", "in", or "out", to indicate how the extent of
window
should be "snapped" tox
- vsi
logical. If
TRUE
, "\vsicurl\" is prepended to filenames that start with "http"- nrows
positive integer. Number of rows
- ncols
positive integer. Number of columns
- nlyrs
positive integer. Number of layers
- xmin
minimum x coordinate (left border)
- xmax
maximum x coordinate (right border)
- ymin
minimum y coordinate (bottom border)
- ymax
maximum y coordinate (top border)
- crs
character. Description of the Coordinate Reference System (map projection) in
PROJ.4
,WKT
orauthority:code
notation. Seecrs
. If this argument is missing, and the x coordinates are within -360 .. 360 and the y coordinates are within -90 .. 90, longitude/latitude is assigned- keeptime
logical. If
FALSE
the time stamps are discarded- keepunits
logical. If
FALSE
the layer units are discarded- props
logical. If
TRUE
the properties (categories and color-table) are kept- extent
object of class SpatExtent. If present, the arguments xmin, xmax, ymin and ymax are ignored
- resolution
numeric vector of length 1 or 2 to set the spatial resolution (see
res
). If this argument is used, argumentsncols
andnrows
are ignored- vals
numeric. An optional vector with cell values (if fewer values are provided, these are recycled to reach the number of cells)
- names
character. An optional vector with layer names (must match the number of layers)
- time
time or date stamps for each layer
- units
character. units for each layer
- type
character. If the value is not
"xyz"
, the raster has the same number of rows and columns as the matrix. If the value is"xyz"
, the matrix must have at least two columns, the first withx
(or longitude) and the second withy
(or latitude) coordinates that represent the centers of raster cells. The additional columns are the values associated with the raster cells.- digits
integer to set the precision for detecting whether points are on a regular grid (a low number of digits is a low precision). Only used when
type="xyz"
- warn
logical. If
TRUE
, a warnings about empty rasters may be emitted- ...
additional arguments passed on to the
rast,missing-method
Details
Files are read with the GDAL library. GDAL guesses the file format from the name, and/or tries reading it with different "drivers" (see gdal
) until it succeeds. In very few cases this may cause a file to be opened with the wrong driver, and some information may be lost. For example, when a netCDF file is opened with the HDF5 driver. You can avoid that by using argument rast("filename.ncdf", drivers="NETCDF")
These classes hold a C++ pointer to the data "reference class" and that creates some limitations. They cannot be recovered from a saved R session either or directly passed to nodes on a computer cluster. Generally, you should use writeRaster
to save SpatRaster objects to disk (and pass a filename or cell values ot cluster nodes). Also see wrap
.
Examples
# Create a SpatRaster from scratch
x <- rast(nrows=108, ncols=21, xmin=0, xmax=10)
# Create a SpatRaster from a file
f <- system.file("ex/elev.tif", package="terra")
r <- rast(f)
s <- rast(system.file("ex/logo.tif", package="terra"))
# Create a skeleton with no associated cell values
rast(s)
#> class : SpatRaster
#> dimensions : 77, 101, 3 (nrow, ncol, nlyr)
#> resolution : 1, 1 (x, y)
#> extent : 0, 101, 0, 77 (xmin, xmax, ymin, ymax)
#> coord. ref. : Cartesian (Meter)
# from a matrix
m <- matrix(1:25, nrow=5, ncol=5)
rm <- rast(m)
# from a "xyz" data.frame
d <- as.data.frame(rm, xy=TRUE)
head(d)
#> x y lyr.1
#> 1 0.5 4.5 1
#> 2 1.5 4.5 6
#> 3 2.5 4.5 11
#> 4 3.5 4.5 16
#> 5 4.5 4.5 21
#> 6 0.5 3.5 2
rast(d, type="xyz")
#> class : SpatRaster
#> dimensions : 5, 5, 1 (nrow, ncol, nlyr)
#> resolution : 1, 1 (x, y)
#> extent : 0, 5, 0, 5 (xmin, xmax, ymin, ymax)
#> coord. ref. :
#> source(s) : memory
#> name : lyr.1
#> min value : 1
#> max value : 25