README.md

Germany_Beer_Map Project

This project is a Python-based project focused on efficiently associating beer bottle caps with their corresponding locations on a wooden map of Germany designed for displaying beer caps which was given to me as a present. Using computer vision techniques, it accurately identifies the positions of the holes in the wooden map from a photograph.

The core functionality involves creating a correlation between the beer bottle caps and the physical locations of their corresponding breweries on the map. This is achieved by matching the list of beer producers with the detected holes. The optimisation process aims to minimize the cumulative spatial distance between each hole on the map (its respective geographic reference) and bottle cap placement.

Key Features:

• Computer vision for precise detection of beer bottle cap locations on a wooden map.
• Rotation, aligning and scaling of the wooden map contour to a reference contour of Germany
• A thin-plate spline transformation carried out on the wooden map onto a reference outline of Germany.
• A Geospatial interpolation of the (image) coordinates of distinctive points on the wooden map contour to the corresponding longitude and latitude coordinates to generate a convex hull encompassing the centres of the hole cutouts.
• Geospatial correlation to establish links between hole cutouts for the bottle caps and their real-world geographic references.
• Optimisation algorithm (Hungarian algorithm) to find optimal pairings of bottle cap-brewery locations and hole cutouts to minimise aggregate spatial discrepancy.

Images

Detected Circles	Detected Outline

Final Output	Reference contour (w/o alignment/rotation/scaling)

How to Run

To run the application, first clone the repo with git, then navigate to the project root directory and run the main.py script:

git clone https://github.com/daniel-jakob/Bottle_Cap_Map
cd Bottle_Cap_Map
python germany_beer_map/src/main.py

Dependencies

The project's dependencies are listed in the requirements.txt file. To install the dependencies, use the following command:

pip install -r requirements.txt

Running the Project with Conda

1. First, make sure you have Anaconda or Miniconda installed.

2. Create a new Conda environment using the conda.yaml file:

   conda env create -f conda.yaml

3. Activate the new environment:

   conda activate germany_beer_map

4. Navigate to the project root directory and run the main.py script

   python germany_beer_map/src/main.py

5. When you're done, you can deactivate the environment with:

   conda deactivate

If looking to adapt for your own bottlecap map…

You must take a photo of your map, ideally as similar as possible to the one I used (found in germany_beer_map/data/images/map.jpg). I suggest a high contrast background. Replace the aforementined file with your picture. Find a reference outline image of your country online and replace the map_ref.jpg file. Change the None in picture_out_filename=None in the circles = detect_circles(...) line in main.py to a chosen filename, for example: "circles_put.png" (with double quotes). Run the script and see if all of the circular hole cutouts of your map are detected. If not, play around with the minRadius=... and maxRadius=... parameters in cv2.HoughCircles(...) in the src/image_processing/circle_detection.py file. Once all circles are being detected, ensure that the outlines (contours) of both the photograph and reference image are being detected correctly, the detected outline can be outputted to an image file in a similar fashion to the circle detection, except for the detect_outline(...) lines.

Testing

Unit tests are located in the tests directory. To run the tests, use the following command from the project root directory:

python & pytest germany_beer_map/tests

License

This project is licensed under the terms of the LICENSE file.