# FR24 / noisemap

Проект шумовой карты авиации для Московской области и локального ADS-B ingest-контура на RTL-SDR.

## Что внутри
- **noisemap / FR24-прототип** — визуализация и расчёт шумовой плотности на базе исторических данных Flightradar24
- **RTL-SDR ingest-контур** — локальный приём ADS-B, хранение в PostgreSQL/PostGIS и recovery после сбоев

## Куда смотреть
- `tasks/flightradar24/PROJECT.md` — общий статус проекта
- `tasks/flightradar24/docs/INDEX.md` — карта документации
- `tasks/flightradar24/docs/ARCHITECTURE.md` — контейнерная архитектура ingest-контура
- `tasks/flightradar24/docs/RTL-SDR_TZ.md` — ТЗ на RTL-SDR ingest
- `tasks/flightradar24/docs/VM_SETUP.md` — инструкция по созданию VM в PVE
- `tasks/flightradar24/docs/DEV_AGENT_HANDOFF.md` — пакет передачи Dev-агенту

## Текущий статус
- FR24-прототип жив и остаётся в проекте как историческая и визуальная база
- новая линия проекта — переход к локальному RTL-SDR контуру
- целевая БД: PostgreSQL + PostGIS
- целевое развёртывание: одна VM + Docker Compose

## Историческая часть
Ниже сохранена справка по старому FR24/noisemap-прототипу.

## 📋 О проекте

Проект создаёт интерактивную веб-карту Московской области, на которой отображаются:
- **Траектории полётов** за выбранный период (до 12 месяцев)
- **Шумовые границы** вокруг траекторий, рассчитанные на основе высоты полёта
- **Интерактивные элементы**: зум, фильтры по времени, всплывающая информация о рейсах

## 🎯 Цели проекта

1. **Визуализация**: Наглядно показать распределение шумового загрязнения от авиации
2. **Анализ**: Выявить наиболее загруженные воздушные коридоры
3. **Информирование**: Предоставить данные для исследований и принятия решений
4. **Оптимизация**: Эффективное использование данных Flightradar24 API в рамках тарифа Explorer

## 🛠 Технологический стек

### Бэкенд
- **Язык**: Python 3.8+
- **Фреймворк**: FastAPI (лёгкий, асинхронный)
- **Библиотеки**: 
  - `requests` - работа с Flightradar24 API
  - `sqlalchemy` / `sqlite3` - работа с базой данных
  - `pandas` / `numpy` - обработка данных
  - `python-dotenv` - управление конфигурацией

### Фронтенд
- **Карты**: Leaflet.js с OpenStreetMap
- **Интерфейс**: Bootstrap 5 + чистый JavaScript
- **Визуализация**: встроенные возможности Leaflet + D3.js (опционально)

### Хранение данных
- **База данных**: SQLite (разработка) / PostgreSQL (production)
- **Кэш**: файловая система (JSON/CSV)
- **Конфигурация**: `.env` файл + `config.json`

## 📊 Модель шумового воздействия (v1.0)

### Основные допущения
- **Фактор**: только высота полёта
- **Зависимость**: уровень шума обратно пропорционален высоте
- **Формула**: 
  ```
  noise_radius_km = base_radius * (min_height / actual_height) * factor
  ```
  где:
  - `base_radius` = 5.0 км (базовый радиус шума)
  - `min_height` = 300 м (минимальная высота для расчёта)
  - `factor` = 0.01 (коэффициент масштабирования)

### Параметры (config.json)
```json
"noise_model": {
  "base_noise_radius_km": 5.0,
  "height_factor": 0.01,
  "min_height_m": 300,
  "max_height_m": 12000,
  "min_radius_km": 0.5,
  "max_radius_km": 10.0
}
```

### Бэклог для v2.0
- Учёт типа воздушного судна
- Учёт времени суток (ночные полёты)
- Учёт направления и скорости ветра
- Привязка к санитарным нормам

## 🚀 Быстрый старт

### 1. Установка зависимостей
```bash
pip install -r requirements.txt
```

### 2. Настройка API ключа
```bash
export FLIGHTRADAR24_API_KEY="your_api_key_here"
```
Или создайте файл `.env`:
```
FLIGHTRADAR24_API_KEY=your_api_key_here
```

### 3. Проверка подключения
```bash
python scripts/check_api.py
```

### 4. Запуск тестового сбора данных
```bash
python scripts/flightradar24_explorer.py
```

## 📁 Структура проекта

```
flightradar24/
├── README.md                    # Эта документация
├── requirements.txt             # Зависимости Python
├── config.json                  # Конфигурация проекта
├── scripts/                     # Вспомогательные скрипты
│   ├── check_api.py            # Проверка API ключа
│   └── flightradar24_explorer.py # Базовый клиент API
├── reports/                     # Отчёты и документация
│   └── ТЗ_Карта_шумового_загрязнения_Flightradar24.md
├── data/                        # Данные (будет создано)
│   ├── cache/                  # Кэшированные данные API
│   ├── processed/              # Обработанные данные
│   └── exports/                # Экспортированные файлы
├── backend/                     # Бэкенд приложения (будет создано)
├── frontend/                    # Фронтенд приложения (будет создано)
└── docs/                       # Документация (будет создано)
```

## 🔧 Конфигурация

Основные параметры настройки в `config.json`:

| Параметр | Описание | Значение по умолчанию |
|----------|----------|----------------------|
| `geography.region` | Регион исследования | Московская область |
| `geography.bounds` | Границы региона | 54.5-56.5°N, 35.5-39.5°E |
| `data_collection.target_period_months` | Целевой период данных | 12 месяцев |
| `data_collection.initial_period_days` | Начальный период для тестирования | 30 дней |
| `visualization.default_center` | Центр карты | [55.7558, 37.6173] (Москва) |
| `visualization.default_zoom` | Увеличение карты | 9 |

## 💳 Использование кредитов Flightradar24 API

### Тариф Explorer
- **Базовый лимит**: 60,000 кредитов/месяц
- **Промо-период**: до 120,000 кредитов/месяц (до 31.05.2026)
- **Обновление**: раз в неделю/месяц в зависимости от лимитов

### Примерная стоимость запросов
| Endpoint | Кредитов/запрос | Примерное использование |
|----------|-----------------|-------------------------|
| `flight/list` (live) | 5 | 100 запросов = 500 кредитов |
| `flight/{id}/history` | 20 | 50 рейсов = 1,000 кредитов |
| `flight/{id}/playback` | 30 | 30 треков = 900 кредитов |

### Стратегия оптимизации
1. **Кэширование**: Сохранять полученные данные локально
2. **Пакетная обработка**: Собирать данные партиями
3. **Приоритизация**: Сначала ключевые маршруты и периоды
4. **Мониторинг**: Регулярно проверять остаток кредитов

## 📈 План разработки

### Этап 1: Подготовка и прототип (23-25 марта 2026)
- [ ] Проверка доступности исторических данных
- [ ] Создание proof-of-concept с 10-50 траекториями
- [ ] Согласование визуализации с Заказчиком

### Этап 2: Разработка бэкенда (26-28 марта 2026)
- [ ] Архитектура FastAPI приложения
- [ ] Система сбора и обработки данных
- [ ] API для фронтенда

### Этап 3: Разработка фронтенда (29-31 марта 2026)
- [ ] Интерфейс карты (Leaflet)
- [ ] Панель управления и фильтры
- [ ] Интеграция с бэкендом

### Этап 4: Тестирование и оптимизация (1-2 апреля 2026)
- [ ] Функциональное тестирование
- [ ] Оптимизация производительности
- [ ] Документация и развёртывание

## 🔗 Полезные ссылки

- [Flightradar24 API Documentation](https://fr24api.flightradar24.com/)
- [Leaflet.js Documentation](https://leafletjs.com/)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Полное ТЗ проекта](reports/ТЗ_Карта_шумового_загрязнения_Flightradar24.md)

## 📞 Контакты

- **Заказчик**: Слава
- **Исполнитель**: Стрим (ИИ-ассистент)
- **Канал связи**: Telegram через OpenClaw

---

*Проект находится в активной разработке. Последнее обновление: 22 марта 2026.*