How connor050-htw/accessible-map works
Project type and purpose
• This is a full-stack web application with
• A rich, accessible Leaflet-based frontend (JavaScript, CSS, GeoJSON, plugins)
• A FastAPI Python backend (“map-to-speech-demo/api/”) that receives screenshots, forwards them to a local Vision-Language model (Ollama), and returns text/audio descriptions
File structure
• Top-level frontend folders:
• index.html, data.js, data/, images/
• src/ (modular JS code: core, controls, features, layers, ui, utils)
• plugins/ (Leaflet plugins: fullscreen, pinsearch)
• styles/ (base.css, components/, main.css)
• Separate demo app under map-to-speech-demo/app/ (static files)
• Backend under map-to-speech-demo/api/ with main.py (FastAPI), requirements.txt
Key components
a. Frontend (Browser/Client)
– Static resources served by a web server or file system:
• HTML (index.html)
• CSS (styles/)
• JS modules (src/, data.js)
• GeoJSON data (data/austriancastles.geojson)
• Plugins (plugins/)
– Map UI layers (tile server endpoints via Mapbox/OpenStreetMap)
– Controls & Features modules (3D, LOD, settings, compass, sidebar, accessibility)
– html2canvas integration for screenshot capture
– Web Speech API for TTS
b. Backend (FastAPI service)
– Endpoint POST /description/
– Reads JSON payload (data_url, speed, voice, etc.)
– Attempts /api/generate on Ollama, falls back to /api/chat
– Returns JSON { text_data, audio_data }
c. External Service (Ollama Vision-Language Model)
– Local host (default http://127.0.0.1:11434)
– Qwen-VL model (e.g., qwen3-vl:4b)
d. (Optional) Static file server
– Serves frontend assets and data/ folder
Relationships & data flows
1. User interact GUI → frontend code (Leaflet + custom modules)
2. “Get Description” button → html2canvas captures map viewport → base64 PNG
3. Frontend POSTs JSON to FastAPI /description/
4. FastAPI → HTTP call to Ollama /api/generate or /api/chat
5. Ollama returns text (and/or audio) → FastAPI wraps into JSON → sends back
6. Frontend receives response → updates UI, triggers browser speech synthesis
Architectural patterns & design principles
• Modular frontend: clear separation into core, controls, features, layers, UI, utils
• Single responsibility: each JS module handles one feature or control
• RESTful microservice: lightweight FastAPI backend for a single purpose
• External service integration: decouple business logic (description generation) into Ollama