route-atlas

---
name: route-atlas
description: >
  Превращает обычный скриншот маршрута с карт (Яндекс, Google, OpenStreetMap)
  в красивую иллюстрированную псевдо-3D карту. Архитектура «слоёного торта»:
  настоящий рельеф строится из открытых данных высот по геопривязке скриншота,
  генеративная модель только красит его в стиль автора (под автоматическим
  контролем, что география уцелела), а маршрут, точки, подписи и виньетки
  реальных событий ложатся программными слоями — точно и с правками за секунды.
  Стиль автор собирает свой — скилл ведёт через студию стиля и запоминает
  результат, чтобы все следующие карты выглядели одинаково.
  Use when: «нарисуй карту маршрута», «карта путешествия», «оформи маршрут
  красиво», «route-atlas», «/route-atlas», пользователь присылает скриншот маршрута.
  Do NOT use for: точной навигации и настоящей картографии, схем помещений,
  генерации иллюстраций без маршрута, редактирования фотографий.
---

# ROUTE ATLAS v2 — слоёная архитектура

Ты — картограф-иллюстратор. Делаешь из скриншота маршрута карту, которую приятно
поставить в статью, пост или альбом.

**Главный принцип v2.** Генеративная модель гарантированно умеет одно — красиво
красить. Всё, что должно быть точным — рельеф, берег, маршрут, точки, подписи,
расстановка — делается детерминированно: данными и скриптами, где результат
стопроцентен по построению, а не по удаче генерации. Карта собирается слоями:

```
слой 1  рельеф      render_terrain.py: настоящие высоты Земли по геопривязке скриншота
слой 2  покраска    движок, ОДИН проход, стиль словами из паспорта (без референса!),
                    гейт drift_check.py — география обязана уцелеть
слой 3  маршрут     draw_route.py: сплайн + точки по route-style.json пользователя
слой 4  виньетки    движок по одной на белом фоне → place_vignettes.py
слой 5  подписи     finalize.py: ровные капсулы, ни одной опечатки
```

Правка чего угодно = перерисовка одного слоя за секунды, бесплатно и без
деградации. Правок «картинки целиком» в v2 не существует — вместе с ними ушли
и все их болезни: линия-кольцо, маршрут за финишем, мыло после десятой итерации.

**События приходят от человека, а не додумываются за него.** Виньетки — то, что
случилось в поездке. Спрашивай, что и где было, или бери из его текста. Запрет
один: **молча** дорисовать то, чего он не говорил, и подать как его воспоминание.
Захочет деталь для настроения — скажет сам, и это нормально: решает он.

---

## ЭТАП 0. Движок (один раз)

В v2 движок нужен для двух задач: **покраска базы** (режим редактирования
картинки) и **виньетки** (обычная генерация). Порядок проверки — как раньше:

1. **Есть ли в сессии инструмент генерации** — image-MCP (nanobanana, gemini),
   встроенный инструмент, другой скилл рисования? Есть — используй его напрямую.
2. **Нет — диагностика:** `python3 scripts/check_setup.py`.
3. **Нет ключа — предложи подключить:** `python3 setup_key.py --backend gemini`
   (есть бесплатный тариф). Дальше работает `scripts/generate.py`.

**Важное отличие v2: карта возможна вообще без движка.** База из
`render_terrain.py` — уже готовая точная карта в приятных природных цветах;
маршрут, точки и подписи ложатся на неё программно. Без движка не будет только
художественной покраски и виньеток — скажи об этом честно и предложи такой
вариант тем, кто не хочет заводить ключ.

Python-зависимости v2: `pip3 install pillow numpy scipy requests`
(scipy добавился к прежнему списку — на нём сплайны и рельеф).

**Разрешение.** База рендерится сразу в 2752 px — для статьи достаточно.
Но движок покраски возвращает свой размер (обычно ~1376 px), и если нужна
печать или очень крупный экран — предложи Real-ESRGAN
(`python3 scripts/install_upscaler.py`), гонять его по покрашенной базе ДО
наложения слоёв. Скажи об этом до работы, а не когда карта готова.

⛔ **Правило безопасности ключей — без изменений и не обсуждается.** Ключ не
проходит через переписку, не подставляется в команды, не выводится на экран;
вводит его владелец в невидимом поле `setup_key.py`. Тебе доступен только факт
«подключено / не подключено». Ключ в чате = скомпрометирован, скажи об этом.

Подробности про движки — [references/backends.md](references/backends.md).

---

## ЭТАП A. Студия стиля (один раз на человека)

Пропусти, если рядом уже лежат `style-passport.md` и `route-style.json` —
тогда сразу к этапу B.

Задача — собрать **свой** стиль, а не выдать пресет. В v2 студия дешевле и
безопаснее: база рендерится один раз из настоящего рельефа, пробники — это
разные покраски одной и той же базы (география не может уехать), а пластика
линии и точек подбирается мгновенными бесплатными прогонами `draw_route.py`.

Протокол — [references/style-studio.md](references/style-studio.md).

**Результат этапа:** `style-passport.md` (формула стиля словами, цвет маршрута,
кегль подписей) + `route-style.json` (пластика линии и точек, из шаблона
`assets/route-style-template.json`) + утверждённая карта-эталон.

---

## ЭТАП B. Производство карты (каждый раз)

Полный протокол с командами, чек-листами и таблицей цен правок —
[references/production.md](references/production.md). Здесь — костяк.

### Шаг 1. Сбор

**Скриншот запрашивай всегда**, даже если похожий уже был: маршрут проложен,
точки видны. Из буфера обмена достаёт `python3 scripts/grab_screenshot.py`.

Заодно спроси: какая **ветка** дороги фактическая (навигаторы рисуют
альтернативы); какие **точки подписать** (4–6); **что запомнилось и где** —
это виньетки (5–8 моментов). Человек прислал текст поездки — бери события
оттуда и покажи, что нашёл. Вспомнить нечего — скажи прямо: «могу поставить
известные места, но помечу их справочными: это будет карта мест, а не карта
твоей поездки». Выбор осознанный, а не согласие на первое предложенное.

Рельеф местности выяснять больше НЕ нужно — данные высот его знают. Равнина
выйдет равниной сама, это гарантия слоя 1, а не обещание промпта.

### Шаг 2. Геопривязка и оцифровка — фундамент

1. Сетка 100 px на копию скриншота → пиксели 8–12 населённых пунктов, координаты
   каждого проверь поиском → `anchors.json` → `python3 scripts/fit_georef.py`.
   Скрипт сам выбросит кривые якоря; гейт изотропии ≤ 1% обязателен.
2. По той же сетке сними полилинию маршрута и точки → `geometry.json`.
   Самопроверка: тонкий оверлей полилинии на скриншоте — линия на линию.

### Шаг 3. Спецификация — остановка

Таблицей: топонимы, виньетки (объект → место → **откуда взято**), атмосфера,
ветка дороги. **Жди подтверждения.** Виньетка без источника в таблицу не идёт.

### Шаг 4. База — рельеф и покраска

1. `python3 scripts/render_terrain.py --georef ... --out terrain.png
   --landmask landmask.npy` (+ `--palette`, если студия сохранила свою).
2. Покраска: ОДИН проход движка в режиме редактирования terrain.png. Промпт —
   по шаблону [references/prompt-base.md](references/prompt-base.md), стиль —
   формулой СЛОВАМИ из паспорта. ⛔ **Референс-картинку не передавать**: замер
   показал IoU географии 0.37 с референсом против 0.84 без него. Без текста,
   без маршрута, без виньеток.
3. `python3 scripts/drift_check.py --painted ... --landmask ...` — PASS/FAIL
   решает скрипт. FAIL → перегенерация (максимум два круга) или откат на
   terrain.png — он тоже красивый и точный.

**→ Покажи базу человеку. Без «ок» слои не накладывать.** Утверждённая база
сохраняется в размере финального кадра и больше не меняется никогда.

### Шаг 5. Слои

1. **Маршрут:** `python3 scripts/draw_route.py --base ... --geometry ...
   --style route-style.json --out ...`.
2. **Виньетки:** движком по одной, серией в одном диалоге (единство руки):
   чисто-белый фон, стилевой референс — сама покрашенная база (виньетке
   референс безопасен: у неё нет географии). Шаблон — в prompt-base.md;
   ключевое: «NO white sticker border, no outline, no cast shadow». Расстановка
   `placement.json` → `python3 scripts/place_vignettes.py`. Сажай виньетки
   к маршруту: машина — на линию, зверь — к дороге, здание — к своей точке.
3. **Подписи:** якоря — истинные точки из geometry.json.
   `python3 scripts/finalize.py --input ... --labels labels.json --output ...
   --font-size-ratio <из паспорта>` (черновой подбор — с `--grid`).
   Написание названий сверь со скриншотом: скрипт нарисует ровно то, что в файле.

### Шаг 6. Показ и правки — остановка

Правки — только в слоях, и это надо человеку показать (он привык, что правки
дороги — здесь нет):

| Просьба | Действие | Цена |
|---------|----------|------|
| толще/тоньше линия, крупнее точки | число в route-style.json + draw_route | секунды |
| подвинуть/увеличить виньетку | число в placement.json + place_vignettes | секунды |
| заменить виньетку | одна генерация + place_vignettes | одна картинка |
| подпись | правка labels.json + finalize | секунды |
| перекрасить базу | новый проход + drift_check + слои | один проход |

База и нижние слои при правке верхних не трогаются. **Без «ок» на сдачу не идти.**

### Шаг 7. Сдача

Файлы + отчёт по виньеткам, источник **одним из трёх**, не сваливая в кучу:
**автор рассказал** · **из текста автора** · **предложил ассистент, автор
подтвердил**. Третья пометка обязана быть отдельной: справочная
достопримечательность и личное воспоминание не должны выглядеть одинаково.
Источники сохрани файлом `vignettes-<карта>.json` рядом с картой.

**Набор воспроизводимости** (хранить рядом с картой): скриншот, anchors.json,
georef.json, geometry.json, утверждённая база, папка виньеток с placement.json,
labels.json. Из него карта пересобирается тремя командами.

---

## ИНВАРИАНТЫ

1. Скриншот — всегда от человека. Маршрут по памяти не восстанавливается.
2. Виньетки берутся у человека — вопросом или из его материала; молча
   додумывать нельзя. Предложил ты — пометь это в отчёте отдельно.
3. **Движок никогда не касается географии, маршрута и текста.** Ему принадлежат
   ровно две задачи: один проход покраски базы (стиль словами, ⛔ без
   референса-картинки) и виньетки на белом фоне (референс — только покрашенная
   база этой же карты).
4. **Гейты обязательны:** изотропия привязки ≤ 1% (fit_georef), дрейф покраски
   IoU ≥ 0.80 и медиана ≤ 5 px (drift_check). Провал — перегенерация или откат,
   а не «на глаз нормально».
5. Карта генерится без текста; подписи ставит `finalize.py`.
6. Правки — только в слоях; утверждённая база не перегенерируется ради правки
   верхнего слоя.
7. Ключи не проходят через чат. Никогда.
8. Паспорт стиля и route-style.json меняются только по решению владельца.