GeoContourMaker

Архитектура

GeoContourMaker состоит из 4 компонентов:

• Nginx — reverse proxy, WebSocket upgrade, кэш статики
• FastAPI (app) — REST API, Web UI (Jinja2), WebSocket live-feed, очередь задач
• Redis — очередь (LPUSH/BRPOP), состояние задач (Sorted Set), PubSub уведомлений
• Worker ×N — воркеры с GDAL, OpenCV, Potrace. Общение с сервером только через HTTP

Жизненный цикл задачи

Ключевые принципы

• Воркеры не имеют доступа к Redis — вся коммуникация через HTTP API сервера
• Sorted Set для индекса задач — O(log N) пагинация, без SCAN
• Heartbeat каждые 10 сек, TTL 30 сек — воркер считается offline после 20 сек тишины
• Stale recovery — задачи давнее 5 мин в running автоматически → error
• Горизонтальное масштабирование: docker compose up -d --scale worker=5

Алгоритм извлечения контура

Контур строится по индексу тайлов в GPKG-файле (таблица tiles). Не зависит от содержимого растра — трассируется именно область покрытия тайлами.

Пайплайн

1. Чтение индекса тайлов — SQLite запрос к GPKG: позиции тайлов (zoom, col, row)
2. Bitmap покрытия — 1 пиксель = 1 тайл (есть/нет). Размер: grid_w × grid_h
3. Upscale — бикубическая интерполяция до upscale_size пикселей (cv2.INTER_CUBIC) + пороговое значение 128
4. Blur (опц.) — Gaussian blur для сглаживания bitmap (blur_sigma)
5. Potrace — трассировка контура Безье-кривыми (CLI: potrace --svg)
6. Гео-трансформация — пересчёт координат из pixel space в CRS тайловой сетки
7. Simplify / Buffer — опциональное упрощение и сглаживание геометрии
8. Репроекция — перевод в EPSG:4326 (WGS 84)

Upscale-механизм

Bitmap покрытия имеет разрешение 1 пиксель = 1 тайл. При прямой трассировке контур повторяет границы тайлов (ступеньки). Upscale с бикубической интерполяцией создаёт сглаженные антиалиасные края, которые Potrace трассирует как плавные кривые — даже при alphamax=0.

upscale_size задаёт максимальную сторону bitmap после масштабирования. Больше = точнее контур, больше вершин, дольше обработка.

Быстрый старт

# Запустить сервис
docker compose up -d --build

# Проверить
curl http://localhost:8080/health

# Список доступных GPKG
curl http://localhost:8080/api/v1/gpkg

# Создать задачу извлечения контура
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"gpkg_name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm"}'

# Получить результат
curl http://localhost:8080/api/v1/tasks/{task_id}

После запуска доступны:

• Задачи — создание и мониторинг задач
• Воркеры — состояние воркеров в реальном времени
• Настройки — конфигурация параметров по умолчанию
• Swagger — интерактивная API-документация

Создать задачу

Создать задачу извлечения контура из GPKG-файла. Задача ставится в очередь Redis и обрабатывается воркером.

Параметры запроса (JSON body)

Ответ — 202 Accepted

{
  "task_id": "a1b2c3d4-...",
  "status": "queued",
  "gpkg_name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
  "queue_depth": 0
}

Примеры

curl -X POST https://contours.service.levkona.ru/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "gpkg_name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
    "upscale_size": 8000,
    "turdsize": 2,
    "alphamax": 1.0,
    "opttolerance": 0.2
  }'

const resp = await fetch('https://contours.service.levkona.ru/api/v1/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    gpkg_name: 'GTSAR_F_2023.06.20_16_1_6_SA6000_20mm',
    upscale_size: 8000,
    turdsize: 2,
    alphamax: 1.0,
    opttolerance: 0.2
  })
});
const { task_id } = await resp.json();
console.log('Task created:', task_id);

import httpx

resp = httpx.post(
    'https://contours.service.levkona.ru/api/v1/tasks',
    json={
        'gpkg_name': 'GTSAR_F_2023.06.20_16_1_6_SA6000_20mm',
        'upscale_size': 8000,
        'turdsize': 2,
        'alphamax': 1.0,
        'opttolerance': 0.2,
    },
)
task_id = resp.json()['task_id']
print(f'Task created: {task_id}')

Получить задачу

Возвращает текущее состояние задачи.

Ответ — задача в обработке

{
  "id": "a1b2c3d4-...",
  "status": "running",
  "gpkg_name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
  "created_at": 1719900000,
  "params": {
    "turdsize": 2,
    "alphamax": 1.0,
    "upscale_size": 8000
  }
}

Ответ — успешное завершение

{
  "id": "a1b2c3d4-...",
  "status": "success",
  "gpkg_name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
  "created_at": 1719900000,
  "duration_ms": 1200,
  "result_file": "/data/results/a1b2c3d4-.../contour.geojson",
  "feature_count": 1,
  "vertex_count": 9971,
  "params": {"turdsize": 2, "alphamax": 1.0, "upscale_size": 8000}
}

Ответ — ошибка

{
  "id": "a1b2c3d4-...",
  "status": "error",
  "gpkg_name": "INVALID_NAME",
  "error": "GPKG not found: INVALID_NAME in /mnt/data/GPKG",
  "duration_ms": 15
}

Примеры

curl https://contours.service.levkona.ru/api/v1/tasks/a1b2c3d4-...

const resp = await fetch('https://contours.service.levkona.ru/api/v1/tasks/a1b2c3d4-...');
const task = await resp.json();
if (task.status === 'success') {
  console.log(`Contour: ${task.vertex_count} vertices, ${task.duration_ms}ms`);
}

resp = httpx.get('https://contours.service.levkona.ru/api/v1/tasks/a1b2c3d4-...')
task = resp.json()
if task['status'] == 'success':
    print(f"Contour: {task['vertex_count']} vertices")

Список задач

Пагинированный список задач (newest first).

{
  "tasks": [...],
  "total": 142,
  "page": 1,
  "per_page": 50,
  "pages": 3
}

Удалить ошибочные / завершённые

Удалить все задачи со статусом error.

Удалить все задачи со статусом success.

{"deleted": 15}

Глубина очереди

Текущее количество задач в очереди.

{"depth": 3}

Список GPKG файлов

Возвращает список доступных GPKG-файлов из директории GPKG_DIR.

Находит как файлы в поддиректориях (name/name.gpkg), так и «голые» файлы (name.gpkg).

[
  "GTMSK_F_2023.01.21_1.6-1.9_1_2_SA6000_20mm",
  "GTMSK_F_2023.02.22_1.6-1.9_1_2_SA6000_20mm",
  "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
  "GTVOL_F_2023.05.20_2.6-2.7_1_8_SA6000_20mm"
]

Примеры

curl https://contours.service.levkona.ru/api/v1/gpkg

const files = await fetch('https://contours.service.levkona.ru/api/v1/gpkg')
  .then(r => r.json());
console.log(`Available: ${files.length} GPKG files`);

resp = httpx.get('https://contours.service.levkona.ru/api/v1/gpkg')
files = resp.json()
print(f"Available: {len(files)} GPKG files")

Метаданные GPKG

Возвращает метаданные тайловой пирамиды: доступные zoom-уровни, путь к файлу для tile-сервера.

{
  "name": "GTSAR_F_2023.06.20_16_1_6_SA6000_20mm",
  "min_zoom": 8,
  "max_zoom": 21,
  "zoom_levels": [8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21],
  "tile_path": "/data/GTSAR_F_2023.06.20_16_1_6_SA6000_20mm.gpkg"
}

Tile-метаданные (прокси)

Прокси к tiles.service.levkona.ru/metadata для обхода CORS. Возвращает полные метаданные файла: CRS, экстент, center, zoom levels.

API — Воркеры

Список всех зарегистрированных воркеров с текущим статусом.

Состояние конкретного воркера.

Обновить конфиг воркера. Body: {"enabled": false} — отключить воркер.

Удалить воркер из реестра. 204 No Content.

Логи воркеров

Последние N строк лога конкретного воркера (фильтр по hostname).

SSE-стрим новых строк лога в реальном времени (text/event-stream).

Настройки

Текущие настройки (merged с defaults).

Deep merge update настроек.

Вебхуки

Список вебхуков (секреты скрыты).

Создать вебхук. Body: {"url": "https://...", "secret": "optional"}

Удалить вебхук. 204 No Content.

Формат callback

При завершении задачи (success/error) сервер отправляет POST на URL вебхука с телом задачи. Если задан secret — заголовок X-Webhook-Signature: sha256=<hmac_hex>.

# Проверка подписи (Python)
import hmac, hashlib

expected = hmac.new(
    secret.encode(), body_bytes, hashlib.sha256
).hexdigest()
assert signature == f'sha256={expected}'

Пресеты качества

Предустановленные наборы параметров для быстрого выбора в UI. Влияют на детализацию контура и скорость обработки.

Параметры Potrace — справочник

WebSocket — Задачи

Live-события задач. При создании или обновлении задачи сервер пушит JSON в WebSocket. Используется для обновления UI в реальном времени без polling.

// JavaScript
const ws = new WebSocket('wss://contours.service.levkona.ru/ws/tasks');
ws.onmessage = (event) => {
    const task = JSON.parse(event.data);
    console.log(`Task ${task.id}: ${task.status}`);
    if (task.status === 'success') {
        console.log(`Vertices: ${task.vertex_count}, Time: ${task.duration_ms}ms`);
    }
};

WebSocket — Воркеры

Live-состояние воркеров. При подключении отправляет текущий список всех воркеров, затем пушит обновления при heartbeat.

// JavaScript
const ws = new WebSocket('wss://contours.service.levkona.ru/ws/workers');
ws.onmessage = (event) => {
    const workers = JSON.parse(event.data);
    console.log(`Online workers: ${workers.length}`);
};

Docker Compose

# Полный запуск
docker compose up -d --build

# Пересборка воркеров (после обновления алгоритма)
docker compose build worker
docker compose up -d worker

# Масштабирование воркеров
docker compose up -d --scale worker=5

# Логи
docker compose logs -f worker

# Остановка
docker compose down

Контейнеры

Переменные окружения

Kubernetes

Манифесты в директории k8s/:

# Применить все манифесты
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/

# Проверить
kubectl -n geocontour get pods
kubectl -n geocontour get hpa

Обработка ошибок

Worker Internal API

Внутренние эндпоинты для коммуникации воркер → сервер. Не предназначены для клиентов.

Swagger / ReDoc

Интерактивная API-документация:

• Swagger UI — /docs
• ReDoc — /redoc
• OpenAPI JSON — /openapi.json

Health Check

Проверка работоспособности. Используется Docker healthcheck и Kubernetes probes.

{"status": "ok"}