# Get started

The flexpolyline R package provides a binding to the C++ implementation of the flexible polyline encoding by HERE. The flexible polyline encoding is a lossy compressed representation of a list of coordinate pairs or coordinate triples.

The encoding is achieved by:

1. Reducing the decimal digits of each value;
2. encoding only the offset from the previous point;
3. using variable length for each coordinate delta; and
4. using 64 URL-safe characters to display the result. The felxible polyline encoding is a variant of the Encoded Polyline Algorithm Format by Google.

Note:

- Decoding gives reliable results up to a precision of 7 digits. The tests are also limited to this range.
- The order of the coordinates (lng, lat) does not correspond to the original C++ implementation (lat, lng). This enables simple conversion to `sf` objects, without reordering the columns.
- The encoding is lossy, this means the encoding process could reduce the precision of your data.

## Installation

You can install the released version of flexpolyline from CRAN with:

    install.packages("flexpolyline")

Install the development version from GitHub with:

    remotes::install_github("munterfi/flexpolyline")

## C++ binding

Encoding and decoding in R is straight forward by using `encode()` and `decode()`. These functions are binding to the flexpolyline C++ implementation and have similar arguments and return values as their counterparts (`hf::encode_polyline` and `hf::decode_polyline`):

    library(flexpolyline)

    (line <- matrix(
      c(8.69821, 50.10228, 10,
        8.69567, 50.10201, 20,
        8.69150, 50.10063, 30,
        8.68752, 50.09878, 40),
      ncol = 3, byrow = TRUE
    ))
    #>         [,1]     [,2] [,3]
    #> [1,] 8.69821 50.10228   10
    #> [2,] 8.69567 50.10201   20
    #> [3,] 8.69150 50.10063   30
    #> [4,] 8.68752 50.09878   40

    (encoded <- encode(line))
    #> [1] "B1Voz5xJ67i1Bgkh9B1B7Pgkh9BzIhagkh9BxL7Ygkh9B"

    (decoded <- decode(encoded))
    #>          LNG      LAT ELEVATION
    #> [1,] 8.69821 50.10228        10
    #> [2,] 8.69567 50.10201        20
    #> [3,] 8.69150 50.10063        30
    #> [4,] 8.68752 50.09878        40

## Simple feature support

A common way to deal with spatial data in R is the sf package, which is built on the concept of simple features. The functions `encode_sf()` and `decode_sf()` provide an interface that support the encoding of sf objects:

    (sfg <- sf::st_linestring(line, dim = "XYZ"))
    #> LINESTRING Z (8.69821 50.10228 10, 8.69567 50.10201 20, 8.6915 50.10063 30, 8.68752 50.09878 40)

    (encoded <- encode_sf(sfg))
    #> [1] "B1Voz5xJ67i1Bgkh9B1B7Pgkh9BzIhagkh9BxL7Ygkh9B"

    (decoded <- decode_sf(encoded))
    #> Simple feature collection with 1 feature and 2 fields
    #> Geometry type: LINESTRING
    #> Dimension:     XYZ
    #> Bounding box:  xmin: 8.68752 ymin: 50.09878 xmax: 8.69821 ymax: 50.10228
    #> z_range:       zmin: 10 zmax: 40
    #> CRS:           NA
    #>   id      dim3                       geometry
    #> 1  1 ELEVATION LINESTRING Z (8.69821 50.10...

## References

- Flexible Polyline Encoding by HERE
- Encoded Polyline Algorithm Format
- Simple Features for R
- Inspired by the googlePolylines package