A functional, purely offline OpenStreetMap (OSM) implementation for Android built with Jetpack Compose and osmdroid.

This repository serves as a working prototype and a learning mini-project. It is not focused on a flashy UI, but rather on providing a rock-solid, functional foundation for displaying offline maps without relying on paid APIs. Feel free to use this code as a starting point for your own apps!

What is this? This is a custom implementation of OpenStreetMap designed specifically to avoid using Google Maps for smaller or independent projects.

Why build this? Using the Google Maps API can get expensive quickly, especially for larger projects. I needed a completely free, offline-capable mapping solution for a much larger project I am working on. By packaging map tiles directly into the app, this approach guarantees zero API costs and works perfectly in areas with poor or no internet connection.

• Language: Kotlin
• UI: Jetpack Compose (using AndroidView to bridge the legacy osmdroid View)
• Map Engine: osmdroid
• Location Services: Google Fused Location Provider (for high-accuracy hardware GPS)
• Architecture: MVVM (ViewModel, StateFlow, Coroutines)

A Note on the Architecture: I am currently in the process of learning Android development and Jetpack Compose. Because I am focusing heavily on mastering the core concepts of UI state and the map engine, I intentionally avoided using Dependency Injection (like Hilt/Dagger) in this prototype to keep the architecture simple and easy to understand.

1. Local Tile Rendering: The app uses osmdroid to read an offline .zip archive of map tiles instead of streaming them from the internet.
2. Compose Integration: Because osmdroid relies on traditional XML Views, the MapView is wrapped inside an AndroidView composable, with its state managed by a ViewModel.
3. Hardware GPS: It requests location permissions and uses the Fused Location Client to plot the user's exact coordinates over the offline map.

To run this project on your local machine:

1. Clone this repository.
2. Ensure you have an offline map file named CampusTiles.zip (see below on how to generate one).
3. Place CampusTiles.zip into the app/src/main/assets/ directory.
4. Sync Gradle and build the project.

(Note: The map will open centered on the coordinates hardcoded in MainActivity.kt. If you are using your own map tiles, update the BoundingBox and setCenter coordinates in the code to match your area!)

If you want to use this project for your own city or campus, you need to generate your own .zip file of map tiles.

Step 1: Contribute to OSM (Optional but recommended) If your campus or area is missing buildings or roads on OpenStreetMap, go to openstreetmap.org and map them out yourself first!

Step 2: Download Mobile Atlas Creator (MOBAC) MOBAC is a free tool used to download map tiles for offline use.

1. Download and open MOBAC on your computer.
2. Select your desired map source (e.g., OpenStreetMap Public Transport or standard OSM).
3. Use your mouse to draw a bounding box around the specific area you want to save.
4. Select the Zoom Levels you want to include (e.g., 15 through 19 for detailed street views).
   • Warning: Higher zoom levels over large areas create massive file sizes.
5. In the "Atlas settings", set the format to Osmdroid ZIP.
6. Click "Create Atlas".
7. Rename the output file to CampusTiles.zip and drop it into this project's assets folder.

This project was built primarily as a working prototype to solve a specific problem (offline mapping without API costs). To save time and focus on the core osmdroid and Jetpack Compose integration, some of the boilerplate setup code was generated using AI.

Because this is a learning project, there is absolutely room for improvement! If you spot any bugs, know a better way to structure the Compose UI, or want to add features, please feel free to fork the repository and open a Pull Request. All contributions, tips, and improvements are highly welcome!