(jenkins)
265 lines
5.3 KiB
Markdown
265 lines
5.3 KiB
Markdown
# Line of Sight 🌍
|
|
|
|
Interactive web application that visualizes lines of sight around the Earth, showing major conurbations along any selected path.
|
|
|
|
## 🚀 Features
|
|
|
|
- **Interactive Map**: Click anywhere to select starting coordinates
|
|
- **360° Direction Selector**: Choose any direction with compass-style control
|
|
- **Fuzziness Tolerance**: Adjustable search radius around the line of sight
|
|
- **Tube-Line Visualization**: Shows up to 20 major cities along the path
|
|
- **Real-time Rendering**: Instant feedback on map with city markers
|
|
- **Map Style Toggle**: Switch between light and dark themes
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
### Frontend
|
|
- **Framework**: React 18
|
|
- **Map Library**: MapLibre GL JS
|
|
- **HTTP Client**: Axios
|
|
- **Styling**: Custom CSS
|
|
|
|
### Backend
|
|
- **Runtime**: Node.js 18
|
|
- **Framework**: Express.js
|
|
- **Database**: PostgreSQL 15 with PostGIS 3.3
|
|
|
|
### DevOps
|
|
- **Containerization**: Docker + Docker Compose
|
|
- **Database**: PostGIS spatial extension
|
|
|
|
## 📋 Prerequisites
|
|
|
|
- Docker 20.10+
|
|
- Docker Compose 2.0+
|
|
- Git (for repository access)
|
|
|
|
## 🚦 Getting Started
|
|
|
|
### 1. Clone Repository
|
|
|
|
```bash
|
|
git clone https://repos.retroweb.dev/ai-zone/line-of-sight.git
|
|
cd line-of-sight
|
|
```
|
|
|
|
### 2. Run with Docker
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
### 3. Access Application
|
|
|
|
- **Frontend**: http://localhost:3050
|
|
- **Backend API**: http://localhost:3001
|
|
- **Database**: localhost:5432 (PostgreSQL with PostGIS)
|
|
|
|
## 🎮 How to Use
|
|
|
|
1. **Select Point**: Click anywhere on the map to set your starting coordinate
|
|
2. **Set Direction**: Use the slider to choose 0-360° direction
|
|
3. **Adjust Tolerance**: Set fuzziness (how close cities must be to the line)
|
|
4. **Show Line of Sight**: Click the button to visualize the path
|
|
5. **View Results**: See up to 20 major conurbations along the path
|
|
|
|
## 🧪 Running Tests
|
|
|
|
### Backend Tests
|
|
```bash
|
|
docker-compose exec backend npm test
|
|
```
|
|
|
|
### Frontend Tests
|
|
```bash
|
|
docker-compose exec frontend npm test
|
|
```
|
|
|
|
## 📡 API Endpoints
|
|
|
|
### GET /api/line-of-sight
|
|
Returns conurbations along a line of sight.
|
|
|
|
**Parameters:**
|
|
- `lat` (float): Starting latitude
|
|
- `lon` (float): Starting longitude
|
|
- `direction` (int): Direction in degrees (0-360)
|
|
- `tolerance` (int): Fuzziness tolerance in km (default: 50)
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"start_point": { "lat": 51.5074, "lon": -0.1278 },
|
|
"direction": 45,
|
|
"tolerance_km": 50,
|
|
"conurbations": [...],
|
|
"line_coordinates": [...]
|
|
}
|
|
}
|
|
```
|
|
|
|
### GET /api/health
|
|
Health check endpoint.
|
|
|
|
## 🐳 Docker Commands
|
|
|
|
### Start Services
|
|
```bash
|
|
docker-compose up
|
|
```
|
|
|
|
### Start in Background
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Stop Services
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
### Rebuild and Start
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
### View Logs
|
|
```bash
|
|
docker-compose logs -f
|
|
```
|
|
|
|
### Access Database
|
|
```bash
|
|
docker-compose exec postgres psql -U line_of_sight -d line_of_sight
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
line_of_sight/
|
|
├── backend/
|
|
│ ├── app/
|
|
│ │ └── server.js # Express API server
|
|
│ ├── tests/ # Backend tests
|
|
│ ├── Dockerfile
|
|
│ └── package.json
|
|
├── frontend/
|
|
│ ├── src/
|
|
│ │ ├── App.js # Main React component
|
|
│ │ ├── services/ # API client
|
|
│ │ └── styles/ # CSS files
|
|
│ ├── public/
|
|
│ ├── Dockerfile
|
|
│ └── package.json
|
|
├── docker/
|
|
│ └── init.sql # Database initialization
|
|
├── docker-compose.yml # Container orchestration
|
|
├── README.md # This file
|
|
└── .gitignore
|
|
```
|
|
|
|
## 🧩 Development
|
|
|
|
### Frontend Development
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
### Backend Development
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## 📝 Current Status
|
|
|
|
**MVP Version 1.0**
|
|
|
|
- ✅ Interactive map with coordinate selection
|
|
- ✅ Direction selector (0-360°)
|
|
- ✅ Fuzziness tolerance control
|
|
- ✅ Mock API returning 20 conurbations
|
|
- ✅ Line visualization on map
|
|
- ✅ City markers with popup info
|
|
- ⏳ Real geospatial calculations (Phase 2)
|
|
- ⏳ Natural Earth data import (Phase 2)
|
|
- ⏳ GeoNames integration (Phase 3)
|
|
|
|
## 🔮 Roadmap
|
|
|
|
### Phase 1: MVP ✅
|
|
- Basic map interface
|
|
- Dummy API endpoints
|
|
- Docker containerization
|
|
|
|
### Phase 2: Real Geospatial
|
|
- Great circle calculations
|
|
- PostGIS queries with ST_DWithin()
|
|
- Natural Earth data import
|
|
|
|
### Phase 3: Enhanced Features
|
|
- GeoNames dataset integration
|
|
- 3D globe visualization
|
|
- Distance calculations
|
|
- Performance optimization
|
|
|
|
### Phase 4: Production Ready
|
|
- User authentication
|
|
- Saved searches
|
|
- Export functionality
|
|
- Mobile optimization
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Port Already in Use
|
|
```bash
|
|
# Find process using port
|
|
lsof -i :3050
|
|
lsof -i :3001
|
|
|
|
# Kill process
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Database Connection Issues
|
|
```bash
|
|
# Check if database is running
|
|
docker-compose ps
|
|
|
|
# Restart database
|
|
docker-compose restart postgres
|
|
```
|
|
|
|
### Build Issues
|
|
```bash
|
|
# Clean and rebuild
|
|
docker-compose down
|
|
docker-compose build --no-cache
|
|
docker-compose up
|
|
```
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Create a feature branch
|
|
2. Make your changes
|
|
3. Add tests for new functionality
|
|
4. Ensure all tests pass
|
|
5. Submit a Pull Request
|
|
|
|
## 📄 License
|
|
|
|
MIT License
|
|
|
|
## 📞 Support
|
|
|
|
For issues or questions, please open an issue on the repository.
|
|
|
|
---
|
|
|
|
*Built with ❤️ by Agent Zero*
|