C++ binding

The package contains two Rcpp functions, which bind directly to the C++ implementation of the flexible polyline encoding. These functions target a tight interface from C++ to R and reflect the arguments and return values of their counterparts (hf::encode_polyline and hf::decode_polyline) in the C++ implementation.

Encode

Encoding a line is straight forward by passing a matrix (column order is longitude, latitude) with its coordinates to encode(). The default precision value is set to 5. If a matrix with two columns is provided, the third dimension is automatically set to "ABSENT":

library(flexpolyline)

line2d <- matrix(
  c(
    8.69821, 50.10228,
    8.69567, 50.10201,
    8.69150, 50.10063,
    8.68752, 50.09878
  ),
  ncol = 2, byrow = TRUE
)

(encodes2d <- encode(line2d, precision = 5))
#> [1] "BFoz5xJ67i1B1B7PzIhaxL7Y"

If a matrix with three columns is passed, a line with a third dimension is encoded. The type of the third dimension can be passed to the encoding and supports the following selection, that are specified via an integer value via the third_dim argument:

0: ABSENT
1: LEVEL
2: ALTITUDE
3: ELEVATION (default)
4: RESERVED1 (not available)
5: RESERVED2 (not available)
6: CUSTOM1
7: CUSTOM2

By default the precision of the third dimension third_dim_precision is set to the same value as the precision value for the longitude and latitude dimensions.

line3d <- matrix(
  c(
    8.69821, 50.10228, 10.11111,
    8.69567, 50.10201, 20.22222,
    8.69150, 50.10063, 30.33333,
    8.68752, 50.09878, 40.44444
  ),
  ncol = 3, byrow = TRUE
)

(encodes3d <- encode(line3d, precision = 5, third_dim = 3, third_dim_precision = 5))
#> [1] "B1Voz5xJ67i1Bu629B1B7Pu629BzIhau629BxL7Yu629B"

Decode

In order to decode the lines from above, the encoded line string is passed to the decode() function. The function detects from the encoded string if it is a two-dimensional or three-dimensional line:

decode(encodes2d)
#>          LNG      LAT
#> [1,] 8.69821 50.10228
#> [2,] 8.69567 50.10201
#> [3,] 8.69150 50.10063
#> [4,] 8.68752 50.09878

In the case of a three-dimensional line, the third column is named after the name of the third dimension that was chosen during the encoding (in this example "ELEVATION"):

decode(encodes3d)
#>          LNG      LAT ELEVATION
#> [1,] 8.69821 50.10228  10.11111
#> [2,] 8.69567 50.10201  20.22222
#> [3,] 8.69150 50.10063  30.33333
#> [4,] 8.68752 50.09878  40.44444

Encode

Decode

References