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 32 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
#> catchmentid3dhp flowpathid3dhp streamlevel startflag terminalflag streamorder
#> 1 <NA> 3 0 0 3
#> 2 <NA> 3 1 0 1
#> 3 <NA> 3 0 0 2
#> 4 <NA> 3 0 0 3
#> 5 <NA> 3 0 0 3
#> 6 <NA> 3 0 0 2
#> streamcalculator hydrosequence dnhydrosequence uphydrosequence dnlevelpath
#> 1 3 5608832 5589222 5628340 5589222
#> 2 1 5686716 5667406 0 5589222
#> 3 2 5667406 5647988 5686716 5589222
#> 4 3 5628340 5608832 5647988 5589222
#> 5 3 5589222 5569423 5608832 1688141
#> 6 2 5647988 5628340 5667406 5589222
#> uplevelpath pathlength arbolatesum divergence divergencelabel rtrndivergence
#> 1 5589222 344.4901 11.21912 0 No divergence 0
#> 2 0 347.6241 1.73200 0 No divergence 0
#> 3 5589222 347.6151 3.64000 0 No divergence 0
#> 4 5589222 344.9071 10.80212 0 No divergence 0
#> 5 5589222 344.4541 11.25512 0 No divergence 0
#> 6 5589222 345.3111 6.61300 0 No divergence 0
#> levelpath terminalpath workunitid Shape__Length
#> 1 5589222 15 NHD 541.51000
#> 2 5589222 15 NHD 2242.83458
#> 3 5589222 15 NHD 11.83702
#> 4 5589222 15 NHD 527.00804
#> 5 5589222 15 NHD 46.02234
#> 6 5589222 15 NHD 2993.04821
#> geometry
#> 1 LINESTRING (-76.86794 39.49...
#> 2 LINESTRING (-76.83305 39.47...
#> 3 LINESTRING (-76.84362 39.48...
#> 4 LINESTRING (-76.86357 39.49...
#> 5 LINESTRING (-76.87187 39.49...
#> 6 LINESTRING (-76.84373 39.48...
# }