queryMPCTileIndex: USGS Lidar Toolkit - Identify Microsoft Planetary Computer...

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

USGS Lidar Toolkit – Identify Microsoft Planetary Computer Lidar Tiles Covering Area

Description

Intersect a set of features (points or polygons) against the lidar point data STAC index on Microsoft Planetary Computer to determine which tiles are needed to provide coverage for the features. This index contains every lidar point tile in the MPC-USGS lidar collection. Queries for features covering a large area can take some time.

Usage

queryMPCTileIndex(
  x = NULL,
  y = NULL,
  buffer = 0,
  projectID = NULL,
  fieldname = "workunit_id",
  shape = "square",
  aoi = NULL,
  crs = "",
  segments = 60,
  return = "index",
  returnType = "sf",
  returncrs = "same",
  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 UTM coordinate reference system before the buffer operation is done so the units for buffer are always meters.
projectID	Character string or list of character strings containing the ID(s) for the lidar project(s). Typically obtained by calling queryUSGSProjectIndex(). You must provide at least one project identifier.
fieldname	Character string containing the name of the field with matches for the projectID to be used when querying the tile index.
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). crs is ignored when aoi is specified. 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.
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 tile shapes that provide coverage for the features in the "aoi" or the area defined by (x,y) and buffer. When tile shapes are returned there is no "aoi" information included with the project shape attributes. There are two types of URLs returned for the lidar tiles. The URL field contains the unsigned URL for the tiles and the signedURL field contains a signed URL. The signed URLs are only valid for the current R session and cannot be saved and used at a later time. If you need to use the URLs in a different R session or a different process, you will need to obtain access tokens and append them to the URLs. If you are using R, you can use the signMPCURL function in the USGSlidar package to sign the URLs.
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).
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 FALSE, 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

The MPC lidar collection contains all lidar data produced by USGS as of Fall 2022. Projects added to the USGS data collection after this date are currently not added to the MPC data collection. This could change in the future. Check MPC for additional information about the lidar data colection.

Query the MPC tile index to find tiles that intersect the buffered (x,y) point(s) or buffered feature(s) provided in aoi.

Value

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

Examples

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

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