QuPath: анализ цифровой патологии и whole-slide изображений

QuPath предназначен для количественного анализа цифровой патологии и микроскопических изображений: он открывает whole-slide сканы, позволяет размечать ткань, находить клетки и другие объекты, обучать пиксельные и объектные классификаторы, измерять морфологию и интенсивность сигналов, работать с тканевыми микроматрицами и автоматизировать обработку серий изображений. Программа полезна исследователям, патологам, специалистам по биомедицинской визуализации и лабораториям, которым нужно связать визуальную проверку с воспроизводимыми измерениями, а не просто отредактировать фотографию.

Что делает QuPath и как устроен рабочий процесс

QuPath строит анализ вокруг изображения, объектов и измерений. Изображение остаётся источником пикселей, а результаты анализа представлены объектами в иерархии: аннотациями, детекциями, клетками, тайлами и ядрами TMA. У каждого объекта могут быть геометрия, классификация, имя, описание, родительский объект и числовые измерения. Такая модель важна для практики: область опухоли может быть аннотацией, найденные внутри неё клетки — детекциями, а итоговые признаки каждой клетки — столбцами в таблице измерений.

Другие инструменты: ФотоМАСТЕР.

Типичный сценарий не сводится к одной кнопке. Сначала создают проект и добавляют изображения, затем проверяют тип изображения, калибровку и каналы или красители. После этого определяют область анализа, запускают сегментацию ткани либо клеток, проверяют качество найденных объектов, присваивают им классы и только затем считают проценты, плотности, расстояния или другие показатели. Если этот порядок нарушить, QuPath формально выполнит команду, но результат может быть бессмысленным. Например, неправильно выбранный тип brightfield/fluorescence меняет интерпретацию интенсивности, а некорректные stain vectors влияют на цветовую деконволюцию и последующие измерения.

Главное преимущество такого подхода — возможность визуально проверять каждую стадию. Пиксельный классификатор показывает цветную карту прямо поверх ткани, объектный классификатор перекрашивает найденные клетки по классам, а таблицы позволяют выбрать строку и вернуться к соответствующему объекту на изображении. Это удобнее, чем экспортировать все данные в таблицу и пытаться понять ошибку без пространственного контекста.

QuPath ориентирован прежде всего на исследовательский анализ. Он не позиционируется как средство для клинической диагностики или назначения лечения. Это ограничение следует учитывать при проектировании лабораторного процесса: даже хорошо обученный классификатор должен проходить валидацию на собственных данных, а решение, от которого зависит диагностика, нельзя автоматически переносить на QuPath только потому, что визуально результат выглядит убедительно.

Установка и начало работы

QuPath выпускается для 64-разрядных Windows, macOS и Linux. На Windows доступны обычная установка и переносимый вариант, который достаточно распаковать и запустить из папки. Если установщик блокируется политиками организации или нет административных прав, переносимый вариант часто удобнее, но его необходимо полностью распаковать: запуск исполняемого файла прямо из ZIP приводит к типичным проблемам с библиотеками и сохранением настроек.

На macOS нужно учитывать архитектуру процессора. Сборка для Apple silicon работает нативно на современных Mac, но поддержка отдельных форматов через Bio-Formats может отличаться от x64-сборки; это особенно важно для редких проприетарных вариантов сжатия. Если конкретный скан не открывается на arm64, проблема может быть не в самом QuPath, а в библиотеке чтения. В такой ситуации полезно проверить тот же файл на x64-сборке или открыть его через другой image server. На Linux поставка распаковывается из архива; иногда лаунчеру требуется разрешение на выполнение.

Приложение не всегда проходит системную проверку как подписанное приложение. На Windows может появиться предупреждение SmartScreen, а на macOS — блокировка Gatekeeper. Это не повод отключать защиту системы целиком. Правильная тактика — использовать штатный механизм подтверждения запуска именно загруженного пакета и только после проверки источника. В корпоративной среде лучше согласовать установку с администратором, поскольку ручное ослабление системной политики создаёт риск для всей машины.

После первого запуска разумно не открывать десятки сканов по одному, а сразу создать проект. Команда File → Project… → Create project просит выбрать пустую папку. QuPath будет считать эту папку своей рабочей областью, поэтому не стоит вручную раскладывать в неё посторонние файлы или переименовывать внутренние каталоги. Для серьёзной серии изображений проект — базовый способ работы: в нём сохраняются связи с исходными файлами, данные объектов, классификаторы, скрипты и служебные метаданные.

Изображения добавляют через File → Project… → Add images или перетаскиванием файлов в окно. В диалоге импорта важен параметр Image server. Обычно лучше оставить автоматический выбор, чтобы QuPath сам решил, использовать OpenSlide, Bio-Formats или другой доступный сервер. Ручной выбор нужен, когда один и тот же формат поддерживается несколькими библиотеками, но одна из них корректнее читает конкретный файл, серию, каналы или метаданные.

При импорте также можно заранее указать Image type, поворот, генерацию пирамиды и импорт объектов, если они уже сохранены в поддерживаемом контейнере. Параметр автоматической пирамиды полезен для больших одноуровневых изображений: QuPath создаёт представление с несколькими масштабами, чтобы не читать исходный массив целиком при каждом перемещении и уменьшении. Для настоящих whole-slide файлов, которые уже содержат пирамиду уровней, эта настройка обычно ничего не меняет.

Если проект должен быть переносимым между рабочими станциями, важно понимать, что исходные изображения обычно не копируются внутрь проекта. В проекте хранятся ссылки на них. Поэтому перенос каталога проекта без исходных WSI может привести к красным «потерянным» путям. QuPath умеет предложить замену URI и искать совпадающие имена в выбранной папке, но лучше заранее сохранять одинаковую относительную структуру каталогов.

Для первых тестов не начинайте с анализа всего слайда. Откройте один репрезентативный скан, проверьте масштаб, тип изображения и небольшой ROI. Настройте алгоритм на ограниченной области, оцените ложные и пропущенные объекты, затем сохраните параметры или классификатор. Этот порядок быстрее и безопаснее, чем сразу запускать тяжёлую обработку на гигапиксельном изображении и только через десятки минут обнаружить ошибку в одном поле.

Рабочее окно: Viewer, проект и панели объектов

Центр интерфейса — Viewer. Он показывает выбранный участок изображения с учётом текущего масштаба, цветового преобразования, каналов и наложений. В правом верхнем углу может отображаться миниатюра всего слайда с прямоугольником текущего поля зрения. На больших WSI это не декоративный элемент, а рабочий навигатор: щелчок по миниатюре быстрее переносит к далёкой области, чем последовательное панорамирование.

Слева расположены вкладки Project, Image, Annotations, Hierarchy и Workflow. Project показывает изображения проекта и позволяет переходить между ними. Image содержит свойства текущего изображения: размеры, калибровку, тип, сервер, каналы или stain vectors. Annotations удобна для списка аннотаций и классов, Hierarchy показывает отношения объектов, а Workflow фиксирует многие выполненные команды и помогает превратить ручную последовательность в скрипт.

Перемещение и масштабирование рассчитаны на работу с очень большими изображениями. Для панорамирования используют инструмент Move, перетаскивание мышью или временное переключение на перемещение клавишей пробела. Колесо мыши меняет масштаб. Для z-стека и временной серии часть клавиш навигации меняет плоскость или момент времени, поэтому перед массовой разметкой многомерных данных стоит убедиться, на каком Z/T-срезе создаются объекты.

Наложения можно включать и отключать отдельно. Аннотации, детекции, TMA-сетка и пиксельная классификация не обязаны одновременно быть видимыми. Если изображение кажется «пустым» после детекции, сначала проверьте не результат алгоритма, а состояние отображения: детекции могли быть скрыты. Полезно также переключать заполнение контуров, чтобы сравнивать границы объектов с реальной морфологией под ними.

Для просмотра каналов и динамического диапазона используется View → Brightness/Contrast. Изменение этих параметров влияет прежде всего на визуализацию и не должно автоматически восприниматься как изменение исходных пикселей. Это принципиально при подготовке публикационных картинок и количественном анализе: красивый контраст на экране и числовые значения, прочитанные из исходного изображения, — разные уровни представления.

Форматы изображений и выбор image server

QuPath рассчитан на форматы цифровой патологии и микроскопии, в том числе на крупные пирамидальные изображения. Поддержка зависит от подключённых библиотек чтения. OpenSlide хорошо подходит для распространённых whole-slide форматов, Bio-Formats закрывает широкий спектр микроскопических контейнеров и метаданных, а встроенные механизмы работают с обычными TIFF и другими стандартными изображениями. Поэтому вопрос «поддерживает ли QuPath расширение» не всегда имеет бинарный ответ: один файл с таким расширением может открываться, а другой — нет из-за кодека, варианта контейнера или нестандартных метаданных.

Для переносимых исследовательских данных предпочтительны открытые форматы. OME-TIFF остаётся практичным вариантом для пирамидальных файлов с метаданными, а OME-Zarr удобен для масштабируемого хранения и доступа к большим многомерным данным. QuPath умеет не только читать, но и экспортировать OME-TIFF и OME-Zarr, поэтому его можно использовать как промежуточный инструмент при стандартизации набора изображений.

Если файл открывается с неправильным числом каналов, серий или уровней, сначала посмотрите свойства в Image и при повторном импорте попробуйте другой image server. Не нужно сразу конвертировать оригинал в JPEG или PNG: такой обходной путь часто уничтожает битность, каналы, физическую калибровку и пирамиду — то есть именно то, что требуется для корректного анализа.

QuPath также может работать не только с локальными файлами. Через расширения он способен обращаться к серверным хранилищам, в частности OMERO. В этом случае изображение остаётся на сервере, а клиент получает необходимые тайлы и метаданные. Для больших наборов это лучше, чем многократно копировать десятки или сотни гигабайт на рабочие станции, но производительность будет зависеть уже не только от компьютера, а и от сети, сервера и способа выдачи пикселей.

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

Проекты, сохранение и структура данных

Проект нужен не только для удобного списка слайдов. Он задаёт контекст, в котором QuPath хранит результаты анализа, классификаторы, скрипты и сведения о каждом изображении. В корне проекта находится файл проекта с описанием записей изображений. Для каждой записи QuPath создаёт собственный каталог данных, где сохраняет иерархию объектов, миниатюру и служебное резюме. Поэтому копирование только файла проекта без каталога данных лишит проект значительной части результатов.

Основной файл данных изображения имеет формат QuPath и содержит аннотации, детекции, измерения и другие связанные с текущим слайдом сведения. Исходные пиксели обычно остаются во внешнем WSI. Такая схема экономит место: десятки вариантов анализа не требуют дублировать гигабайтный скан. Но она же накладывает дисциплину резервного копирования — нужно сохранять и проект, и исходные изображения, и понимать, какие пути между ними используются.

Внутри проекта могут появляться каталоги scripts и classifiers. Скрипты, относящиеся к исследованию, удобно хранить рядом с проектом и запускать через меню автоматизации. Пиксельные и объектные классификаторы также логично сохранять в проекте: это снижает риск применить к новой выборке похожий по имени, но фактически другой классификатор из сторонней папки.

Метаданные проекта полезны для группировки и ослепления. Для записи изображения можно добавлять пары «ключ — значение»: например, группу, партию окрашивания, центр, животное, образец или временную точку. Эти поля затем становятся удобным основанием для сортировки, фильтрации и построения скриптов. Если исследование слепое, интерфейс умеет маскировать имена изображений, чтобы оператор не видел исходные идентификаторы во время разметки.

Переименование WSI в файловом менеджере после импорта — плохая привычка. QuPath хранит URI, и при массовом переименовании проект потеряет связь. Если пути уже изменились, при открытии проекта используйте окно исправления URI, а не редактируйте файл проекта вручную. Ручная правка JSON оправдана только как аварийная мера с резервной копией, когда штатный механизм не может восстановить соответствия.

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

Аннотации, ROI и иерархия объектов

Аннотация в QuPath — не просто цветной контур. Это полноценный объект, который задаёт ROI и может ограничивать область вычислений, хранить класс и измерения, служить обучающим примером для классификатора или родителем для детекций. По этой причине качество аннотаций напрямую влияет на анализ: слишком широкая область заставляет алгоритм обрабатывать фон и артефакты, слишком узкая — исключает релевантную ткань.

Для ручной разметки доступны прямоугольник, эллипс, линия, кисть, многоугольник, «волшебная палочка» и другие инструменты. Прямоугольник удобен для быстрого тестового ROI; полигон — для грубой обводки сложной ткани; кисть — для уточнения границ; wand помогает строить контуры на основе локального изображения. При активной кисти или wand клавиша Alt временно переводит инструмент в режим вычитания, а Shift позволяет продолжать добавление к выбранной аннотации.

После создания аннотации ей стоит сразу присвоить понятный класс. Классы используются не только для цвета. Они становятся целевыми метками при обучении, фильтрами при подсчёте и экспортируются вместе с объектами. В проектах с несколькими операторами лучше заранее согласовать короткий словарь классов и не создавать дубликаты вроде «Tumor», «tumour» и «Опухоль», если они должны означать одно и то же.

QuPath различает обычные и производные классификации. Например, объект может иметь базовый класс Tumor и дополнительный признак Positive. Для интенсивностных задач такая структура удобнее, чем создавать совершенно независимые категории для всех комбинаций. Специальный класс Ignore* используется для областей, которые не должны участвовать в некоторых измерениях и обучении. Он полезен для складок, пустого стекла, некроза или других регионов, которые нужно явно исключить из расчёта.

Иерархия связывает крупные и мелкие объекты. Детекции, созданные внутри аннотации, могут становиться её потомками, а TMA cores образуют специализированную структуру сетки. Если геометрия была создана не в том месте и отношения нарушились, команда вставки объектов в иерархию помогает перестроить родительство. Это особенно важно перед экспортом сводных показателей по аннотациям: проценты и количество дочерних клеток имеют смысл только при корректной принадлежности объектов.

Готовые аннотации можно блокировать. Команды Objects → Lock… защищают выбранные объекты от случайного перемещения или изменения. Для больших проектов это практическая мера: после утверждения разметки «заморозьте» её перед запуском следующего этапа, чтобы тестирование инструментов на соседней области не повредило исходный ROI.

QuPath умеет импортировать и экспортировать объекты как GeoJSON. Это удобный мост между QuPath, Python, геоинформационными библиотеками и специализированными пайплайнами, но нужно помнить о координатной системе изображения. Если внешний код меняет масштаб, ориентацию или начало координат, геометрия вернётся не в то место. Перед массовым обменом всегда проверьте один объект с очевидной формой и положением.

Для контроля аннотаций используйте вкладку Annotations и таблицу измерений выбранного объекта. QuPath автоматически показывает площадь, периметр, координаты центра и другие свойства, доступные для конкретной геометрии. Если после редактирования контура значения не меняются, убедитесь, что выбран именно тот объект, который виден в Viewer, а не перекрывающая его аннотация.

Подготовка brightfield-изображений

Для H&E, H-DAB и других хромогенных brightfield-слайдов первый технический вопрос — правильный Image type. QuPath должен знать, что более тёмные участки связаны с большим количеством красителя и что изображение следует интерпретировать через цветовую деконволюцию. Если оставить тип неопределённым или выбрать fluorescence, некоторые команды будут использовать неверную модель интенсивности.

Цветовая деконволюция разделяет вклад красителей на условные каналы. Для H-DAB обычно используются hematoxylin и DAB, для H&E — hematoxylin и eosin. Начальные stain vectors подходят для демонстрации, но реальная окраска зависит от лаборатории, сканера, партии реагентов и подготовки образца. Поэтому при количественном анализе важно проверить, что разделённые каналы действительно визуально соответствуют ожидаемым структурам.

Stain vector можно уточнить вручную. Выберите небольшой участок с максимально «чистым» красителем, затем на вкладке Image откройте свойства нужного stain и обновите значения по выбранной области. Для фона аналогично полезно использовать чистое стекло. Выбирать огромный ROI не нужно: усреднение при даунсэмплинге смешивает цвета и ухудшает оценку.

Когда в изображении ровно два основных хромогенных красителя, команда Analyze → Estimate stain vectors помогает оценить разделение автоматически. Перед её запуском нужно выделить репрезентативный участок с обоими красителями и, по возможности, фоном. Результат проверяют по scatter plots и по тому, как выглядят деконволюционные каналы, а не принимают вслепую.

Stain vectors следует устанавливать до детекции и измерений. Уже созданные измерения не пересчитываются магически при изменении векторов. Если вы сначала нашли клетки, затем исправили разделение H-DAB, детекцию и связанные интенсивностные измерения нужно повторить. Иначе часть таблицы будет относиться к старым параметрам, а визуализация — к новым, что особенно опасно при сравнении образцов.

Для серии слайдов лучше определить правила стандартизации заранее. Если все образцы окрашены и сканированы сопоставимо, можно оценить stain vectors на типичном образце и затем применить одинаковые настройки ко всему проекту скриптом. Если вариабельность велика, одна пара векторов может быть недостаточной. В таком случае методику нужно валидировать на нескольких представительных слайдах и решить, допустима ли общая настройка.

Флуоресцентные и многоканальные изображения

В fluorescence-режиме QuPath трактует высокий сигнал как большую интенсивность маркера. Для многоканальных данных ключевым становится не разделение stain vectors, а корректное описание каналов. Окно Brightness/Contrast показывает список каналов, их цвета и диапазоны отображения. Здесь можно переименовать канал так, чтобы измерения и будущие классификаторы получали осмысленные названия.

Названия каналов лучше сделать короткими и однозначными: DAPI, CD8, PD-L1, FoxP3 и так далее. QuPath включает имя канала в названия измерений, поэтому длинные служебные подписи из сканера быстро превращают таблицы в нечитаемый набор столбцов. Переименование следует выполнить до массовой детекции, иначе уже созданные измерения сохранят старые названия.

Отображение каналов можно включать и выключать независимо. Это позволяет поочерёдно проверить ядерный канал, мембранные и цитоплазматические маркеры. Для multiplex-изображений полезен View → Show channel viewer: он показывает несколько каналов одновременно и синхронизирован с текущей областью. Такой просмотр хорошо выявляет bleed-through, неравномерный фон и ситуации, когда выбранный канал плохо подходит для ядерной сегментации.

Для автоматической детекции клеток чаще всего требуется канал, на котором видны все ядра, например DAPI. QuPath может попытаться угадать такой канал по названию, но оператор должен проверить результат. Если часть ядер не экспрессирует выбранный маркер или сигнал неоднороден, сегментация на нём неизбежно будет смещена. Специализированные модели глубокого обучения могут использовать несколько каналов, но это не снимает требования проверить входные данные.

Изменение минимального и максимального уровня в окне Brightness/Contrast не исправляет реальные пиксели и не заменяет нормализацию алгоритма. Оно делает слабый сигнал заметнее для человека, но классификатор, работающий с исходными интенсивностями, продолжит видеть исходный диапазон. Поэтому при настройке порога смотрите не только на цвет изображения, но и на числовые значения измерений.

При работе с z-stack и time series важно учитывать, что многие команды QuPath ориентированы на двумерный анализ текущей плоскости. Viewer умеет перемещаться по Z и T, но это не означает, что каждый алгоритм превращается в полноценную 3D/4D сегментацию. Если задача требует объёмной реконструкции, нужно отдельно проверить возможности конкретного алгоритма или использовать специализированный инструмент.

Поиск ткани, пороговая обработка и пиксельная классификация

Пиксельная классификация отвечает на вопрос «к какому классу относится этот участок изображения» до того, как из него обязательно создаются отдельные объекты. Самый простой вариант — Classify → Pixel classification → Create thresholder. Он полезен для отделения ткани от стекла, выделения DAB-положительных областей и других задач, где один числовой признак достаточно хорошо разделяет классы.

Основные параметры thresholder — источник сигнала, разрешение, порог, класс выше порога, класс ниже порога и область предварительного просмотра. Resolution задаёт, на каком масштабе будет выполняться классификация: слишком грубое разрешение ускоряет вычисления, но делает границы ступенчатыми и теряет мелкие структуры; слишком высокое увеличивает нагрузку и может подчёркивать шум. Правильное значение выбирают из биологического масштаба объекта, а не из желания получить самый детальный overlay.

Threshold следует подбирать по реальным значениям пикселей и распределению на репрезентативных участках. Для DAB после цветовой деконволюции можно ориентироваться на optical density, но фиксированный универсальный порог для всех лабораторий не существует. Меняется окраска, сканер, экспозиция, фон и подготовка ткани. Поэтому числовой порог, найденный на учебном слайде, нельзя без проверки переносить на собственный набор.

Поля Above threshold и Below threshold определяют, какие классы получат пиксели по разные стороны порога. Если одна сторона не нужна, её оставляют неклассифицированной. Если требуется процент положительной области относительно всей релевантной ткани, полезно явно классифицировать и положительную, и отрицательную части. Тогда QuPath сможет рассчитывать относительные площади на основании классифицированных пикселей.

После настройки thresholder его стоит сохранить под осмысленным именем. Сохранённый классификатор можно заново загрузить и использовать в скрипте. Если применить порог без сохранения, одноразовая операция сработает, но воспроизводимость ухудшится: будет сложнее восстановить параметры и автоматически повторить шаг на проекте.

Результат порога можно использовать тремя способами. Первый — оставить его как пиксельный overlay и получить измерения площади. Второй — создать аннотации из классифицированных областей. Третий — использовать классификацию как вспомогательный шаг для уже существующих объектов. При создании аннотаций дополнительно задаются правила очистки мелких фрагментов и отверстий, поэтому визуально одинаковый порог может дать разные геометрии при разных настройках постобработки.

Для неоднородной ткани одного порога часто недостаточно. Тогда открывают Classify → Pixel classification → Train pixel classifier. Пользователь рисует небольшие обучающие аннотации для нескольких классов, включает Live prediction и видит, как модель переносит метки на остальную область. Такой режим особенно удобен для итеративного обучения: ошибка в конкретном морфологическом паттерне сразу превращается в новый обучающий пример.

В окне пиксельного классификатора параметр Classifier выбирает алгоритм, Resolution — пространственный масштаб, Features — признаки, Output — тип выхода, а Region — область, где строится предварительный overlay. Region не меняет саму модель; он ограничивает объём вычислений при интерактивной настройке. Это полезно на WSI: можно обучать модель на нескольких выбранных участках, не заставляя программу каждый раз пересчитывать весь слайд.

В Features выбираются каналы, масштабы и преобразования. Для H-DAB логично включать релевантные деконволюционные каналы; для fluorescence — конкретные маркеры. Больше признаков не всегда лучше. Ненужные каналы и слишком много масштабов увеличивают время, память и риск того, что классификатор выучит нестабильный признак. Хороший набор начинается с минимально необходимого и расширяется только тогда, когда визуально понятна природа ошибки.

Обучающие аннотации должны быть небольшими, разнообразными и покрывать реальные варианты класса. Несколько огромных областей одной и той же текстуры дают много почти одинаковых пикселей и плохо представляют разнообразие выборки. Лучше добавить отдельные небольшие примеры светлой и тёмной опухоли, участков у края ткани, областей с артефактами и других вариаций, если они действительно должны относиться к одному классу.

Класс Ignore* полезен для областей, которые модель не должна считать ни положительными, ни отрицательными: пустого стекла, складок, мусора или структур, не входящих в исследовательский вопрос. Это не «третья биологическая категория», а способ явно исключить регион из некоторых итоговых расчётов. Если убрать такие области только визуально, но не исключить вычислительно, проценты площади будут систематически смещены.

Главный риск — переобучить классификатор на одном слайде. Даже очень красивый Live prediction не доказывает переносимость. Различия окраски, толщины среза, партии реагентов, сканера и биологии могут изменить признаки. Для проверки используйте изображения из других партий, а при обучении — Load training для уже размеченных изображений проекта. Ещё один вариант — собрать тренировочное изображение из фрагментов нескольких слайдов через Classify → Training images → Create region annotations и Create training image.

Тренировочное изображение в QuPath может быть виртуальным: фрагменты остаются в исходных файлах, а новый элемент проекта объединяет обращения к ним. Это экономит место, но при большом числе источников может замедлить чтение. Если такой виртуальный набор становится узким местом, его можно экспортировать в единый пирамидальный файл и продолжить работу уже с ним.

Пиксельный классификатор не заменяет экспертную разметку там, где класс определяется не локальной текстурой, а сложным контекстом. Если алгоритм уверенно окрашивает доброкачественный эпителий как опухоль потому, что локально они похожи, увеличение количества похожих признаков не обязательно решит проблему. В таких случаях правильнее ограничить анализ экспертно заданным ROI и использовать классификатор для тонкой сегментации внутри него.

Детекция клеток и положительного окрашивания

Клеточная детекция превращает изображение в набор отдельных объектов, для которых затем можно измерять форму, интенсивность и соседство. Встроенная команда Analyze → Cell detection → Cell detection подходит для многих brightfield и fluorescence-задач, если ядра достаточно хорошо отделяются от фона. Positive cell detection выполняет ту же базовую сегментацию, но дополнительно сразу присваивает интенсивностную категорию по выбранному измерению.

Настраивать детекцию нужно на небольшой аннотации, где есть и простые, и сложные клетки. Слишком «идеальный» участок даст ложное чувство качества. В тестовый ROI полезно включить плотные скопления, слабые ядра, границу ткани и небольшой артефакт, если такие случаи типичны для набора. После изменения параметра увеличьте изображение и проверьте границы, а не только итоговое число объектов.

Detection image или Detection channel определяет, какой сигнал используется для поиска ядер. В H-DAB это может быть hematoxylin или optical-density-представление; в fluorescence — DAPI или другой ядерный канал. Requested pixel size определяет рабочее разрешение. Более крупный размер пикселя ускоряет обработку и сглаживает мелкие детали, но маленькие ядра могут исчезнуть; слишком мелкий размер увеличивает шум и нагрузку.

Background radius задаёт масштаб оценки локального фона. Если он слишком мал по сравнению с ядром, фон начинает «подстраиваться» под сам объект; если слишком велик, локальные изменения освещения и окраски будут компенсироваться хуже. Значение подбирают относительно типичного диаметра ядра и проверяют на нескольких областях, а не копируют из чужого протокола.

Median filter radius и Sigma влияют на сглаживание. Их увеличение может убрать мелкий шум, но одновременно стереть слабые небольшие ядра или слить близкие объекты. Minimum area и Maximum area отсеивают сегменты по размеру. Эти поля особенно зависят от корректной физической калибровки: если микрометры в метаданных неверны, числовые ограничения перестают соответствовать реальному размеру клетки.

Threshold отделяет предполагаемые ядра от фона. Параметр Split by shape пытается разделять соприкасающиеся ядра по геометрии. Он полезен в плотной ткани, но при агрессивной настройке одно крупное ядро может распасться на несколько детекций. После запуска обязательно смотрите места контакта клеток: общая плотность объектов может выглядеть правдоподобно, хотя локально сегментация систематически пере- или недоразделяет ядра.

Cell expansion строит приближённую клеточную область вокруг ядра. Это не полноценная мембранная сегментация: граница расширяется геометрически и может пересекаться с реальной морфологией неточно. Для маркеров, локализованных в цитоплазме или мембране, качество такого приближения нужно оценить отдельно. Если точная клеточная граница критична, предпочтительнее специализированная модель сегментации.

Опция Include cell nucleus сохраняет ядерный компонент внутри объекта клетки, а Make measurements создаёт числовые признаки. Для brightfield могут вычисляться показатели по деконволюционным каналам, для fluorescence — по именованным каналам. Если вы поменяли названия каналов или stain vectors после детекции, старые измерения не становятся автоматически эквивалентны новым.

В Positive cell detection поле Score compartment определяет, по какому компартменту и измерению оценивать положительность. Для ядерного DAB-маркера логично использовать ядерное измерение, а для мембранного или цитоплазматического — соответствующий сигнал. До трёх порогов позволяют разделить клетки на Negative, 1+, 2+ и 3+; режим Single threshold сводит задачу к бинарной Positive/Negative классификации.

Нельзя выбирать порог только потому, что итоговый процент выглядит ожидаемо. Сначала откройте таблицу детекций и гистограмму релевантного измерения, затем сопоставьте клетки по обе стороны порога с изображением. Хороший порог должен отделять визуально согласованные популяции и оставаться устойчивым на независимых областях, а не воспроизводить заранее желаемое число.

После запуска проверьте как минимум четыре типа ошибок: пропущенные слабые ядра, ложные объекты на пигменте или мусоре, слияние соседних ядер и дробление одного ядра. Кроме того, сравните область обработки с выбранной аннотацией. Если детекция прошла по фону за пределами ROI, вероятно, родительский объект был не выбран или команда запускалась в другом режиме.

Если детекции «исчезли», сначала включите отображение detection objects. QuPath хранит объекты независимо от того, показаны ли их контуры. На плотной ткани также полезно переключать заполнение объектов: прозрачные контуры лучше показывают совпадение с реальными границами, а заполненные области быстрее выявляют крупные систематические ошибки сегментации.

Таблицы детекций и контроль качества сегментации

Команда Measure → Show detection measurements открывает таблицу, где каждая строка соответствует детекции или клетке, а столбцы содержат классификацию, координаты, форму и интенсивности. Таблица связана с Viewer: выбор строки позволяет найти объект на изображении. Эта связь особенно полезна при поиске выбросов — например, клеток с аномально большой площадью или экстремальным сигналом.

В таблице можно включить графики и построить гистограмму выбранного измерения. Если площадь ядер имеет длинный правый хвост, проверьте самые крупные объекты: часто это слипшиеся клетки. Если много объектов сосредоточено у минимального допустимого размера, возможно, порог или фильтрация создают шумовые фрагменты. Такой контроль над распределением параметров быстрее выявляет проблемы, чем просмотр случайных участков.

Не все выбросы нужно автоматически удалять. Биологически крупные ядра, митозы или редкие клетки могут быть реальными. Правильная последовательность — найти объект через таблицу, посмотреть исходные пиксели и только затем решать, является ли он ошибкой. Фильтрация «по красивой статистике» без визуальной проверки рискует удалить именно интересную субпопуляцию.

Если после настройки параметров вы собираетесь обрабатывать серию, сохраните состояние тестового изображения и зафиксируйте критерии приемки. Например: ядра должны быть разделены в плотных зонах, контур не должен захватывать крупные пустоты, слабая популяция должна обнаруживаться в пределах допустимого процента по ручной выборке. Такие критерии полезнее субъективной фразы «выглядит хорошо».

InstanSeg, StarDist и расширенная сегментация

Встроенная детекция удобна и быстра, но сложная морфология, multiplex fluorescence и неравномерный фон часто требуют более современных моделей. В QuPath глубокое обучение подключается через расширения. В актуальном менеджере расширений доступны, в частности, InstanSeg, Deep Java Library, WSInfer, OMERO и другие компоненты, а StarDist устанавливается отдельным расширением. Сам факт наличия расширения не означает, что оно нужно каждому проекту: сначала стоит понять, какую конкретную ошибку базового алгоритма вы хотите исправить.

InstanSeg предназначен для сегментации ядер и клеток с использованием предварительно обученных моделей. Для работы требуется расширение InstanSeg и Deep Java Library; модель и, при необходимости, PyTorch загружаются отдельно. На первом запуске модели лучше создать небольшой ROI. Это позволяет быстро проверить, соответствует ли тип модели вашим данным и не расходуется ли память на заведомо неподходящую конфигурацию.

В окне InstanSeg выбирают каталог моделей, саму модель и родительские аннотации или TMA cores. Дополнительные параметры включают вычислительное устройство, количество потоков подготовки тайлов, размер тайла, перекрытие и входные каналы. На CPU метод работает без специальной видеокарты, но заметное ускорение возможно на поддерживаемом GPU или через MPS на современных Mac. Совместимость зависит от библиотек глубокого обучения, поэтому «видеокарта есть» не гарантирует, что конкретный backend автоматически заработает.

Tile size — компромисс между накладными расходами и памятью. Большой тайл уменьшает число переключений, но требует больше памяти. Tile padding задаёт перекрытие соседних тайлов, которое помогает не обрезать клетки на границах. Слишком маленькое перекрытие может давать характерные вертикальные и горизонтальные дефекты сегментации; слишком большое увеличивает объём повторных вычислений.

InstanSeg может создавать ядра, клетки и измерения в зависимости от модели и настроек. После выполнения результат всё равно нужно проверять в Viewer. Модель, хорошо работающая на fluorescence, не обязана переноситься на другой протокол или brightfield, а универсальный pretrained-вариант не освобождает от валидации. Особенно внимательно смотрите на участки с некрозом, складками, насыщенным сигналом и очень плотными скоплениями.

StarDist в QuPath — ещё один вариант для детекции ядер. Он использует модели, обученные предсказывать звездообразные полигоны вокруг ядер. Расширение поддерживает модели для разных типов изображений, а ключевым параметром является рабочий pixel size: входное изображение масштабируется до разрешения, которое ожидает модель. Если физическая калибровка неправильна, ядра оказываются «не того размера» относительно обучения и качество резко падает.

В StarDist важна нормализация. Нормализация каждого тайла независимо может сделать чистый фон похожим на информативный участок и породить ложные ядра. В подходящих сценариях лучше использовать нормализацию, рассчитанную по более широкой области или по всему изображению в пониженном разрешении. Это пример общего правила: локальная предобработка должна учитывать, не меняет ли она статистику фона от тайла к тайлу.

StarDist и InstanSeg решают сегментацию, но не автоматически отвечают на биологический вопрос. После получения клеток всё равно нужно выбрать признаки, определить классы и проверить переносимость. Если задача состоит только в площади окрашивания, создание миллионов клеточных объектов может быть лишним: пиксельный классификатор даст более простой и прозрачный путь. Глубокая модель оправдана тогда, когда именно границы отдельных клеток являются значимой единицей анализа.

Классификация клеток и других объектов

После детекции каждая клетка содержит набор числовых признаков. Для простых задач хватает порога по одному измерению; для сложных — интерактивного объектного классификатора. Команда Classify → Object classification → Create single measurement classifier подходит, когда один показатель действительно разделяет классы. Например, положительность конкретного fluorescence-маркера можно задавать порогом по средней интенсивности выбранного компартмента.

Для многомерных признаков используется Classify → Object classification → Train object classifier. QuPath обучает модель на уже созданных объектах, а пользователь задаёт правильные ответы с помощью размеченных аннотаций или точек. Важно, чтобы в обучающих областях детекции уже существовали: классификатор учится не на абстрактной ткани, а на измерениях объектов, попавших под размеченные регионы.

В окне обучения выбираются фильтр объектов, алгоритм, набор features, классы и источник обучающих аннотаций. Для старта часто подходит Random Trees, поскольку он устойчив к смешанным признакам и интерактивно обновляется достаточно быстро. Но название алгоритма не важнее данных: плохая сегментация и неинформативные features не исправляются заменой одного классификатора на другой.

Режим Live update позволяет видеть классификацию сразу после добавления новых обучающих областей. Рабочий цикл должен быть диагностическим: добавьте несколько маленьких областей Tumor и Stroma, включите Live update, найдите систематическую ошибку, затем добавьте пример именно этой ошибки. Не закрашивайте половину слайда одним классом — вы получите множество повторяющихся клеток и ухудшите баланс обучения.

В Features можно использовать все измерения или ограничить набор. Для brightfield иногда полезны форма, ядерно-клеточное соотношение и интенсивности деконволюционных каналов; для multiplex — выбранные маркеры. Чем больше признаков, тем выше риск включить технический суррогат: например, координаты, признаки фона или канал, который отличается между партиями не по биологии, а по сканированию. Такие признаки дают красивый результат на обучающих слайдах и проваливаются на новых.

Для нескольких маркеров QuPath позволяет строить отдельные классификаторы и объединять их. В multiplex-задачах один распространённый подход — сделать бинарный классификатор положительности для каждого маркера, а затем комбинировать результаты в составные фенотипы. Преимущество в прозрачности: порог или модель каждого маркера можно проверить отдельно. Недостаток — число комбинаций быстро растёт, поэтому нужно заранее определить биологически релевантные фенотипы.

Если положительность задаётся интенсивностным порогом, команда Set cell intensity classifications обновляет только интенсивностный слой классификации, не уничтожая базовый тип клетки. Это удобно для схемы Tumor:Positive или Stroma:Negative. При трёх порогах доступны категории 1+, 2+ и 3+, а для соответствующих схем QuPath может рассчитывать H-score. Пороговые значения всё равно требуют валидации и не должны выбираться только по форме гистограммы.

Сохранённый объектный классификатор можно загрузить и применить к новым детекциям, но это не то же самое, что продолжить его обучение. Если условия изменились настолько, что требуется адаптация, лучше вернуться к исходному обучению и создать новую версию классификатора. Называйте файлы так, чтобы различались биомаркер, партия или назначение, а не только «final» и «final2».

После классификации выберите несколько участков с разной морфологией и выключайте/включайте контуры детекций, чтобы видеть исходные клетки. Ошибка модели часто маскируется плотной цветной заливкой: красивый красно-зелёный overlay воспринимается убедительнее, чем он есть. Контроль должен включать и клеточные границы, и исходный сигнал, и таблицу измерений.

Измерения, гистограммы и measurement maps

QuPath создаёт измерения на разных уровнях. Аннотация может иметь площадь, периметр и сводные показатели дочерних клеток; детекция — форму, интенсивность ядра, клетки или цитоплазматической области; TMA core — агрегированные показатели своей области. Поэтому перед экспортом нужно явно выбрать тип объекта. Таблица аннотаций и таблица детекций отвечают на разные вопросы и не являются взаимозаменяемыми.

В Measure → Show detection measurements график Histogram показывает одномерное распределение признака. Он полезен для поиска порога, выбросов и смешанных популяций. Scatter plot связывает два признака и помогает увидеть кластеры, корреляцию и зоны перекрытия классов. Для больших таблиц число одновременно отображаемых точек может ограничиваться ради отзывчивости интерфейса, поэтому график — диагностическое представление, а не полный статистический отчёт.

Команда Measure → Show measurement maps переносит числовой признак обратно на изображение. Каждая детекция окрашивается по значению выбранного измерения, благодаря чему видно, где в ткани концентрируются клетки с высоким сигналом, большой площадью ядра или другим признаком. Это удобный способ заметить пространственный артефакт: например, повышение интенсивности только у края скана или систематический сдвиг между участками.

Цветовая шкала measurement map влияет только на визуальную интерпретацию. Слишком узкий диапазон искусственно подчёркивает небольшие различия, слишком широкий скрывает структуру. Настраивайте шкалу после просмотра числового распределения и не сравнивайте две картинки с разными диапазонами как будто цвета эквивалентны.

Для локального контекста существуют сглаженные признаки. Команда добавления smoothed features усредняет измерения соседних клеток в заданном радиусе и помогает выявлять области, где локальная популяция отличается от окружающей. Но сглаживание меняет смысл показателя: это уже характеристика микроокружения, а не конкретной клетки. Радиус должен соответствовать биологическому вопросу и быть указан в методике.

Measurement maps особенно полезны перед машинным обучением. Если выбранный feature визуально разделяет Tumor и Stroma только на одном углу слайда, он, вероятно, кодирует техническую вариацию. Если же карта согласуется с морфологией на разных областях, признак выглядит более содержательным. Такой визуальный аудит помогает сократить набор features ещё до обучения классификатора.

Многоканальная клеточная аналитика

В multiplex-изображениях QuPath после детекции может измерить каждый канал в разных клеточных компартментах. Поэтому правильные имена каналов — часть анализа, а не косметика. Если канал C3 позже переименовать в FoxP3, старые измерения с C3 и новые измерения с FoxP3 окажутся двумя разными наборами столбцов, хотя относятся к одному сигналу.

Для каждого маркера можно выбрать измерение и порог либо обучить отдельный объектный классификатор. На практике удобно сначала построить гистограмму и scatter plot, затем проверить вручную клетки возле предполагаемого порога. Если положительная и отрицательная популяции хорошо разделены одним измерением, сложная модель не нужна. Если сигнал зависит от формы, соседних каналов или фона, многомерный классификатор может быть оправдан.

Каналы следует оценивать и на предмет технической взаимозависимости. Если два маркера сильно коррелируют из-за спектрального bleed-through, классификатор может использовать не биологический сигнал, а оптический артефакт. QuPath не выполняет за пользователя полную спектральную компенсацию; корректность входного multiplex-изображения остаётся ответственностью экспериментального пайплайна.

После присвоения фенотипов пригодны стандартные инструменты QuPath: сводные проценты по аннотациям, карты измерений, пространственные расстояния и экспорт клеточных данных. Сначала лучше подтвердить одну-две ключевые комбинации на ограниченном наборе, и только затем запускать десятки фенотипов по всему проекту. Иначе ошибка в одном канале размножится на все составные классы.

Тканевые микроматрицы: TMA dearrayer и работа с cores

Для tissue microarray в QuPath есть отдельный тип объектов — TMA cores и отдельная сетка. Команда TMA → TMA dearrayer пытается определить расположение ядер микроматрицы автоматически. Она особенно полезна для регулярных матриц с похожим диаметром cores, но результат нужно проверять: отсутствующие, смятые или плохо окрашенные cores могут нарушить автоматическую геометрию.

Если автоматическая сетка не совпала, её можно создать или скорректировать вручную через TMA → Specify TMA grid, добавить или удалить строки и столбцы, а затем выполнить Relabel TMA grid. Перед анализом убедитесь, что метки рядов и колонок соответствуют реальной карте блока. Ошибка на один столбец опаснее обычной ошибки сегментации: все дальнейшие показатели будут связаны не с тем образцом.

Отсутствующий core нужно помечать как missing, а не просто оставлять пустым ROI. QuPath хранит этот статус отдельно, благодаря чему отсутствующие элементы можно исключать из экспорта и сводных расчётов. Если ткань частично выпала, это уже другой случай: core существует, но площадь анализа должна быть ограничена оставшейся тканью или аннотацией.

После построения сетки к каждому core можно применять те же основные операции, что и к обычной аннотации: детекцию клеток, пиксельную классификацию, вычисление измерений. Преимущество TMA-структуры в том, что Measure → Show TMA measurements и grid view позволяют сравнивать cores в их пространственном расположении, а File → TMA data… → Export TMA data сохраняет специализированный набор данных.

Для пакетного анализа TMA сначала протестируйте алгоритм на нескольких cores с разной интенсивностью и качеством. Не выбирайте только самые чистые. Один и тот же threshold может хорошо работать на центре блока и плохо — на краях из-за окраски или фокуса. Если требуется нормализация, её метод должен быть определён до экспорта, иначе корректировка после факта усложнит воспроизводимость.

Пространственный анализ клеток

После сегментации и классификации клеток QuPath может рассчитывать пространственные признаки. Команда Analyze → Spatial analysis → Distance to annotations 2D измеряет расстояние от центра детекции до ближайшей аннотации определённого класса, причём клетки внутри аннотации получают ноль. Signed distance to annotations 2D использует отрицательные значения внутри границы и положительные снаружи, что удобно для анализа градиента относительно опухоли, сосуда или другой структуры.

Detection centroid distances 2D считает расстояния между центроидами детекций разных классов. Такой показатель может отвечать на вопрос, насколько близко одна популяция клеток находится к другой, но интерпретация зависит от плотности и качества сегментации. Если часть клеток пропущена, ближайший сосед окажется искусственно дальше; если одно ядро раздроблено на несколько объектов, расстояния будут искусственно малы.

Команда на основе Delaunay triangulation связывает соседние детекции и помогает исследовать локальные кластеры. Визуализация связей включается отдельно от самих детекций. Не следует трактовать ребро триангуляции как биологический контакт: это геометрическое соседство центров. Для настоящей мембранной близости или колокализации нужно учитывать размеры клеток и биологический контекст.

Большинство встроенных пространственных команд относится к 2D. Если у вас серия оптических срезов, расстояние по одной плоскости не равно трёхмерному расстоянию. Перед анализом z-stack нужно решить, допустимо ли свести задачу к 2D-проекции или требуется другой инструмент, который учитывает координату Z.

Пространственные измерения разумно добавлять после того, как подтверждены и сегментация, и классификация. Иначе ошибка раннего этапа маскируется большим количеством красивых чисел. Контрольная выборка должна включать ручную проверку нескольких пар клеток и границ аннотаций, чтобы убедиться, что геометрия соответствует ожидаемой.

Карты плотности и поиск hotspots

Analyze → Density maps → Create density map строит низкоразрешённое изображение, в котором значение пикселя связано с плотностью выбранных объектов в заданном радиусе. Входом обычно служат детекции или клетки определённого класса. Это полезно для поиска областей с высокой концентрацией опухолевых клеток, позитивных клеток, иммунной инфильтрации и других пространственных скоплений.

Density map рассчитывается не на полном разрешении WSI, поэтому её задача — эффективная оценка пространственного распределения, а не субпиксельная локализация. Радиус определяет биологический масштаб: маленький подчёркивает локальные пики и шум, большой сглаживает структуру и объединяет соседние очаги. Выбирать радиус стоит исходя из размера микроокружения, которое имеет смысл для исследовательского вопроса.

В настройках указывают тип объектов и основной класс, которые должны участвовать в карте. Если оставить все detections, плотность будет отражать общую клеточность, а не конкретную популяцию. Для отношения одной популяции к другой нужно явно продумать знаменатель: карта абсолютной плотности CD8 и процент CD8 среди всех клеток — разные величины.

Функция Find hotspots создаёт неперекрывающиеся круглые аннотации в областях с наиболее высокими значениями. Параметр количества hotspots ограничивает число результатов, а минимальное количество объектов помогает не выбирать область, где высокое значение создано одиночным выбросом. Hotspot — это кандидат на интересный регион, а не доказательство биологической значимости.

Поскольку hotspot определяется по растрированной карте, его центр не является результатом исчерпывающего поиска среди всех возможных координат. После создания аннотации QuPath уже может пересчитать фактические объекты внутри неё с исходной геометрией, поэтому число в hotspot может немного отличаться от значения карты. Это нормальное следствие двух разных разрешений расчёта.

Экспорт измерений

Для одного изображения проще всего открыть таблицу аннотаций или детекций и сохранить её. Перед сохранением полезно убрать лишние столбцы, если формат таблицы это позволяет, и проверить единицы измерения. Экспортировать «всё на всякий случай» удобно только до тех пор, пока сотни признаков с почти одинаковыми именами не начинают мешать статистическому анализу.

Для нескольких изображений используйте Measure → Export measurements. Measurement Exporter позволяет выбрать изображения проекта, тип объектов, выходной файл, разделитель и набор столбцов. Если поле столбцов оставить пустым, попадут все доступные измерения. Кнопка Populate собирает список имеющихся столбцов по выбранным изображениям, после чего можно экспортировать только необходимые признаки.

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

Перед массовым экспортом сохраните открытое изображение. Measurement Exporter читает сохранённые данные проекта; несохранённые изменения в Viewer могут не соответствовать тому, что попадёт в итоговый файл. Практический контроль прост: экспортируйте два изображения, вручную сопоставьте несколько строк с таблицами QuPath и только затем запускайте полный проект.

Миллионы клеток создают очень большие таблицы. Экспорт всех детекций как текста может занимать много времени и места. Если исследовательский вопрос требует только сводных показателей по аннотации или TMA core, выгоднее экспортировать агрегаты. Объектный уровень нужен тогда, когда downstream-анализ действительно будет моделировать отдельные клетки, их фенотипы или пространственные отношения.

Экспорт изображений, областей и разметки

В QuPath нужно различать экспорт исходных пикселей и экспорт того, что видно на экране. Команды File → Export images… → Original pixels, OME-TIFF и OME-Zarr работают с пиксельными данными. Если выделена аннотация, можно экспортировать только её область; параметр downsample позволяет снизить разрешение. Доступные форматы зависят от типа изображения: обычный JPEG или PNG не подходит для сохранения большинства многоканальных fluorescence-данных без потери структуры каналов.

OME-TIFF и OME-Zarr позволяют сохранить пирамидальное представление, что важно для больших областей. Если вместо этого попытаться записать весь WSI в обычный непирамидальный TIFF, файл может оказаться неудобным или слишком большим для downstream-инструмента. Выбор формата должен учитывать не только размер, но и то, какие метаданные и многоканальность нужны дальше.

File → Export snapshot… → Current viewer content сохраняет визуально отрисованное представление. Это RGB-картинка с текущими настройками отображения и, при необходимости, overlay; она удобна для отчёта или публикации, но не является заменой исходных пикселей. Для векторного представления видимого окна есть экспорт SVG, где аннотации и ROI могут сохраняться как редактируемые векторы.

Если требуется обучать внешнюю нейросеть, часто удобнее экспортировать тайлы и маски. В скриптах QuPath есть TileExporter, который может задавать разрешение, размер тайла, перекрытие и условие «только аннотированные тайлы». Для разметки можно строить labeled или multichannel binary image server. При этом нужно сохранять информацию о масштабе и координатах, чтобы прогнозы внешней модели можно было связать обратно с исходным WSI.

GeoJSON — предпочтительный формат для обмена геометрией аннотаций. Координаты задаются в пикселях относительно верхнего левого угла изображения полного разрешения. Эллипсы при таком экспорте становятся полигонами, поскольку GeoJSON хранит геометрию иначе. Если внешняя система ожидает микрометры, центр координат в другом углу или уже повернутое изображение, преобразование следует выполнить явно.

Интеграция с ImageJ позволяет отправить выбранную область через меню Extensions → ImageJ. Это полезно, когда нужна функция ImageJ/Fiji, отсутствующая в QuPath, например специализированный фильтр или сохранение через другой plugin. Перед отправкой определите, нужны ли исходные пиксели или именно отрисованный snapshot: эти варианты содержат разную информацию.

Скрипты и воспроизводимая автоматизация

QuPath записывает многие действия во вкладке Workflow и в истории команд. Команда Automate → Show workflow command history показывает последовательность, а Create command history script формирует заготовку Groovy-скрипта. Это один из самых практичных способов перейти от ручной настройки к пакетной обработке: сначала вы добиваетесь правильного результата через интерфейс, затем редактируете сгенерированный код.

История не является полным журналом каждого щелчка. Некоторые действия не записываются, а некоторые команды требуют ручной доработки параметров в скрипте. Поэтому сгенерированный код нужно читать и тестировать. Он служит отправной точкой, а не формальным доказательством воспроизводимости.

Automate → Script editor открывает редактор Groovy. Команда Run → Run применяет весь скрипт к текущему изображению, Run selected — только выделенный фрагмент, а Run for project позволяет выбрать несколько записей проекта. Последний режим нужен для batch processing после того, как сценарий проверен на одном-двух слайдах.

В пакетном скрипте избегайте жёстко прописанных абсолютных путей, если проект будет переноситься. Используйте каталог проекта и имена записей, а параметры анализа выносите в верхнюю часть файла. Хороший скрипт должен явно задавать image type, stain vectors или каналы, вызывать классификаторы по стабильным именам и контролировать, какие объекты удаляются или перезаписываются.

Если сценарий повторно запускается на том же изображении, заранее решите, что делать со старыми детекциями. Иначе новый набор клеток может добавиться поверх старого, и итоговое количество удвоится. Воспроизводимый pipeline либо удаляет предыдущие промежуточные объекты контролируемо, либо создаёт новый проект/версию данных.

QuPath также поддерживает командную строку и headless-запуск скриптов. Это полезно для серверной обработки и очередей, но требует особенно аккуратного сохранения: запуск скрипта из командной строки по умолчанию не означает автоматического сохранения всех изменённых data-файлов. Перед переносом в headless-режим проверьте на тестовом проекте, какие данные сохраняет ваш конкретный сценарий и какой код возврата получается при исключении.

Для длительных batch-процессов лог важнее индикатора прогресса. Записывайте имя изображения перед обработкой и ключевые стадии, чтобы после сбоя было понятно, на каком файле остановился процесс. При повторном запуске лучше уметь пропустить уже успешно обработанные записи, чем начинать проект с нуля.

Расширения, OMERO и связь с другими инструментами

Расширения добавляют функции без замены всего приложения. Их основной интерфейс — Extensions → Manage extensions. Менеджер показывает каталог QuPath и позволяет установить, обновить или удалить поддерживаемые расширения. Если пользовательская директория ещё не задана, QuPath предложит выбрать её: именно туда будут попадать расширения и часть пользовательских данных.

Расширение стоит устанавливать только под понятную задачу. InstanSeg нужен для соответствующей нейросетевой сегментации, Deep Java Library — для запуска поддерживаемых deep-learning backends, WSInfer — для patch-based inference, OMERO — для серверных изображений. Чем больше сторонних JAR-файлов установлено вручную, тем труднее диагностировать конфликт версий после обновления QuPath.

Для расширения, отсутствующего в каталоге, возможна ручная установка JAR в пользовательскую директорию. После этого обычно рекомендуется перезапуск QuPath. Не следует держать одновременно каталоговую и вручную установленную копию одного расширения: две версии могут загрузиться непредсказуемо. При проблемах сначала проверьте менеджер и пользовательский каталог, а уже затем переустанавливайте программу целиком.

OMERO-расширение позволяет открывать удалённые изображения без полного локального копирования. После установки сервер добавляют через Extensions → OMERO → Browse server…. Изображения также можно открывать по поддерживаемому OMERO URI через File → Open URI… или добавлять в проект. Преимущество в том, что QuPath запрашивает необходимые пиксели и метаданные, а исходный набор остаётся централизованным.

Расширение умеет передавать между QuPath и OMERO аннотации, некоторые метаданные и настройки изображения при наличии соответствующих прав. Важно различать доступ на чтение и право записи. Подключение публичной учётной записью может позволять просматривать данные, но не отправлять назад ROI или key-value pairs. Перед пакетной синхронизацией проверьте одну тестовую аннотацию и убедитесь, что класс, координаты и пользователь-владелец соответствуют ожиданиям.

Связь с ImageJ/Fiji полезна не как конкурирующий режим, а как специализированное расширение рабочего процесса. QuPath лучше управляет WSI, объектами и иерархией; Fiji предлагает огромную экосистему фильтров, макросов и плагинов для отдельных изображений. Отправка выбранного ROI в ImageJ позволяет применить узкую операцию к небольшой области без попытки загрузить целый гигапиксельный слайд в память.

При обмене данными всегда фиксируйте, что именно передаётся: исходные пиксели, rendered RGB, ROI или маска. Один и тот же видимый участок может существовать в четырёх разных формах с разными числовыми значениями. Ошибка возникает, когда, например, RGB snapshot с уже применённой цветовой настройкой затем анализируют как исходный fluorescence-канал.

Производительность, память и масштабирование

QuPath не загружает whole-slide изображение целиком. Viewer запрашивает тайлы на нужном уровне пирамиды, а многие алгоритмы разбивают большую область на части. Это делает работу с гигапиксельными сканами возможной на обычной рабочей станции, но не отменяет ограничений памяти. Самые тяжёлые объекты — не только пиксели: миллионы детекций и сотни измерений на каждую клетку также занимают значительный объём Java heap.

Максимальную память можно изменить в Edit → Preferences → General → Set maximum memory for QuPath. По умолчанию приложение ориентируется примерно на долю доступной памяти, а не бесконечно занимает весь RAM. Не выделяйте QuPath почти всю физическую память: операционной системе, файловому кэшу и другим процессам тоже нужен запас. Если система начинает активно использовать swap, увеличение heap может сделать работу медленнее, а не быстрее.

Симптом недостатка памяти — не только явное сообщение OutOfMemoryError. Интерфейс может становиться очень медленным при открытии таблицы с огромным числом объектов, создании сложных аннотаций из пиксельной маски или тренировке по слишком большим областям. Уменьшение разрешения анализа, ограничение ROI и сокращение количества features часто дают больший эффект, чем простое добавление RAM.

Не создавайте full image annotation в максимальном разрешении только потому, что команда доступна. Если анализ интересует конкретную ткань, сначала выделите её на низком разрешении и работайте внутри аннотации. Это снижает количество фоновых тайлов, детекций и измерений. На WSI с большим пустым стеклом разница может быть принципиальной.

Встроенные интерактивные классификаторы в основном используют CPU через высокооптимизированные библиотеки. Общей GPU-акселерации для всех функций QuPath нет. GPU применяется прежде всего в отдельных deep-learning расширениях и зависит от backend. Поэтому покупка мощной видеокарты не ускорит автоматически построение каждой таблицы, чтение тайлов или обычный pixel classifier.

Для InstanSeg и некоторых DJL-моделей GPU может существенно ускорить inference, но настройка CUDA и PyTorch — отдельная задача. На Apple silicon некоторые модели могут использовать MPS. Если GPU не определяется, сначала добейтесь правильного результата на CPU. Ошибка вычислительного backend не должна блокировать методическую проверку сегментации.

Производительность чтения часто определяется диском или сетью. WSI на медленном NAS может открываться дольше, чем тот же файл на локальном SSD, хотя объём RAM одинаков. При OMERO добавляется задержка сервера и сети. Если Viewer подгружает серые тайлы с паузой, проверьте путь хранения и сервер до попытки «лечить» проблему параметрами Java.

Пиксельная классификация чувствительна к Resolution. Выбирайте самое грубое разрешение, которое сохраняет нужную структуру. Для отделения ткани от стекла нет смысла анализировать каждый пиксель исходного 40× скана; для мелких лимфоцитов, наоборот, чрезмерный downsample уничтожит объект. Разрешение — часть модели и должно быть зафиксировано в протоколе вместе с threshold и feature set.

Количество обучающих данных тоже влияет на интерактивность. Для Train pixel classifier несколько маленьких разнообразных ROI обычно полезнее огромных закрашенных зон. Для object classifier десятки тысяч почти идентичных клеток в одном поле не компенсируют отсутствие примеров из других слайдов. Сокращение избыточных примеров одновременно улучшает отзывчивость и уменьшает риск переобучения.

Перед длительным batch run оцените время на нескольких слайдах разного размера. Не нужно превращать эту оценку в «бенчмарк QuPath»: скорость зависит от формата, диска, алгоритма, разрешения, числа объектов и расширений. Цель теста — понять порядок времени и убедиться, что выбранный pipeline технически выполним для вашей выборки.

Типичные ошибки и способы их исправления

Изображение выглядит неправильно сразу после открытия

Проверьте image type, каналы и Brightness/Contrast. Для fluorescence убедитесь, что нужные каналы включены и их диапазоны отображения разумны. Для brightfield проверьте, не выбран ли неверный тип. Если число каналов или размеры явно неправильны, повторно откройте файл с другим image server. Не конвертируйте исходник в 8-bit JPEG как первый способ «починить» просмотр.

Клетки не находятся или находятся в фоне

Сначала убедитесь, что выбран правильный detection channel. Затем проверьте физическую калибровку и Requested pixel size. Настройте threshold на небольшом ROI. Если фон неоднороден, подберите Background radius и сглаживание. После запуска включите отображение детекций и посмотрите границы на большом увеличении. Если встроенный алгоритм систематически не справляется с плотными клетками, рассмотрите InstanSeg или StarDist, но только после проверки входного изображения.

После изменения stain vectors результаты не изменились

Уже сохранённые измерения не пересчитываются автоматически. Удалите или перезапустите соответствующие детекции и расчёты после исправления stain vectors. Чтобы избежать смешения старых и новых результатов, сохраните исходный вариант проекта отдельно или явно очистите промежуточные объекты перед повторным запуском.

Пиксельный классификатор хорош на одном слайде и плох на других

Это типичный перенос домена. Добавьте обучающие примеры из разных слайдов и партий, уменьшите зависимость от нестабильных features, проверьте stain/channel normalization. Используйте Load training или training image из нескольких источников. Обязательно оставьте независимые изображения, которые не участвовали в разметке, для проверки переносимости.

Классификатор использует артефакт вместо биологии

Откройте measurement maps по признакам, которые вошли в модель. Если класс совпадает с краем скана, фокусом, участком конкретной партии или координатой, признак, вероятно, технический. Уберите его из features или измените обучение. Добавьте контрпримеры, где артефакт встречается в обоих классах.

Проект перестал находить изображения

Не создавайте новый проект поверх старого. Откройте существующий и используйте диалог обновления URI. Для массового исправления укажите корневую папку, где лежат перемещённые файлы, и дайте QuPath найти совпадения по именам. Прежде чем нажать Apply changes, проверьте несколько строк вручную.

Экспорт пустой или содержит старые значения

Сохраните данные изображения перед Measure → Export measurements. Проверьте Export type и выбранные изображения. Если запрошенный столбец существует не во всех слайдах, пустые ячейки допустимы. Если таблица полностью пуста, убедитесь, что нужный тип объектов действительно сохранён в проекте, а не только отображается в текущей несохранённой сессии.

QuPath тормозит после создания миллионов объектов

Оцените, действительно ли нужен объектный уровень. Для площади окрашивания используйте pixel measurements вместо клеток. Для пространственной задачи ограничьте ROI. Удалите ненужные промежуточные детекции и сократите набор measurements. Увеличение памяти имеет смысл только после сокращения очевидной избыточности.

Расширение установлено, но команда не появляется

Перезапустите QuPath, проверьте пользовательскую директорию и версию расширения. В менеджере убедитесь, что нет второй вручную установленной копии. Для deep-learning расширений отдельно проверьте обязательные зависимости: отсутствие DJL или PyTorch не исправляется повторной установкой самого QuPath.

GPU есть, но обработка идёт на CPU

Общая часть QuPath и не обязана использовать GPU. Для конкретного deep-learning расширения выберите поддерживаемое устройство и проверьте совместимость backend. На NVIDIA важны версии CUDA и библиотек; на Mac — поддержка MPS конкретной моделью. Если ускоритель нестабилен, CPU остаётся корректным резервным вариантом.

Аннотации экспортировались со сдвигом во внешнюю систему

Проверьте происхождение координат, ориентацию, downsample и единицы. QuPath GeoJSON использует пиксельные координаты полного разрешения с началом в левом верхнем углу. Если downstream-система работает в микрометрах или после поворота, преобразование должно учитывать калибровку и трансформацию.

Практический сценарий: H-DAB whole-slide изображение

Ниже — безопасная последовательность для исследовательского подсчёта положительных клеток в H-DAB. Она не задаёт универсальных числовых порогов, потому что их нужно валидировать на конкретной окраске.

1. Создайте проект. Добавьте WSI и сохраните исходные файлы в стабильном месте. Убедитесь, что масштаб в микрометрах читается корректно.
2. Установите Image type. Выберите Brightfield H-DAB и проверьте деконволюционные каналы.
3. Проверьте stain vectors. На репрезентативной области оцените разделение hematoxylin и DAB. Если требуется, скорректируйте vectors до любых измерений.
4. Определите ткань. Используйте Create thresholder или ручные аннотации, чтобы исключить стекло, крупные артефакты и нерелевантные области.
5. Настройте детекцию. На небольшом ROI запустите Cell detection или Positive cell detection. Проверьте слабые ядра, плотные скопления и ложные объекты.
6. Выберите score compartment. Он должен соответствовать локализации маркера. Ядерный маркер не следует оценивать по случайной клеточной области только потому, что такое поле есть в списке.
7. Подберите порог положительности. Используйте таблицу, гистограмму и визуальную проверку клеток около порога. Не подгоняйте результат под ожидаемый процент.
8. Проверьте независимые ROI. Перейдите к другим участкам того же слайда и к нескольким другим слайдам.
9. Сохраните параметры. Зафиксируйте классификатор и историю команд, затем превратите последовательность в скрипт.
10. Запустите проект пакетно. Следите за логом и сохраняйте данные после успешной обработки каждого изображения.
11. Экспортируйте сводные или клеточные данные. Выберите уровень в зависимости от статистического плана и убедитесь, что единицы и названия столбцов одинаковы.

Контроль качества должен сопровождать все стадии. Если после смены stain vectors или разрешения алгоритма результаты изменились, не смешивайте старые и новые таблицы. Воспроизводимый анализ — это единый набор параметров, применённый к определённой выборке с заранее описанными исключениями.

Практический сценарий: multiplex fluorescence

Для многоканального fluorescence-набора главная задача — не перепутать визуальную настройку с измерительным pipeline. Сначала добавьте изображения в проект и проверьте Image type = Fluorescence. Затем откройте Brightness/Contrast, задайте короткие имена каналов и убедитесь, что цвета отображения помогают различать маркеры, но не скрывают слабую популяцию.

Далее выберите канал, пригодный для сегментации всех ядер. Если DAPI чистый и равномерный, можно начать со встроенного Cell detection. Если клетки плотно прилегают, границы важны или данные сложнее, протестируйте InstanSeg на небольшой аннотации. Сравните не количество клеток, а качество отдельных контуров в разных типах ткани.

После сегментации откройте measurement table и убедитесь, что для каждого канала появились ожидаемые измерения в нужных компартментах. Постройте гистограммы нескольких маркеров и measurement maps. Если интенсивность одного маркера меняется по полю из-за фона или затухания, один глобальный threshold может быть неподходящим.

Для хорошо разделённых сигналов создайте single measurement classifier по каждому маркеру. Для более сложных случаев обучите object classifier на точках или небольших аннотациях. Положительные и отрицательные примеры должны быть представлены на нескольких изображениях. Не включайте в обучение только яркие «очевидные» клетки: классификатор чаще ошибается именно в пограничной зоне.

После получения отдельных маркерных классификаций объедините их в нужные фенотипы. Не генерируйте все математически возможные комбинации, если исследовательский протокол использует только несколько. Каждая дополнительная комбинация усложняет проверку, экспорт и статистику.

Затем проверьте пространственный контекст. Для популяций иммунных клеток можно вычислить расстояние до опухолевой аннотации, плотность или hotspots. Если анализ связан с границей опухоли, лучше использовать экспертно подтверждённую аннотацию этой границы, чем позволять клеточному классификатору косвенно задавать её через плотность.

Перед batch run сохраните тестовые данные и классификаторы. Запустите скрипт на небольшой группе слайдов, включая слабый и сильный сигнал. Сравните распределения количества клеток, процентов фенотипов и основных интенсивностей. Резкий сдвиг одного изображения часто указывает на проблему канала, экспозиции или сегментации, которую проще поймать до полной обработки проекта.

Сравнение с аналогами

QuPath стоит сравнивать с программами, которые решают близкие задачи цифровой патологии, и отдельно — с обычными фоторедакторами. Требования к ним принципиально различаются. Для патологии важны whole-slide навигация, физическая калибровка, объектная иерархия, клеточная сегментация, классификаторы, таблицы измерений и пакетная воспроизводимость. Для фотографии приоритеты другие: тон, цвет, ретушь, удаление объектов и композиционное редактирование.

QuPath и ФотоМАСТЕР

ФотоМАСТЕР предназначен для обработки обычных фотографий. Он открывает в том числе RAW-файлы с камер, предлагает цветокоррекцию, HSL, локальный корректор, портретную ретушь, восстановительную кисть, заплатку, удаление объектов, замену и размытие фона. Если задача — улучшить фотографию, скорректировать цвет, убрать дефект кожи или заменить задний план, такой набор инструментов релевантен.

QuPath решает другую задачу. Он не пытается конкурировать по ретуши и декоративным эффектам, зато связывает микроскопические пиксели с физическим масштабом, объектами, классами и измерениями. Пользователь может создать ROI опухоли, найти десятки тысяч клеток, измерить маркеры, классифицировать популяции и экспортировать таблицу. ФотоМАСТЕР не является прямой заменой этому pipeline, а QuPath не является удобной заменой фоторедактору.

Практический критерий выбора простой: если итог работы — визуально отредактированная фотография, нужен редактор класса ФотоМАСТЕР. Если итог — количественные данные по ткани, клеткам, маркерам и пространственным отношениям, нужен QuPath или специализированная система цифровой патологии. Сравнивать их по числу фильтров или поддерживаемых WSI бессмысленно, потому что это разные классы задач.

QuPath и Orbit Image Analysis

Orbit — более прямая альтернатива. Он также рассчитан на большие whole-slide изображения, использует тайловую обработку, поддерживает сегментацию объектов, trainable tissue quantification, классификацию и подключение к OMERO. Orbit может работать локально и имеет механизмы масштабирования вычислений через Spark. По набору базовых задач он ближе к QuPath, чем обычные редакторы или универсальные средства микроскопии.

Различие нужно оценивать по конкретному pipeline и привычкам команды. QuPath предлагает очень развитую модель объектов, Groovy-скрипты, интерактивные pixel/object classifiers, TMA-инструменты, интеграцию ImageJ, GeoJSON и современную экосистему расширений. Orbit имеет собственный интерфейс обучения, API и архитектуру. Готовые модели, параметры и аннотации нельзя считать взаимозаменяемыми только потому, что обе программы рисуют похожие контуры.

Если организация уже использует OMERO и Orbit-процессы, миграция ради отдельной функции может не окупиться. Если же нужен открытый активно развиваемый workflow с тесной связью интерактивного анализа и скриптов, QuPath часто проще встроить в исследовательскую методику. Решение лучше принимать на пилотном наборе, сравнивая качество сегментации, воспроизводимость экспорта и удобство batch processing.

QuPath и HALO

HALO — коммерческая платформа для количественного анализа цифровой патологии. Она поддерживает распространённые WSI и микроскопические форматы, клеточный анализ, multiplex, spatial analysis, heatmaps, TMA и AI-модули. Существенная часть функций оформлена как специализированные модули и сопровождается коммерческой поддержкой и обучением. Для лаборатории, которой важны готовая инфраструктура, централизованная поддержка и стандартизованные модули, это может быть принципиальным преимуществом.

QuPath, напротив, распространяется как открытое программное обеспечение и делает больший акцент на прозрачной пользовательской настройке, скриптах и расширениях. Это даёт свободу адаптации, но требует компетенции внутри команды. Там, где HALO предлагает лицензируемый модуль с определённым интерфейсом, в QuPath исследователь может собирать pipeline из встроенных команд, Groovy и расширений — и сам отвечает за его валидацию.

Поэтому выбор между ними нельзя свести к «у какой программы больше функций». В регулируемой или крупной корпоративной среде важны поддержка, управление лицензиями, инфраструктура и валидационные процедуры. В академической лаборатории могут быть важнее доступ к исходному коду, отсутствие платы за каждое рабочее место, автоматизация и возможность модифицировать pipeline. При этом QuPath официально не предназначен для клинической диагностики.

QuPath и Fiji / ImageJ

Fiji — дистрибутив ImageJ с большим набором плагинов, включая Bio-Formats и инструменты для научной обработки. Он силён там, где нужен конкретный фильтр, макрос, анализ небольшого многомерного изображения или специализированный community-plugin. Поддержка десятков и сотен форматов через Bio-Formats делает Fiji удобным универсальным инструментом лабораторной визуализации.

QuPath лучше приспособлен к навигации по whole-slide данным, иерархии аннотаций и детекций, привязке измерений к объектам и построению pathology-oriented workflow. Вместо выбора «один из двух» часто рациональнее использовать интеграцию: найти и аннотировать ROI в QuPath, отправить нужный регион в ImageJ, выполнить узкую операцию и вернуть или сохранить результат в контролируемой форме.

Кому подходит QuPath и где его границы

QuPath особенно уместен, если исследование включает большие гистологические или микроскопические изображения, ручную или автоматическую разметку ROI, сегментацию клеток, подсчёт маркеров, классификацию тканей, TMA, multiplex и пространственный анализ. Он хорошо подходит для задач, где визуальная проверка должна быть связана с табличными данными и повторяемым скриптом.

Программа требует методической дисциплины. Она не определяет за пользователя правильный порог, stain vector, biological class или способ валидации. Даже простой percentage positive зависит от ROI, разрешения, сегментации, компартмента и threshold. Сильная сторона QuPath — дать инструменты, чтобы эти решения можно было сделать явными и воспроизвести.

Если задача заключается только в ретуши фотографии, подготовке иллюстрации для соцсетей или замене фона, QuPath избыточен и неудобен. Если нужна полноценная 3D-сегментация объёма, следует проверить специализированные программы: многие встроенные пространственные команды QuPath двумерны. Если требуется клиническое диагностическое применение, необходимо использовать соответствующим образом одобренные и валидированные системы, а не исследовательский QuPath.

Для исследовательской цифровой патологии QuPath наиболее полезен тогда, когда проект организован с самого начала: стабильные пути к изображениям, единые имена каналов и классов, сохранённые классификаторы, проверенные ROI, скрипт пакетной обработки и контрольная выборка. В таком режиме программа становится не просто viewer с алгоритмами, а воспроизводимой средой, где каждый числовой результат можно вернуть к конкретному объекту и конкретному участку ткани.

ФотоМАСТЕР предназначен для обычной визуальной обработки фотографий и не заменяет специализированные функции этой программы: управление оборудованием, астрономические расчёты, измерения или научный анализ. В сравнении рассматриваются разные этапы работы с изображениями, а не полная взаимозаменяемость приложений.