Readme & images

README.md

@@ -0,0 +1,112 @@
+# Wikiloc Google Earth layer
+
+
+<p align="center">
+  <img width="300" src="docs/wikiloc-earth-layer.png">
+</p>
+
+<br>
+<p align="center">
+<b>View Wikiloc.com trails in Google Earth.</b>
+</p>
+
+<p align="center">
+Tiny http server written in Go that fetch trails from wikiloc.com to compose KML updates in the Google Earth view area.
+</p>
+
+<br>
+
+<p align="center">
+  <img width="600" src="https://i.imgur.com/icPolzI.gif">
+</p>
+<p align="center">
+  <img width="600" src="docs/1.jpg">
+</p>
+<p align="center">
+  <img width="600" src="docs/2.jpg">
+</p>
+<p align="center">
+  <img width="600" src="docs/3.jpg">
+</p>
+
+## Usage
+
+### Use remotely
+- Download [this KML file](https://jonamat.cloud/wikiloc-layer/static/wikiloc-earth-layer.kml) 
+- Open Google Earth Pro, go to file > open and select the downloaded wikiloc-earth-layer.kml
+- Navigate to the area you want to explore
+- Refresh the layer by right clicking on the layer > refresh
+- Enjoy your adventures!
+
+**This service is demonstrative. See "[Slow or unresponsive service using remote KML](#slow-or-unresponsive-service-using-remote-kml)" section if you experience lag or connection problems**
+
+### Use locally
+- Download & extract the last release from [this page](https://github.com/jonamat/wikiloc-earth-layer/releases) according to the target platform.
+- Run the binary "wikiloc-earth-layer"
+- Open Google Earth, go to file > open and select from the extracted folder ./web/static/wikiloc-earth-layer.kml
+- Navigate to the area you want to explore
+- Refresh the layer by right clicking on the layer > refresh
+- Enjoy your adventures!
+
+If you want to compile the binary yourself, follow [these](#build-with-go) instructions  
+
+### Use from the app (Android)
+- Download [this KML file](https://wikiloc-layer.io/static/wikiloc-layer.kml) 
+- Open it directly or import in Google Earth: go to settings > projects > open and select the downloaded wikiloc-layer.kml
+- Navigate to the area you want to explore
+- Refresh the layer by tapping on settings > project > layer > refresh
+- Enjoy your adventures!
+
+## Known issues
+
+### Refresh system is inconvenient to use
+I know, but it's necessary. Uploading the trails on camera movement has an even worse user experience. Unfortunately Google Earth doesn't support interactive applications as much. But maybe I found a workaround, I'm working on it. Encourage me supporting this project!
+
+### Slow or unresponsive service using remote KML
+The service is currently hosted in an unscaled machine that has the computing power of a coffee maker. Each request to the server must handle up to 25 calls to wikiloc, involving geometric calculations and encoding/decoding operations for each of them, so it's easy that the server blown down with multiple users connected. Furthermore, an excessive amount of requests to the Wikiloc servers could trigger their rate limiters.
+If you want a decent lag and zero problems, follow the [Use locally](#use-locally) instructions to host the service yourself.
+
+### Elevation and distance are displayed in metric units only
+If you want to use imperial units, use the env var UNITS=imperial and restart the server
+
+### Only 24 trails are shown, although there are many more in the area
+This is a (reasonable) Wikiloc limitation. You can encounter the same problem from navigating the official wikiloc maps. Zoom in the area you want to explore and refresh the layer to show more specific trails for that area.
+
+### When camera is tilted, the resulting trails are far from the view area
+Yep. When camera is tilted, the area you are exploring is the Lat-Lon point from the top right to the bottom left corner of the screen. Straighten your view to get a more precise result.
+
+## Tips and tricks
+I recommend using the layer in combination with  
+- [Google Maps Terrain layer](https://ge-map-overlays.appspot.com/google-maps/terrain) to show the contour lines of the terrain 
+- [Open Street Map layer](https://ge-map-overlays.appspot.com/openstreetmap) to show a detailed map of the terrain types, peak names and more
+
+## Development and contribution
+The project is a suite of 3 software
+- **get-icons** to fetch the svg icon set from wikiloc.com and convert them to png
+- **gen-kml** to generate the init KML file which contains the network link for Google Earth
+- **wikiloc-connector** is the http server that handle the updates from the network link
+
+In the Makefile are defined the commands to run and build the source.  
+The project is set up to follow the guidelines of the Golang team that you can find [here](https://github.com/golang-standards/project-layout).
+
+### Build with Go
+- Download [Go](https://golang.org)
+- Clone the repo
+- Go to the directory of the project with your terminal and type "make build"
+- Wait for the build to finish
+- Now you can find the compiled binaries in ./bin/
+
+### Build with Docker
+- Download [Docker](https://)
+- Clone the repo
+- Go to the directory of the project with your terminal and type "make build-image"
+- Wait for the build to finish
+- Now you can find the compiled binaries in ./bin/
+
+### Working with dev containers
+This repository provide all the tools to start writing and testing your code without any configuration.  
+To use devcontainer feature you need to have Docker installed and the Remote Containers extension enabled in VSCode.  
+See [Developing inside a Container](https://code.visualstudio.com/docs/remote/containers) for details.  
+
+## Licence
+MIT