# OsmShortlink

This library allowes to generate short links to any geo coordinates. The longer the link the more precisce we can specify our desired position Description I based it on the erlang implementation and converted it to elixir, then refactored to be more readable and added a reverse function

## How it works:

http://osm.org/go/0EEQjE12 is a valid url, so is http://osm.org/go/0EE with removed 5 letteras, is still valid and pointing to the same area just less precise

`x = trunc((lng + 180) / 360 * (1 <<< 32)`

this line makes the number positive in the range between 0..1 and then casts it to 32 bit integer (1 <<< 32 is just a fancy way of calculation 2^32)

having the coordinates as 32 bit indeger can be easily manipulated with binary functions and its fast the most important stuff here is that the oldest bits are the more importnat ones - even if we remove half of the young ones we wont loose lots of accuracy imagine we have a starting number of 5.4321

```
(5.4321 + 180) /360 * 2^32 =
185.4321 / 360 * 2^32 =
2212291125
10000011_11011100_11100010_00110101
```

this now gets saved send somewhere and we are loosing second half of the information:

```
10000011_11011100_00000000_00000000 converted to int
2212233216
```

now lets reverse the calculation:

```
2212233216 / 2 ^ 32
0.51507568359 * 360 - 180
5.427246094
```

we lost 50% of the information but are only

`0.00485390625 degree away - thats around 300-500m accuracy`

when we loose 75% of the information

`2197815296 we are on 4.21875 so its still 1.21335 away`

around 80-120km, we can still tell the country and region every bit multiplies the accuracy by 2 so adding here 4 bits up to total of 12bits its (120km / 2^4) = around 10-16 km accuracy - you can tell the city

When we have the latitude and longitude in binary form we "zip" it imagine we have for simplicity 6bit numbers instead of 32:

```
111111
000001
```

then our number that gets encoded is

`101010101011`

it happens in the interleave_bits function by pattern matching on every bit:

```
def interleave_bits(
<<a1::1, a2::1, a3::1, a4::1, a5::1, a6::1>>,
<<b1::1, b2::1, b3::1, b4::1, b5::1, b6::1>>
), do: <<a1::1, b1::1, a2::1, b2::1, a3::1, b3::1, a4::1, b4::1, a5::1, b5::1, a6::1, b6::1>>
```

this is pretty straight forward we just take one bit from a then one from b then again one from a and so on

in 64 we can fit 6 bits so now we chunking our binary and encode it - it would look like

`101010101010 >>> (58 - 6 * zoom_var) &&& 63`

on every iteration of this function we take the 6 oldest bits and cast it to char our magic number here is 63 which is 11111111bin &&& is binary AND: it just resets all the bits that are 0 to 0 and keeps the ones that are 1 on both

```
101010101011 >>> (12 - 6 * 0) &&& 63
101010101011 >>> 6 &&& 63
101010101011 &&& 1111111 = 101011
```

on next iteration shift by 6 bits

```
101010101011 >>> (12 - 6 * 1) &&& 63
000000101010 &&& 1111111 = 101010
```

last thing we do here is a custom base64 encode function that does not use + and / these cant be used in urls

```
@chars "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_~"
101010bin is 42dec and its the letter q, 43 is r
so our custom url is `/rq`
```

when reversing ist the same:

we search for our letters and get back rq which is 43 42 - 101010101011 binary

then we need to run a recursive function that takes the first 2 bits and add it to the end of 2 bitwords then takes next to bits adding it again to the end of the word - shifting our bits to the front - this way the bist in front are the most omportant ones

```
101010101011
1010101011 1 0
10101011 11 00
101011 111 000
1011 1111 0000
11 11111 00000
111111 000001
```

we need a 32 bit words here to our function checks the lenght and if its not 32 bit then adds 0 to the end

`11111100000000000000000000000000 0000010000000000000000000000000`

these now got converted to integers and then back to our coordinates

## Installation

If available in Hex, the package can be installed
by adding `osm_shortlink`

to your list of dependencies in `mix.exs`

:

```
def deps do
[
{:osm_shortlink, "~> 0.1.0"}
]
end
```

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/osm_shortlink.