terra provides methods to manipulate geographic (spatial) data in "raster" and "vector" form. Raster data divide space into rectangular grid cells and they are commonly used to represent spatially continuous phenomena, such as elevation or the weather. Satellite images also have this data structure, and in that context grid cells are often referred to as pixels. In contrast, "vector" spatial data (points, lines, polygons) are typically used to represent discrete spatial entities, such as a road, country, or bus stop.

The package implements two main classes (data types): SpatRaster and SpatVector. SpatRaster supports handling large raster files that cannot be loaded into memory; local, focal, zonal, and global raster operations; polygon, line and point to raster conversion; integration with modeling methods to make spatial predictions; and more. SpatVector supports all types of geometric operations such as intersections.

Additional classes include SpatExtent, which is used to define a spatial extent (bounding box); SpatRasterDataset, which represents a collection of sub-datasets for the same area. Each sub-dataset is a SpatRaster with possibly many layers, and may, for example, represent different weather variables; and SpatRasterCollection and SpatVectorCollection that are equivalent to lists of SpatRaster or SpatVector objects. There is also a SpatGraticule class to assist in adding a longitude/latitude lines and labels to a map with another coordinate reference system.

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 to cluster nodes). Also see wrap.

The terra package is conceived as a replacement of the raster package. terra has a very similar, but simpler, interface, and it is faster than raster. At the bottom of this page there is a table that shows differences in the methods between the two packages.

Below is a list of some of the most important methods grouped by theme.

---------------------------------------------------------------------------------------------------------------------

## SpatRaster

---------------------------------------------------------------------------------------------------------------------

## XV. SpatRasterCollections

A SpatRasterCollection is a vector of SpatRaster objects. Unlike for a SpatRasterDataset, there the extent and resolution of the SpatRasters do not need to match each other.

 sprc create a SpatRasterCollection from (a list of) SpatRaster objects length how many SpatRasters does the SpatRasterCollection have? crop crop a SpatRasterCollection impose force the members of SpatRasterCollection to the same geometry merge merge the members of a SpatRasterCollection mosaic mosaic (merge with a function for overlapping areas) the members of a SpatRasterCollection [ extract a SpatRaster --------------------------- ------------------------------------------------------------------------------------------

## SpatVector

---------------------------------------------------------------------------------------------------------------------

## XVI. Create SpatVector objects

 vect Create a SpatVector from a file (for example a "shapefile") or from another object vector_layers list or delete layers in a vector database such as GPGK rbind append SpatVectors of the same geometry type unique remove duplicates na.omit remove empty geometries and/or fields that are NA project Project a SpatVector to a different coordinate reference system writeVector Write SpatVector data to disk centroids Get the centroids of a SpatVector voronoi Voronoi diagram delaunay Delaunay triangles convHull Compute the convex hull of a SpatVector fillHoles Remove or extract holes from polygons --------------------------- ------------------------------------------------------------------------------------------

## XVII. Properties of SpatVector objects

 geom returns the geometries as matrix or WKT crds returns the coordinates as a matrix linearUnits returns the linear units of the crs (in meter) ncol The number of columns (of the attributes) nrow The number of rows (of the geometries and attributes) names Get or set the layer names ext Get the extent (minimum and maximum x and y coordinates ("bounding box") crs The coordinate reference system (map projection) is.lonlat Test if an object has (or may have) a longitude/latitude coordinate reference system --------------------------- ------------------------------------------------------------------------------------------

## XVIII. Geometric queries

 adjacent find adjacent polygons expanse computes the area covered by polygons nearby find nearby geometries nearest find the nearest geometries relate geometric relationships such as "intersects", "overlaps", and "touches" perim computes the length of the perimeter of polygons, and the length of lines --------------------------- ------------------------------------------------------------------------------------------

## XIX. Geometric operations

 erase or "-" erase (parts of) geometries intersect or "*" intersect geometries union or "+" Merge geometries cover update polygons symdif symmetrical difference of two polygons aggregate dissolve smaller polygons into larger ones buffer buffer geometries disagg split multi-geometries into separate geometries crop clip geometries using a rectangle (SpatExtent) or SpatVector --------------------------- ------------------------------------------------------------------------------------------

## XX. SpatVector attributes

We use the term "attributes" for the tabular data (data.frame) associated with vector geometries.

 extract spatial queries between SpatVector and SpatVector (e.g. point in polygons) sel select - interactively select geometries click identify attributes by clicking on a map merge Join a table with a SpatVector as.data.frame get attributes as a data.frame as.list get attributes as a list values Get the attributes of a SpatVector values<- Set new attributes to the geometries of a SpatRaster sort sort SpatVector by the values in a field --------------------------- ------------------------------------------------------------------------------------------

## XXI. Change geometries (for display, experimentation)

 shift change the position geometries by shifting their coordinates in horizontal and/or vertical direction spin rotate geometries around an origin rescale shrink (or expand) geometries, for example to make an inset map flip flip geometries vertically or horizontally t transpose geometries (switch x and y) --------------------------- ------------------------------------------------------------------------------------------

## XXII. Geometry properties and topology

 width the minimum diameter of the geometries clearance the minimum clearance of the geometries sharedPaths shared paths (arcs) between line or polygon geometries simplifyGeom simplify geometries gaps find gaps between polygon geometries fillHoles get or remove the polygon holes makeNodes create nodes on lines mergeLines connect lines to form polygons removeDupNodes remove duplicate nodes in geometries and optionally rounds the coordinates is.valid check if geometries are valid makeValid attempt to repair invalid geometries snap make boundaries of geometries identical if they are very close to each other erase (single argument) remove parts of geometries that overlap union (single argument) create new polygons such that there are no overlapping polygons rotate rotate to (dis-) connect them across the date-line normalize.longitude move geomtries that are outside of the -180 to 180 degrees range. elongate make lines longer by extending both sides combineGeoms combine geometries that overlap, share a border, or are within a minimum distance of each other --------------------------- ------------------------------------------------------------------------------------------

## XXIII. SpatVectorCollections

A SpatVectorCollection is a vector of SpatVector objects.

 svc create a SpatVectorCollection from (a list of) SpatVector objects length how many SpatRasters does the SpatRasterCollection have? [ extract a SpatVector --------------------------- ------------------------------------------------------------------------------------------

## Other classes

---------------------------------------------------------------------------------------------------------------------

## XXIV. SpatExtent

 ext Create a SpatExtent object. For example to crop a Spatial dataset intersect Intersect two SpatExtent objects, same as - union Combine two SpatExtent objects, same as + Math-methods round/floor/ceiling of a SpatExtent align Align a SpatExtent with a SpatRaster draw Create a SpatExtent by drawing it on top of a map (plot) --------------------------- ------------------------------------------------------------------------------------------

## XXV. SpatGraticule

 graticule Create a graticule crop crop a graticule plot plot a graticule --------------------------- ------------------------------------------------------------------------------------------

## General methods

---------------------------------------------------------------------------------------------------------------------

## XXVI. Conversion between spatial data objects from different packages

You can coerce SpatRasters to Raster* objects, after loading the raster package, with as(object, "Raster"), or raster(object) or brick(object) or stack(object)

 rast SpatRaster from matrix and other objects vect SpatVector from sf or Spatial* vector data sf::st_as_sf sf object from SpatVector rasterize Rasterizing points, lines or polygons rasterizeWin Rasterize points with a moving window rasterizeGeom Rasterize attributes of geometries such as "count", "area", or "length" as.points Create points from a SpatRaster or SpatVector as.lines Create points from a SpatRaster or SpatVector as.polygons Create polygons from a SpatRaster as.contour Contour lines from a SpatRaster --------------------------- ------------------------------------------------------------------------------------------

## XXVII. Plotting

### Maps

 plot Plot a SpatRaster or SpatVector. The main method to create a map panel Combine multiple plots points Add points to a map lines Add lines to a map polys Add polygons to a map text Add text (such as the values of a SpatRaster or SpatVector) to a map halo Add text with a halo to a map image Alternative to plot to make a map with a SpatRaster plotRGB Combine three layers (red, green, blue channels) into a single "real color" plot plot plot a graticule sbar Add a scale bar to a map north Add a north arrow to a map inset Add a small inset (overview) map dots Make a dot-density map cartogram Make a cartogram persp Perspective plot of a SpatRaster contour Contour plot or filled-contour plot of a SpatRaster colorize Combine three layers (red, green, blue channels) into a single layer with a color-table --------------------------- ------------------------------------------------------------------------------------------

### Interacting with a map

 zoom Zoom in to a part of a map by drawing a bounding box on it click Query values of SpatRaster or SpatVector by clicking on a map sel Select a spatial subset of a SpatRaster or SpatVector by drawing on a map draw Create a SpatExtent or SpatVector by drawing on a map --------------------------- ------------------------------------------------------------------------------------------

### Other plots

 plot x-y scatter plot of the values of (a sample of) the layers of two SpatRaster objects hist Histogram of SpatRaster values barplot Bar plot of a SpatRaster density Density plot of SpatRaster values pairs Pairs plot for layers in a SpatRaster boxplot Box plot of the values of a SpatRaster --------------------------- ------------------------------------------------------------------------------------------

## Comparison with the raster package

---------------------------------------------------------------------------------------------------------------------

## XXVIII. New method names

terra has a single class SpatRaster for which raster has three (RasterLayer, RasterStack, RasterBrick). Likewise there is a single class for vector data SpatVector that replaces six Spatial* classes. Most method names are the same, but note the following important differences in methods names with the raster package

 raster package terra package raster, brick, stack rast rasterFromXYZ rast( , type="xyz") stack, addLayer c addLayer add<- area cellSize or expanse approxNA approximate calc app cellFromLine, cellFromPolygon, cells cellsFromExtent cells cellStats global clump patches compareRaster compareGeom corLocal focalCor coordinates crds couldBeLonLat is.lonlat disaggregate disagg distanceFromPoints distance drawExtent, drawPoly, drawLine draw dropLayer subset extent ext getValues values isLonLat, isGlobalLonLat is.lonlat layerize segregate layerStats layerCor movingFun roll NAvalue NAflag nlayers nlyr overlay lapp unstack as.list projectRaster project rasterToPoints as.points rasterToPolygons as.polygons reclassify, subs, cut classify sampleRandom, sampleRegular spatSample shapefile vect stackApply tapp stackSelect selectRange

## XXIX. Changed behavior

Also note that even if function names are the same in terra and raster, their output can be different. In most cases this was done to get more consistency in the returned values (and thus fewer errors in the downstream code that uses them). It other cases it simply seemed better. Here are some examples:

 as.polygons By default, terra returns dissolved polygons quantile computes by cell, across layers instead of the other way around extract By default, terra returns a matrix, with the first column the sequential ID of the vectors. raster returns a list (for lines or polygons) or a matrix (for points, but without the ID column. You can use list=TRUE to get the results as a list values terra always returns a matrix. raster returns a vector for a RasterLayer Summary-methods With raster, mean(x, y) and mean(stack(x, y) return the same result, a single layer with the mean of all cell values. This is also what terra returns with mean(c(x, y)), but with mean(x, y) the parallel mean is returned -- that is, the computation is done layer-wise, and the number of layers in the output is the same as that of x and y (or the larger of the two if they are not the same). This affects all summary functions (sum, mean, median, which.min, which.max, min, max, prod, any, all, stdev), except range, which is not implemented for this case (you can use min and max instead) --------------------------- ------------------------------------------------------------------------------------------

## Authors

Except where indicated otherwise, the methods and functions in this package were written by Robert Hijmans. The configuration scripts were written by Roger Bivand. Some of code using the GEOS library was adapted from code by Edzer Pebesma for sf. Michael Sumner contributed various bits and pieces.

## Acknowledgments

This package is an attempt to climb on the shoulders of giants (GDAL, PROJ, GEOS, NCDF, GeographicLib, Rcpp, R). Many people have contributed by asking questions or raising issues. Feedback and suggestions by Márcia Barbosa, Kendon Bell, Andrew Gene Brown, Jean-Luc Dupouey, Krzysztof Dyba, Alex Ilich, Gerald Nelson, Jakub Nowosad and Monika Tomaszewska have been especially helpful.