| Title: | Automate the Delineation of Urban River Spaces |
|---|---|
| Description: | Provides tools to automate the morphological delineation of riverside urban areas based on a method introduced in Forgaci (2018) <doi:10.7480/abe.2018.31>. Delineation entails the identification of corridor boundaries, segmentation of the corridor, and delineation of the river space using two-dimensional spatial information from street network data and digital elevation data in a projected CRS. The resulting delineation can be used to characterise spatial phenomena that can be related to the river as a central element. |
| Authors: | Claudiu Forgaci [aut, cre, cph] (ORCID: <https://orcid.org/0000-0003-3218-5102>), Francesco Nattino [aut] (ORCID: <https://orcid.org/0000-0003-3286-0139>), Fakhereh Alidoost [ctb] (ORCID: <https://orcid.org/0000-0001-8407-6472>), Meiert Willem Grootes [ctb] (ORCID: <https://orcid.org/0000-0002-5733-4795>), Yehan Wu [ctb] (ORCID: <https://orcid.org/0000-0003-4063-7535>), Netherlands eScience Center [fnd] |
| Maintainer: | Claudiu Forgaci <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 0.3.1 |
| Built: | 2026-09-22 16:23:46 UTC |
| Source: | https://github.com/cityriverspaces/rcrisp |
If the x does not have a CRS, WGS84 is assumed.
as_bbox(x)as_bbox(x)
x |
Simple feature object (or compatible) or a bounding box, provided either as a matrix (with x, y as rows and min, max as columns) or as a vector (xmin, ymin, xmax, ymax) |
A bbox object as returned by sf::st_bbox()
library(sf) bounding_coords <- c(25.9, 44.3, 26.2, 44.5) bb <- as_bbox(bounding_coords) class(bb) st_crs(bb)library(sf) bounding_coords <- c(25.9, 44.3, 26.2, 44.5) bb <- as_bbox(bounding_coords) class(bb) st_crs(bb)
Standardise the coordinate reference system (CRS) of an object
as_crs(x, allow_geographic = FALSE)as_crs(x, allow_geographic = FALSE)
x |
An object of class |
allow_geographic |
Logical, whether to allow geographic CRS (lat/lon). |
An object of class sf::crs with a valid CRS.
library(sf) # Standardise a numeric EPSG code as_crs(4326, allow_geographic = TRUE) # Standardise a character EPSG code as_crs("EPSG:4326", allow_geographic = TRUE) # Standardise a bbox object bb <- st_bbox(c(xmin = 25.9, ymin = 44.3, xmax = 26.2, ymax = 44.5), crs = 4326) as_crs(bb, allow_geographic = TRUE) # Standardise a simple feature object bb_sfc <- st_as_sfc(bb) bb_sf <- st_as_sf(bb_sfc) as_crs(bb_sf, allow_geographic = TRUE) as_crs(bb_sfc, allow_geographic = TRUE)library(sf) # Standardise a numeric EPSG code as_crs(4326, allow_geographic = TRUE) # Standardise a character EPSG code as_crs("EPSG:4326", allow_geographic = TRUE) # Standardise a bbox object bb <- st_bbox(c(xmin = 25.9, ymin = 44.3, xmax = 26.2, ymax = 44.5), crs = 4326) as_crs(bb, allow_geographic = TRUE) # Standardise a simple feature object bb_sfc <- st_as_sfc(bb) bb_sf <- st_as_sf(bb_sfc) as_crs(bb_sf, allow_geographic = TRUE) as_crs(bb_sfc, allow_geographic = TRUE)
Create a network from a collection of line strings
as_network(edges, flatten = TRUE, clean = TRUE, na_action = "warn")as_network(edges, flatten = TRUE, clean = TRUE, na_action = "warn")
edges |
An |
flatten |
Whether all intersections between edges should be converted to nodes |
clean |
Whether general cleaning tasks should be run on the generated
network (see |
na_action |
A case-insensitive character string specifying how to deal
with missing values in non-geometry columns of
|
An sfnetworks::sfnetwork object
edges <- sf::st_sfc( sf::st_linestring(matrix(c(0, 0, 1, 1), ncol = 2, byrow = TRUE)), sf::st_linestring(matrix(c(0, 1, 1, 0), ncol = 2, byrow = TRUE)), crs = sf::st_crs("EPSG:32635") ) # Run with default values as_network(edges) # Only build the spatial network as_network(edges, flatten = FALSE, clean = FALSE)edges <- sf::st_sfc( sf::st_linestring(matrix(c(0, 0, 1, 1), ncol = 2, byrow = TRUE)), sf::st_linestring(matrix(c(0, 1, 1, 0), ncol = 2, byrow = TRUE)), crs = sf::st_crs("EPSG:32635") ) # Run with default values as_network(edges) # Only build the spatial network as_network(edges, flatten = FALSE, clean = FALSE)
Delineation generated with rcrisp example data found at https://zenodo.org/records/16325879
bucharest_dambovitabucharest_dambovita
A list of sf objects representing:
The valley boundaries of river Dâmbovița.
The corridor boundaries of river Dâmbovița.
Corridor segments of river Dâmbovița.
River space of Dâmbovița.
By default, the user-specific directory as returned by
tools::R_user_dir() is used. A different directory can be used by
setting the environment variable CRISP_CACHE_DIRECTORY. This can also be
done by adding the following line to the .Renviron file:
CRISP_CACHE_DIRECTORY=/path/to/crisp/cache/dir.
cache_directory()cache_directory()
The cache directory used by rcrisp.
cache_directory()cache_directory()
A message is displayed if the cache size is > 100 MB or if it includes files older than 30 days.
check_cache()check_cache()
NULL
check_cache()check_cache()
Subdivide edges by adding missing nodes,
(optionally) simplify the network (see simplify_network()), remove
pseudo-nodes,
and discard all but the main connected component.
clean_network(network, simplify = TRUE)clean_network(network, simplify = TRUE)
network |
A network object of class |
simplify |
Whether the network should be simplified with
|
A cleaned network object of class sfnetworks::sfnetwork
bucharest_osm <- get_osm_example_data() edges <- dplyr::bind_rows(bucharest_osm$streets, bucharest_osm$railways) network <- sfnetworks::as_sfnetwork(edges, directed = FALSE) clean_network(network)bucharest_osm <- get_osm_example_data() edges <- dplyr::bind_rows(bucharest_osm$streets, bucharest_osm$railways) network <- sfnetworks::as_sfnetwork(edges, directed = FALSE) clean_network(network)
Remove files from cache directory either before a given date or entirely.
clear_cache(before_date = NULL)clear_cache(before_date = NULL)
before_date |
Date before which cache files should be removed provided
as object of class |
NULL
# Clear all cache clear_cache() # Clear cache before given date before_date <- as.Date("1-1-1999", "%m-%d-%Y") clear_cache(before_date = before_date)# Clear all cache clear_cache() # Clear cache before given date before_date <- as.Date("1-1-1999", "%m-%d-%Y") clear_cache(before_date = before_date)
Endpoint and collection ID of the default STAC collection where to access digital elevation model (DEM) data. This is the global Copernicus DEM 30 dataset hosted on AWS, as listed in the EarthSearch STAC API endpoint. Note that AWS credentials need to be set up in order to access the data (not the catalog). References:
default_stac_demdefault_stac_dem
An object of class list of length 2.
Define delineation parameters within an area of interest
define_aoi( city_name, river_name, crs = NULL, network_buffer = 3000, dem_buffer = 2500, buildings_buffer = 100 )define_aoi( city_name, river_name, crs = NULL, network_buffer = 3000, dem_buffer = 2500, buildings_buffer = 100 )
city_name |
A character vector of length one |
river_name |
A character vector of length one |
crs |
The projected Coordinate Reference System (CRS) to use. If not provided, the suitable Universal Transverse Mercator (UTM) CRS is selected |
network_buffer |
Add a buffer (an integer in meters) around river to retrieve additional data (streets, railways, etc.). Default is 3000 m. |
dem_buffer |
Size of the buffer region (in meters) around the spatial network to retrieve the DEM. |
buildings_buffer |
Add a buffer (an integer in meters) around the river to retrieve additional data (buildings). Default is 100 m. |
A list with delineation parameter values, namely city_name and
river_name as character vectors of length one, bb as object of class
sf::bbox, crs as object of class sf::crs, and
network_buffer, dem_buffer and buildings_buffer as numerical vector
of length one.
# Get default parameters in AOI aoi <- define_aoi("Bucharest", "Dâmbovița") # Get parameters in AOI with custom CRS aoi <- define_aoi("Bucharest", "Dâmbovița", crs = "EPSG:3844") # National projected CRS # Get parameters in AOI with non-default buffers aoi <- define_aoi("Bucharest", "Dâmbovița", network_buffer = 2000, dem_buffer = 2000, buildings_buffer = 150)# Get default parameters in AOI aoi <- define_aoi("Bucharest", "Dâmbovița") # Get parameters in AOI with custom CRS aoi <- define_aoi("Bucharest", "Dâmbovița", crs = "EPSG:3844") # National projected CRS # Get parameters in AOI with non-default buffers aoi <- define_aoi("Bucharest", "Dâmbovița", network_buffer = 2000, dem_buffer = 2000, buildings_buffer = 150)
Given a set of delineation parameters and input data, carry out corridor delineation, corridor segmentation and/or riverspace delineation as indicated by the user.
delineate( aoi, osm, dem = NULL, corridor_init = "valley", max_iterations = 10, capping_method = "shortest-path", angle_threshold = 100, corridor = TRUE, segments = FALSE, riverspace = FALSE )delineate( aoi, osm, dem = NULL, corridor_init = "valley", max_iterations = 10, capping_method = "shortest-path", angle_threshold = 100, corridor = TRUE, segments = FALSE, riverspace = FALSE )
aoi |
A list of delineation parameters for an area of interest, namely
|
osm |
A list with OpenStreetMap data sets within the |
dem |
Digital elevation model (DEM) of the region (only used if
|
corridor_init |
How to estimate the initial guess of the river corridor. It can take the following values:
|
max_iterations |
Maximum number of iterations employed to refine the
corridor edges (see |
capping_method |
The method employed to connect the corridor edge end
points (i.e., to "cap" the corridor), as character vector of length one.
See |
angle_threshold |
Only network edges forming angles above this threshold
(in degrees) are considered when forming segment edges. See
|
corridor |
Whether to carry out the corridor delineation |
segments |
Whether to carry out the corridor segmentation |
riverspace |
Whether to carry out the riverspace delineation |
The returned delineation class is a list wrapping objects of class
sf::sfc_POLYGON or sf::sfc_MULTIPOLYGON which can be retrieved
through subsetting and converted to other common spatial classes in typical
sf- or terra-based workflows.
Corridor delineation depends on the availability of OpenStreetMap street and railway data around the river. Sparse OSM data, especially too few river crossings, may lead to failed delineation.
A list object of class delineation containing zero or more of the
following elements: "valley", "corridor", "segments", and "riverspace",
each as an sf::sfc_POLYGON or sf::sfc_MULTIPOLYGON object
(depending on the geometry of the input data). The list contains only
the geometries corresponding to the delineation steps that were carried out
(e.g., if segments is FALSE, the list will not contain a "segments"
element). In any case, the returned object also contains the base layers
and a list aoi with the parameters used for delineation.
# Define delineation parameters within area of interest aoi <- define_aoi("Bucharest", "Dâmbovița") # Get data osm <- get_osm(aoi) dem <- get_dem(aoi, osm) # Delineate with defaults delineate(aoi, osm, dem) # Carry out all delineations delineate(aoi, osm, dem, segments = TRUE, riverspace = TRUE)# Define delineation parameters within area of interest aoi <- define_aoi("Bucharest", "Dâmbovița") # Get data osm <- get_osm(aoi) dem <- get_dem(aoi, osm) # Delineate with defaults delineate(aoi, osm, dem) # Carry out all delineations delineate(aoi, osm, dem, segments = TRUE, riverspace = TRUE)
This is a convenience function used for quick delineation. With only the city name and river name as input, it uses default delineation parameters, it retrieves OSM and DEM data and returns a list with all three delineations.
delineate_city_river( city_name, river_name, corridor = TRUE, segments = TRUE, riverspace = TRUE )delineate_city_river( city_name, river_name, corridor = TRUE, segments = TRUE, riverspace = TRUE )
city_name |
A character vector of length one. |
river_name |
A character vector of length one. |
corridor |
Whether to carry out the corridor delineation. Default is TRUE. |
segments |
Whether to carry out the corridor segmentation. Default is TRUE. |
riverspace |
Whether to carry out the riverspace delineation. Default is TRUE. |
A list with the valley, corridor, segments, and riverspace
geometries as sf::sfc_POLYGON objects.
delineate_city_river("Bucharest", "Dâmbovița")delineate_city_river("Bucharest", "Dâmbovița")
The corridor edges on the two river banks are drawn on the provided spatial network starting from an initial guess of the corridor (based e.g. on the river valley).
delineate_corridor( network, river, corridor_init = 1000, max_width = 3000, max_iterations = 10, capping_method = "shortest-path" )delineate_corridor( network, river, corridor_init = 1000, max_width = 3000, max_iterations = 10, capping_method = "shortest-path" )
network |
The spatial network of class |
river |
A (MULTI)LINESTRING simple feature geometry of class |
corridor_init |
How to estimate the initial guess of the river corridor. It can take the following values: |
max_width |
A positive number representing the (approximate) maximum width of the corridor in meters. The upper limit is unrestricted. The spatial network is trimmed by a buffer region of this size around the river. |
max_iterations |
A positive integer greater than 0, with upper limit
unrestricted, representing the maximum number of iterations employed to
refine the corridor edges (see |
capping_method |
Case-insensitive character vector of length 1 with the
method employed to connect the corridor edge end points (i.e. to "cap" the
corridor). See |
A simple feature geometry of class sf::sfc_POLYGON representing
the river corridor
bucharest_osm <- get_osm_example_data() streets <- bucharest_osm$streets railways <- bucharest_osm$railways river <- bucharest_osm$river_centerline # Delineate with default values network <- rbind(streets, railways) |> as_network() delineate_corridor(network = network, river = river) # Delineate with user-specified parameters bucharest_dem <- get_dem_example_data() corridor_init <- delineate_valley(dem = bucharest_dem, river = river) delineate_corridor(network = network, river = river, corridor_init = corridor_init, max_width = 4000, max_iterations = 5, capping_method = "direct")bucharest_osm <- get_osm_example_data() streets <- bucharest_osm$streets railways <- bucharest_osm$railways river <- bucharest_osm$river_centerline # Delineate with default values network <- rbind(streets, railways) |> as_network() delineate_corridor(network = network, river = river) # Delineate with user-specified parameters bucharest_dem <- get_dem_example_data() corridor_init <- delineate_valley(dem = bucharest_dem, river = river) delineate_corridor(network = network, river = river, corridor_init = corridor_init, max_width = 4000, max_iterations = 5, capping_method = "direct")
Delineate the space surrounding a river
delineate_riverspace( river, occluders = NULL, density = 1/50, ray_num = 40, ray_length = 100 )delineate_riverspace( river, occluders = NULL, density = 1/50, ray_num = 40, ray_length = 100 )
river |
List with river surface and centerline |
occluders |
Geometry of occluders |
density |
Density of viewpoints |
ray_num |
Number of rays as numeric vector of length one |
ray_length |
Length of rays in meters as numeric vector of length one |
For riverspace delineation, OSM water polygons intersecting the river centerline are treated as part of the river, including connected water bodies such as lakes and reservoirs. Viewpoints are calculated from water edges where available, and from the river centerline when river surface polygons are missing or partial.
Riverspace as object of class sf::sfc_POLYGON
bucharest_osm <- get_osm_example_data() delineate_riverspace(bucharest_osm$river_surface, bucharest_osm$buildings)bucharest_osm <- get_osm_example_data() delineate_riverspace(bucharest_osm$river_surface, bucharest_osm$buildings)
Segments are defined as corridor subregions separated by river-crossing transversal lines that form continuous strokes in the network.
delineate_segments(corridor, network, river, angle_threshold = 100)delineate_segments(corridor, network, river, angle_threshold = 100)
corridor |
The river corridor as a simple feature geometry of class
|
network |
The spatial network of class |
river |
The river centerline as a simple feature geometry of class
|
angle_threshold |
Only consider angles above this threshold (in degrees)
to form continuous strokes in the network. The value can range between
0 and 180, with the default set to 100. See |
Segment polygons as a simple feature geometry of class
sf::sfc_POLYGON
bucharest_osm <- get_osm_example_data() corridor <- bucharest_dambovita$corridor network <- rbind(bucharest_osm$streets, bucharest_osm$railways) |> as_network() river <- bucharest_osm$river_centerline delineate_segments(corridor, network, river)bucharest_osm <- get_osm_example_data() corridor <- bucharest_dambovita$corridor network <- rbind(bucharest_osm$streets, bucharest_osm$railways) |> as_network() river <- bucharest_osm$river_centerline delineate_segments(corridor, network, river)
The slope of the digital elevation model (DEM) is used as friction (cost) surface to compute the cost distance from any grid cell of the raster to the river. A characteristic value (default: the mean) of the cost distance distribution in a region surrounding the river (default: a buffer region of 2 km) is then calculated, and used to threshold the cost-distance surface. The resulting area is then "polygonized" to obtain the valley boundary as a simple feature geometry.
delineate_valley(dem, river)delineate_valley(dem, river)
dem |
|
river |
River valley as a simple feature geometry of class sfc_MULTIPOLYGON
bucharest_osm <- get_osm_example_data() bucharest_dem <- get_dem_example_data() delineate_valley(bucharest_dem, bucharest_osm$river_centerline)bucharest_osm <- get_osm_example_data() bucharest_dem <- get_dem_example_data() delineate_valley(bucharest_dem, bucharest_osm$river_centerline)
An S3 class representing the result of a delineation as returned by
delineate().
An object of class delineation containing zero or more of the
spatial layers $valley, $corridor, $segments, and $riverspace
(each an sf::sfc_POLYGON or sf::sfc_MULTIPOLYGON object), plus
the base OSM and optionally DEM layers and an $aoi list with the
delineation parameters produced by define_aoi(). See delineate() for
details.
bd <- delineate_city_river("Bucharest", "Dâmbovița") class(bd)bd <- delineate_city_river("Bucharest", "Dâmbovița") class(bd)
All crossing edges are identified, and the points of intersections are
injected within the edge geometries. Note that the injected points are
not converted to network nodes (this can be achieved via sfnetworks'
sfnetworks::to_spatial_subdivision(), which is part of the tasks
that are included in clean_network().
flatten_network(network)flatten_network(network)
network |
A network object of class |
The functionality is similar to sfnetworks'
sfnetworks::st_network_blend(), but in that case an external point is
only injected to the closest edge.
An sfnetworks::sfnetwork object with additional points at
intersections
bucharest_osm <- get_osm_example_data() edges <- dplyr::bind_rows(bucharest_osm$streets, bucharest_osm$railways) network <- sfnetworks::as_sfnetwork(edges, directed = FALSE) flatten_network(network)bucharest_osm <- get_osm_example_data() edges <- dplyr::bind_rows(bucharest_osm$streets, bucharest_osm$railways) network <- sfnetworks::as_sfnetwork(edges, directed = FALSE) flatten_network(network)
Creates a list of ggplot2::geom_sf() layers representing the delineation
results of a delineation object. The list can be added to a
ggplot2::ggplot() object with +, and further layers or themes can be
added on top. Base layers (streets, railways, river_centerline,
river_surface) are not included and can be added separately with
ggplot2::geom_sf().
geom_delineation(x, extent = "corridor", legend = TRUE)geom_delineation(x, extent = "corridor", legend = TRUE)
x |
An object of class delineation. This is typically the output
of the |
extent |
The delineation layer whose bounding box sets the plot extent.
One of |
legend |
Whether the plot should display a legend. Default is TRUE. |
The following layers are included (where present in x), in the following
order:
corridor or riverspace (only when corridor is absent):
drawn first to set the plot extent
valley: light grey, transparent fill, no outlines
segments: outlined polygons
corridor: outlined polygon
A list of ggplot2::geom_sf() and ggplot2::coord_sf() elements
to be added to a ggplot2::ggplot() object.
plot.delineation() for a base R alternative.
library(ggplot2) bd <- delineate_city_river("Bucharest", "Dâmbovița") ggplot() + geom_delineation(bd) + theme_void() ggplot() + geom_delineation(bd, extent = "valley") + theme_void()library(ggplot2) bd <- delineate_city_river("Bucharest", "Dâmbovița") ggplot() + geom_delineation(bd) + theme_void() ggplot() + geom_delineation(bd, extent = "valley") + theme_void()
Access digital elevation model (DEM) for a given region
get_dem( aoi, osm, dem_source = "STAC", stac_endpoint = NULL, stac_collection = NULL, force_download = FALSE )get_dem( aoi, osm, dem_source = "STAC", stac_endpoint = NULL, stac_collection = NULL, force_download = FALSE )
aoi |
A list of delineation parameters, including |
osm |
A list with OpenStreetMap data sets for the a location, as
objects of class |
dem_source |
Source of the DEM:
|
stac_endpoint |
URL of the STAC API endpoint (only used if |
stac_collection |
Identifier of the STAC collection to be queried (only
used if |
force_download |
Download data even if cached data is available |
DEM as a terra SpatRaster object
# Define delineation parameters and get OSM data within area of interest aoi <- define_aoi("Bucharest", "Dâmbovița") osm <- get_osm(aoi) # Get DEM with default values dem <- get_dem(aoi, osm) # Get DEM from custom STAC endpoint get_dem(aoi, osm, stac_endpoint = "some endpoint", stac_collection = "some collection") # Specify CRS get_dem(bb, crs = crs)# Define delineation parameters and get OSM data within area of interest aoi <- define_aoi("Bucharest", "Dâmbovița") osm <- get_osm(aoi) # Get DEM with default values dem <- get_dem(aoi, osm) # Get DEM from custom STAC endpoint get_dem(aoi, osm, stac_endpoint = "some endpoint", stac_collection = "some collection") # Specify CRS get_dem(bb, crs = crs)
This function retrieves example Digital Elevation Model (DEM) data from the Zenodo data repository, and it can be used in examples and tests. The code used to generate the example dataset is available at https://github.com/CityRiverSpaces/CRiSpExampleData. Note that the example dataset is cached locally, so that subsequent calls to the function can load the example data from disk without having to re-download the data.
get_dem_example_data(force_download = FALSE)get_dem_example_data(force_download = FALSE)
force_download |
Download data even if cached data is available |
An object of class terra::SpatRaster containing the DEM data.
get_dem_example_data(force_download = TRUE)get_dem_example_data(force_download = TRUE)
Retrieve OpenStreetMap data for a given location, including the city boundary, the river centreline and surface, the streets, the railways, and the buildings
get_osm( aoi, city_boundary = TRUE, network = TRUE, buildings = TRUE, force_download = FALSE )get_osm( aoi, city_boundary = TRUE, network = TRUE, buildings = TRUE, force_download = FALSE )
aoi |
A list of delineation parameters |
city_boundary |
A logical indicating if the city boundary should be retrieved. Default is TRUE. |
network |
A logical indicating if the spatial network should be retrieved. Default is TRUE. |
buildings |
A logical indicating if buildings should be retrieved. Default is TRUE. |
force_download |
Download data even if cached data is available |
A list with the retrieved OpenStreetMap data sets for the
given location, as objects of class sf::sfc
# Set parameters city <- "Bucharest" river <- "Dâmbovița" # Define AOI parameters aoi <- define_aoi(city, river) # Get OSM data with defaults get_osm(aoi) # Get OSM data without city boundary get_osm(aoi, city_boundary = FALSE) # Use custom network buffer to get streets and railways aoi2 <- aoi aoi2$network_buffer = 3500 get_osm(aoi2) # Use custom buffer to get buildings aoi3 <- aoi aoi3$buildings_buffer = 150 get_osm(aoi3) # Use custom CRS aoi4 <- aoi aoi4$crs <- "EPSG:31600" get_osm(aoi4) # Avoid getting OSM data from cache get_osm(city_name = city, river_name = river, force_download = TRUE)# Set parameters city <- "Bucharest" river <- "Dâmbovița" # Define AOI parameters aoi <- define_aoi(city, river) # Get OSM data with defaults get_osm(aoi) # Get OSM data without city boundary get_osm(aoi, city_boundary = FALSE) # Use custom network buffer to get streets and railways aoi2 <- aoi aoi2$network_buffer = 3500 get_osm(aoi2) # Use custom buffer to get buildings aoi3 <- aoi aoi3$buildings_buffer = 150 get_osm(aoi3) # Use custom CRS aoi4 <- aoi aoi4$crs <- "EPSG:31600" get_osm(aoi4) # Avoid getting OSM data from cache get_osm(city_name = city, river_name = river, force_download = TRUE)
Get the bounding box of a city
get_osm_bb(city_name)get_osm_bb(city_name)
city_name |
A character vector of length one |
A bbox object with the bounding box of the city
get_osm_bb(city_name = "Bucharest")get_osm_bb(city_name = "Bucharest")
Get buildings from OpenStreetMap within a given buffer around a river.
get_osm_buildings(aoi, crs = NULL, force_download = FALSE)get_osm_buildings(aoi, crs = NULL, force_download = FALSE)
aoi |
Area of interest as sf object or bbox |
crs |
Coordinate reference system as EPSG code |
force_download |
Download data even if cached data is available |
An object of class sf::sfc_POLYGON
bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_buildings(aoi = bb, crs = crs)bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_buildings(aoi = bb, crs = crs)
This function retrieves the city boundary from OpenStreetMap based on a bounding box with the OSM tags "place:city" and "boundary:administrative". The result is filtered by the city name.
get_osm_city_boundary( bb, city_name, crs = NULL, multiple = FALSE, force_download = FALSE )get_osm_city_boundary( bb, city_name, crs = NULL, multiple = FALSE, force_download = FALSE )
bb |
Bounding box of class |
city_name |
A case-sensitive character vector of length 1 with the name of the city |
crs |
Coordinate reference system as EPSG code |
multiple |
A logical indicating if multiple city boundaries should be returned. By default, only the first one is returned. |
force_download |
Download data even if cached data is available |
An object of class sf::sfc_POLYGON or sf::sfc_MULTIPOLYGON
with the city boundary
bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_city_boundary(bb = bb, city_name = "Bucharest", crs = crs)bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_city_boundary(bb = bb, city_name = "Bucharest", crs = crs)
This function retrieves example OpenStreetMap (OSM) data from the Zenodo data repository, and it can be used in examples and tests. The code used to generate the example dataset is available at https://github.com/CityRiverSpaces/CRiSpExampleData. Note that the example dataset is cached locally, so that subsequent calls to the function can load the example data from disk without having to re-download the data.
get_osm_example_data(force_download = FALSE)get_osm_example_data(force_download = FALSE)
force_download |
Download data even if cached data is available |
A list of sf objects containing the OSM data as sf::sfc
objects.
get_osm_example_data(force_download = TRUE)get_osm_example_data(force_download = TRUE)
Get OpenStreetMap railways
get_osm_railways( aoi, crs = NULL, railway_values = "rail", force_download = FALSE )get_osm_railways( aoi, crs = NULL, railway_values = "rail", force_download = FALSE )
aoi |
Area of interest as sf object or bbox |
crs |
A numeric vector of length one with the EPSG code of the CRS |
railway_values |
A case-insensitive character vector with the railway values to retrieve. |
force_download |
Download data even if cached data is available |
An object of class sf::sfc_LINESTRING
bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_railways(aoi = bb, crs = crs)bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_railways(aoi = bb, crs = crs)
Get the river centreline from OpenStreetMap
get_osm_river_centerline( bb, river_name, crs = NULL, buffer_distance = NULL, force_download = FALSE )get_osm_river_centerline( bb, river_name, crs = NULL, buffer_distance = NULL, force_download = FALSE )
bb |
Bounding box of class |
river_name |
The name of the river as character vector of length 1, case-sensitive. |
crs |
Coordinate reference system as EPSG code |
buffer_distance |
Optional buffer distance in metres to expand the
bounding box before cropping the river centreline. Useful when downstream
processing (e.g. network or DEM analysis) extends beyond the original |
force_download |
Download data even if cached data is available |
The river centreline as object of class sf::sfc_LINESTRING or
sf::sfc_MULTILINESTRING.
bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_river_centerline(bb = bb, river_name = "Dâmbovița", crs = crs, force_download = FALSE)bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) get_osm_river_centerline(bb = bb, river_name = "Dâmbovița", crs = crs, force_download = FALSE)
Get the river surface from OpenStreetMap
get_osm_river_surface(bb, river_centerline, crs = NULL, force_download = FALSE)get_osm_river_surface(bb, river_centerline, crs = NULL, force_download = FALSE)
bb |
Bounding box of class |
river_centerline |
The river centerline as an object of class
|
crs |
Coordinate reference system as EPSG code |
force_download |
Download data even if cached data is available |
The river surface as object of class sf::sfc_POLYGON or
sf::sfc_MULTIPOLYGON.
bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) river <- get_osm_river_centerline(bb, "Dâmbovița") get_osm_river_surface(bb = bb, river_centerline = river, crs = crs, force_download = FALSE)bb <- get_osm_bb("Bucharest") crs <- get_utm_zone(bb) river <- get_osm_river_centerline(bb, "Dâmbovița") get_osm_river_surface(bb = bb, river_centerline = river, crs = crs, force_download = FALSE)
Get OpenStreetMap streets
get_osm_streets(aoi, crs = NULL, highway_values = NULL, force_download = FALSE)get_osm_streets(aoi, crs = NULL, highway_values = NULL, force_download = FALSE)
aoi |
Area of interest as sf object or bbox. Required, no default. |
crs |
A numeric vector of length one with the EPSG code of the CRS |
highway_values |
A character vector with the highway values to retrieve. If left NULL, the function retrieves the following values: "motorway", "trunk", "primary", "secondary", "tertiary" |
force_download |
Download data even if cached data is available |
An object of class sf::sfc_LINESTRING
# Set parameters bb <- get_osm_bb("Bucharest") crs <- 31600 # National projected CRS # Get streets with default values get_osm_streets(aoi = bb, crs = crs) # Specify street categories to be retrieved get_osm_streets(aoi = bb, crs = crs, highway_values = "primary") # Ensure that data is not retrieved from cache get_osm_streets(aoi = bb, crs = crs, force_download = FALSE)# Set parameters bb <- get_osm_bb("Bucharest") crs <- 31600 # National projected CRS # Get streets with default values get_osm_streets(aoi = bb, crs = crs) # Specify street categories to be retrieved get_osm_streets(aoi = bb, crs = crs, highway_values = "primary") # Ensure that data is not retrieved from cache get_osm_streets(aoi = bb, crs = crs, force_download = FALSE)
Get an area of interest (AoI) around a river, cropping to the bounding box of a city
get_river_aoi(river, city_bbox, buffer_distance)get_river_aoi(river, city_bbox, buffer_distance)
river |
A |
city_bbox |
Bounding box of class |
buffer_distance |
A positive number representing the buffer size around the river in meters. The upper limit is unrestricted. |
An sf::sfc_POLYGON object in lat/lon coordinates
bb <- get_osm_bb("Bucharest") river_centerline <- get_osm_river_centerline(bb, "Dâmbovița") river_surface <- get_osm_river_surface(bb, "Dâmbovița") river <- list(centerline = river_centerline, surface = river_surface) get_river_aoi(river = river, city_bbox = bb, buffer_distance = 100)bb <- get_osm_bb("Bucharest") river_centerline <- get_osm_river_centerline(bb, "Dâmbovița") river_surface <- get_osm_river_surface(bb, "Dâmbovița") river <- list(centerline = river_centerline, surface = river_surface) get_river_aoi(river = river, city_bbox = bb, buffer_distance = 100)
Retrieve the URLs of all the assets intersecting a bbox from a STAC API
get_stac_asset_urls(bb, endpoint = NULL, collection = NULL)get_stac_asset_urls(bb, endpoint = NULL, collection = NULL)
bb |
A bounding box, provided either as a matrix (rows for "x", "y",
columns for "min", "max") or as a vector ("xmin", "ymin", "xmax", "ymax"),
in lat/lon coordinates (WGS84 coordinate referece system) of class |
endpoint |
URL of the STAC API endpoint. To be provided together with
|
collection |
Identifier of the STAC collection to be queried. To be
provided together with |
A list of URLs for the assets in the collection overlapping with the specified bounding box
bb <- get_osm_bb("Bucharest") get_stac_asset_urls(bb) # Use non-default STAC API get_stac_asset_urls(bb, endpoint = "some endpoint", collection = "some collection")bb <- get_osm_bb("Bucharest") get_stac_asset_urls(bb) # Use non-default STAC API get_stac_asset_urls(bb, endpoint = "some endpoint", collection = "some collection")
Get the UTM zone of a spatial object
get_utm_zone(x)get_utm_zone(x)
x |
Object in any class accepted by |
The EPSG code of the UTM zone
# Get EPSG code for UTM zone of Bucharest bb <- c(xmin = 25.97, ymin = 44.33, xmax = 26.23, ymax = 44.54) get_utm_zone(bb)# Get EPSG code for UTM zone of Bucharest bb <- c(xmin = 25.97, ymin = 44.33, xmax = 26.23, ymax = 44.54) get_utm_zone(bb)
Load DEM data from a list of tiles, crop and merge using a given bounding box to create a raster DEM for the specified region. Results are cached, so that new queries with the same input parameters will be loaded from disk.
load_dem(bb, tile_urls, force_download = FALSE)load_dem(bb, tile_urls, force_download = FALSE)
bb |
A bounding box, provided either as a matrix (rows for "x", "y",
columns for "min", "max") or as a vector ("xmin", "ymin", "xmax", "ymax")
of class |
tile_urls |
A list of tiles where to read the DEM data from |
force_download |
Download data even if cached data is available |
A DEM of class terra::SpatRaster, retrieved and retiled to the
given bounding box
bb <- get_osm_bb("Bucharest") tile_urls <- get_stac_asset_urls(bb) load_dem(bb = bb, tile_urls = tile_urls, force_download = TRUE)bb <- get_osm_bb("Bucharest") tile_urls <- get_stac_asset_urls(bb) load_dem(bb = bb, tile_urls = tile_urls, force_download = TRUE)
Query the Overpass API for a key:value pair within a given bounding box (provided as lat/lon coordiates). Results are cached, so that new queries with the same input parameters will be loaded from disk.
osmdata_as_sf(key, value, aoi, force_download = FALSE)osmdata_as_sf(key, value, aoi, force_download = FALSE)
key |
A case-insensitive character vector of length 1 with the key to filter the data |
value |
A case-insensitive character vector with the value(s) to filter the data |
aoi |
An area of interest, provided either as as sf object or "bbox" or as a vector ("xmin", "ymin", "xmax", "ymax") |
force_download |
Download data even if cached data is available |
An osmdata::osmdata object with the retrieved OpenStreetMap data
bb <- get_osm_bb("Bucharest") osmdata_as_sf(key = "highway", value = "motorway", aoi = bb, force_download = FALSE)bb <- get_osm_bb("Bucharest") osmdata_as_sf(key = "highway", value = "motorway", aoi = bb, force_download = FALSE)
This S3 method provides a way to quickly visualise how the layers of a
delineation object fit together using base R graphics. A delineation object
typically includes the base layers streets, railways,
river_centerline and river_surface, and the delineations of the
valley, corridor, segments, and riverspace. Depending on the
delineation object, some of the delineation layers may not be present and
thus will not be plotted.
## S3 method for class 'delineation' plot(x, ..., legend = TRUE)## S3 method for class 'delineation' plot(x, ..., legend = TRUE)
x |
An object of class delineation, which is typically the output of
the |
... |
Not used; included for compatibility with the generic. |
legend |
logical. If TRUE (default), a legend is added to the plot. |
NULL, invisibly. This function is called for its side effect of
producing a plot.
geom_delineation() for a ggplot2-based alternative.
bd <- delineate_city_river("Bucharest", "Dâmbovița") plot(bd)bd <- delineate_city_river("Bucharest", "Dâmbovița") plot(bd)
Prints a compact summary of a delineation object, showing which layers are present and their feature counts.
## S3 method for class 'delineation' print(x, ...)## S3 method for class 'delineation' print(x, ...)
x |
An object of class delineation. |
... |
Not used; included for compatibility with the generic. |
x, invisibly.
bd <- delineate_city_river("Bucharest", "Dâmbovița") print(bd)bd <- delineate_city_river("Bucharest", "Dâmbovița") print(bd)
Print a summary.delineation object
## S3 method for class 'summary.delineation' print(x, ...)## S3 method for class 'summary.delineation' print(x, ...)
x |
An object of class |
... |
Not used; included for compatibility with the generic. |
x, invisibly.
bd <- delineate_city_river("Bucharest", "Dâmbovița") s <- summary(bd) print(s)bd <- delineate_city_river("Bucharest", "Dâmbovița") s <- summary(bd) print(s)
Reproject a raster or vector dataset to the specified coordinate reference system (CRS)
reproject(x, crs, ...)reproject(x, crs, ...)
x |
Raster ( |
crs |
CRS to be projected to, provided as |
... |
Optional arguments for raster or vector reproject functions |
sf::sf, sf::sfc, or terra::SpatRaster object reprojected
to specified CRS
# Reproject a raster to EPSG:4326 r <- terra::rast(matrix(1:12, nrow = 3, ncol = 4), crs = "EPSG:32633") reproject(r, 4326)# Reproject a raster to EPSG:4326 r <- terra::rast(matrix(1:12, nrow = 3, ncol = 4), crs = "EPSG:32633") reproject(r, 4326)
Computes summary statistics for a delineation object and returns them as
a structured list of class summary.delineation. Delineation layers are
reported with their area (in km²). For segments, the number of features
and mean area are also given. Base layers are reported with feature counts;
river_centerline as total length (in km) and river_surface as area
(in km²).
## S3 method for class 'delineation' summary(object, ...)## S3 method for class 'delineation' summary(object, ...)
object |
An object of class |
... |
Not used; included for compatibility with the generic. |
An object of class summary.delineation, which is a named list
with elements city_name, river_name, crs, parameters,
delineation_layers, and base_layers. parameters contains
network_buffer, dem_buffer, and buildings_buffer (in metres), or
NULL if no aoi was stored. Each layer entry is itself a named list
of stats, or NULL if the layer is absent.
bd <- delineate_city_river("Bucharest", "Dâmbovița") s <- summary(bd) s$delineation_layers$corridor$area_km2bd <- delineate_city_river("Bucharest", "Dâmbovița") s <- summary(bd) s$delineation_layers$corridor$area_km2