|
1 | | - |
2 | | -# Flexible Polyline Encoding for R <img src="man/figures/logo.png" align="right" alt="" width="120" /> |
3 | | - |
4 | | -<!-- badges: start --> |
5 | | -[](https://CRAN.R-project.org/package=flexpolyline) |
6 | | -[](https://cran.r-project.org/web/checks/check_results_flexpolyline.html) |
7 | | -[](https://CRAN.R-project.org/package=flexpolyline) |
8 | | -[](https://github.com/munterfi/flexpolyline/actions) |
9 | | -[](https://codecov.io/gh/munterfi/flexpolyline?branch=master) |
10 | | -[](https://www.codefactor.io/repository/github/munterfi/flexpolyline) |
11 | | -<!-- badges: end --> |
12 | | - |
13 | | -The **flexpolyline** R package provides a binding to the |
14 | | -[C++ implementation](https://github.com/heremaps/flexible-polyline/tree/master/cpp) of the |
15 | | -flexible polyline encoding by [HERE](https://github.com/heremaps/flexible-polyline). |
16 | | -The flexible polyline encoding is a lossy compressed representation of a list of |
17 | | -coordinate pairs or coordinate triples. The encoding is achieved by: |
18 | | -(1) Reducing the decimal digits of each value; |
19 | | -(2) encoding only the offset from the previous point; |
20 | | -(3) using variable length for each coordinate delta; and |
21 | | -(4) using 64 URL-safe characters to display the result. |
22 | | -The flexible polyline encoding is a variant of the [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) by Google. |
23 | | - |
24 | | -**Note:** |
25 | | - |
26 | | -* 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. |
27 | | -* The encoding is lossy, this means the encoding process could reduce the precision of your data. |
28 | | - |
29 | | -## Installation |
30 | | - |
31 | | -Install the released version of **flexpolyline** from [CRAN](https://CRAN.R-project.org/package=flexpolyline): |
32 | | - |
33 | | -``` r |
34 | | -install.packages("flexpolyline") |
35 | | -``` |
36 | | - |
37 | | -Or get the development version from [GitHub](https://github.com/munterfi/flexpolyline): |
38 | | - |
39 | | -``` r |
40 | | -remotes::install_github("munterfi/flexpolyline") |
41 | | -``` |
42 | | - |
43 | | -## C++ binding |
44 | | - |
45 | | -Encoding and decoding in R is straight forward by using `encode()` and `decode()`. |
46 | | -These functions are binding to the flexpolyline C++ implementation and reflect the arguments and return values of their counterparts (`hf::encode_polyline` and `hf::decode_polyline`): |
47 | | - |
48 | | -``` r |
49 | | -line <- matrix( |
50 | | - c(8.69821, 50.10228, 10, |
51 | | - 8.69567, 50.10201, 20, |
52 | | - 8.69150, 50.10063, 30, |
53 | | - 8.68752, 50.09878, 40), |
54 | | - ncol = 3, byrow = TRUE |
55 | | -) |
56 | | - |
57 | | -encode(line) |
58 | | - |
59 | | -decode("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU") |
60 | | -``` |
61 | | - |
62 | | -## Simple feature support |
63 | | -A common way to deal with spatial data in R is the |
64 | | -[sf](https://CRAN.R-project.org/package=sf) package, which is |
65 | | -built on the concept of simple features. The functions `encode_sf()` and |
66 | | -`decode_sf()` provide an interface that support the encoding of sf objects: |
67 | | - |
68 | | -``` r |
69 | | -sfg <- sf::st_linestring(line, dim = "XYZ") |
70 | | - |
71 | | -encode_sf(sfg) |
72 | | - |
73 | | -decode_sf("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU") |
74 | | -``` |
75 | | - |
76 | | -## Contributing |
77 | | - |
78 | | -* Contributions to this package are very welcome, issues and pull requests are the preferred ways to share them. Please see the [Contribution Guidelines](https://github.com/munterfi/flexpolyline/blob/master/.github/CONTRIBUTING.md). |
79 | | -* This project is released with a [Contributor Code of Conduct](https://github.com/munterfi/flexpolyline/blob/master/.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. |
80 | | - |
81 | | -## References |
82 | | - |
83 | | -* [Flexible Polyline Encoding by HERE](https://github.com/heremaps/flexible-polyline) |
84 | | -* [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) |
85 | | -* [Simple Features for R](https://CRAN.R-project.org/package=sf) |
86 | | -* Inspired by the [googlePolylines](https://github.com/SymbolixAU/googlePolylines) package |
87 | | - |
88 | | -## License |
89 | | - |
90 | | -* The **flexpolyline** R package is licensed under GNU GPL v3.0. |
91 | | -* The C++ implementation by HERE Europe B.V. is licensed under MIT. |
| 1 | + |
| 2 | +# Flexible Polyline Encoding for R <img src="man/figures/logo.png" align="right" alt="" width="120" /> |
| 3 | + |
| 4 | +<!-- badges: start --> |
| 5 | +[](https://CRAN.R-project.org/package=flexpolyline) |
| 6 | +[](https://cran.r-project.org/web/checks/check_results_flexpolyline.html) |
| 7 | +[](https://CRAN.R-project.org/package=flexpolyline) |
| 8 | +[](https://github.com/munterfi/flexpolyline/actions) |
| 9 | +[](https://app.codecov.io/gh/munterfi/flexpolyline?branch=master) |
| 10 | +[](https://www.codefactor.io/repository/github/munterfi/flexpolyline) |
| 11 | +<!-- badges: end --> |
| 12 | + |
| 13 | +The **flexpolyline** R package provides a binding to the |
| 14 | +[C++ implementation](https://github.com/heremaps/flexible-polyline/tree/master/cpp) of the |
| 15 | +flexible polyline encoding by [HERE](https://github.com/heremaps/flexible-polyline). |
| 16 | +The flexible polyline encoding is a lossy compressed representation of a list of |
| 17 | +coordinate pairs or coordinate triples. The encoding is achieved by: |
| 18 | +(1) Reducing the decimal digits of each value; |
| 19 | +(2) encoding only the offset from the previous point; |
| 20 | +(3) using variable length for each coordinate delta; and |
| 21 | +(4) using 64 URL-safe characters to display the result. |
| 22 | +The flexible polyline encoding is a variant of the [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) by Google. |
| 23 | + |
| 24 | +**Note:** |
| 25 | + |
| 26 | +* 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. |
| 27 | +* The encoding is lossy, this means the encoding process could reduce the precision of your data. |
| 28 | + |
| 29 | +## Installation |
| 30 | + |
| 31 | +Install the released version of **flexpolyline** from [CRAN](https://CRAN.R-project.org/package=flexpolyline): |
| 32 | + |
| 33 | +``` r |
| 34 | +install.packages("flexpolyline") |
| 35 | +``` |
| 36 | + |
| 37 | +Or get the development version from [GitHub](https://github.com/munterfi/flexpolyline): |
| 38 | + |
| 39 | +``` r |
| 40 | +remotes::install_github("munterfi/flexpolyline") |
| 41 | +``` |
| 42 | + |
| 43 | +## C++ binding |
| 44 | + |
| 45 | +Encoding and decoding in R is straight forward by using `encode()` and `decode()`. |
| 46 | +These functions are binding to the flexpolyline C++ implementation and reflect the arguments and return values of their counterparts (`hf::encode_polyline` and `hf::decode_polyline`): |
| 47 | + |
| 48 | +``` r |
| 49 | +line <- matrix( |
| 50 | + c(8.69821, 50.10228, 10, |
| 51 | + 8.69567, 50.10201, 20, |
| 52 | + 8.69150, 50.10063, 30, |
| 53 | + 8.68752, 50.09878, 40), |
| 54 | + ncol = 3, byrow = TRUE |
| 55 | +) |
| 56 | + |
| 57 | +encode(line) |
| 58 | + |
| 59 | +decode("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU") |
| 60 | +``` |
| 61 | + |
| 62 | +## Simple feature support |
| 63 | +A common way to deal with spatial data in R is the |
| 64 | +[sf](https://CRAN.R-project.org/package=sf) package, which is |
| 65 | +built on the concept of simple features. The functions `encode_sf()` and |
| 66 | +`decode_sf()` provide an interface that support the encoding of sf objects: |
| 67 | + |
| 68 | +``` r |
| 69 | +sfg <- sf::st_linestring(line, dim = "XYZ") |
| 70 | + |
| 71 | +encode_sf(sfg) |
| 72 | + |
| 73 | +decode_sf("BlBoz5xJ67i1BU1B7PUzIhaUxL7YU") |
| 74 | +``` |
| 75 | + |
| 76 | +## Contributing |
| 77 | + |
| 78 | +* Contributions to this package are very welcome, issues and pull requests are the preferred ways to share them. Please see the [Contribution Guidelines](https://github.com/munterfi/flexpolyline/blob/master/.github/CONTRIBUTING.md). |
| 79 | +* This project is released with a [Contributor Code of Conduct](https://github.com/munterfi/flexpolyline/blob/master/.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. |
| 80 | + |
| 81 | +## References |
| 82 | + |
| 83 | +* [Flexible Polyline Encoding by HERE](https://github.com/heremaps/flexible-polyline) |
| 84 | +* [Encoded Polyline Algorithm Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) |
| 85 | +* [Simple Features for R](https://CRAN.R-project.org/package=sf) |
| 86 | +* Inspired by the [googlePolylines](https://github.com/SymbolixAU/googlePolylines) package |
| 87 | + |
| 88 | +## License |
| 89 | + |
| 90 | +* The **flexpolyline** R package is licensed under GNU GPL v3.0. |
| 91 | +* The C++ implementation by HERE Europe B.V. is licensed under MIT. |
0 commit comments