oe_read {osmextract}

Read a .pbf or .gpkg object from file or url

Description

This function is used to read a .pbf or .gpkg object from file or URL. It is a wrapper around oe_download(), oe_vectortranslate(), and sf::st_read(), creating an easy way to download, convert, and read a .pbf or .gpkg file. Check the introductory vignette and the help pages of the wrapped function for more details.

Usage

oe_read(
  file_path,
  layer = "lines",
  ...,
  provider = NULL,
  download_directory = oe_download_directory(),
  file_size = NULL,
  force_download = FALSE,
  max_file_size = 5e+08,
  download_only = FALSE,
  skip_vectortranslate = FALSE,
  vectortranslate_options = NULL,
  osmconf_ini = NULL,
  extra_tags = NULL,
  force_vectortranslate = FALSE,
  never_skip_vectortranslate = FALSE,
  boundary = NULL,
  boundary_type = c("spat", "clipsrc"),
  quiet = FALSE
)

Arguments

file_path

A URL or the path to a .pbf or .gpkg file. If a URL, then it must be specified using HTTP/HTTPS protocol.

layer

Which layer should be read in? Typically points, lines (the default), multilinestrings, multipolygons or other_relations. If you specify an ad-hoc query using the argument query (see introductory vignette and examples), then oe_get() and oe_read() will read the layer specified in the query and ignore layer. See also #122.

...

(Named) arguments that will be passed to sf::st_read(), like query, wkt_filter or stringsAsFactors. Check the introductory vignette to understand how to create your own (SQL-like) queries.

provider

Which provider should be used to download the data? Available providers can be found with the following command: oe_providers(). For oe_get() and oe_match(), if place is equal to ⁠ITS Leeds⁠, then provider is set equal to test. This is just for simple examples and internal tests.

download_directory

Where to download the file containing the OSM data? By default this is equal to oe_download_directory(), which is equal to tempdir() and it changes each time you restart R. You can set a persistent download_directory by adding the following to your .Renviron file (e.g. with edit_r_environ function in usethis package): ⁠OSMEXT_DOWNLOAD_DIRECTORY=/path/to/osm/data⁠.

file_size

How big is the file? Optional. NA by default. If it's bigger than max_file_size and the function is run in interactive mode, then an interactive menu is displayed, asking for permission to download the file.

force_download

Should the .osm.pbf file be updated if it has already been downloaded? FALSE by default. This parameter is used to update old .osm.pbf files.

max_file_size

The maximum file size to download without asking in interactive mode. Default: 5e+8, half a gigabyte.

download_only

Boolean. If TRUE, then the function only returns the path where the matched file is stored, instead of reading it. FALSE by default.

skip_vectortranslate

Boolean. If TRUE, then the function skips all vectortranslate operations and it reads (or simply returns the path) of the .osm.pbf file. FALSE by default.

vectortranslate_options

Options passed to the sf::gdal_utils() argument options. Set by default. Check details in the introductory vignette and the help page of oe_vectortranslate().

osmconf_ini

The configuration file. See documentation at gdal.org. Check details in the introductory vignette and the help page of oe_vectortranslate(). Set by default.

extra_tags

Which additional columns, corresponding to OSM tags, should be in the resulting dataset? NULL by default. Check the introductory vignette and the help pages of oe_vectortranslate() and oe_get_keys(). Ignored when osmconf_ini is not NULL.

force_vectortranslate

Boolean. Force the original .pbf file to be translated into a .gpkg file, even if a .gpkg with the same name already exists? FALSE by default. If tags in extra_tags match data in previously translated .gpkg files no translation occurs (see #173 for details). Check the introductory vignette and the help page of oe_vectortranslate().

never_skip_vectortranslate

Boolean. This is used in case the user passed its own .ini file or vectortranslate options (since, in those case, it's too difficult to determine if an existing .gpkg file was generated following the same options.)

boundary

An sf/sfc/bbox object that will be used to create a spatial filter during the vectortranslate operations. The type of filter can be chosen using the argument boundary_type.

boundary_type

A character vector of length 1 specifying the type of spatial filter. The spat filter selects only those features that intersect a given area, while clipsrc also clips the geometries. Check the examples and also here for more details.

quiet

Boolean. If FALSE, the function prints informative messages. Starting from sf version 0.9.6, if quiet is equal to FALSE, then vectortranslate operations will display a progress bar.

Details

The arguments provider, download_directory, file_size, force_download, and max_file_size are ignored if file_path points to an existing .pbf or .gpkg file.

Please note that you cannot add any field to an existing .gpkg file using the argument extra_tags without rerunning the vectortranslate process on the corresponding .pbf file. On the other hand, you can extract some of the tags in other_tags field as new columns. See examples and oe_get_keys() for more details.

Value

An sf object or, when download_only argument equals TRUE, a character vector.

Examples

# Read an existing .pbf file. First we need to copy a .pbf file into a
# temporary directory
its_pbf = file.path(tempdir(), "test_its-example.osm.pbf")
file.copy(
  from = system.file("its-example.osm.pbf", package = "osmextract"),
  to = its_pbf
)
oe_read(its_pbf)

# Read a new layer
oe_read(its_pbf, layer = "points")

# The following example shows how to add new tags
names(oe_read(its_pbf, extra_tags = c("oneway", "ref"), quiet = TRUE))

# Read an existing .gpkg file. This file was created internally by oe_read().
its_gpkg = file.path(tempdir(), "test_its-example.gpkg")
oe_read(its_gpkg)

# You cannot add any new layer to an existing .gpkg file but you can extract
# some of the tags in other_tags. Check oe_get_keys() for more details.
names(oe_read(its_gpkg, extra_tags = c("maxspeed"))) # doesn't work
# Instead, use the query argument
names(oe_read(
  its_gpkg,
  quiet = TRUE,
  query =
  "SELECT *,
  hstore_get_value(other_tags, 'maxspeed') AS maxspeed
  FROM lines
  "
))

# Read from a URL
my_url = "https://github.com/ropensci/osmextract/raw/master/inst/its-example.osm.pbf"
# Please note that if you read from a URL which is not linked to one of the
# supported providers, you need to specify the provider parameter:
## Not run: 
oe_read(my_url, provider = "test", quiet = FALSE)
## End(Not run)

# Remove .pbf and .gpkg files in tempdir
oe_clean(tempdir())