prepareTargetDataLegacy: USGS Lidar Toolkit - Prepare Target Data

In bmcgaughey1/USGSlidar: Provides Functions to Access USGS LIDAR Data Collection

USGS Lidar Toolkit – Prepare Target Data

Description

Prepare features for use when querying a lidar project or tile index to determine available data coverage. The basic operation done by this function is to apply the buffer to the features.

Usage

prepareTargetDataLegacy(
  x,
  y,
  buffer = 0,
  shape = "square",
  aoi = "",
  crs = "",
  segments = 60,
  returnType = "sf"
)

Arguments

x	Location or list of locations containing the easting for the center of the area-of-interest.
y	Location or list of locations containing the northing for the center of the area-of-interest.
buffer	Distance or list of distances added or subtracted to (x,y) to create the area-of-interest. Can be 0 when used with (x,y) to return projects providing coverage for point location(s). Can be a vector of values corresponding to the number of objects in aoi allowing a different buffer size for each object when aoi is a Spatial* or sf object. buffer can be negative with polygon features to reduce the area considered. However, you may end up with weird shapes if the distance is larger than the width of the polygon.
shape	Character string describing the shape of the sample area. Valid values are "square" or "circle". The buffer shape is the same for all objects specified by (x,y) or aoi.
aoi	Spatial* or sf object containing a point(s) or polygon(s) describing the area(s) of interest. Can be points or polygons.
crs	Valid proj4string string defining the coordinate reference system of (x,y) or aoi. crs is required when using (x,y). It is optional when using aoi. This can also be a valid SRS_string for use with the sp::CRS() function where it will be provided as the projargs argument. crs can also be an EPSG code (numeric).
segments	Number of segments to use when generating a circular area of interest. When using a SpatialPoint* or sf object with shape = "circle", set segments to a rather large value (60 or higher) that is a multiple of 4. The st_buffer function from sf is used to build the sample areas and it accepts the number of segments in a quarter circle so small values for segments may not produce good circles. Values for segments that are not a multiple of 4 will not produce circles with the correct number of segments.
returnType	Character string specifying the object type for the polygon object returned by prepareTargetDataLegacy when (x,y) is used to specify the area-of-interest. Valid values are "Spatial" or "sf". returnType is ignored when aoi is specified and the return type will match the object type of aoi.

Details

Prepare point or polygon data for use when querying to determine the lidar project or tile coverage. Typically this preparation is done by the queryUSGSProjectIndex or queryUSGSTileIndex functions but you can use prepareTargetDataLegacyu to build the query objects so they can be used for other purposes.

Units for buffer are the same as the horizontal units for the input features so you shouldn't use data in LON-LAT with units of degrees. In addition, LON-LAT coordinates are not allowed when working with Spatial* return types and (x,y) inputs. If you must use LON-LAT coords, set returnType = "sf".

Ideally, you should use a projection for the input (x,y) or aoi that preserves distances and areas so the buffered area is accurate. UTM is a good choice. Web Mercator does not preserve distance or areas so the actual area produced when buffering a point varies considerably as you go from mid to northern or southern latitudes. You can use the computeClipBufferForCONUS function to adjust the buffer width depending on the location of (x,y) or aoi. This isn't a perfect solution but it gets you close. More accurate results can be produced by projecting you (x,y) or aoi into UTM, calling prepareTargetDataLegacy, then reproject the returned features into the desired projection.

prepareTargetDataLegacy is the original version of the prepareTargetData function in the package. It has been replaced by a new version of the function that projects features to UTM, applies the buffer, then projects feature back to the original projection. The new version produces more accurate features. This is especially true when using point features.

Value

A set of optionally buffered spatial features. The return type will be the same as the aoi type. When (x,y) is used, returnType specifies the object type returned by prepareTargetDataLegacy.

Examples

prepareTargetDataLegacy(-13540901, 5806426, 180, shape = "circle",
  crs = sp::CRS(SRS_string="EPSG:3857")@projargs)
pt1 <- sf::st_point(c(-13540901, 5806426 + 500))
pt2 <- sf::st_point(c(-13540901 + 500, 5806426 - 500))
pt3 <- sf::st_point(c(-13540901 - 500, 5806426))
pt4 <- sf::st_point(c(-13540901 + 1000, 5806426 - 1000))
id <- c("P1", "P2", "P3", "P4")
x_sf <- sf::st_sf(data.frame(ID = id, stringsAsFactors = FALSE),
  geom = sf::st_sfc(pt1, pt2, pt3, pt4),
  crs = sp::CRS(SRS_string="EPSG:3857")@projargs)
samples <- prepareTargetDataLegacy(aoi = x_sf, buffer = 180)

bmcgaughey1/USGSlidar documentation built on June 23, 2024, 1:25 a.m.