Addresses (snaps) point features to the 3D Hydrography Program (3DHP) network using the HydroAdd3D web service. For each input point the service determines the nearest 3DHP flowline, the snapped location and its elevation, the mainstem of that flowline, the measure along the mainstem, and associated GNIS attributes.
get_3dhp_index(points, t_srs = NULL, convert_missing = TRUE, batch_size = 100)sf data.frame of POINT features to address. Must have a coordinate reference system with a resolvable EPSG code.
character or object compatible with st_crs. Target coordinate reference system of the returned features. Defaults to the coordinate reference system of `points`.
logical. If `TRUE` (default), the service no-data values (`zsnap = -9999`, `m = -1`, `snapdistance = -1`) are converted to `NA` and a logical `snapped` column flags points that addressed successfully. If `FALSE`, no data values are returned as-is.
integer number of points sent to the service per request. Default 100.
sf data.frame of POINT (XYZ) features in `t_srs`, one row per input point. The geometry is the snapped location on the 3DHP flowline: the X and Y coordinates are the snapped position and the Z coordinate is the snapped elevation in meters. Points that did not snap carry their original input location as the geometry. Attribute columns:
`source_id` - input row, echoed for joins
`zsnap` - snapped elevation in meters (the geometry Z coordinate)
`mainstemid` - geoconnex mainstem uri
`m` - measure along the mainstem, 0 = downstream, 100 = upstream
`gnisidlabel` / `gnisid` - GNIS name and id
`featuredate` - date the 3DHP feature was loaded
`snapdistance` - distance in meters from the original to the snapped point
`snapdate` - timestamp of the addressing run
`snapped` - logical, added when `convert_missing = TRUE`, flagging points that addressed successfully
Points are sent to the service in batches. The `mainstemid` is a geoconnex mainstem uri (e.g. `https://geoconnex.us/ref/mainstems/312091`) that can be passed to get_3dhp or used with the functions in add_mainstems.
See https://apps.usgs.gov/hydroadd3d for the web service.
# \donttest{
points <- sf::st_sf(
id = c(1, 2, 3),
geometry = sf::st_sfc(sf::st_point(c(-76.86934, 39.49328)),
sf::st_point(c(-76.91711, 39.40884)),
sf::st_point(c(-76.88081, 39.36354)),
crs = 4326))
indexed <- get_3dhp_index(points)
#> POST https://apps.usgs.gov/hydroadd3d/api/v1/address
#> [{"source_id":"1","x":-76.8693,"y":39.4933,"crs":4326},{"source_id":"2","x":-76.9171,"y":39.4088,"crs":4326},{"source_id":"3","x":-76.8808,"y":39.3635,"crs":4326}]
if(inherits(indexed, "sf")) {
# points that did not snap to a flowline
indexed[!indexed$snapped, ]
# pull the flowline a point was addressed to
get_3dhp(ids = indexed$mainstemid[indexed$snapped][1], type = "flowline")
}
#> POST https://3dhp.nationalmap.gov/arcgis/rest/services/usgs_3dhp_all/FeatureServer/50/query
#> POST https://3dhp.nationalmap.gov/arcgis/rest/services/usgs_3dhp_all/FeatureServer/50/query
#> Simple feature collection with 6 features and 34 fields
#> Geometry type: LINESTRING
#> Dimension: XY
#> Bounding box: xmin: -76.8721 ymin: 39.47476 xmax: -76.83305 ymax: 39.49488
#> Geodetic CRS: WGS 84
#> id3dhp featuredate mainstemid gnisid
#> 1 1CVLK 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> 2 41O5R 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> 3 62DKD 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> 4 9B33I 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> 5 FIUDQ 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> 6 H0ECA 1.69465e+12 https://geoconnex.us/usgs/mainstems/11829962 <NA>
#> gnisidlabel featuretype featuretypelabel lengthkm waterbodyid3dhp
#> 1 <NA> 1 Channel Line 0.417 <NA>
#> 2 <NA> 1 Channel Line 1.732 <NA>
#> 3 <NA> 1 Channel Line 0.009 <NA>
#> 4 <NA> 1 Channel Line 0.404 <NA>
#> 5 <NA> 5 Waterbody Connector 0.036 K9R2W
#> 6 <NA> 1 Channel Line 2.304 <NA>
#> flowdirection
#> 1 1
#> 2 1
#> 3 1
#> 4 1
#> 5 1
#> 6 1
#> flowdirectionlabel
#> 1 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> 2 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> 3 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> 4 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> 5 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> 6 Flow direction is in digitized direction, and z-values on vertices flow downslope
#> onsurface onsurfacelabel catchmentid3dhp flowpathid3dhp
#> 1 1 Feature is on the land surface <NA>
#> 2 1 Feature is on the land surface <NA>
#> 3 1 Feature is on the land surface <NA>
#> 4 1 Feature is on the land surface <NA>
#> 5 1 Feature is on the land surface <NA>
#> 6 1 Feature is on the land surface <NA>
#> streamlevel startflag terminalflag streamorder streamcalculator hydrosequence
#> 1 3 0 0 3 3 5651428
#> 2 3 1 0 1 1 5731111
#> 3 3 0 0 2 2 5711346
#> 4 3 0 0 3 3 5671379
#> 5 3 0 0 3 3 5631398
#> 6 3 0 0 2 2 5691468
#> dnhydrosequence uphydrosequence dnlevelpath uplevelpath pathlength
#> 1 5631398 5671379 5631398 5631398 344.4901
#> 2 5711346 0 5631398 0 347.6241
#> 3 5691468 5731111 5631398 5631398 347.6151
#> 4 5651428 5691468 5631398 5631398 344.9071
#> 5 5611201 5651428 1688747 5631398 344.4541
#> 6 5671379 5711346 5631398 5631398 345.3111
#> arbolatesum divergence divergencelabel rtrndivergence levelpath terminalpath
#> 1 11.21912 0 No divergence 0 5631398 15
#> 2 1.73200 0 No divergence 0 5631398 15
#> 3 3.64000 0 No divergence 0 5631398 15
#> 4 10.80212 0 No divergence 0 5631398 15
#> 5 11.25512 0 No divergence 0 5631398 15
#> 6 6.61300 0 No divergence 0 5631398 15
#> workunitid Shape__Length geometry
#> 1 NHD 541.51000 LINESTRING (-76.86794 39.49...
#> 2 NHD 2242.83458 LINESTRING (-76.83305 39.47...
#> 3 NHD 11.83702 LINESTRING (-76.84362 39.48...
#> 4 NHD 527.00804 LINESTRING (-76.86357 39.49...
#> 5 NHD 46.02234 LINESTRING (-76.87187 39.49...
#> 6 NHD 2993.04821 LINESTRING (-76.84373 39.48...
# }