ORS-based sampling

Sample point geometries within the boundaries of the running ORS extract. This function works by reading in the mounted extract file and can thus only be run with a local instance.

Usage

ors_sample(
  size,
  ...,
  force = FALSE,
  instance = NULL,
  poly = NULL,
  verbose = TRUE
)

get_extract_boundaries(instance = NULL, force = FALSE, verbose = TRUE)

Arguments

size

[integer]

Number of points to be sampled.

...

Passed to st_sample.

force

[logical]

If TRUE, forces the cached extract geometries to be overwritten. Defaults to FALSE to increase speed. Set this to TRUE if the extract has changed and a new one needs to be loaded.

instance

[ors_instance]

Object of an OpenRouteService instance that should be used for route computations. It is recommended to use ors_instance to set an instance globally. This argument should only be used if activating an instance globally is not feasible.

poly

[sf/sfc]

Boundary polygon used to sample points. If NULL, the default, boundary polygons are extracted from the current instance as set by ors_instance.

verbose

[logical]

If TRUE, prints a loading spinner.

Value

ors_sample returns an sfc object containing the sampled POINT geometries. get_extract_boundaries returns an sfc object of the currently mounted extract boundaries.

Details

The function vectortranslates the extract file to an sf object. Depending on the file, this can take a while. The unionized boundaries are then cached making subsequent function calls a lot faster.

If instance is not local, it is more difficult to derive the extract boundaries. There is thus far no way of accessing an OSM extract file knowing only the server address. We can, however, make use of some heuristics: ors_export can export the built graphs from an ORS server if it allows it. However, it does not work on the public API and it requires knowledge about the approximate area of an extract. ors_guess can make an approximation of an extract area. It accesses the snap endpoint which also does not work on the public API and needs to be enabled on other servers. ors_guess can make a lot of requests and might not be feasible in many situations.

Caching

The following functions make use of a runtime caching system: ors_ready(), ors_status(), get_profiles(), get_extract_boundaries(), ors_sample(). This means that, if force = FALSE, previously generated output is re-used instead of sending new requests. This can be particularly useful in automated workflows like loops where speed is important. When run directly, caching should not be necessary, which is why force = FALSE is the default of most of these functions (except get_extract_boundaries() because it deals with potentially much larger amounts of data).

"Runtime" in this context refers to the runtime of an ORS instance, i.e. the time after it is started. Cached results should only be valid for a specific runtime and discarded afterwards. When mounting a new instance different from the one mounted before, the runtime cache is cleared so that fresh requests must be made.

Examples

if (FALSE) { # \dontrun{
# ORS sampling only works with a local instance
monaco <- system.file("setup/monaco.pbf", package = "rors")
ors <- ors_instance()
ors$set_extract(file = monaco)
ors$up()

# reads in boundaries of monaco pbf file
bounds <- get_extract_boundaries()
plot(bounds)

# subsequent calls do not need to read the pbf file
ors_sample(5)

# ... except when they are forced to
ors_sample(force = TRUE)
} # }