osmextract (version 0.2.1)

oe_read: 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,
  quiet = FALSE
)

Arguments

file_path

A URL or the path of 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.

...

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.)

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.

Value

An sf object.

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.

You cannot add any field or layer to an existing .gpkg file (unless you have the .pbf file and you convert it again with a different configuration), but you can extract some of the tags in other_tags field. Check examples and oe_get_keys() for more details.

Examples

# NOT RUN {
# Read an existing .pbf file. First we need to copy a .pbf file into a
# temporary directory
file.copy(
  from = system.file("its-example.osm.pbf", package = "osmextract"),
  to = file.path(tempdir(), "its-example.osm.pbf")
)
my_pbf = file.path(tempdir(), "its-example.osm.pbf")
oe_read(my_pbf)
oe_read(my_pbf, layer = "points") # Read a new layer
# The following example shows how to add new tags
names(oe_read(my_pbf, extra_tags = c("oneway", "ref"), quiet = FALSE))

# Read an existing .gpkg file. This file was created by oe_read
my_gpkg = file.path(tempdir(), "its-example.gpkg")
oe_read(my_gpkg)
# You cannot add any 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(my_gpkg, extra_tags = c("maxspeed"))) # doesn't work
# Instead, use the query argument
names(oe_read(
  my_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)
# }