Версия: 0.0.3-beta
Лицензия: MIT
Репозиторий: https://github.com/ppvikentiy/ThermalDecoder
Thermal Decoder — утилита для восстановления карты температур по цветной термограмме в формате BMP. По выделенной области цветной шкалы и заданным Min / Max строится соответствие «цвет → температура», результат сохраняется в CSV и визуализируется в виде оверлея (градации серого исходного кадра). Доступны графический мастер из четырёх шагов и режим командной строки без окна для сценариев и автоматизации.
Приложение не обращается к внешним серверам: анализ выполняется локально на вашем компьютере.
- Возможности
- Как это устроено (алгоритм)
- Зависимости и технологии
- Установка и запуск
- Интерфейсы использования («API»)
- Точность, погрешности и ограничения
- Опциональный сертификат сборки
- Лицензия
- Загрузка термограммы только в формате BMP с видимой вертикальной цветной шкалой.
- Задание области шкалы вручную (прямоугольник X, Y, W, H): верх ROI соответствует Max, низ — Min (как на типичной шкале термокамеры).
- Автопоиск шкалы — эвристика по правой части кадра (
ScaleDetector), если не указан прямоугольник или включён режим авто в CLI. - Проверка гладкости градиента по шкале в цветовом пространстве LAB: режим строгий / мягкий (разные пороги на скачки между соседними строками палитры).
- Опциональное размытие Гаусса перед анализом (снижает влияние мелкого шума).
- Построение полной матрицы температур по пикселям и экспорт в
data.csv(UTF-8, столбцыX,Y,Temperature; для «невалидных» точек температура пустая). - Экспорт
result_overlay.bmp— оттенки серого исходной термограммы (без автоматической цветной тепловой карты на диске в основном пайплайне экспорта). - GUI: масштаб и панорама, окно просмотра температур после анализа, маркеры, сохранение аннотированных снимков, опционально ZIP-архив с результатами, технологический отчёт.
- CLI: полный проход пайплайна без графики, код возврата при ошибках.
Подробнее по шагам мастера и типичным ситуациям см. файл ИНСТРУКЦИЯ.txt в составе проекта.
Краткая цепочка обработки (модуль thermal_decoder, класс ThermalDecoder):
- Чтение BMP через
cv_io.imread_bgr: чтение байтов файла иcv2.imdecode(удобство для путей с кириллицей на Windows); при необходимости резервное чтение через Pillow для некоторых вариантов BMP. - При необходимости —
cv2.GaussianBlur(размер ядра и параметры задаются константами вconstants.py). - Определение прямоугольника шкалы:
- вручную или
ScaleDetector.detect_scale: анализ правой полосы кадра, поиск столбца с максимальной «активностью» вертикального градиента яркости.
- Извлечение палитры шкалы —
ScaleDetector.get_scale_colors: для каждой строки ROI медиана BGR по ширине (для широких ROI берётся правая четверть столбцов, чтобы не смешивать полоску с подписями и фоном). - Валидация —
validate_scale_gradient: перевод палитры в LAB, проверка, что вертикальные скачки в «середине» последовательности не превышают адаптивный порог; учёт особенностей термограмм у краёв шкалы (белые/чёрные наконечники). При провале выбрасываетсяSystem_OCV_Vis_Temp_Errorс понятным текстом. - Сопоставление пикселей кадра с палитрой (
calculate_temperature_matrix):- для каждого пикселя ищется ближайший по Евклидову расстоянию в BGR цвет из палитры;
- если расстояние слишком велико — пиксель INVALID (в матрице NaN, в CSV пустая ячейка);
- для пограничных случаев (среднее расстояние) дополнительная проверка в LAB (ΔE-подобная метрика) относительно выбранного уровня палитры;
- маска «похоже на текст/UI» (HSV/LAB признаки чёрного/белого и нейтральных тонов): если пиксель под маской и при этом «далек» от палитры — результат INVALID;
- индекс уровня палитры 0…N−1 линейно отображается в температуру: верх шкалы = max_temp, низ = min_temp (формула
temp = max_temp + (idx/(N-1)) * (min_temp - max_temp)при N > 1).
- Область самой шкалы на матрице обнуляется (NaN), чтобы не смешивать калибровочную полоску с измерением сцены.
- Экспорт:
save_temperature_csvи запись BMP черезimwrite.
Вспомогательная функция build_overlay (в io_export.py) умеет строить цветную тепловую карту OpenCV, накладку сетки с подписями и маркеры INVALID для визуализации; основной сохранённый файл result_overlay.bmp в scan_ocv формируется функцией build_result_overlay_file как яркость исходного кадра (согласовано с пользовательской инструкцией).
См. requirements.txt:
| Пакет | Назначение |
|---|---|
| opencv-python | Чтение/запись изображений через imencode/imdecode, преобразования цветов (BGR ↔ LAB/HSV), размытие, цветовые карты для оверлея в коде (build_overlay). |
| numpy | Массивы изображений и матрицы температур, векторные расстояния до палитры, чанковая обработка пикселей. |
| Pillow | GUI (ImageTk), резервное чтение части BMP, конвертация RGB→BGR для OpenCV в cv_io. |
Минимальные версии в манифесте: OpenCV ≥ 4.8, NumPy ≥ 1.24, Pillow ≥ 10.
- tkinter — графический интерфейс, диалоги, мастер.
- csv, json, hashlib, hmac, zipfile, threading, socket (локально, например имя узла в отчётах), platform, pathlib и др.
Внешние HTTP/HTTPS вызовы отсутствуют.
pip install -r requirements.txtГрафический режим (по умолчанию):
python main.pyКомандная строка:
python -m thermal_decoder scan путь\к\файлу.bmp -o путь\к\папке_вывода --rect "X Y W H" --min-temp 0 --max-temp 100Обязательны: входной .bmp, папка -o/--output. Укажите либо --rect "X Y W H", либо --auto-scale. Дополнительно: --blur, --soft-gradient, --overlay {grid,colormap,both}, --colormap JET, --grid-step 64, --no-matrix.
При ошибке в stderr выводится сообщение, код выхода ≠ 0.
Сборка «один EXE» для Windows описана в пользовательской инструкции: запуск ThermalDecoder.exe из каталога дистрибутива, служебные файлы рядом с exe не удалять.
Под «API» здесь понимаются локальные интерфейсы программы (не REST).
Основной класс экспортируется из пакета thermal_decoder:
from thermal_decoder import ThermalDecoder, __version__, System_OCV_Vis_Temp_Error
dec = ThermalDecoder()
result = dec.scan_ocv(
"snapshot.bmp",
output_dir="out",
scale_rect=(x, y, w, h), # или None при auto_detect_scale=True
min_temp=0.0,
max_temp=100.0,
apply_blur=False,
auto_detect_scale=False,
gradient_strict=True,
overlay_mode="both",
colormap_name="JET",
grid_step=64,
include_temp_matrix=True,
)Ключи словаря result (типичный успешный сценарий):
| Ключ | Описание |
|---|---|
image_path |
Путь к исходному BMP |
output_dir |
Каталог вывода |
result_overlay |
Путь к result_overlay.bmp |
data_csv |
Путь к data.csv |
scale_rect |
Использованный прямоугольник шкалы (x, y, w, h) |
min_temp, max_temp |
Границы шкалы |
invalid_pixel_count |
Число пикселей без достоверного сопоставления |
temp_matrix |
Матрица numpy (если include_temp_matrix=True) |
Дополнительно доступны низкоуровневые методы: load_image, build_color_map, get_pixel_temp, calculate_temperature_matrix, класс ScaleDetector.
Подкоманда scan парсится в thermal_decoder/__main__.py и вызывает тот же ThermalDecoder.scan_ocv.
Исключение System_OCV_Vis_Temp_Error используется для ошибок, связанных с областью шкалы и проверкой градиента.
Температура не измеряется датчиком — она восстанавливается по цвету относительно выбранных Min / Max:
- Дискретность по вертикали шкалы. Палитра содержит один эталонный цвет на строку ROI высотой N пикселей. Значение для пикселя сцены выбирается как ближайший уровень палитры (без интерполяции между соседними уровнями по температуре).
- Ориентировочный шаг по температуре: ( |Max - Min| / (N - 1) ). На практике погрешность алгоритма часто сопоставима с этим шагом (плюс эффект квантования); при сбое сопоставления с соседним уровнем ошибка может достигать порядка одного шага и более на проблемных участках.
- Ошибка в Min / Max линейно смещает и масштабирует всю карту; программа не считывает цифры с подписей на снимке автоматически.
- Пороги в BGR/LAB (константы в
constants.py, напримерbgr_near_scale_thresh,bgr_ambiguous_low, параметры режимов градиента) задают когда считать совпадение с палитрой достоверным, а не фиксированную погрешность в °C. - Шум, сжатие, блики, неверный ROI шкалы, текст на кадре ухудшают соответствие палитре; такие точки становятся INVALID.
Для задач с жёсткими метрологическими требованиями результаты нужно независимо перепроверять.
Файл ThermalDecoder.cert (если выдан с дистрибутивом) проверяется локально через HMAC: подтверждает связку версия приложения + дата выпуска внутри сертификата. Отсутствие или несоответствие сертификата не отключает функциональность — см. модуль cert_license.py и переменную окружения THERMAL_DECODER_CERT_SECRET для сборочного процесса.
Проект распространяется по лицензии MIT. Полный текст обычно приводится в файле LICENSE в корне репозитория ThermalDecoder на GitHub.
README соответствует версии приложения 0.0.3-beta.