# Audion Cars Counter — руководство пользователя

**Содержание**

- [Что нужно](#что-нужно)
- [Запуск и установка](#запуск-и-установка)
- [Снимки и папки](#снимки-и-папки)
- [Коротко: от снимков до отчёта](#коротко-от-снимков-до-отчёта)
- [Как устроено окно](#как-устроено-окно)
- [ИЗОБРАЖЕНИЯ](#изображения)
- [ПРОСМОТР](#просмотр)
- [СЧЁТ](#счёт)
- [Своя сеть под свои снимки](#своя-сеть-под-свои-снимки)
- [НАСТРОЙКИ](#настройки)
- [Клавиши](#клавиши)
- [Чего ждать от точности](#чего-ждать-от-точности)
- [Где что лежит](#где-что-лежит)
- [Что программа делает в сети и на машине](#что-программа-делает-в-сети-и-на-машине)
- [Если что-то не так](#если-что-то-не-так)

Программа считает легковые автомобили на спутниковых снимках с привязкой к местности: сколько
их на каждом снимке и на всём наборе, где стоит каждый и какова плотность по районам. Итог —
число с границами, документ Word, ведомость Excel и слои для MapInfo.

Счёт идёт на вашей машине. Снимки никуда не отправляются.

Считает программа обученной сетью. С публичным выпуском идёт сеть `open-03`: она обучена на
свободных аэрофотоснимках трёх открытых государственных служб и ни на чём другом, и новый
набор снимков считается ею сразу. Ваши снимки — другой источник, чем те, что она видела:
прежде чем верить счёту, проверьте сеть на нескольких участках, размеченных глазом. Свою сеть
обучают на своих снимках вместе с ИИ-агентом или кладут в программу файл
сети, который вам передали: см. раздел «Своя сеть под свои снимки». Чего стоит сеть, обученная
таким способом, сказано в разделе «Чего ждать от точности» — прочитайте его до того, как
пользоваться числом.

## Что нужно

- Windows 10 или 11, 64 бита.
- Видеокарта NVIDIA с драйвером 570 или новее — быстрый путь: у автора снимок в 165
  мегапикселей (12490 × 13253) на RTX 5070 считался около минуты. Без такой видеокарты счёт
  идёт на процессоре: счёт тот же, но такой снимок занимал около двадцати минут на процессоре
  ноутбука.
- Интернет на время установки и место на диске: скачивается от 0,7 до 3,4 ГБ; установленная
  программа занимает около 7 ГБ на машине с видеокартой NVIDIA и около 3,5 ГБ без неё.
- Снимки: папка файлов `.jpg`, у каждого рядом — файл привязки растра MapInfo `.tab`
  (подробно — в разделе «Снимки и папки»).
- Обученная сеть. С публичным выпуском идёт сеть, обученная на свободных аэрофотоснимках; свою
  сеть обучают на своих снимках или кладут в
  программу («Своя сеть под свои снимки»).
- MapInfo — только если нужны слои для карты; для счёта и отчёта он не нужен.

## Запуск и установка

Распакуйте папку программы куда угодно и запустите `Start.exe`. Всё своё программа держит в
этой папке. В Windows ставится одно: Microsoft Visual C++ Redistributable, который нужен
PyTorch, — и только если его там нет.

При первом запуске движка счёта ещё нет: окно само открывает раздел **УСТАНОВКА** и
спрашивает, ставить ли его. В вопросе сказано, что без движка программа показывает снимки, но
не считает, сколько гигабайт скачается под эту машину и что будет поставлено в Windows.
Ничего не скачивается, пока вы не ответите **СКАЧАТЬ И УСТАНОВИТЬ**; после отказа тот же
вопрос задаёт кнопка **УСТАНОВИТЬ НУЖНОЕ**:

1. Карточка **ЭТА МАШИНА** показывает процессор, память, видеокарты и то, что из них следует:
   пойдёт счёт на видеокарте NVIDIA или на процессоре.
2. Нажмите **УСТАНОВИТЬ НУЖНОЕ** и подтвердите. Под названием кнопки написано, чего этой
   машине не хватает. Первым шагом программа смотрит, есть ли в Windows Microsoft Visual C++
   Redistributable, и, если нет, ставит его через winget — Windows спросит разрешение
   администратора. Потом ставит свой Python 3.12 в папку `runtime`, PyTorch под эту машину (с
   CUDA на видеокарте NVIDIA, иначе для процессора) и библиотеки.
3. Ход установки виден в журнале — он открывается сам. Установку можно остановить кнопкой
   СТОП и запустить заново.
4. Когда всё поставлено, программа удаляет скачанные установочные файлы, а карточка **ЧТО
   УСТАНОВЛЕНО** говорит: «Всё на месте: можно считать». В программе без сети она говорит
   другое: «Движок установлен. Обученной сети нет: считать пока нечем», и одна из её строк —
   «Обученной сети нет». Это не ошибка установки: сеть ещё предстоит обучить или положить в
   программу — см. «Своя сеть под свои снимки».

Остальные кнопки карточки УСТАНОВИТЬ чинят одну часть: **ОКРУЖЕНИЕ ЦЕЛИКОМ** ставит всё
заново, когда движок не отвечает; **PYTORCH ДЛЯ NVIDIA** — счёт на видеокарте (около 3 ГБ);
**PYTORCH ДЛЯ ПРОЦЕССОРА** — для машины без видеокарты NVIDIA (около 0,7 ГБ). Каждая
перед загрузкой спрашивает.

Если драйвер NVIDIA старше 570, раздел скажет об этом, и счёт пойдёт на процессоре. Обновите
драйвер и нажмите **ПРОВЕРИТЬ СНОВА**: раздел покажет, что теперь нужно поставить PYTORCH ДЛЯ
NVIDIA.

## Снимки и папки

**Какие снимки берёт программа.** Папку файлов `.jpg`; рядом с каждым лежит файл привязки
растра MapInfo `.tab` с тем же именем. Имя файла снимка кончается номером столбца и строки
снимка в наборе: `…_2-3.jpg` — второй столбец, третья строка сверху. По этим номерам
программа раскладывает снимки на карте набора; одиночный снимок называется так же, например
`…_1-1.jpg`.

Из файла `.tab` программа берёт размер снимка, размер пикселя на местности, площадь и
координаты; его единицы она принимает за метры. Сеть автора училась на снимках около 0,3 м в
пикселе. Снимки программа только читает.

**Куда их положить.** Двумя способами:

- *Рядом с программой.* Программа сама ищет рядом со своей папкой папку данных:
  `Audion Counters Data\Cars Counter`, а если её нет — `Cars Counter`. Положите снимки в
  папку с любым именем внутри её папки `Pictures` — например, `Pictures\Город`, — и рабочая
  папка `Work` появится сама. Настраивать ничего не нужно. Если таких папок в `Pictures`
  несколько, считается та, на которой сделана папка `Work`, а в новой папке данных — первая
  по имени; любую другую называют в НАСТРОЙКАХ.
- *В любой папке.* В разделе НАСТРОЙКИ назовите папку со снимками (карточка СНИМКИ) и рабочую
  папку (карточка РАБОЧАЯ ПАПКА); пустая рабочая папка годится.

Автоматические проверки программы шли первым способом; сами диалоги выбора папки ими не
проходились.

**Рабочая папка** — всё, что программа делает из снимков: итоги счёта, плитки для просмотра,
разметка, сети, обученные на этой разметке. Она принадлежит одному набору снимков: с другими
снимками программа ей откажет. Другой город или другая съёмка того же места — это другой
набор со своей рабочей папкой; числа двух наборов не складываются.

## Коротко: от снимков до отчёта

1. УСТАНОВКА, **УСТАНОВИТЬ НУЖНОЕ** — один раз.
2. Положите снимки рядом с программой или назовите их папку в НАСТРОЙКАХ. Если окно в это
   время было открыто, нажмите **ПЕРЕЧИТАТЬ**.
3. Сеть — один раз, когда в программе её нет: обучите её на своих снимках вместе с
   ИИ-агентом или положите файл сети, который вам передали («Своя сеть под свои снимки»).
4. СЧЁТ, **ПОСЧИТАТЬ СНИМКИ**.
5. Щёлкните по снимку в таблице ПО СНИМКАМ и посмотрите в ПРОСМОТРЕ, на чём стоят отметки.
6. СЧЁТ, **ОТЧЁТ ПО ВСЕМ СНИМКАМ**; для карты — **СЛОИ ДЛЯ MAPINFO**.

## Как устроено окно

- **Вверху** — название программы с версией; три раздела работы по порядку: ИЗОБРАЖЕНИЯ,
  ПРОСМОТР, СЧЁТ — под названием каждого его состояние (сколько снимков, какой открыт,
  сколько посчитано); справа — язык (RU | EN), тёмная и светлая тема, размер шрифта.
- **Внизу слева** — УСТАНОВКА, НАСТРОЙКИ и О ПРОГРАММЕ; повторное нажатие возвращает к
  разделу работы. **Внизу справа** — кнопка **ПЕРЕЧИТАТЬ**: заново прочитать набор, когда
  снимки, разметку или счёт поменяли не из этого окна.
- Строкой выше — кнопка **F1 DOCS** (это руководство), сообщения программы, ход долгой
  операции с кнопкой **СТОП** и кнопка **ЖУРНАЛ**: всё, что делает программа, и вывод движка.
- У каждой кнопки и карточки есть подробная подсказка: задержите на ней мышь.

В окне снимок местами назван «изображением» — это одно и то же.

## ИЗОБРАЖЕНИЯ

Карта набора: каждый снимок стоит на своём месте по столбцу и строке из имени файла. На
плитке — имя снимка (`2-3`); если на нём есть разметка — сколько участков и машин размечено;
если он посчитан — «сеть:» и число отметок. Подсказка плитки называет размер снимка в
пикселях, размер пикселя в метрах и площадь. Щелчок открывает снимок в ПРОСМОТРЕ.

Мелкие копии снимков для карты программа делает один раз, при первом чтении набора; для
набора из 31 снимка это меньше минуты.

Справа:

- **НАБОР** — итоги: сколько снимков, мегапикселей, какая площадь, сколько размечено и какие
  сети есть; кнопка **ПАПКА СНИМКОВ**.
- **ОТВЕТЫ СЕТИ** — чей счёт показан на карте и в ПРОСМОТРЕ («Счёт сети:») и с какой
  уверенности ответ программы показывается как автомобиль («Порог уверенности:»). Эта
  карточка — рабочее место того, кто проверяет и учит сеть. Раздел СЧЁТ от неё не зависит: он
  всегда показывает счёт при той уверенности, с которой сеть принята.

## ПРОСМОТР

Один снимок. Посередине — кусок снимка крупно, справа — снимок целиком и карточка УЧАСТОК,
слева — инструменты разметки и слои. Снимок в 165 мегапикселей целиком в окно не грузится:
при первом открытии программа один раз режет его на плитки — около десяти секунд и около
100 МБ в рабочей папке на снимок.

- Кусок двигается шагами по двум осям — стрелками на клавиатуре или кнопками-стрелками: при
  осмотре подряд ничего не пропускается. Щелчок по снимку целиком переносит крупный вид в это
  место.
- Размер куска выбирается кнопками: **КРУПНО** (120 × 120 пикселей), **УЧАСТОК** (240 × 240,
  около 75 × 75 м), **2 × 2**, **4 × 4**. Вокруг куска приглушённо видна полоса соседней
  местности.
- **ПРЕДЫДУЩИЙ** и **СЛЕДУЮЩИЙ** (Page Up, Page Down) ведут по размеченным участкам.
- **К КАРТЕ** возвращает в раздел ИЗОБРАЖЕНИЯ.
- Под кнопками написано, где стоит кусок, сколько в рамке размеченных машин и сколько ответов
  сети.

Карточка **СЛОИ** — что нарисовано поверх снимка:

- **ОТВЕТЫ СЕТИ** — отметки программы: голубые кольца, рядом уверенность в сотых долях;
- **РАЗМЕТКА** — точки, поставленные глазом, и рамки размеченных участков: зелёный кружок —
  машина, оранжевый квадрат — грузовик или автобус, жёлтое кольцо — «не разобрать»;
- **ОСВЕТЛИТЬ** — осветляет снимок, чтобы тёмные автомобили в тени дома отделились от тени.
  На счёт это не влияет — только на то, что видно в окне.

На снимке целиком зелёные квадраты — размеченные участки, голубые точки — отметки программы,
оранжевая рамка — то, что показано крупно.

Чтобы проверить счёт глазами, разметка не нужна: откройте посчитанный снимок, включите слой
ОТВЕТЫ СЕТИ и пройдите стрелками несколько мест — стоянку, двор, промзону, лес.

### Разметка

Разметка — точки, которые человек ставит на автомобили глазом. На ней учат сеть и по ней её
проверяют. Чтобы считать сетью, которая уже есть, размечать ничего не нужно.

Участок — квадрат 240 × 240 пикселей, размеченный **целиком**: у каждого автомобиля точка, а
всё остальное в рамке для сети — «земля», место без автомобиля. Поэтому, начав участок,
пройдите его весь.

| Инструмент (клавиша) | Что делает щелчок |
|---|---|
| СМОТРЕТЬ (1) | ничего не ставит |
| МАШИНА (2) | точка на легковой автомобиль: легковой, внедорожник, фургон, пикап. Точка ставится в середину автомобиля |
| ГРУЗОВИК (3) | грузовик, автобус, прицеп, техника: в счёт не идёт, и «землёй» сеть на нём не учат |
| НЕ РАЗОБРАТЬ (4) | тёмное пятно в тени, наполовину под деревом — то ли автомобиль, то ли нет: в счёт не идёт, сеть на нём не учат |
| СТЕРЕТЬ (5) | щелчок по точке убирает её |

Щелчок по точке другим инструментом меняет её вид, своим — убирает; правая кнопка мыши
стирает при любом инструменте. Первая точка в квадрате сетки делает этот квадрат участком.

Кнопки участка работают, когда показан один участок (размер УЧАСТОК):

- **УЧАСТОК БЕЗ МАШИН** записывает участок как размеченный, на котором нет ни одного
  автомобиля: для крыш, леса, кладбища — всего, что программа принимает за автомобили;
- **ВЗЯТЬ ОТВЕТЫ СЕТИ** ставит точку «машина» на каждую отметку программы в участке — как
  черновик: лишнее потом убирается, пропущенное добавляется;
- **ОТМЕНИТЬ** (Ctrl+Z) возвращает разметку участка к виду до последней правки;
- **УБРАТЬ УЧАСТОК** убирает участок из разметки целиком. Файл не стирается, а переносится в
  папку `labels\_removed` рабочей папки.

Каждая правка сразу пишется в файл.

Как размечать:

- сомневаетесь — ставьте НЕ РАЗОБРАТЬ: неверная точка учит хуже, чем пропущенная;
- точка ставится на середину автомобиля, а не на нос; в ряду стоящих автомобилей считайте
  вдоль ряда;
- тёмные автомобили в тени дома там есть: включите ОСВЕТЛИТЬ и ищите пары светлых точек
  стёкол;
- не автомобили: надгробия рядами, вентиляция и люки на крыше, грядки и теплицы, штабели
  поддонов, лодки, крыши сараев и гаражей, одиночные светлые кроны.

## СЧЁТ

Слева — карточки **СЧЁТ** и **ОТЧЁТ**, справа — таблица **ПО СНИМКАМ**; прокручивается только
таблица.

**ПОСЧИТАТЬ СНИМКИ** считает все снимки набора, которые ещё не посчитаны: программа проходит
каждый снимок и ставит отметку на каждый легковой автомобиль. Уже посчитанные снимки не
пересчитываются: добавили новые — посчитаются только они. Число снимка появляется в таблице и
на карте, как только он посчитан. Остановить счёт можно кнопкой СТОП внизу окна: посчитанное
остаётся, следующий запуск продолжит с непосчитанных. Пока идёт счёт, компьютер сам не уснёт.

Без сети кнопка приглушена, а карточка говорит: «Обученной сети нет ни в рабочей папке, ни в
программе: считать нечем.» См. «Своя сеть под свои снимки».

Крупные числа карточки СЧЁТ:

- **отметок программы** — сколько мест на снимках программа сочла легковыми автомобилями;
- **автомобилей, в этих границах** — от … до …, см. «Как понимать число»;
- **снимков посчитано**;
- **км² снято** — площадь посчитанных снимков;
- **отметок на км²** — плотность.

Таблица **ПО СНИМКАМ** — то же по каждому снимку: отметок, автомобилей от и до, площадь,
плотность на км². Щелчок по имени снимка открывает его в ПРОСМОТРЕ с отметками.

### Как понимать число

Отметка программы — место на снимке, которое программа сочла легковым автомобилем. Число
отметок — ещё не число автомобилей:

- при таком разрешении многие тёмные пятна не разберёт и человек — автомобиль это или тень, —
  а программа отмечает часть из них;
- часть автомобилей в тени и в плотных рядах она пропускает;
- отдельные отметки стоят на грузовиках и на том, что автомобилем не является.

Поэтому число всегда называется с границами: **автомобилей от «отметки минус четверть» до
«отметки плюс половина»**. Тысяча отметок — это от 750 до 1500 автомобилей. Одно число без
границ называть нельзя.

**Плотность** — отметок на квадратный километр снятой площади; по ней сравнивают районы:
застройка даёт сотни отметок на квадратный километр, лес и вода — единицы.

Снимок показывает автомобили под открытым небом в минуту съёмки.

### Отчёт: файлы Word и Excel

Карточка **ОТЧЁТ** выгружает результат в папку, которую вы назовёте:

- **ОТЧЁТ ПО ВСЕМ СНИМКАМ** — по всем посчитанным снимкам;
- **ОТЧЁТ ПО ЭТОМУ СНИМКУ** — по одному снимку, тому, что открыт в ПРОСМОТРЕ;
- **ПАПКА ОТЧЁТОВ** — открывает папку последней выгрузки.

Файлов два, оба написаны для инженера-транспортника, на языке окна.

**Документ Word** («Отчёт об учёте автомобилей …») начинается с главных чисел — снимков,
отметок программы, автомобилей не меньше и не больше, площадь, отметок на км² — и абзаца «Как
понимать число». Дальше идут схема снимков, как они лежат на местности, с числом отметок на
каждом; таблица по снимкам с итогом; и по странице на снимок: снимок с точкой на каждой
отметке и восемнадцать отметок, взятых наугад и увеличенных, — видно, что именно программа
сочла автомобилем. Последняя страница — «Как читать отчёт».

**Ведомость Excel** («Ведомость учёта автомобилей …»): лист «Сводная» — таблица по снимкам с
итогом (у снимка с разметкой рядом стоит число автомобилей, проверенных глазом); лист
«Чувствительность» — сколько отметок осталось бы при другой строгости программы; лист
«Отметки» — каждая отметка с местом на снимке и координатами на местности, его можно положить
на карту; лист «Служебное» — чем посчитано, для того, кто обслуживает программу.

Имя файла содержит дату и время: новый отчёт прежнего не затирает. Отчёт ничего не считает
заново — числа берутся из счёта, поэтому его всегда можно выгрузить ещё раз. Набор из 31
снимка даёт документ на 46 страниц, около 15 МБ, за 20 секунд.

На странице снимка смотрите лист образцов. Если на нём много не автомобилей — крыши,
надгробия, блики на воде, — числу по этому снимку доверять нельзя: см. «Чего ждать от
точности».

### Слои для MapInfo

**СЛОИ ДЛЯ MAPINFO** выгружает счёт для карты в системе координат привязки ваших снимков —
она берётся из их файлов `.tab`, поэтому слои ложатся на снимки без подгонки.

Перед выгрузкой выберите **Квадрат сетки**: 100, 250, 500 или 1000 м. Мельче — видны
отдельные стоянки и дворы, но карта рябит; крупнее — видны районы. Место каждой отметки от
этого не зависит.

| Файл | Что в нём |
|---|---|
| `Автомобили_растр_плотности_….png` и `.tab` | карта плотности картинкой со своей привязкой: в MapInfo открывается сразу (Файл > Открыть). Квадрат закрашен по числу отметок; белый — снято и пусто, серый — снимка здесь нет |
| `Автомобили_отметки_….mif` и `.mid` | каждая отметка точкой: снимок, уверенность программы, место на снимке |
| `Автомобили_сетка_250м_….mif` и `.mid` | сетка квадратов: номер квадрата, отметок, автомобилей от и до, покрытие снимками в процентах, площадь покрытой части, плотность на км² |
| `Автомобили_снимки_….mif` и `.mid` | контуры посчитанных снимков с итогами |
| `Автомобили_карта_плотности_….png`, `Автомобили_карта_плотности_тёмная_….png` | та же карта со шкалой цветов и подписью: на светлом фоне для отчётов и писем, на тёмном — для экрана и слайдов |
| `Автомобили_слои_описание_….txt` | описание слоёв и столбцов |

В имени файла сетки стоит выбранная сторона квадрата, в конце каждого имени — дата и время
выгрузки. При английском языке окна имена файлов и столбцов английские. Слои `.mif` —
обменный формат MapInfo: Таблица > Импорт, выбрать файл `.mif` (одноимённый `.mid` должен
лежать рядом).

- Квадраты сетки привязаны к местности, а не к снимкам: у двух выгрузок с одной стороной
  квадрата квадраты одни и те же, их можно сравнивать один к одному.
- Квадрат на краю набора покрыт снимками частично: плотность считается по покрытой части, а
  столбец «Покрытие_проц» говорит, сколько это.
- Пустые квадраты в сетке есть: «автомобилей нет» — тоже ответ.
- Квадрат с двумя-тремя отметками может быть пустым, а квадрат с сотней — стоянкой: судить по
  районам и кварталам надёжнее, чем по одному квадрату.
- Снимок без файла `.tab` в слои не попадает.

**Что не проверено.** Файлы слоёв прочитаны обратно и сверены по числам, но в самом MapInfo
не открывались ни разу. Если импорт не проходит или в слоях чего-то не хватает — это первое,
что нужно поправить в программе.

## Своя сеть под свои снимки

С публичным выпуском программы идёт сеть `open-03`. Она обучена со случайного начала на
разметке, поставленной глазом на свободных аэрофотоснимках, — 2334 автомобиля на 22 снимках
трёх открытых государственных служб (Нидерланды, Эстония, Германия), 0,31 м на пиксель, — и ни
на чём другом. На трёх снимках тех же служб, на которых её не учили, она посчитала +2 % к 296
автомобилям, размеченным глазом (найдено 92 %); на спутниковых снимках четвёртого источника,
которых не видела вовсе, — +1 % к 511 автомобилям (найдено 89 %). Это её числа на тех снимках.
Ваши — ещё один источник: сеть, которая держится на четырёх, может не удержаться на пятом,
поэтому сначала разметьте несколько участков и проверьте её — порядок ниже с этого и
начинается.

Своя сеть появляется одним из двух способов.

- *Её обучают на своих снимках* вместе с ИИ-агентом — порядок ниже. Обученная сеть лежит в
  рабочей папке набора и считает этот набор.
- *Файл сети, который вам передали* (`<имя>.pt`), кладут в папку `system_core\nets` программы
  и называют в файле `config\counting_default.json`: `{"net": "<имя>", "least": 0.20}` — имя
  файла без `.pt` и уверенность, с которой отметка идёт в счёт: её называет тот, кто передал
  сеть. Если окно в это время было открыто, нажмите **ПЕРЕЧИТАТЬ**, а в разделе УСТАНОВКА —
  **ПРОВЕРИТЬ СНОВА**. Сеть, которая лежит в программе, считает каждый набор, у которого нет
  своей принятой сети: новый набор снимков считается сразу. Сеть, которую вы обучили сами,
  кладут туда так же — чтобы считать ею и другие наборы.

Сеть знает снимки, на которых её учили, — как правило, один город и один источник. На другом
источнике или на местности, какой она не видела, её нужно сначала проверить, а если проверку
она не прошла — обучить сеть на своих снимках. Кнопок для этого в окне нет: обучение сети и её
проверка — команды движка. Точки можно ставить самому в разделе ПРОСМОТР или поручить это
агенту.

Порядок такой (подробно, с командами, — в руководстве для агента):

1. **Проверка того, что есть** — когда сеть есть. Посчитать ею два-три снимка и посмотреть
   образцы отметок; разметить глазом ровную сетку участков на двух-трёх снимках и сравнить
   счёт с разметкой. Без сети проверять нечего: работа начинается со следующего шага, и
   каждая точка ставится глазом.
2. **Проверочные снимки.** Несколько снимков размечаются только для проверки, и на них сеть
   не учат никогда: иначе проверка покажет то, что сеть уже видела.
3. **Разметка для обучения** — на других снимках: ровная сетка и места, где сеть ошибается
   (стоянки в тени, плотные ряды, дворы; крыши, кладбища, вода — участками без машин).
4. **Обучение.** Учатся четыре сети на одной и той же разметке и склеиваются в один файл:
   одно обучение отличается от другого само по себе (до 13 % в счёте на той же разметке), а
   четыре вместе отвечают ровнее. Для вас это одна сеть — один файл, одно имя. На RTX 5070
   четыре обучения идут около десяти минут; на процессоре ноутбука одно занимает около двух с
   половиной часов.
5. **Проверка новой сети** на проверочных снимках, две таблицы: одинакова ли ошибка от места
   к месту и держится ли счёт, когда снимок выглядит иначе — светлее, мягче, сильнее сжат.
6. **Принятая сеть** записывается в рабочую папку набора, и кнопка ПОСЧИТАТЬ СНИМКИ считает
   ею. Сеть, которая лежит в программе, если она там есть, остаётся на месте.

Что мы узнали:

- решает не длина обучения и не размер сети, а разметка — сколько её и насколько она разная;
- ещё разметка того же вида после некоторого предела ничего не прибавляет: учить нужно то,
  что проверка провалила;
- местность нового вида без разметки даёт ложные отметки сотнями; когда её размечают
  участками без машин, они уходят;
- если снимки местами размыты, устойчивого счёта на них не добиться никаким обучением.

### Работа с Claude и Codex

Программа сделана так, чтобы с ней можно было работать вместе с ИИ-агентом — Claude Code или
Codex, — как работали её авторы. Руководство для агента —
[`Docs\AI_AGENT_GUIDE_RU.md`](AI_AGENT_GUIDE_RU.md) (английское —
[`AI_AGENT_GUIDE_EN.md`](AI_AGENT_GUIDE_EN.md)): команды движка, форматы файлов, порядок
работы и то, что уже измерено.

**Как начать.** Установите программу (УСТАНОВКА, УСТАНОВИТЬ НУЖНОЕ), назовите папку снимков,
откройте папку программы в Claude Code или Codex и первым сообщением попросите прочитать
`Docs\AI_AGENT_GUIDE_RU.md`. Дальше говорите обычными словами:

- «Сети ещё нет: доведи меня до первой; смотреть снимки разрешаю» — или, когда сеть есть,
  «Проверь, как сеть считает мои снимки; смотреть снимки разрешаю»;
- «Разметь проверочные участки сеткой на снимках 2-3 и 4-1, я посмотрю их в ПРОСМОТРЕ»;
- «Обучи сеть под эти снимки и скажи, держится ли у неё ошибка»;
- «Посчитай весь набор новой сетью и выгрузи отчёт в такую-то папку».

**О снимках.** Агент работает на вашей машине, и сами снимки никуда не уходят. Но то, что
агент рассматривает — уменьшенный снимок для выбора участков, увеличенные участки для
разметки, листы образцов, — уходит в сервис, на котором он работает (Anthropic у Claude,
OpenAI у Codex). У спутниковых снимков обычно есть условия использования поставщика:
проверьте их. Агент должен спросить разрешения до первой картинки. Если снимки показывать
нельзя, размечайте сами в разделе ПРОСМОТР — файлы разметки те же, и агенту хватит команд:
обучить, проверить и посчитать он может, не глядя на картинки.

## НАСТРОЙКИ

Где лежат данные (кнопка внизу слева, между УСТАНОВКОЙ и О ПРОГРАММЕ). На каждый род данных —
своя карточка. Снимки и отчёты воспроизводимы: снимки можно скопировать заново, отчёт
выгрузить ещё раз. У сети карточки нет: сеть, обученная на ваших снимках, лежит в рабочей
папке их набора, рядом с разметкой, на которой её учили; сеть, которая пришла с программой
или положена в неё, лежит в самой программе.

Карточка **СНИМКИ** — какие снимки считаются. **ПО УМОЛЧАНИЮ** — папка со снимками внутри
`Pictures` в папке данных рядом с программой: та, на которой сделана рабочая папка `Work`, а в
новой папке данных — первая такая папка по имени (или сама `Pictures`, когда снимки лежат
прямо в ней). **В ПАПКЕ ПОЛЬЗОВАТЕЛЯ** — любая папка со снимками: другой город или другая
съёмка; её называет кнопка **ВЫБРАТЬ ПАПКУ…**. Снимки программа только читает.

Карточка **РАБОЧАЯ ПАПКА** — где лежит то, что сделано из снимков: разметка, итоги счёта,
плитки просмотра, сети, обученные на этой разметке. **ПО УМОЛЧАНИЮ** — папка `Work` в папке
данных для набора по умолчанию, а для другого набора — своя папка `Work-<имя набора>` рядом
с ней. **В ПАПКЕ ПОЛЬЗОВАТЕЛЯ** — папка, которую вы назовёте; пустая годится: когда сеть
лежит в программе, считать можно сразу. У каждого набора снимков рабочая папка своя: если
дать набору чужую, программа скажет «сделана на других снимках» и считать не станет. Разметку
программа не стирает.

Карточка **ОТЧЁТЫ** — куда выгружаются отчёты Word и Excel и слои для MapInfo: кнопки
выгрузки в разделе СЧЁТ открывают выбор папки на этом месте. Пока папка не выбрана, её
спросит первая выгрузка.

Карточка **ДВИЖОК** — где лежат Python и движок счёта и найдены ли они. **ПРОВЕРИТЬ**
спрашивает движок, какие папки, какой PyTorch и какую видеокарту он видит; ответ — в журнале.

Кнопка **ОТКРЫТЬ** в карточке открывает её папку.

Сами диалоги выбора папки автоматическими проверками программы не проходились. Если диалог
ведёт себя не так, папки можно назвать в файле `config\settings.json` при закрытом окне:
ключи `"Pictures"`, `"Work"`, `"ReportFolder"` (обратная косая черта в пути удваивается).

## Клавиши

| Клавиши | Что делают |
|---|---|
| Ctrl+1 … Ctrl+6 | разделы по порядку: ИЗОБРАЖЕНИЯ, ПРОСМОТР, СЧЁТ, УСТАНОВКА, НАСТРОЙКИ, О ПРОГРАММЕ |
| Ctrl+J | журнал |
| F1 | это руководство |
| Esc | из УСТАНОВКИ, НАСТРОЕК и О ПРОГРАММЕ — назад к разделу работы |
| ← → ↑ ↓ | ПРОСМОТР: на шаг в сторону |
| Page Up, Page Down | ПРОСМОТР: предыдущий и следующий размеченный участок |
| A, M, L | ПРОСМОТР: слои — ответы сети, разметка, осветление |
| 1 … 5 | ПРОСМОТР: инструменты — смотреть, машина, грузовик, не разобрать, стереть |
| Ctrl+Z | ПРОСМОТР: отменить последнюю правку разметки |

## Чего ждать от точности

Все числа ниже получены в работе автора: программа считала сетью автора на наборе, на котором
она сделана, — спутниковые снимки одного города из одного источника, около 0,3 м в пикселе.
В публичный выпуск эта сеть не входит. Числа — то, что дала сеть, обученная таким способом:
чего ждать от сети, которую обучите вы, и с чем её сравнивать, — не обещание и не свойство
программы, которая у вас.

- **На снимках, которых сеть не видела.** На трёх проверочных снимках глазом уверенно
  отмечено 511 автомобилей; с сетью автора программа поставила 509 отметок. По видам
  местности: завод с большой открытой стоянкой −2 %; жилая застройка (посёлок, деревня,
  производственная площадка) +12 %; старый город в длинных тенях 0 % — но там четверть
  автомобилей пропущена и столько же отметок лишние. Они гасят друг друга; в другом месте
  могут и не погасить.
- **Когда снимок просто выглядит иначе** — светлее, мягче, сильнее сжат — счёт сдвигается: до
  4 % на открытых стоянках и до 16 % в старом городе в тенях. Такого различия стоит ждать
  между полосами одной мозаики.
- **Отметка — ещё не автомобиль.** Число всегда называется с границами: от «отметки минус
  четверть» до «отметки плюс половина». Границы заданы в программе и получены на тех же
  проверочных снимках; для ваших снимков и вашей сети они заново не выводятся.
- **Другой источник снимков.** На снимках того же города из другого источника — с более
  низким фактическим разрешением, местами размытых — сеть автора нашла около трети
  автомобилей. Новый источник или новый вид местности нужно сначала проверить и, как правило,
  доучить: см. «Своя сеть под свои снимки».
- **Местность, какой сеть не видела** — кладбище, вентиляция на крышах цехов, блики на воде —
  может дать ложные отметки сотнями. Число по такому снимку берите только после взгляда на
  лист образцов на его странице отчёта.
- **Что стоит под отметками.** На листах из 80 отметок, просмотренных глазом на двух снимках,
  не автомобилями оказались около 5–7 %, ещё около 6 % на одном из них — грузовики и фургоны.
- **Соседние снимки** считаются каждый целиком: автомобиль на полосе, общей для двух снимков,
  посчитается дважды. У набора, на котором программа сделана, эта полоса — несколько
  пикселей.
- **Чего программа не видит.** Снимок показывает автомобили под открытым небом в минуту
  съёмки: тех, что под крышей или под кронами, на нём нет. Грузовые автомобили и автобусы в
  счёт не входят — сеть учат их не отмечать, хотя отдельные отметки на них попадают.
- На видеокарте и на процессоре счёт может различаться на единицы: проверочные таблицы
  сошлись с точностью до одного-двух автомобилей.

## Где что лежит

| Папка | Что в ней |
|---|---|
| `Start.exe`, `App\` | окно программы |
| `runtime\` | Python с библиотеками — ставится разделом УСТАНОВКА |
| `system_core\` | движок счёта; `system_core\nets\` — место сети, которая пришла с программой или положена в неё (в публичном выпуске там `open-03`, сеть, обученная на свободных аэрофотоснимках) |
| `config\settings.json` | настройки программы: три папки, язык, тема — всегда в её папке |
| `config\counting_default.json` | какой сетью из `system_core\nets` программа считает и с какой уверенности, когда в рабочей папке набора сеть не названа |
| `logs\` | журнал, по файлу на день |
| `Docs\` | руководства |
| папка снимков | ваши файлы `.jpg` и `.tab`; только читаются |
| рабочая папка | всё, что сделано из снимков, — пять строк ниже |
| `runs\count_<сеть>\` | счёт: по таблице отметок на снимок и `summary.json` с итогами |
| `runs\thumbs\`, `runs\pyramid\` | мелкие копии и плитки снимков для окна; их можно удалить — сделаются заново |
| `labels\<снимок>\` | разметка: по файлу на участок; `labels\_removed\` — участки, убранные в окне |
| `models\` | сети, обученные на вашей разметке; `counting.json` называет ту, которой считается набор |
| `set.json` | на каких снимках сделана эта рабочая папка |
| папка отчётов | документы Word, ведомости Excel, слои для MapInfo |

## Что программа делает в сети и на машине

Ничего не собирает и не отправляет. В сеть выходит только при установке — скачать Python
(python.org), установщик пакетов pip (bootstrap.pypa.io), библиотеки (PyPI) и PyTorch
(download.pytorch.org).

Всё своё программа держит в своей папке; в Windows она ставит только Microsoft Visual C++
Redistributable, если его не было, — он остаётся и нужен многим программам. Чтобы удалить
программу, удалите её папку; снимки, рабочая папка и отчёты лежат отдельно и остаются.

## Если что-то не так

| Что видно | Что делать |
|---|---|
| «Движок счёта не установлен» | раздел УСТАНОВКА, кнопка УСТАНОВИТЬ НУЖНОЕ |
| УСТАНОВКА говорит, что драйвер NVIDIA стар | обновите драйвер и нажмите ПРОВЕРИТЬ СНОВА; до тех пор счёт идёт на процессоре |
| «Счёт идёт на процессоре, хотя видеокарта NVIDIA есть» | кнопка PYTORCH ДЛЯ NVIDIA |
| «Движок не отвечает» | кнопка ОКРУЖЕНИЕ ЦЕЛИКОМ |
| «Обученной сети нет» в УСТАНОВКЕ; «Обученной сети нет ни в рабочей папке, ни в программе: считать нечем.» в разделе СЧЁТ | это не ошибка установки: сеть ещё не обучена и не положена в программу — см. «Своя сеть под свои снимки» |
| «В папке … нет снимков» | назовите папку снимков в НАСТРОЙКАХ; имена файлов должны кончаться на `_столбец-строка.jpg` |
| «Рабочая папка сделана на других снимках» | у каждого набора рабочая папка своя: назовите для этого набора другую в НАСТРОЙКАХ |
| у снимка нет площади и плотности, слои не выгружаются | рядом со снимком нет файла `.tab` |
| кнопки отчёта приглушены | ещё ничего не посчитано; для кнопки ОТЧЁТ ПО ЭТОМУ СНИМКУ откройте посчитанный снимок в ПРОСМОТРЕ |
| числа на карте и в разделе СЧЁТ разные | карта показывает счёт и порог, выбранные в карточке ОТВЕТЫ СЕТИ раздела ИЗОБРАЖЕНИЯ |
| счёт идёт медленно | он идёт на процессоре: посмотрите раздел УСТАНОВКА |
| отметки стоят там, где автомобилей нет, — на крышах, надгробиях, воде | местность, какой программа не видела: см. «Чего ждать от точности» и «Своя сеть под свои снимки» |
| снимки, разметку или счёт поменяли командой, а окно показывает прежнее | кнопка ПЕРЕЧИТАТЬ |