Skip to content

Commit

Permalink
[FEATURE] docu: Update & refactor README and install-docu for setting…
Browse files Browse the repository at this point in the history 
… up Anaconda environment (#84)

- adjust Anaconda quickstart according to #82
- makes README more attractive and shorter
- extracts usage information to docs/USAGE.md to separate page
- unify Quickstart docu for macOS and Windows and do not link anymore to there from README


* unify Windows and macOS Quickstart

* update readme

* update install docu

* adjust Anaconda quickstart according to #82

* adjust README

* Extract Usage information to separate page

* minor enhancement

* adjust headlines & typo

* update links in README: icons, text and format

* update CONTRIBUTING.md: Add link to installation of Anaconda environment & format
  • Loading branch information
@treee111
treee111 committed Jan 19, 2022
1 parent 5ed0375 commit 07dbeea
Show file tree
Hide file tree
Showing 6 changed files with 183 additions and 158 deletions.
10 changes: 8 additions & 2 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,14 @@ After testing carefully, changes are merged into main and a Release will be crea

### Automatic CHANGELOG creation
After installing [git-chglog](https://github.com/git-chglog/git-chglog) locally, the CHANGELOG.md can be generated with this command:
`git-chglog -o CHANGELOG.md`
```
git-chglog -o CHANGELOG.md
```

To generate the CHANGELOG.md for a upcoming release (no tag exists yet), the following command can be used:
`git-chglog -o CHANGELOG.md --next-tag v0.10.0`
```
git-chglog -o CHANGELOG.md --next-tag v0.10.0
```

## Structure of the repository
There is one python coding base for both Windows and for macOS.
Expand All @@ -91,4 +95,6 @@ and the .yml files with the dependencies via
conda env export > environment.yml
```

The installation of Anaconda envirionments is described [here](docs/QUICKSTART_ANACONDA.md)

more information on [documentation for sharing anaconda environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#exporting-an-environment-file-across-platforms)
106 changes: 35 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,98 +10,62 @@
</p>
<h1>Wahoo Maps Creator</h1>
</div>
A tool to create up-to-date maps for your Wahoo ELEMNT BOLT and BOLTv2, ELEMNT ROAM and Wahoo ELEMNT! It runs on Windows, macOS as well as on Unix!
A tool to create up-to-date maps for your Wahoo ELEMNT BOLT and BOLTv2, ELEMNT ROAM and Wahoo ELEMNT!

# Basic Overview
WahooMapsCreator is a tool to create maps based on the latest OSM data for your Wahoo devices. You can generate maps for the countries you like and you can control which OSM-tags are included.

The maps of your device may be old because Wahoo did not release a newer version in the last years. OSM maps are constantly updated and with this program, the updated maps can be used on our Wahoo bike-computers.
It runs on Windows, macOS as well as on Linux!

## Get it running
The instructens are intended to be suitable for beginners.
If anything is unclear or just wrong, write an issue!
## Basic Overview
WahooMapsCreator is a tool to create maps based on the latest OSM data for your Wahoo devices. You can generate maps for the countries you like and you can control which OSM-tags are included.

### Overview of the steps
The steps for all OS are similar:
- Download and Install required programs
- Download a release of wahooMapsCreator or clone Repository
- Run wahooMapsCreator for your country
- Copy the map-files to your device
The maps of your device may be old because Wahoo did not release a newer version in the last years.

Optional:
- use a custom theme on your Wahoo
OSM maps are constantly updated. With this program, the updated maps can be used on our Wahoo.

### Download and Install required programs
The initial setup takes some minutes but is only a one-timer!
# Get it running
The instructions are intended to be suitable for beginners.

Follow the Quick Start guide depending on your OS:
- [Quick Start Guide for Windows](docs/QUICKSTART_WINDOWS.md)
- [Quick Start Guide for macOS](docs/QUICKSTART_MACOS.md)
If anything is unclear or seams wrong, write an [:pencil2: issue](https://github.com/treee111/wahooMapsCreator/issues)!

Or use Anaconda to create a Python environment
- [Quick Start Guide for Anaconda](docs/QUICKSTART_ANACONDA.md)
## Download and Install required programs
Using Anaconda to setup a virtual Python environment is the fastest way to get wahooMapsCreator running!

### Get wahooMapsCreator
Download the latest Release from the ["Releases" Section](https://github.com/treee111/wahooMapsCreator/releases) and Save the folder on your drive. You can also clone the repository and have the latest coding.
[:rocket: Quick Start Guide for Anaconda](docs/QUICKSTART_ANACONDA.md#download-and-install-required-programs)

## Run wahooMapsCreator
wahooMapsCreator can be used in two different ways:
- as [graphical window](#gui-graphical-user-interface) programm
- as [command line](#cli-command-line-interface) programm

Both ways support the same arguments to be used for the map-creation process. You can choose the arguments via GUI or as [CLI-arguments](#advanced-cli-usage).

### GUI (Graphical User Interface)

From the `root` folder of wahooMapsCreator, run:
- `python3 wahoo_map_creator.py` or
- `python wahoo_map_creator.py`

Set your arguments as required via the window:
via GUI
```
python wahoo_map_creator.py
```
```
python3 wahoo_map_creator.py
```
via CLI
```
python wahoo_map_creator.py malta
```
```
python3 wahoo_map_creator.py malta
```

A detailled description of the usage is documented [:computer: here](docs/USAGE.md#usage-of-wahoomapscreator)

<img src="https://github.com/treee111/wahooMapsCreator/blob/develop/docs/gui.png" alt="wahooMapsCreator GUI" width=35%>

### CLI (Command Line Interface)

From the `root` folder of wahooMapsCreator, run:
- `python3 wahoo_map_creator.py <country_name>` or
- `python wahoo_map_creator.py <country_name>`

Examples:
- for Malta: `python3 wahoo_map_creator.py malta`
- for Ireland: `python3 wahoo_map_creator.py ireland`

### Run wahooMapsCreator for your country
It might be a good idea to run wahooMapsCreator first for a small country e.g. Malta to check if everything is running fine.
In a next step you can run it for your own country.

### Advanced CLI-Usage
The script supports many arguments.
For a list of all supported arguments, run:
- `python3 wahoo_map_creator.py -h` or
- `python wahoo_map_creator.py -h`
## Copy the map-files to your device
When file-creation is finished, copy the maps files to your Wahoo device.

Examples:
- for Malta, download new maps if existing maps are older than 100 days and process files even if files exist
- `python3 wahoo_map_creator.py malta -md 100 -fp`
- for Germany, download and process whole tiles which involves other countries than the given
- `python3 wahoo_map_creator.py germany -bc`
[:floppy_disk: docu](docs/COPY_TO_WAHOO.md#copy-maps-files-to-wahoo-device-)

## Copy the map-files to your device
When file-creation is finished copy the map-files to your device:
- [Copy maps files to Wahoo](docs/COPY_TO_WAHOO.md)
## (Optional) Use a custom theme on your Wahoo
You can use a custom theme to control which OSM-tags are displayed on your device. Also in which zoom-level certain streets appear!

## use a custom theme on your Wahoo
You can use a custom theme to control which OSM-tags are displayed in which zoom-level
- [OSM-tags during map creation and on your device](docs/TAGS_ON_MAP_AND_DEVICE.md)
[:mag: docu](docs/TAGS_ON_MAP_AND_DEVICE.md#osm-tags-during-map-creation-and-on-your-device-)

## Contribution
You are welcome to provide input via Pull Requests, Issues or in any other way!
Discussion goes on:
- in this telegram channel: https://t.me/joinchat/TaMhjouxlsAzNWZk
- in this google group: https://groups.google.com/g/wahoo-elemnt-users/c/PSrdapfWLUE

More details can be found here: [CONTRIBUTING](.github/CONTRIBUTING.md#Contributing-to-wahooMapsCreator)
More details can be found here: [CONTRIBUTING](.github/CONTRIBUTING.md#contributing-to-wahoomapscreator-)

## Thanks to
[@Intyre](https://github.com/Intyre)/Hank for the initial version of the script
Expand Down
35 changes: 16 additions & 19 deletions docs/QUICKSTART_ANACONDA.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,37 @@
#### Table of contents <!-- omit in toc -->
- [Download and Install required programs](#download-and-install-required-programs)
- [Anaconda](#anaconda)
- [wahooMapsCreator](#wahoomapscreator)
- [Create Anaconda Environment](#create-anaconda-environment)
- [Run wahooMapsCreator](#run-wahoomapscreator)

# Download and Install required programs

## Anaconda
1a. Download `Anaconda Individual Edition` for your OS from
1. Download `Anaconda Individual Edition` for your OS from

https://www.anaconda.com/products/individual


1b. Install `Anaconda Individual Edition` with default settings
2. Install `Anaconda Individual Edition` with default settings

# Create Anaconda Environment
You can have a look at this: which guides you throught 2a and 2b!

https://opensourceoptions.com/blog/how-to-install-gdal-with-anaconda/
## wahooMapsCreator
Download the latest .zip file from the [Releases](https://github.com/treee111/wahooMapsCreator/releases) page and save the folder on your drive. Extract the folder.

2a. Create a new Anaconda Environment using Python 3.7 and activate the environment
```
conda create -n conda-gdal python=3.7
```
You can also clone the repository to have the latest coding.

2b. install the required Anaconda Python package GDAL
# Create Anaconda Environment
1. Open (or change to) the root of the extracted wahooMapsCreator folder in terminal or cmd prompt
2. Create a new Anaconda environment via
```
conda install -c conda-forge gdal
conda env create --prefix ./envs -f ./conda_env/enduser.yml
```
2b. In addition to GDAL, you have to install these packages:
3. activate Anaconda environment with the command printed out
```
conda install -c conda-forge geojson
conda install -c conda-forge requests
conda install -c conda-forge shapely
conda activate <PATH_TO_FOLDER>/wahooMapsCreator/envs
```
# Run wahooMapsCreator
Run wahooMapsCreater as described in the [README](../README.md/#Run-wahooMapsCreator)

You have to move to the downloaded/cloned folder via the Anaconda Prompt before or during your Anaconda environment is activated.
Additional informations: https://opensourceoptions.com/blog/how-to-install-gdal-with-anaconda/

# Run wahooMapsCreator
Run wahooMapsCreater as described in the [README](../README.md/#Run-wahooMapsCreator)
73 changes: 44 additions & 29 deletions docs/QUICKSTART_MACOS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,53 +3,68 @@
# Quick Start Guide for macOS <!-- omit in toc -->

#### Table of contents <!-- omit in toc -->

## Install Java
- [Download and Install required programs](#download-and-install-required-programs)
- [Java](#java)
- [homebrew](#homebrew)
- [OSM-tools](#osm-tools)
- [GDAL - The Geospatial Data Abstraction Library](#gdal---the-geospatial-data-abstraction-library)
- [Install additional Python modules](#install-additional-python-modules)
# Download and Install required programs

## Java
https://www.oracle.com/technetwork/java/javase/downloads

## Install homebrew
## homebrew
Install using terminal
https://brew.sh/

## Install Osmfilter
Install using homebrew in terminal:
`brew install osmfilter`

## Install osmium-tool
Install using homebrew in terminal:
`brew install osmium-tool`

## Install Osmosis
Download latest version from Github
https://github.com/openstreetmap/osmosis/releases

## Install mapsforge-map-writer plugin (Osmosis Plugin)
Download the [mapsforge-map-writer](https://search.maven.org/search?q=a:mapsforge-map-writer) plugin, click on "file_download" and select "jar-with-dependecies.jar". Put the .jar in one of these directories. Create it when it doesn't exist.

Linux/macOS ~/.openstreetmap/osmosis/plugins

https://github.com/mapsforge/mapsforge/blob/master/docs/Getting-Started-Map-Writer.md#plugin-installation
## OSM-tools
1. Install **Osmfilter** using homebrew in terminal:
```
brew install osmfilter
```
2. Install **osmium-tool** using homebrew in terminal:
```
brew install osmium-tool
```
4. Download **Osmosis** latest version from Github
* https://github.com/openstreetmap/osmosis/releases

1. Install mapsforge-map-writer plugin (Osmosis Plugin)
* Download the [mapsforge-map-writer](https://search.maven.org/search?q=a:mapsforge-map-writer) plugin, click on "file_download" and select "jar-with-dependecies.jar".
* Put the .jar in this directory. Create it when it doesn't exist:
`~/.openstreetmap/osmosis/plugins`
* more information: https://github.com/mapsforge/mapsforge/blob/master/docs/Getting-Started-Map-Writer.md#plugin-installation
6. Install osmctools

*I'm not really sure, if this is relevant. If a error concerning osmconvert occurs while using wahooMapsCreator, install osmctools*

## Install osmctools
*I'm not really sure, if this is relevant. try to install if a error concerning osmconvert occurs*
Install using terminal:
* with homebrew: `brew install interline-io/planetutils/osmctools` or
* `apt install osmctools` (this may only work on linux and not macOS)

https://gitlab.com/osm-c-tools/osmctools
* more information: https://gitlab.com/osm-c-tools/osmctools

## Install GDAL
## GDAL - The Geospatial Data Abstraction Library
Install using homebrew
`brew install gdal`
```
brew install gdal
```

Wait for it to install (can take a while), and then update the “pip” Python package manager:
`pip3 install --upgrade pip`
```
pip3 install --upgrade pip
```

After this, we can finally install GDAL for Python
`pip3 install gdal`
```
pip3 install gdal
```

https://medium.com/@vascofernandes_13322/how-to-install-gdal-on-macos-6a76fb5e24a4

## Install additional Python modules
Move to the root-folder of wahooMapsCreator and install required Python modules:
`pip install -r ./conda_env/requirements.txt`
```
pip install -r ./conda_env/requirements.txt
```
Loading

0 comments on commit 07dbeea

Please sign in to comment.