ASOC UON

📚 Table of Contents

1. About The Project
   • Project Structure
2. Viewing Maps
   • Example Maps
   • How To Use
3. Features
4. Requirements
   • Installing Libraries
5. Setup
   • Google Sheet Structure
   • Example Google Sheet
   • Map Icon Symbols
6. Usage
   • Updating Sabbath Walks Map
   • Creating Route Map
   • Updating Letterbox Map
7. Roadmap
8. Contributing To The Maps
9. License
10. Contact
11. Acknowledgments

About The Project

This project provides Python scripts to create interactive HTML maps, which can be viewed in any web browser. Specifically, maps are created for ASOC church locations/routes, Sabbath walks and letterboxing.

📚 Project Structure

• Docs: Contains all the documentation for project.
  • Website FolderSmall webpage wrapper.
  • Letterbox_Documentation.mdDocuments the letterbox code.
  • Using_GPX_Studio.md Details how GPX Studio can be used to create gpx files.
• gpx: Contains all GPX files
  • Church_Locations: Contains GPX files for Church Locations.
  • Letterbox_Routes: Contains GPX files of completed Letterbox routes.
  • Misc: Contains any other GPX files.
  • Sabbath_Walks: Contains GPX files for Sabbath walks.
• src: Contains the code for generating maps.
  • Create_Routes: Creates a route.
  • Letterbox: Creates the letterbox maps.
  • Misc: Other codes.
  • Route_Code
  • README.md
  • Update_Walks.py: Updates the map of ASOC walks.
• maps: Contains the HTML files for the maps.
  • Church_Locations: Contains maps for church and caregroup locations.
  • Letterbox: Contains maps used for letterboxing.
  • Misc: Other maps.
  • Sabbath_Walks: Contains maps for Sabbath walks.
• Images: Contains all images used in this repo.
  • Icons: Contains Font Awesome Icons.
  • UML_Diagrams: Contails UML diagrams for code.
• ASOC_Walks.ipynb: Jupyter notebook for code testing.
• CHANGELOG.md: Records changes between versions.
• LICENSE: Explains the licensing of this project.
• README.md: Explains this project.

(back to top)

Viewing Maps

The maps can be viewed through GitHub Pages. You can access them using the following link format: https://nuac-av.github.io/ASOC-UON/`file-name`.html

Replace file-name with the specific file you want to view. Note: replace spaces(" ") with "%20".

Example Maps

Here are some example usages of the maps:

1. Main ASOC Walk Locations Map:

   • Description: This map shows the main locations for the ASOC walks.
   • Link: https://nuac-av.github.io/ASOC-UON/Maps/Misc/ASOC_walk_locations_map.html

2. Letterbox Map:

   • Description: This map shows the letterbox regions and completed streets.
   • Link: https://nuac-av.github.io/ASOC-UON/Maps/Letterbox/main.html

How To Use

1. Accessing the Map:

   • Open your web browser.
   • Type the URL or click on the provided link for the specific map you want to view.

2. Interacting with the Map:

   • Zoom In/Out: Use the zoom controls to focus on specific areas.
   • Pan: Click and drag to move around the map.
   • Markers: Click on markers to get more information about each location.
   • Filter: Click on layer symbol in top right corner, allowing you to toggle on or off the different coloured icons.

🗺️ Other Maps

• Church_Locations
  • ES_Building.html
  • Library_Church.html
  • Library_Test.html
• Letterbox
  • letterbox_test_1.html
  • letterbox_test_2.html
  • letterbox_test_3.html
  • ⋮
  • letterbox_test_23.html
• Misc
  • ASOC_walk_locations_map.html
  • routes_map.html
• Sabbath_Walks
  • Hickson_Street_Lookout.html
  • Islington_Park.html
  • Mount_Sugarloaf.html

(back to top)

Features

• Creates Interactive Sabbath Walk Maps:
  • Using the following sheet as a backend: Google Sheets Document
  • Reads data from the google sheets.
  • Plots
• Create an interactive map from the database
• Add markers for each location with popups containing relevant information
• Save the map as an HTML file
• Add GPX routes from a folder and group them on the same level as regions in the tree structure

(back to top)

Requirements

The requirements are contained in the requirements.txt file.

Required Libraries

• Python 3.x

📚 Libraries

Library	Version
branca	0.7.2
charset-normalizer	3.3.2
cycler	0.12.1
fonttools	4.53.1
gpxpy	1.6.2
Jinja2	3.1.4
MarkupSafe	2.1.5
networkx	3.3
osmnx	1.9.3
pandas	2.2.2
pillow	10.4.0
pyparsing	3.1.2
python-dateutil	2.9.0.post0
requests	2.32.3
six	1.16.0
urllib3	2.2.2
xyzservices	2024.6.0

<table>
  <tr><th>Library</th><th>Version</th></tr>
  <tr><td>certifi</td><td>2024.7.4</td></tr>
  <tr><td>contourpy</td><td>1.2.1</td></tr>
  <tr><td>folium</td><td>0.17.0</td></tr>
  <tr><td>geopandas</td><td>1.0.1</td></tr>
  <tr><td>idna</td><td>3.7</td></tr>
  <tr><td>kiwisolver</td><td>1.4.5</td></tr>
  <tr><td>matplotlib</td><td>3.9.2</td></tr>
  <tr><td>numpy</td><td>2.0.0</td></tr>
  <tr><td>packaging</td><td>24.1</td></tr>
  <tr><td>pathlib</td><td>1.0.1</td></tr>
  <tr><td>pyogrio</td><td>0.9.0</td></tr>
  <tr><td>pyproj</td><td>3.6.1</td></tr>
  <tr><td>pytz</td><td>2024.1</td></tr>
  <tr><td>shapely</td><td>2.0.5</td></tr>
  <tr><td>tzdata</td><td>2024.1</td></tr>
  <tr><td>uuid</td><td>1.30</td></tr>
</table>

⚠️ Disclaimer: Please ensure to use the specific package versions listed in the requirements.txt file. This guarantees that the program runs as expected and avoids compatibility issues.

Virtual Enviroments

To run this software using the specific configureations a virtual environment can be setup using the following procedure.

🔧 Setting Up a Virtual Environment

Install GDAL (Required for pyogrio and geopandas):

• On macOS:

  brew install gdal

• On Ubuntu:

  sudo apt update && sudo apt install gdal-bin libgdal-dev

• On Windows:

  choco install gdal

  Alternatively, download and install the GDAL binaries from GDAL's official site and add the installation path to your system's PATH variable.

Create a virtual environment:

python3 -m venv asoc_maps

Activate the virtual environment:

• On macOS/Linux:

  source asoc_maps/bin/activate

• On Windows:

  asoc_maps\Scripts\activate

Install required packages from requirements.txt:

pip install -r requirements.txt

Deactivate the virtual environment when done:

deactivate

(back to top)

Setup

The Sabbath Walk, Caregroup and Church locations are stored in a google sheet. With the following structure.

Google Sheet Structure

• Name: The name of the location.
• Latitude: The latitude of the location.
• Longitude: The longitude of the location.
• Google_Link: A Google Maps link or other relevant URL.
• Address: The address of the location.
• Description: A description of the location or any additional notes.
• Route_Link: A link to the route map for that location.
• Icon: The icon to use for the marker.
• Colour: The colour of the marker.

(back to top)

Example Google Sheet

Location	Latitude	Longitude	Google_Link	Address	Discription	Route_Link	Icon	Color
Awabakal Nature Reserve	-32.99149503	151.7222826	Link	13 Ivy St, Dudley NSW 2290	It will be in the bush, so please have proper walking shoes for the walk. We can park on the road around Ivy Street.	Link	tree	green
Bar Beach	-32.94047053	151.7695674	Link	Yuelarbah Track, Bar Beach NSW 2300			umbrella-beach	beige
⋮	⋮	⋮	⋮	⋮	⋮	⋮	⋮

Map Icon Symbols

Icon Symbol	Icon Name	Colour	Description
	water	blue	Used for rivers and lakes (excluding saltwater).
	plant-wilt	lightgreen	Used for wetlands.
	tree	green	Used for forests and parks.
	umbrella-beach	beige	For beaches and other sandy environments.
	mountain	darkgreen	For hilly and mountainous walks.
	sailboat	pink	For boat ramps.
,	Ferry and Ship	black	Used for other harbour/coastal walks.
	flag	red	Other walks not listed.

(back to top)

Icon Colors and Symbols

The available colors for icons are: black, beige, lightblue, gray, blue, darkred, lightgreen, purple, red, green, lightred, white, darkblue, darkpurple, cadetblue, orange, pink, lightgray, darkgreen.

More details can be found here.

Icons can be chosen from Font Awesome. Additionally, PNG files can be used as icons.

(back to top)

Usage

clone the repo, then execute the following codes.

git clone https://github.com/NUAC-AV/ASOC-UON.git

Updating Sabbath Walks Map

1. Pull latest GitHub repository

   git pull origin

2. Ensure the Google Sheets is correctly formatted.
3. Run the Update_Walks.py file.
4. Commit changes

   git commit -m "Update Sabbath Walks Map."

5. Push changes to the ASOC-UON repository.

   git push origin main

Creating Route Map

1. Pull the latest changes from the ASOC-UON GitHub repository.

   git pull origin main

2. Create the route map in the appropriate subfolder of `Sabbath_Walks` based on the [plot_routes_example.py](Map_Generating_Codes/Create_Routes/plot_routes_example.py) script.
3. Push the changes to the ASOC-UON GitHub repository.

   git push origin main

Updating Letterbox Map

1. Pull latest:

   git pull origin

2. Add all gpx files to GPX_Files/Letterbox_Routes folder.
3. Activate the virtual environment:

   source asoc_maps/bin/activate

4. Run the Update_Letterbox_Map.py file:

   python3 src/Letterbox/Update_Letterbox_Map.py

5. Track gpx files:

   git add .

6. Commit changes:

   git commit -m "📮 Update letterbox map"

7. Push changes:

   git push origin main

(back to top)

Roadmap

• Add Changelog
• Add back to top links
• Add route maps for all walks
• Redesign create_route_map codes
• Create letterbox map
• Make website wrapper for maps

(back to top)

Contributing To The Maps

If you would like to contribute to the maps, follow these steps:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/name-of-changes)
3. Commit your Changes (git commit -m 'Add name-of-changes')
4. Push to the Branch (git push origin feature/name-of-changes)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Rory Yarr

• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/rory-yarr-3a5833211/

(back to top)

Acknowledgments

• OSMnx: Boeing, G. 2017. "OSMnx: New Methods for Acquiring, Constructing, Analyzing, and Visualizing Complex Street Networks." Computers, Environment and Urban Systems, 65, 126-139. https://doi.org/10.1016/j.compenvurbsys.2017.05.004