{"id":50911353,"url":"https://github.com/kaushik0911/jubilant-guide","last_synced_at":"2026-06-16T10:30:55.933Z","repository":{"id":353302467,"uuid":"1216186492","full_name":"kaushik0911/jubilant-guide","owner":"kaushik0911","description":"A Streamlit application for advanced route planning and accessibility analysis using OpenRouteService (ORS). Explore optimal routes while avoiding roadblocks and discover points of interest (POIs) within travel time ranges.","archived":false,"fork":false,"pushed_at":"2026-06-09T11:14:21.000Z","size":969,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T13:11:07.764Z","etag":null,"topics":["data-analysis","data-visualization","geospatial-analysis","python","streamlit"],"latest_commit_sha":null,"homepage":"https://medium.com/@kaushikshamantha/forget-postgis-building-a-modern-geospatial-stack-with-duckdb-and-streamlit-d881e07694c8","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kaushik0911.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T16:50:49.000Z","updated_at":"2026-06-09T11:14:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kaushik0911/jubilant-guide","commit_stats":null,"previous_names":["kaushik0911/jubilant-guide"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kaushik0911/jubilant-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushik0911%2Fjubilant-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushik0911%2Fjubilant-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushik0911%2Fjubilant-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushik0911%2Fjubilant-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kaushik0911","download_url":"https://codeload.github.com/kaushik0911/jubilant-guide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kaushik0911%2Fjubilant-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34402648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-analysis","data-visualization","geospatial-analysis","python","streamlit"],"created_at":"2026-06-16T10:30:53.144Z","updated_at":"2026-06-16T10:30:55.916Z","avatar_url":"https://github.com/kaushik0911.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jubilant Guide\n\nA Streamlit application for advanced route planning and accessibility analysis using OpenRouteService (ORS). Explore optimal routes while avoiding roadblocks and discover points of interest (POIs) within travel time ranges.\n\n## Features\n\n### 1. **Roadblock Avoidance**\n- Plan routes while dynamically avoiding roadblocks\n- Upload roadblocks via CSV file (latitude, longitude format)\n- View route metrics including distance and estimated time\n- Interactive map visualization with start, end, and roadblock markers\n- Results caching for improved performance\n\n### 2. **Accessibility Analyzer**\n- Discover Points of Interest (POIs) within a specified travel time from a location\n- Search for amenities: hospitals, pharmacies, cafes, restaurants, banks, schools\n- Visualize reachable areas using isochrone maps\n- City-based geolocation support\n\n## Project Structure\n\n```\njubilant-guide/\n├── src/\n│   ├── __init__.py\n│   ├── cache.py              # Disk cache management\n│   ├── db.py                 # Database utilities\n│   ├── routing.py            # ORS routing client\n│   ├── components/\n│   │   ├── roadblock.py      # Roadblock logic and visualization\n│   │   └── isochrone.py      # Isochrone and POI filtering\n│   └── pages/\n│       ├── accessibility_analyzer.py\n│       └── roadblock_avoidance.py\n├── ors-docker/               # ORS Docker configuration and data\n│   ├── config/\n│   ├── elevation_cache/\n│   ├── files/\n│   ├── graphs/\n│   └── logs/\n├── app.py                    # Main Streamlit application\n├── pyproject.toml            # Project configuration\n├── docker-compose.yml        # ORS Docker Compose setup\n├── Makefile                  # Convenient CLI commands\n└── README.md                 # This file\n```\n\n## Prerequisites\n\n- **Python**: 3.11 or higher\n- **Docker**: For running OpenRouteService locally\n- **uv**: Python package manager (recommended) - [Installation guide](https://docs.astral.sh/uv/getting-started/installation/)\n\n## Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd jubilant-guide\n```\n\n### 2. Install Dependencies using `uv`\n\n```bash\n# Using Makefile\nmake install\n\n# Or directly with uv\nuv sync\n```\n\nThis will:\n- Create a virtual environment\n- Install all dependencies from `pyproject.toml`\n- Set up the development environment\n\n### 3. Environment Setup\n\nNo additional environment variables are required for local development. The application connects to ORS at `http://localhost:8080/ors` by default.\n\n**Optional**: To customize ORS connection, modify the `BASE_URL` in `src/routing.py`:\n```python\nBASE_URL = \"http://localhost:8080/ors\"\n```\n\n## Running OpenRouteService (ORS) Locally\n\n### Prerequisites for ORS\n\n- Docker and Docker Compose installed\n- Minimum 2GB RAM available for ORS\n- Disk space: ~2GB for graphs and elevation cache\n\n### Start ORS Service\n\n```bash\n# Using Makefile\nmake orsup\n\n# Or directly with docker compose\ndocker compose up -d\n```\n\nThe ORS service will:\n- Build/pull the ORS container (v9.8.0)\n- Expose API on `http://localhost:8080`\n- Load the example Heidelberg routing graph\n- Cache elevation data automatically\n\n**Wait for service to be ready** (1-5 minutes depending on system):\n```bash\ncurl http://localhost:8080/ors/v2/health\n```\n\nExpected response:\n```json\n{\"status\":\"ready\"}\n```\n\n### Stop ORS Service\n\n```bash\n# Using Makefile\nmake orsdown\n\n# Or directly\ndocker compose down\n```\n\n### ORS Configuration\n\nThe ORS configuration is managed through:\n- **Config file**: `ors-docker/config/ors-config.yml`\n- **Environment variables**: Set in `docker-compose.yml` under `environment:`\n\nKey settings in `docker-compose.yml`:\n```yaml\nXMS: 1g              # Initial JVM heap size\nXMX: 2g              # Maximum JVM heap size\nREBUILD_GRAPHS: False # Rebuild routing graphs on startup\n```\n\nTo use custom graph data:\n1. Place PBF files in `ors-docker/files/`\n2. Update config in `ors-docker/config/ors-config.yml`\n3. Restart the container\n\n## Running the Application\n\n### Development Mode\n\n```bash\n# Using Makefile\nmake run\n\n# Or directly\nuv run streamlit run app.py\n```\n\nThe application will be available at: `http://localhost:8501`\n\n### Stop the Application\n\n```bash\nmake stop\n```\n\n## Usage Guide\n\n### Roadblock Avoidance\n\n1. Open the **Roadblock Avoidance** page from the navigation menu\n2. Enter start and end coordinates (default: Heidelberg example)\n3. Configure settings in the sidebar:\n   - **Search Buffer**: Defines the search area around the route (1-20km)\n   - **Roadblock Radius**: Size of avoidance zones (10-100 meters)\n   - **Avoidance Buffer**: Margin around roadblocks (0.0001-0.001 degrees)\n4. Upload a CSV file with roadblock locations:\n   ```csv\n   latitude,longitude\n   49.408663957747,8.689759402170136\n   49.41017207323517,8.686369285199621\n   ```\n5. Click **Calculate Route** to compute the optimal path\n6. View results with distance, time, and interactive map\n\n### Accessibility Analyzer\n\n1. Open the **Accessibility Analyzer** page\n2. Enter a city name (default: Heidelberg)\n3. Select the type of amenity to search for\n4. Set the travel time range (5-30 minutes)\n5. Click **Analyze Reachability** to find accessible POIs\n6. View results with:\n   - Reachable area (isochrone) highlighted on the map\n   - All POIs within range\n   - Accessibility statistics\n\n![Alt text](screenshot.png)\n\n## Available Commands\n\n```bash\nmake install    # Install dependencies using uv\nmake clean      # Remove virtual environment and cache\nmake run        # Start Streamlit application\nmake stop       # Stop the application\nmake orsup      # Start ORS Docker service\nmake orsdown    # Stop ORS Docker service\n```\n\n## Troubleshooting\n\n### ORS Service Connection Error\n\n**Error**: `Error calculating route: Connection refused`\n\n**Solution**:\n1. Verify ORS is running: `docker ps | grep ors-app`\n2. Check service health: `curl http://localhost:8080/ors/v2/health`\n3. Check container logs: `docker logs ors-app`\n4. Restart the service:\n   ```bash\n   make orsdown\n   make orsup\n   ```\n\n### CSV Upload Errors\n\n**Error**: `CSV must contain columns: latitude, longitude`\n\n**Solution**:\n- Ensure your CSV has exactly these column headers (case-sensitive)\n- Example format:\n  ```csv\n  latitude,longitude\n  49.40,8.68\n  ```\n\n### Memory Issues with ORS\n\n**Error**: `Container exits or becomes unresponsive`\n\n**Solution**:\n1. Increase JVM heap size in `docker-compose.yml`:\n   ```yaml\n   XMS: 2g  # Increase from 1g\n   XMX: 4g  # Increase from 2g\n   ```\n2. Rebuild and restart:\n   ```bash\n   make orsdown\n   make orsup\n   ```\n\n### Port Already in Use\n\n**Error**: `Port 8080 is already allocated`\n\n**Solution**:\nOption 1: Change the port mapping in `docker-compose.yml`:\n```yaml\nports:\n  - \"8090:8082\"  # Use 8090 instead\n```\n\nOption 2: Find and stop the process:\n```bash\nlsof -i :8080\nkill -9 \u003cPID\u003e\n```\n\n## Data Caching\n\nThe application uses disk caching to improve performance:\n- **Route Cache**: Caches computed routes to avoid recalculation\n- **Location**: `cache/` directory\n- **Automatic**: Caching is handled automatically by the application\n\nTo clear cache:\n```bash\nmake clean\nrm -rf cache/\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaushik0911%2Fjubilant-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaushik0911%2Fjubilant-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaushik0911%2Fjubilant-guide/lists"}