Metadata-Version: 2.4
Name: BestNearestPath
Version: 1.2.9
Summary: An offline Python navigation library for shortest-path routing and interactive map visualization using OpenStreetMap data
Home-page: 
Author: Mohammad Hossein Rostami
Author-email: MHRo.R84@GMAIL.Com
License: MIT
Keywords: navigation routing route-planning shortest-path astar a-star gis geospatial map maps osm openstreetmap osmnx networkx graph pathfinding coordinates latitude longitude streamlit folium web-map navigator
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: osmnx
Requires-Dist: RapidFuzz
Requires-Dist: streamlit-folium
Requires-Dist: folium
Requires-Dist: streamlit
Requires-Dist: networkx
Requires-Dist: geopy
Requires-Dist: pandas
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# BestNearestPath

Offline Navigation Library for Python.

**BestNearestPath** is an open-source Python library designed for offline route planning and interactive map visualization using OpenStreetMap (OSM) data. The library provides a simple and intuitive API for calculating optimal routes between geographic coordinates while displaying the result through a local interactive web interface.

Unlike cloud-based navigation services, BestNearestPath performs all routing operations locally, making it suitable for offline environments, research projects, educational purposes, GIS applications, and custom navigation systems.

---

## Features

* 🚗 Offline route planning
* ⭐ Shortest path calculation using the **A*** algorithm
* 📍 Coordinate-based routing (Latitude, Longitude)
* 🗺 Interactive web map visualization
* 📌 Start and destination markers
* 🔍 Local place searching
* 💾 SQLite-based place database
* 🌐 Local Streamlit web interface
* ⚡ Lightweight and easy-to-use Python API
* 🔒 No external routing service required

---

## Example

```python
from BestNearestPath import APIReadyNavigator

nav = APIReadyNavigator()

nav.show_route(
    start=(33.98508654513751, 51.424067616462715),
    destination=(33.98031584036005, 51.411316394805915)
)
```
![WEB UI: Source Selection Using Search](docs/images/Test.pyOutput.jpg)

---

## Current Capabilities

The current version supports:

* Loading OpenStreetMap road network graphs
* Finding the nearest road node from geographic coordinates
* Computing optimal routes using the A* algorithm
* Interactive map visualization
* Local place searching
* Offline navigation without Internet access (after map preparation)

---

## Use Cases

BestNearestPath can be used for:

* Navigation applications
* Geographic Information Systems (GIS)
* University projects
* Research and academic studies
* Smart city solutions
* Logistics and delivery systems
* Autonomous robotics
* Offline navigation software
* Route analysis and visualization

---

## Installation

```bash
pip install BestNearestPath
```
---
## Web User Interface (Web UI)

The project provides a user-friendly web interface designed to simplify interaction with the path-finding and navigation system. The Web UI allows users to search for locations, define source and destination points, and visualize the calculated route through an intuitive graphical environment.

The interface consists of several main sections, including the main dashboard, location search, source selection, destination selection, and route visualization.

---

### Main Web Interface

The main interface serves as the entry point of the application and provides access to the core features of the navigation system.

Through this page, users can start the navigation process, access location search functionality, and interact with the available mapping tools. The design focuses on simplicity, accessibility, and providing a smooth user experience.

By Run th code Below:
```python
from BestNearestPath import APIReadyNavigator

nav = APIReadyNavigator()
nav.launch_web()
```
you will see a page opend in your browser & it like this:

![WEB UI: First Page](docs/images/MainWebUIFisrtPage.jpg)

---

### Location Search

The location search module enables users to quickly find desired places by entering a search query.

The system processes the provided query and returns relevant location results. After selecting a suitable result, the selected location information is used for further navigation operations.

This feature eliminates the need for manual map navigation and provides a faster and more accurate way to locate specific points.

![WEB UI: Search](docs/images/MainWebUISearch.jpg)

---

### Source Selection Using Search

The system provides the ability to define the starting point of a route through the search functionality.

Users can search for a specific location, select the desired result, and assign it as the source point for navigation. The selected location is automatically processed and prepared for route calculation.

This approach improves accuracy and simplifies the process of selecting the starting position.

![WEB UI: Source Selection Using Search](docs/images/MainWebUISelectionStartPointSearch.jpg)

---

### Destination Selection Using Mouse Marker

In addition to search-based selection, the system supports direct destination selection through an interactive map marker.

Users can select any point on the map by moving the mouse cursor and clicking on the desired location. The corresponding geographic coordinates are extracted automatically and used as the destination point for path calculation.

This functionality is especially useful for selecting locations that may not have a specific address or searchable name.

![WEB UI: Source Selection Using Search](docs/images/MainWebUIManualDestinationSelected.jpg)

---

### Route Finding and Visualization

After defining the source and destination points, the system performs the path-finding process and displays the calculated route on the map.

The generated route is visualized in a clear graphical format, allowing users to easily understand the navigation path between the selected locations.

The system processes geographic information and applies path-finding algorithms to determine an appropriate route between the source and destination points.

![WEB UI: Source Selection Using Search](docs/images/RoutingUsingWebUI.jpg)

## License and Attributions

This project is licensed under the **MIT License**.

All third-party libraries retain their original licenses and attributions.

---

## Dependencies

BestNearestPath is built using several excellent open-source libraries, including:

* NetworkX
* OSMnx
* Folium
* Streamlit
* streamlit-folium
* RapidFuzz
* Pandas

We gratefully acknowledge the authors and maintainers of these projects.

Map data is provided by:

**© OpenStreetMap contributors**
https://www.openstreetmap.org/copyright
