queryUSGSProjectIndex: USGS Lidar Toolkit - Identify USGS Lidar Project Covering...

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

USGS Lidar Toolkit – Identify USGS Lidar Project Covering Area

Description

Intersect a set of features (points or polygons) against a lidar project index to determine which projects provide coverage for the features. This is purely a spatial overlay operation and does not use the attribute data associated with the index.

Usage

queryUSGSProjectIndex(
  x,
  y,
  buffer = 0,
  shape = "square",
  aoi = NULL,
  crs = "",
  index = "",
  segments = 60,
  return = "index",
  returnType = "sf",
  returncrs = "same",
  lidarOnly = FALSE,
  dropNAColumns = NULL,
  clean = FALSE,
  verbose = FALSE,
  useLegacyBuffering = FALSE,
  ...
)

Arguments

x	Location easting for the center of the area-of-interest.
y	Location northing for the center of the area-of-interest.
buffer	Distance in meters added or subtracted to (x,y) to create the area-of-interest. Can be 0 when used with (x,y) to return items 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. Data in (x,y) and aoi are projected into the web mercator coordinate reference system before the buffer operation is done so the units for buffer are always meters. When buffer = 0, aoi is point(s), and return = "index" the return type will be polygon(s). While this is useful to determine the lidar projects needed to provide coverage for plots, it doesn't allow you to maintain a set of points that are covered by one or more lidar projects. If you want the set of points, pass the set of all points as aoi, set buffer = 0, and set return = "aoi" but realize that a specific sample area associated with a point may actually be covered by additional lidar projects than those that cover the point location or may be partially outside the lidar project polygon.
shape	Character string describing the shape of the sample area in the case of point features or the shape applied to the buffer corners when using polygon features. Valid values are "square" or "circle".
aoi	Spatial* or sf object containing a point or polygon describing the area of interest. Can be points or polygons.
crs	Valid proj4string string defining the coordinate reference system of (x,y). crs is required when using (x,y). 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 is ignored when aoi is specified.
index	Index file for USGS lidar projects. If not provided, an index previously specified by a call to fetchUSGSProjectIndex or setUSGSProjectIndex will be used. If not provided and you have not called fetchUSGSProjectIndex or setUSGSProjectIndex, the function displays a warning and returns.
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.
return	Character string specifying the kind of shapes to be returned. Valid values are ""aoi" to return shapes for each object in the aoi or the object defined by (x,y) and buffer with additional attributes providing lidar project information and "index" (default) to return project shapes that provide coverage for the features in the "aoi" or the area defined by (x,y) and buffer. When project shapes are returned there is no "aoi" information included with the project shape attributes.
returnType	Character string specifying the object type for the returned polygon object when (x,y) is used to specify the area-of-interest. Valid values are "Spatial" or "sf". returnType is ignored when aoi is specified.
returncrs	Valid proj4string string defining the coordinate reference system of the returned SpatialPolygonsDataFrame or sf object. A value of "same" will project the return object to the same coordinate reference system as aoi or to crs when used with (x,y). This can also be a valid SRS_string for use with the sp::CRS() function where it will be provided as the projargs argument.
lidarOnly	Boolean indicating that only lidar projects should be considered for the spatial overlay. For the USGS WESM index, setting lidarOnly = TRUE will include projects with the following values for the collection method: linear-mode lidar, Bathymetric LIDAR, Topobathymetric LIDAR, Geiger-mode LIDAR, Single Photon LIDAR. For other indexes, use the default, lidarOnly = FALSE, to prevent errors.
dropNAColumns	list of column names to test in the index for NA values. If any values in any of the columns are NA, the feature will be dropped from the index prior to the spatial overlay. Default is to consider all features in the index.
clean	Boolean to enable a cleaning operation for the project polygons using a call to st_buffer with dist = 0. This operation can fix some, but not all, topology problems. If you see warnings about self-intersecting rings, you may need to do some additional cleaning on a local copy of the project index. As of 9/22/2021, I added some additional checks and removed the call to st_buffer. The operations invoked when clean = TRUE can take a long time so you may be better off loading the index and cleaning it outside of this library.
verbose	Boolean to enable printing of status messages. This is really only useful for code debugging.
useLegacyBuffering	Boolean flag indicating that the buffer should be applied to features in their original projection. This was the original behavior of prepareTargetData prior to changes in June 2023. When TRUE, the old version of prepareTargetData is used. When TRUE, the new version of prepareTargetData is used. When writing new code, you will get more accurate features using the new version of prepareTargetData because features are first projected to UTM and then buffers are generated. The old version of prepareTargetData applied buffers using the features in their native projection so if you were using a projection that did not preserve distances or areas, buffered shapes (e.g., points with a circular buffer) did not represent the correct area.
...	Additional arguments passed to download.file

Details

Finds all USGS lidar projects that cover the area-of-interest and associates the polygon attributes with those of the input object(s) to produce the return object.

When used with (x,y), a data object is created containing a single point. The buffer is then applied and the resulting area is intersected with the project polygons.

Internally, all data are in the web mercator coordinate reference system (EPSG:3857). Various data objects are projected to this CRS to perform the intersection and then projected to desired CRS for the return object.

Value

A SpatialPolygonsDataFrame or sf object containing project polygon(s) and attribute(s) for lidar projects covering the specified area. Attributes for the aoi are placed first in the data.frame followed by attributes for the lidar project polygons.

Examples

## Not run: 
queryUSGSProjectIndex(-13540901, 5806426, 180, shape = "circle", crs = 3857)
  
## End(Not run)

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