Skip to contents

Build a shapefile from a mosaic raster

Source: R/utils_shapefile.R
shapefile_build.Rd

This function takes a mosaic raster to create a shapefile containing polygons for the specified regions. Users can drawn Areas of Interest (AOIs) that can be either a polygon with n sides, or a grid, defined by nrow, and ncol arguments.

Usage

shapefile_build(
  mosaic,
  basemap = NULL,
  controlpoints = NULL,
  r = 3,
  g = 2,
  b = 1,
  crop_to_shape_ext = TRUE,
  grid = TRUE,
  nrow = 1,
  ncol = 1,
  nsides = 200,
  plot_width = NULL,
  plot_height = NULL,
  layout = "lrtb",
  serpentine = TRUE,
  build_shapefile = TRUE,
  check_shapefile = FALSE,
  sf_to_polygon = FALSE,
  buffer_edge = 1,
  buffer_col = 0,
  buffer_row = 0,
  as_sf = TRUE,
  verbose = TRUE,
  max_pixels = 1e+06,
  downsample = NULL,
  quantiles = c(0, 1)
)

Arguments

mosaic

A SpatRaster object, typically imported using mosaic_input(). If not provided, a latitude/longitude basemap will be generated in the "EPSG:4326" coordinate reference system.

basemap

An optional mapview object.

controlpoints

An sf object created with mapedit::editMap(), containing the polygon that defines the region of interest to be analyzed.

r, g, b

The layer for the Red, Green and Blue band, respectively. Defaults to 1, 2, and 3.

crop_to_shape_ext

Crop the mosaic to the extension of shapefile? Defaults to TRUE. This allows for a faster index computation when the region of the built shapefile is much smaller than the entire mosaic extension.

grid

Logical, indicating whether to use a grid for segmentation (default: TRUE).

nrow

Number of rows for the grid (default: 1).

ncol

Number of columns for the grid (default: 1).

nsides

The number of sides if the geometry is generated with Draw Circle tool.

plot_width, plot_height

The width and height of the plot shape (in the mosaic unit). It is mutually exclusiv with buffer_col and buffer_row.

layout

Character: one of

  • 'tblr' for top/bottom left/right orientation

  • 'tbrl' for top/bottom right/left orientation

  • 'btlr' for bottom/top left/right orientation

  • 'btrl' for bottom/top right/left orientation

  • 'lrtb' for left/right top/bottom orientation

  • 'lrbt' for left/right bottom/top orientation

  • 'rltb' for right/left top/bottom orientation

  • 'rlbt' for right/left bottom/top orientation

serpentine

Create a serpentine-based layout? Defaults to FALSE.

build_shapefile

Logical, indicating whether to interactively draw ROIs if the shapefile is NULL (default: TRUE).

check_shapefile

Logical, indicating whether to validate the shapefile with an interactive map view (default: TRUE). This enables live editing of the drawn shapefile by deleting or changing the drawn grids.

sf_to_polygon

Convert sf geometry like POINTS and LINES to POLYGONS? Defaults to FALSE. Using TRUE allows using POINTS to extract values from a raster using exactextractr::exact_extract().

buffer_edge

Width of the buffer around the shapefile (default: 5).

buffer_col, buffer_row

Buffering factor for the columns and rows, respectively, of each individual plot's side. A value between 0 and 0.5 where 0 means no buffering and 0.5 means complete buffering (default: 0). A value of 0.25 will buffer the plot by 25% on each side.

as_sf

Logical value indicating whether to convert the imported shapefile to an sf object (default is TRUE).

verbose

Logical, indicating whether to display verbose output (default: TRUE).

max_pixels

Maximum number of pixels to render in the map or plot (default: 500000).

downsample

Downsampling factor to reduce the number of pixels (default: NULL). In this case, if the number of pixels in the image (width x height) is greater than max_pixels a downsampling factor will be automatically chosen so that the number of plotted pixels approximates the max_pixels.

quantiles

the upper and lower quantiles used for color stretching.

Value

A list with the built shapefile. Each element is an sf object with the coordinates of the drawn polygons.

Details

Since multiple blocks can be created, the length of arguments grid, nrow, ncol, buffer_edge, buffer_col, and buffer_row can be either an scalar (the same argument applied to all the drawn blocks), or a vector with the same length as the number of drawn blocks. In the last, shapefiles in each block can be created with different dimensions.

Examples

if (interactive() && requireNamespace("EBImage")) {
library(pliman)
mosaic <- mosaic_input(system.file("ex/elev.tif", package="terra"))
shps <-
      shapefile_build(mosaic,
                      nrow = 6,
                      ncol = 3,
                      buffer_row = -0.05,
                      buffer_col = -0.25,
                      check_shapefile = FALSE,
                      build_shapefile = FALSE) ## Use TRUE to interactively build the plots
mosaic_plot(mosaic)
shapefile_plot(shps[[1]], add = TRUE)
}