================================================================================
Байт-о-скоп
Версия: 0.1.1
Автор: pav13 (pav13@mail.ru)
Примечание: Часть кода была сгенерирована или доработана с использованием ИИ.
================================================================================

СОДЕРЖАНИЕ:

1.  НАЗНАЧЕНИЕ И ОБЩАЯ ИНФОРМАЦИЯ
2.  УСТАНОВКА И ЗАПУСК
3.  ИНТЕРФЕЙС И УПРАВЛЕНИЕ
    3.1. Левая панель (Основные настройки)
    3.2. Центральная панель (Просмотр изображения)
    3.3. Правая панель (Инструменты и информация)
4.  ПАЛИТРЫ И ИХ НАСТРОЙКИ
    4.1. Однобайтовые/битовые палитры
    4.2. Многобайтовые палитры
    4.3. Настройка пользовательской палитры
5.  КЛАВИАТУРНЫЕ СОКРАЩЕНИЯ (ГОРЯЧИЕ КЛАВИШИ)
6.  РАБОТА С ФАЙЛАМИ И НАСТРОЙКАМИ
    6.1. Открытие файлов
    6.2. Сохранение/загрузка настроек визуализации (.bos)
    6.3. Экспорт в PNG
    6.4. Сравнение файлов (XOR)
    6.5. Список последних файлов
7.  ПРОИЗВОДИТЕЛЬНОСТЬ И НАСТРОЙКИ
8.  ТЕХНИЧЕСКИЕ ДЕТАЛИ И АРХИТЕКТУРА
9.  ВОЗМОЖНЫЕ ПРОБЛЕМЫ И РЕШЕНИЯ
10. СПИСОК ИЗМЕНЕНИЙ

================================================================================

1. НАЗНАЧЕНИЕ И ОБЩАЯ ИНФОРМАЦИЯ

Байт-о-скоп (Byte-o-scope) — это интерактивный визуализатор бинарных файлов,
который преобразует последовательности байтов в изображения. Программа
позволяет исследовать структуру файлов, выявлять паттерны, скрытые данные,
артефакты сжатия и многое другое через различные палитры и режимы отображения.

Основные возможности:
- Визуализация файлов любого размера (от килобайт до гигабайт) с
  оптимизацией через тайловый рендеринг.
- Более 20 встроенных палитр для анализа (оттенки серого, тепловые карты,
  битовые плоскости, частотные распределения и др.).
- Поддержка многобайтовых форматов (RGBA, RGB, целые числа, числа с плавающей
  точкой с настройкой порядка байтов).
- Интерактивный просмотр с масштабированием, панорамированием и зеркальным
  отражением.
- Информационная панель с детализацией байтов под курсором.
- Панорамный вид (overview) для навигации по большим изображениям.
- Экспорт визуализации в PNG.
- Сравнение двух файлов через операцию XOR.
- Сохранение и загрузка настроек визуализации для каждого файла.
- Темная/светлая темы оформления.

================================================================================

2. УСТАНОВКА И ЗАПУСК

Требования:
- Python 3.6 или новее.
- Установленные зависимости: PyQt5, numpy, psutil.

Автоматическая установка зависимостей:
При первом запуске скрипт проверит наличие библиотек и предложит установить
отсутствующие. Для подтверждения введите 'y', 'yes', 'д' или 'да'.

Ручная установка зависимостей:
pip install PyQt5 numpy psutil

Запуск:
python byte-o-scope.py

Также поддерживается drag-and-drop: можно перетащить файл(ы) прямо в окно
программы.

================================================================================

3. ИНТЕРФЕЙС И УПРАВЛЕНИЕ

3.1. Левая панель (Основные настройки)

- Группа "Файл":
    * "📂 Открыть" – открыть файл. При клике показывается меню с последними
      файлами.
    * "↔ Сравнить" – открыть два файла для сравнения (XOR).
    * "💾 Сохр" – сохранить текущие настройки визуализации в файл .bos
      (рядом с исходным файлом).
    * "📥 Загр" – загрузить настройки визуализации из .bos файла.
    * "🖼️ В PNG" – экспортировать текущее изображение в PNG.
    * "↺ Сброс" – сбросить все настройки к значениям по умолчанию.
    * "☀️ Светлая"/"🌙 Тёмная" – переключение темы.

- Группа "Палитры":
    * "Однобайтовые/битовые" – выбор палитры для интерпретации каждого байта
      как отдельного пикселя (или его битов).
    * "Многобайтовые" – выбор палитры для интерпретации нескольких байтов
      как одного пикселя (RGB, целые числа, float и т.д.).

- Группа "Регион":
    * "Начало (адрес)" – смещение в файле, с которого начинается визуализация.
    * "Длина (0 = весь)" – количество байтов для визуализации. 0 означает
      весь файл от указанного смещения до конца.
    * "X" – кнопка сброса региона (смещение=0, длина=0).
    * "✓" – применить введенные значения начала и длины.
    * "В hex" – переключение между десятичным и шестнадцатеричным вводом
      для смещения и длины.

- Группа "Отображение":
    * "Режим ширины":
        - "Ручной" – фиксированная ширина изображения.
        - "Авто (1:1)" – автоматический подбор ширины для квадратного
          изображения (ширина ≈ √(число пикселей)).
        - "Авто (степень 2)" – ширина как степень двойки, не превышающая
          число пикселей.
    * "Ширина" – задаёт ширину изображения в пикселях (в режиме "Ручной").
    * "Шаг ширины" – шаг изменения ширины при прокрутке колеса мыши с
      зажатым Ctrl.
    * "Масштаб" – коэффициент увеличения/уменьшения от 1 до 32.
    * "Автомасштаб" – автоматически подбирать масштаб, чтобы изображение
      помещалось в окно просмотра.

3.2. Центральная панель (Просмотр изображения)

- Основная область отображения визуализированного файла.
- Управление:
    * ЛЕВАЯ КНОПКА МЫШИ на пикселе – "зафиксировать" информацию о байте.
      Повторный клик снимает фиксацию. Фиксированный байт подсвечивается
      пунктирной рамкой.
    * ПРАВАЯ КНОПКА МЫШИ + перемещение – панорамирование (перетаскивание
      изображения).
    * КОЛЕСО МЫШИ – изменение масштаба.
    * CTRL + КОЛЕСО МЫШИ – изменение ширины изображения (в ручном режиме)
      с шагом, указанным в "Шаг ширины".

3.3. Правая панель (Инструменты и информация)

- Информация о байте:
    * "Всплывающая информация о байте" – показывать информацию во всплывающем
      окне рядом с курсором.
    * Отображает адрес, hex, ASCII и двоичное представление байта, а также
      контекст (соседние байты). Для многобайтовых палитр показывает
      интерпретированное значение.

- Группа "Зеркальное отражение":
    * "Отразить по горизонтали" – зеркально отразить изображение по
      горизонтали.
    * "Отразить по вертикали" – зеркально отразить изображение по вертикали.
    * "Сбросить отражения" – отключить оба отражения.

- Область настроек палитры:
    * Появляется при выборе настраиваемой палитры (например, "Пользовательская",
      "Полосы энтропии" и др.).
    * Содержит элементы управления для тонкой настройки параметров палитры.
    * "X" – сбросить настройки текущей палитры к значениям по умолчанию.
    * "Автоприменять настройки" – автоматически обновлять изображение при
      изменении параметров палитры.

- Группа "Панорама":
    * Миниатюра всего изображения с прямоугольником, обозначающим видимую
      область в основном окне.
    * Перетаскивание прямоугольника мышью прокручивает основное изображение.
    * При наведении на прямоугольник меняется курсор, подсвечивается область.

- Группа "Производительность":
    * "Выделенная память" – текущее потребление оперативной памяти процессом.
    * Ползунок – управление балансом между потреблением памяти и
      производительностью.
        - Влево (0.2 Гб) – меньше кэша, меньше памяти, возможны подтормаживания
          при рендеринге.
        - Вправо (4 Гб) – больше кэша тайлов, больше памяти, более плавная
          работа.
    * Изменения применяются с задержкой в 1 секунду после отпускания ползунка.
    * Текстовый индикатор "[⏳ ...]" отображает состояние занятости (рендеринг,
      сохранение PNG).

================================================================================

4. ПАЛИТРЫ И ИХ НАСТРОЙКИ

4.1. Однобайтовые/битовые палитры

Каждый байт (0-255) отображается в цвет по заданному правилу.

- "Оттенки серого" – значение байта как интенсивность (0=чёрный, 255=белый).
- "Инвертированная" – инвертированные оттенки серого.
- "Тепловая" – градиент от синего через голубой, желтый к красному.
- "Термальная" – градиент от чёрного через красный к жёлтому.
- "Вирдис" – градиент от фиолетового через зелёный к жёлтому (perceptually uniform).
- "Плазма" – RGB-градиент на основе синусоид.
- "Радуга" – градиент красный-жёлтый-зелёный-голубой.
- "HSV" – полный цикл оттенков HSV (Hue).
- "Нули/Единицы" – 0 → синий, 255 → жёлтый, остальные → чёрный.
- "Не-Ноль" – все ненулевые байты → зелёный, 0 → чёрный.
- "Установлен старший бит" – байты со старшим битом=1 → красный.
- "Установлен младший бит" – байты с младшим битом=1 → голубой.
- "Полубайты" – старший полубайт → красная компонента, младший → зелёная.
- "Старший полубайт" – отображает только старший полубайт (4 старших бита).
- "Младший полубайт" – отображает только младший полубайт (4 младших бита).
- "Порог" – байты ниже порога → тёмно-синие, выше/равные → серо-голубые.
    * Настраиваемый параметр: "Порог (0–255)".
- "Полосы энтропии" – группирует байты по диапазонам (полосам) и окрашивает
  полосы в чередующиеся цвета.
    * Настраиваемый параметр: "Шаг (полосы)" – размер диапазона.
- "Битовая плоскость" – отображает значение конкретного бита (0 или 1) для
  каждого байта.
    * Настраиваемый параметр: "Битовая плоскость (0–7)" – 0=младший бит, 7=старший.
- "Частота байтов" – окрашивает байты в зависимости от частоты их встречаемости
  в файле (редкие → зелёный, частые → красный). Работает для файлов до 10 МБ.
    * Настраиваемый параметр: "Автоматический расчёт" – включить/выключить
      анализ файла.
- "Повторы" – выделяет цветом байты, которые повторяются в файле много раз.
    * Настраиваемые параметры:
        - "Автоматическое определение" – анализ файла до 1 МБ.
        - "Мин. количество повторов" – порог для выделения.
- "Пользовательская" – позволяет задать собственные цветовые правила для
  диапазонов значений байтов.

4.2. Многобайтовые палитры

Несколько байтов интерпретируются как одно значение (пиксель).

- "RGBA" – 4 байта как Red, Green, Blue, Alpha.
- "ABGR" – 4 байта как Alpha, Blue, Green, Red (обратный порядок).
- "RGB" – 3 байта как Red, Green, Blue.
    * Настраиваемый параметр: "Порядок цветов" – можно поменять порядок
      байтов (RGB, GBR, BRG, BGR, GRB, RBG).
- "Integer 8" – 1 байт как целое число.
    * Настраиваемый параметр: "Со знаком (signed)" – интерпретировать как
      signed (-128..127) или unsigned (0..255).
- "Integer 16" – 2 байта как целое число.
    * Настраиваемые параметры:
        - "Порядок байтов" – big (от старшего к младшему) или little
          (от младшего к старшему).
        - "Со знаком (signed)" – signed или unsigned.
- "Integer 32" – 4 байта как целое число.
    * Настраиваемые параметры: порядок байтов и signed/unsigned.
- "Integer 64" – 8 байтов как целое число.
    * Настраиваемые параметры: порядок байтов и signed/unsigned.
- "Float 32" – 4 байта как число с плавающей точкой одинарной точности (float).
    * Настраиваемый параметр: "Порядок байтов".
- "Float 64" – 8 байтов как число с плавающей точкой двойной точности (double).
    * Настраиваемый параметр: "Порядок байтов".

4.3. Настройка пользовательской палитры

Позволяет задать цвет для любого диапазона значений байта (0-255).

- "Цвет вне диапазонов" – цвет для всех значений, не попавших ни в один
  заданный диапазон.
- "Правила диапазонов" – список правил. Каждое правило состоит из:
    * Начало диапазона (0-255).
    * Конец диапазона (>= начала).
    * Кнопка выбора цвета.
    * Кнопка "×" для удаления правила.
- Кнопка "+ Добавить правило" – добавить новое правило.
- Правила применяются сверху вниз. При пересечении диапазонов "побеждает"
  последнее правило.
- Кнопка "X" (Сброс) – восстанавливает набор правил по умолчанию
  (8 цветных диапазонов).

================================================================================

5. КЛАВИАТУРНЫЕ СОКРАЩЕНИЯ (ГОРЯЧИЕ КЛАВИШИ)

Ctrl+O      – открыть файл.
Ctrl+S      – сохранить настройки визуализации (.bos).
Ctrl+L      – загрузить настройки визуализации.
Ctrl+R      – сбросить настройки к значениям по умолчанию.
Ctrl+E      – экспортировать изображение в PNG.
Ctrl+X      – сравнить два файла (открыть диалог).

================================================================================

6. РАБОТА С ФАЙЛАМИ И НАСТРОЙКАМИ

6.1. Открытие файлов

- Через меню "📂 Открыть" или Ctrl+O.
- Перетаскиванием файла в окно программы.
- Из меню последних файлов (отображается при клике на кнопку "📂 Открыть").
- При открытии программа автоматически ищет файл настроек .bos с тем же
  именем и загружает его, если он существует.

6.2. Сохранение/загрузка настроек визуализации (.bos)

Настройки визуализации (палитра, масштаб, ширина, смещение и т.д.) можно
сохранить в файл с расширением .bos (JSON-формат). Файл сохраняется рядом
с исходным файлом.

- "💾 Сохр" – сохранить текущие настройки.
- "📥 Загр" – загрузить настройки из .bos файла (если он существует).

6.3. Экспорт в PNG

- "🖼️ В PNG" или Ctrl+E.
- Открывается диалог сохранения. По умолчанию предлагается имя,
  соответствующее исходному файлу с расширением .png.
- Экспортируется ТОЧНОЕ изображение в соответствии с текущими настройками
  (палитра, ширина, отражения и т.д.), БЕЗ сглаживания.

6.4. Сравнение файлов (XOR)

- "↔ Сравнить" или Ctrl+X.
- Открывается диалог выбора двух файлов.
- Программа выполняет побайтовую операцию XOR между файлами и визуализирует
  результат.
- Полезно для нахождения различий между двумя версиями файла.

6.5. Список последних файлов

- В меню кнопки "📂 Открыть" отображается до 8 последних успешно открытых
  файлов.
- "🗑️ Очистить список" – очистить весь список последних файлов.
- "❌ Закрыть текущий файл" – закрыть открытый файл и вернуться к демо-данным.

================================================================================

7. ПРОИЗВОДИТЕЛЬНОСТЬ И НАСТРОЙКИ

Программа использует тайловый рендеринг и кэширование для работы с большими
файлами.

- Ползунок производительности регулирует три параметра:
    1. Размер тайла (128–1024 пикселя). Большие тайлы — меньше обращений к
       данным, но больше памяти на кэш.
    2. Запас предзагрузки (1–6 тайлов). Сколько тайлов вокруг видимой области
       загружать заранее.
    3. Максимальный размер кэша (180–4000 МБ). Лимит памяти для хранения
       закэшированных тайлов.

Рекомендации:
- Для небольших файлов (<100 МБ) можно сдвинуть ползунок влево для экономии
  памяти.
- Для гигабайтных файлов и плавной навигации лучше сдвинуть ползунок вправо.
- Индикатор "Выделенная память" показывает текущее потребление ОЗУ.

================================================================================

8. ТЕХНИЧЕСКИЕ ДЕТАЛИ И АРХИТЕКТУРА

Основные компоненты:

- Visualizer (QMainWindow) – главное окно, координация всех компонентов.
- CanvasWidget – виджет для отображения тайлов. Обрабатывает взаимодействие
  с мышью, рендеринг через TileManager.
- TileManager – менеджер тайлов. Занимается созданием, кэшированием и
  очисткой тайлов. Реализует prefetching (предзагрузку тайлов вокруг
  видимой области).
- PaletteManager – менеджер палитр. Содержит определения и фабрики всех
  палитр.
- PaletteSettingsManager – построение UI для настраиваемых палитр.
- ByteInfoWidget – виджет с информацией о байте под курсором, поддерживает
  всплывающее окно.
- PanoramaWidget – виджет панорамы (overview) для навигации.
- ControlsPanel – левая панель с основными элементами управления.
- ThemeManager – управление тёмной/светлой темами.
- WindowSettingsManager – сохранение/загрузка геометрии окна, последних
  файлов и других настроек между сеансами.

Оптимизации:
- Файлы отображаются через memory-mapping (mmap), что позволяет работать с
  файлами, превышающими размер оперативной памяти.
- Рендеринг происходит по тайлам, только для видимой области.
- Используется NumPy для быстрых векторных операций при создании тайлов.
- Кэш тайлов с LRU-политикой вытеснения.
- Индикатор занятости (busy) показывает состояние длительных операций
  (рендеринг, экспорт).

================================================================================

9. ВОЗМОЖНЫЕ ПРОБЛЕМЫ И РЕШЕНИЯ

1. "Не удалось открыть файл" – убедитесь, что файл не занят другим
   процессом и доступен для чтения.

2. Медленная работа/подтормаживания при масштабировании или панорамировании:
   - Увеличьте значение ползунка производительности (сдвиньте вправо).
   - Убедитесь, что файл не находится на медленном носителе (сетевой диск).
   - Закройте другие ресурсоемкие приложения.

3. Высокое потребление памяти:
   - Сдвиньте ползунок производительности влево.
   - Закройте и снова откройте программу (кэш не сбрасывается до полного
     закрытия).

4. Палитра "Частота байтов" или "Повторы" не показывает ожидаемый результат:
   - Эти палитры работают только для файлов до 10 МБ.
   - Для больших файлов включается эмуляция (все байты считаются равномерными).

5. Не сохраняются настройки окна или последние файлы:
   - Проверьте права на запись в домашнюю директорию пользователя.
   - Настройки сохраняются в ~/.byte-o-scope/config.json.

6. При экспорте PNG получается пустое или некорректное изображение:
   - Проверьте, что регион (смещение/длина) задан корректно и содержит данные.

================================================================================

10. СПИСОК ИЗМЕНЕНИЙ

0.1.1
+ в настройках Региона добавлена возможность задать не только длину региона от начала, но и адрес конца региона от начала файла

0.1 (19.01.2026)
* первый выпуск