---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The **flexpolyline** R package provides a binding to the
[C++ implementation](https://github.com/heremaps/flexible-polyline/tree/master/cpp) of the
flexible polyline encoding by [HERE](https://github.com/heremaps/flexible-polyline).
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 flexible polyline encoding is a variant of the [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) by Google.

**Note:**

- The order of the coordinates (lng, lat) does not correspond to the original
  C++ implementation (lat, lng). This enables direct 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

Install the released version of **flexpolyline** from [CRAN](https://CRAN.R-project.org/package=flexpolyline):

```r
install.packages("flexpolyline")
```

To install the development version from [GitHub](https://github.com/munterfi/flexpolyline):

```r
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 reflect the arguments and return values of their counterparts
(`hf::flexpolyline::polyline_encode` and `hf::flexpolyline::polyline_decode`):

```r
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
)

encode(line)

decode("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU")
```

## Simple feature support

The **flexpolyline** package integrates with the popular
[sf](https://CRAN.R-project.org/package=sf) package for working with spatial
data in R, which is built on the concept of simple features. The package
provides additional functions for encoding and decoding sf objects directly:

```r
sfg <- sf::st_linestring(line, dim = "XYZ")

encode_sf(sfg)

decode_sf("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU")
```

## References

- [Flexible Polyline Encoding by HERE](https://github.com/heremaps/flexible-polyline)
- [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
- [Simple Features for R](https://CRAN.R-project.org/package=sf)
- Inspired by the [googlePolylines](https://github.com/SymbolixAU/googlePolylines) package