StarDist: сегментация ядер и клеток на микроскопических изображениях

StarDist решает задачу экземплярной сегментации объектов на микроскопических изображениях: он находит отдельные ядра или клетки, даже когда они расположены плотно, соприкасаются и частично перекрываются, и возвращает не просто бинарную маску, а отдельную геометрию для каждого объекта. Программа особенно полезна исследователям в биомедицинской визуализации, гистологии и клеточной биологии, которым нужно получать воспроизводимые маски, считать объекты, измерять их форму и площадь, передавать сегментацию в Fiji/ImageJ, napari, Python или QuPath и при необходимости обучать собственные модели на размеченных данных.

Что именно делает StarDist

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

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

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

Результатом обычно является label image, где фон имеет значение 0, а каждый найденный экземпляр получает собственный положительный идентификатор. В Fiji результат можно также вернуть как набор ROI, в napari — как слой Labels и отдельно как Polygons или Polyhedra, а в Python — как массив меток плюс словарь геометрических данных. Такая форма результата удобна для последующего подсчёта, фильтрации по размеру, измерения интенсивности, построения статистики и ручного контроля спорных объектов.

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

Как выбрать рабочий интерфейс

У StarDist нет единственного обязательного пользовательского интерфейса. Один и тот же метод доступен в нескольких рабочих контурах, и выбор влияет не на идею алгоритма, а на доступные размеры данных, 2D/3D-режим, автоматизацию и удобство контроля результата. Для разового анализа двумерного кадра проще всего Fiji/ImageJ. Для интерактивной работы с 2D и 3D данными удобнее napari. Для воспроизводимых серийных задач, обучения и тонкой настройки нужен Python API. В цифровой патологии StarDist часто используют через расширение QuPath, где сегментация становится частью сценария анализа whole-slide изображений.

Переключение между интерфейсами не означает, что все параметры называются одинаково или имеют одинаковый набор опций. Например, в Fiji пользователь задаёт Probability/Score Threshold и Overlap Threshold прямо в диалоге StarDist 2D, а в QuPath аналогичный порог вероятности передают в builder через threshold(); перекрытия QuPath обрабатывает по собственным правилам, потому что ядра как объекты QuPath не должны пересекаться. Поэтому при переносе настройки из одного контура в другой нужно переносить смысл параметра, а не механически копировать число.

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

Fiji/ImageJ

Для работы через Fiji нужен сам Fiji и три update site, которые используются плагином: CSBDeep, StarDist и TensorFlow. В Fiji откройте Help → Update…, затем нажмите Manage update sites, отметьте соответствующие сайты обновлений, закройте список, примените изменения кнопкой Apply changes и перезапустите Fiji. После успешной установки в меню Plugins → StarDist появляется команда StarDist 2D.

Если StarDist отсутствует в списке update sites, сначала обновите список источников обновлений. Если после установки команда есть, но запуск заканчивается Java-ошибкой, причиной чаще бывает несовместимость библиотек в конкретной сборке Fiji, а не неправильное изображение. В таких случаях полезно создать чистую копию Fiji и включить только необходимые update site, а не пытаться «долечить» среду десятками сторонних плагинов. Старые сообщения о конфликте protobuf в экспериментальных сборках Fiji-Latest особенно важны как напоминание: для рабочего контура лучше фиксировать известную стабильную конфигурацию, а обновления проверять отдельно.

Python и napari

Базовый пакет устанавливается в отдельное Python-окружение. Перед StarDist должен быть установлен совместимый TensorFlow; затем ставится пакет stardist. Для графического интерфейса napari дополнительно устанавливается stardist-napari и сам napari. Отдельная среда полезна не только для порядка: TensorFlow, CUDA, cuDNN, Qt и плагины napari имеют собственные матрицы совместимости, и системный Python быстро превращается в источник конфликтов.

Современные колёса StarDist доступны для распространённых 64-битных Windows, Linux и macOS, включая Apple Silicon. Если подходящего wheel нет и пакет собирается из исходников, понадобится C/C++ компилятор; на Windows это Build Tools Visual Studio, а на Unix-подобных системах — совместимый GCC или Clang. Для пользователя, которому нужно только применить готовую модель, сборка из исходников обычно не даёт преимуществ: проще подобрать поддерживаемую версию Python и установить готовый пакет.

Плагин napari можно открыть через Plugins → stardist-napari: StarDist. Для проверки установки удобно использовать встроенный пример через File → Open Sample → stardist-napari. При первом выборе некоторых предобученных моделей веса загружаются и кэшируются; поэтому первый запуск может занимать больше времени, чем последующие.

Первый рабочий сценарий в Fiji

Откройте в Fiji двумерное микроскопическое изображение или 2D+time стек. Для многоканальных данных заранее выберите тот канал, который соответствует входу модели, если модель одноканальная. Для DAPI-флуоресценции обычно используют канал ядер. После этого запустите Plugins → StarDist → StarDist 2D. Откроется диалог, разделённый на блоки Neural Network Prediction, NMS Postprocessing и Advanced Options.

Для первого прогона на флуоресцентных ядрах выберите встроенную модель Versatile (fluorescent nuclei), оставьте включённой Normalize Image, а процентили — близкими к значениям модели по умолчанию. В типичных примерах используются нижний процентиль около 1 и верхний около 99,8. Эти числа не являются универсальной «правильной настройкой», но дают безопасную отправную точку для изображений, похожих на данные обучения.

В блоке NMS Postprocessing сначала оставьте пороги модели. Probability/Score Threshold определяет, какие кандидаты вообще допускаются к постобработке. При увеличении значения объектов становится меньше, и слабые ложные срабатывания часто исчезают вместе с частью слабых настоящих объектов. Overlap Threshold задаёт допустимую степень перекрытия конкурирующих кандидатов: увеличение порога позволяет сильнее перекрываться окончательным объектам. Для первого запуска разумнее не «крутить» оба параметра одновременно, а сначала оценить базовый результат.

В Output Type выберите Both, чтобы получить и Label Image, и записи в ROI Manager. Это удобный режим для контроля: label image сразу показывает, разделены ли соприкасающиеся ядра, а ROI Manager позволяет включить Show All, выбрать конкретный объект, измерить его или удалить ошибочный ROI. После этого нажмите OK и дождитесь завершения.

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

Параметры окна StarDist 2D в Fiji

Model

Встроенный список включает модели для флуоресцентных ядер и H&E. В документации плагина перечисляются Versatile (fluorescent nuclei), DSB 2018 (from StarDist 2D paper) и Versatile (H&E nuclei). Первая рассчитана на разнообразные флуоресцентные ядра, DSB-модель связана с исходным набором Data Science Bowl 2018, а H&E-модель обучалась на гистологических изображениях. Выбор должен соответствовать типу изображения, а не названию файла или привычке пользователя.

Плагин умеет открывать пользовательскую модель из ZIP-файла или по URL, но для воспроизводимого локального процесса лучше хранить проверенный архив модели вместе с проектом и фиксировать его контрольную сумму или внутреннюю версию. Если модель обучена самостоятельно, перед передачей коллегам нужно экспортировать её в формат, который ожидает ImageJ-плагин; обычная папка Python-модели и ZIP для Fiji — это разные способы упаковки.

Normalize Image и процентили

Процентильная нормализация отображает выбранный нижний процентиль распределения интенсивностей в 0, а верхний — в 1. Значения ниже и выше диапазона могут выходить за пределы 0…1 до последующего клиппинга внутри цепочки обработки. Смысл настройки в том, чтобы привести диапазон входа ближе к тому, что видела модель при обучении, и не позволить нескольким выбросам определять весь диапазон.

Если данные уже нормализованы внешним пайплайном именно так, как ожидает модель, повторная нормализация может быть лишней. В остальных случаях отключать её без проверки не стоит. Особенно плохо работают произвольные изменения контраста «для красивой картинки» перед сегментацией: LUT в Fiji меняет отображение, а не обязательно пиксели, тогда как команды, реально изменяющие значения, меняют статистику входа и могут существенно сдвинуть результат.

Probability/Score Threshold

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

Overlap Threshold

Порог перекрытия используется при non-maximum suppression. Модель генерирует множество частично дублирующих кандидатов, а NMS оставляет наиболее правдоподобные. Более высокий порог допускает более сильное взаимное перекрытие окончательных объектов. В плотно упакованных культурах это может помочь сохранить соседние ядра, но чрезмерно свободный порог способен оставить дубли. В гистологии, где ядра геометрически перекрываются в проекции реже, базовые значения обычно являются лучшей отправной точкой.

Advanced Options

Number of Tiles разбивает изображение на части для нейросетевого предсказания и снижает пиковое потребление памяти. Boundary Exclusion исключает объекты, расположенные слишком близко к границе изображения, если нужно избежать усечённых объектов. Параметр ROI Position управляет тем, как позиции ROI привязываются к обычному стеку или гиперстеку. Флаги Verbose, Show CNN Progress и Show CNN Output полезны для диагностики, но для пакетной работы создают лишний визуальный вывод.

Кнопка Set optimized postprocessing thresholds (for selected model) возвращает пороги, сохранённые в выбранной модели, а Restore Defaults восстанавливает исходные значения интерфейса. Это важно, потому что после серии экспериментов пользователь нередко забывает, что изменял пороги. Перед сравнением двух изображений стоит либо фиксировать параметры в журнале, либо восстанавливать один и тот же набор настроек.

Работа через napari

Плагин napari предоставляет те же основные принципы, но лучше подходит для многомерных массивов. После открытия изображения StarDist появляется как dock-widget справа от viewer. В верхней части выбирается Input Image, ниже задаются Image Axes, затем тип модели, конкретная предобученная или пользовательская модель, нормализация, NMS, тип выхода и параметры тайлинга.

Первое, что нужно проверить, — оси. Napari показывает массив как слой, но StarDist должен знать семантику каждого измерения. Строка Image Axes использует обозначения X, Y, Z, C и T. Для простой двумерной картинки это обычно YX; для трёхмерного стека — ZYX; для многоканального 2D изображения — YXC или CYX в зависимости от фактического порядка массива. Плагин пытается угадать оси, но автоматическая догадка не заменяет проверку формы массива.

Если активна 2D-модель и viewer находится в двумерном режиме, может быть доступен флаг Predict on field of view. Он запускает предсказание только на текущей видимой области. Это полезно для подбора параметров на большом изображении: можно быстро сравнить несколько порогов на характерном фрагменте, а уже затем запускать всю картинку. Такой режим нельзя считать заменой полной валидации, потому что выбранный участок может не содержать редкие типы артефактов.

В блоке Model Type доступны 2D, 3D и пользовательская модель. Поле Pre-trained Model показывает зарегистрированные модели. Для пользовательской модели указывается папка, где находятся как минимум config.json и совместимый файл весов .h5 или .hdf5. Если рядом есть thresholds.json, плагин может загрузить оптимизированные пороги кнопкой, расположенной под параметрами постобработки.

Model Axes — поле только для чтения. Оно показывает, какие оси и число каналов ожидает модель, например YXC[1] для 2D-модели с одним входным каналом. Если входной слой имеет два канала, а модель ожидает один, правильное решение — выбрать или сформировать нужный канал, а не пытаться скрыть несовместимость перестановкой букв в Image Axes.

Нормализация и масштаб входного изображения

В napari флаг Normalize Image включает процентильную нормализацию, а Percentile low и Percentile high задают границы. По умолчанию пространственные оси нормализуются совместно, а каналы можно нормализовать раздельно через Normalization Axes. Для независимых флуоресцентных каналов раздельная статистика обычно логична: один яркий канал не должен сжимать динамический диапазон другого.

Input image scaling — отдельный инструмент и не эквивалент нормализации. Он изменяет пространственный масштаб перед предсказанием и затем пересчитывает координаты результата обратно. Это один из самых полезных параметров, когда объекты на ваших данных заметно крупнее или мельче объектов, на которых обучалась модель. Например, коэффициент 0,5 по пространственным осям уменьшает изображение вдвое перед сетью, то есть делает крупные объекты в координатах модели меньше.

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

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

Порог вероятности и NMS в napari

Probability/Score Threshold и Overlap Threshold в napari соответствуют тем же этапам, что и в Fiji. Кнопка Set optimized postprocessing thresholds (for selected model) устанавливает значения, которые были оптимизированы и сохранены разработчиком или автором пользовательской модели. Эти значения следует воспринимать как отправную точку, а не как гарантию качества на любых изображениях.

Практически удобно настраивать пороги в два шага. Сначала зафиксируйте Overlap Threshold и меняйте только Probability/Score Threshold на контрольных изображениях. Отметьте, где начинают исчезать ложные положительные объекты и где появляются ложно отрицательные. Затем зафиксируйте выбранный порог вероятности и исследуйте зоны тесного контакта объектов, меняя Overlap Threshold. Такой порядок даёт более понятную причинно-следственную связь, чем хаотичное перемещение двух ползунков.

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

Типы выходов и слои результата

В napari поле Output Type управляет тем, какие представления результата создаются. Label Image возвращает слой StarDist labels, где каждому объекту соответствует целочисленная метка. Polygons / Polyhedra создаёт геометрию: Shapes для 2D или Surface для 3D. Режим Both возвращает оба представления одновременно.

Для проверки сегментации удобен режим Both. Цветные метки позволяют быстро увидеть, разделились ли соседние объекты, а геометрический слой даёт понятную границу поверх исходного изображения. Для дальнейшего количественного анализа обычно удобнее label image: его легко передать в scikit-image, pandas, CellProfiler-подобные сценарии или собственные скрипты, где идентификатор метки становится ключом измерений.

Флаг Show CNN Output добавляет промежуточные предсказания сети: карту вероятности объектов и карты радиальных расстояний; для многоклассовых моделей может появиться и выход классов. Это диагностический режим. Он помогает понять, ошибается ли сеть уже на уровне вероятности объекта или правильные кандидаты теряются позднее при NMS. Для обычного потока его лучше выключать, иначе память расходуется на крупные промежуточные массивы.

После завершения 3D-предсказания слой Labels можно просматривать по срезам или в объёмном режиме napari, а Surface — как набор многогранников. Не следует путать визуальную гладкость поверхности с фактической точностью: StarDist описывает форму конечным числом лучей, поэтому граница остаётся аппроксимацией. При морфометрии чувствительных параметров нужно оценить систематическую ошибку на размеченных объектах.

Крупные изображения и тайлинг

Нейросетевое предсказание на крупном кадре может не помещаться в оперативную память или видеопамять. В napari поле Number of Tiles принимает число плиток по осям; в Python для обычного предсказания используется n_tiles. Смысл одинаков: изображение делится на перекрывающиеся области, сеть обрабатывает их по очереди, а кандидаты объединяются перед финальной NMS.

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

Число плиток подбирают минимальное, при котором задача стабильно выполняется. Слишком мелкие плитки увеличивают накладные расходы, число граничных зон и время подготовки данных. Если память заканчивается в 3D, обычно выгоднее сначала делить по наиболее длинной пространственной оси и постепенно увеличивать разбиение. В napari подсказка к полю показывает соответствие чисел семантическим осям, что помогает не перепутать Z, Y и X.

Для действительно больших изображений Python API предоставляет отдельный механизм обработки больших массивов. В таких сценариях важно задавать блоки с перекрытием, чтобы объект у границы блока не оказался усечён. Размер блока должен учитывать поле зрения сети и максимальный ожидаемый диаметр объектов. Если результат на швах отличается от результата на небольшом тестовом кадре, блоки слишком малы или не хватает контекста.

Трёхмерная сегментация

Официальный Fiji-плагин StarDist ориентирован на 2D и 2D+time, поэтому для настоящего 3D стека следует использовать Python или napari. В napari выберите Model Type = 3D, задайте корректные оси ZYX и модель, подходящую для трёхмерных данных. В демонстрационных данных используется зарегистрированная 3D-модель, но для реальной лабораторной серии чаще требуется собственная модель, потому что размер и анизотропия ядер сильно зависят от оптики и шага по Z.

В 3D геометрия строится по набору лучей, распределённых по сфере. Конфигурация StarDist3D по умолчанию использует лучи типа Golden Spiral, а параметр anisotropy позволяет учитывать неравный масштаб по осям. Если шаг по Z значительно больше размера пикселя XY, игнорирование анизотропии делает объект в индексных координатах «сплющенным» или «вытянутым» относительно физических размеров. Это влияет и на обучение, и на качество многогранников.

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

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

Python API: воспроизводимый рабочий процесс

Python API нужен, когда анализ должен повторяться на десятках или тысячах изображений, когда требуется собственное обучение или когда результаты нужно связать с последующей статистикой. Для 2D используется класс StarDist2D, для 3D — StarDist3D. Предобученную модель можно получить через from_pretrained(), затем вызвать predict_instances().

from stardist.models import StarDist2D
from csbdeep.utils import normalize

model = StarDist2D.from_pretrained("2D_versatile_fluo")
img_n = normalize(img, 1, 99.8, axis=(0, 1))
labels, details = model.predict_instances(img_n)

Функция возвращает массив экземпляров и словарь с дополнительной геометрией. В зависимости от версии и типа модели там доступны координаты центров, полигоны или многогранники, вероятность и связанные данные. Для научного пайплайна разумно сохранять не только итоговый TIFF с метками, но и параметры запуска: имя модели, пороги, процентили нормализации, n_tiles, порядок осей и версию окружения.

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

Для сохранения label image предпочтителен целочисленный формат без потери идентификаторов. Если число объектов превышает диапазон 8-битного TIFF, 8 бит использовать нельзя. На практике часто выбирают 16 или 32 бита в зависимости от количества экземпляров. При сохранении RGB-превью цвет каждой метки предназначен только для визуализации и не должен заменять исходный массив идентификаторов.

Подготовка данных для собственной модели

Собственная модель нужна, когда предобученные варианты систематически ошибаются из-за другой морфологии, масштаба, окраски, оптики или уровня шума. Входом обучения служат пары «изображение — label mask». Маска должна быть целочисленной: фон 0, каждый экземпляр имеет уникальное положительное значение. Значения не обязаны идти подряд; важно, чтобы разные соприкасающиеся объекты имели разные идентификаторы.

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

В FAQ проекта отмечается, что хорошие 2D-результаты иногда удаётся получить на сравнительно небольшом количестве тщательно размеченных кропов, но это не универсальная гарантия. Важнее разнообразие примеров: разные поля, интенсивности, плотность объектов, артефакты, края ткани и редкие формы. Набор из сотен почти одинаковых клеток из одного поля может быть менее полезен, чем несколько десятков разнообразных изображений.

Train и validation должны разделяться на уровне биологически независимых изображений, а не случайных соседних патчей одного большого поля. Иначе валидация становится слишком оптимистичной: соседние кропы имеют одинаковый фон, освещение и морфологию. Для многосрезовых данных особенно опасно разбрасывать соседние Z-срезы одного образца между обучением и валидацией.

Аугментация должна отражать возможные вариации эксперимента. Повороты и отражения обычно безопасны для ядер без ориентационного смысла; умеренные изменения интенсивности помогают устойчивости к экспозиции. Сильные деформации, не встречающиеся в реальной оптике, создают искусственные формы и могут ухудшить модель. Любая геометрическая аугментация должна одинаково преобразовывать изображение и его label mask, причём маску нельзя интерполировать как обычное фото — только методами, сохраняющими целые идентификаторы.

Конфигурация и обучение модели

В 2D конфигурация создаётся через Config2D. Ключевые параметры включают n_rays, grid, число входных каналов, архитектуру backbone, размер обучающего патча, batch size, число эпох и шагов на эпоху. По умолчанию 2D-модель использует 32 радиальных направления. Больше лучей позволяет точнее аппроксимировать контур, но увеличивает число выходных каналов и стоимость обучения.

from stardist.models import Config2D, StarDist2D

conf = Config2D(
    n_rays=32,
    grid=(2, 2),
    n_channel_in=1,
    train_patch_size=(256, 256),
    train_batch_size=4,
)
model = StarDist2D(conf, name="nuclei_custom", basedir="models")

grid задаёт субдискретизацию предсказаний и должен согласовываться с архитектурой. Увеличение grid снижает пространственную плотность точек-кандидатов и увеличивает эффективное поле зрения, но может мешать мелким объектам. Для задач с маленькими ядрами агрессивная субдискретизация опасна; для крупных объектов она может быть полезна.

Функция train() принимает изображения X, label masks Y и отдельные validation_data. Пользовательский augmenter вызывается для пары изображения и маски. После обучения модель сохраняет веса и конфигурацию. На практике имеет смысл вести TensorBoard или хотя бы сохранять историю loss, но выбирать модель только по минимальному loss нельзя: итоговая задача — экземплярная сегментация, поэтому нужно оценивать качество совпадений объектов.

Для 3D используется Config3D; конфигурация по умолчанию задаёт 96 лучей Golden Spiral. Можно передать anisotropy, чтобы распределение лучей и геометрия учитывали разные масштабы по Z, Y и X. Обучающий patch size должен быть кратен требованиям сети и помещаться в память. Если объекты занимают почти весь патч, сеть видит слишком мало фона и соседства; если патч огромен, batch size падает до единицы и обучение становится менее гибким по памяти.

Оценка качества и оптимизация порогов

После обучения StarDist выполняет два связанных шага: сеть прогнозирует вероятность и радиальные расстояния, затем NMS превращает множество кандидатов в отдельные экземпляры. Поэтому качество зависит и от весов сети, и от порогов. Метод optimize_thresholds() позволяет подобрать probability threshold и NMS threshold по размеченной validation-выборке. Это предпочтительнее ручного выбора по одному изображению.

Для оценки используют сопоставление предсказанных и истинных объектов по IoU. При заданном пороге IoU объект считается совпавшим, если перекрытие достаточно велико. Затем можно вычислять precision, recall, F1, среднее качество совпавших объектов и panoptic quality. Один показатель не описывает всё: модель может иметь высокий recall за счёт большого числа ложных объектов или высокий precision ценой пропусков слабых ядер.

Практический протокол состоит из трёх наборов. Training нужен для обновления весов, validation — для выбора порогов и параметров, test — для финальной оценки. Если после просмотра test пользователь снова меняет порог и повторяет оценку на том же test, он превращает test в validation и теряет независимую проверку.

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

Интеграция с QuPath

Для цифровой патологии StarDist доступен через расширение QuPath. Оно использует 2D-детекцию ядер и связывает её с объектной моделью QuPath. Типичный сценарий начинается с установки расширения, подготовки модели и запуска Groovy-скрипта, созданного на основе шаблона Extensions → StarDist. В скрипте задаются путь к модели, probability threshold, нормализация, физический размер пикселя и при необходимости канал.

def stardist = StarDist2D.builder(pathModel)
    .threshold(0.5)
    .normalizePercentiles(1, 99)
    .pixelSize(0.5)
    .build()

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

Для флуоресценции можно указать канал через channels(). Для яркопольных H&E данных есть модели, обученные на соответствующей окраске. Расширение также умеет включать вероятность как измерение, оценивать форму и интенсивность и расширять ядро до приблизительной области клетки. Эти дополнительные операции выполняет QuPath после детекции ядра и не являются собственно сегментацией StarDist.

Важное отличие от Fiji — обработка перекрытий. Fiji допускает перекрывающиеся ROI и управляет ими через overlap threshold. QuPath не разрешает перекрытие ядер как объектов: более вероятное ядро сохраняется, а пересекающаяся часть у менее вероятного удаляется; сильно потерявшийся объект может быть отброшен. Поэтому одинаковые веса и threshold не гарантируют пиксельно идентичный результат в Fiji и QuPath.

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

Производительность и использование GPU

StarDist можно запускать на CPU, но нейросетевое предсказание и особенно обучение заметно выигрывают от GPU. Точный выигрыш зависит от размера данных, архитектуры, тайлинга, версии TensorFlow и видеокарты, поэтому фиксированные обещания «в N раз быстрее» некорректны. В небольшом 2D кадре накладные расходы могут составлять значимую часть времени, тогда как 3D объёмы лучше раскрывают параллелизм GPU.

Основной технический риск GPU — совместимость TensorFlow, CUDA и cuDNN. На native Windows классическая поддержка CUDA в TensorFlow закончилась после ветки 2.10; для более новых TensorFlow Microsoft обычно требуется WSL2 или другой поддерживаемый стек. Поэтому попытка установить «самые новые» версии всех компонентов нередко приводит к ситуации, когда TensorFlow видит только CPU. Сначала выбирают поддерживаемую связку, затем ставят StarDist.

Проверять GPU нужно в том же окружении, где запускается StarDist. Команда TensorFlow, перечисляющая физические GPU, даёт более надёжный ответ, чем наличие драйвера в системе. В napari полезно открыть терминал, из которого запущено приложение, и проверить сообщения TensorFlow о созданном GPU-устройстве. Если память GPU мала, наличие ускорителя не отменяет тайлинг.

CPU-режим также может быть вполне практичным для 2D. Пакет StarDist использует нативный код для некоторых операций, а сборки с OpenMP способны задействовать несколько ядер. При компиляции из исходников отсутствие OpenMP не всегда ломает установку, но может снизить скорость CPU-части. Для рабочей станции важнее стабильность окружения и возможность воспроизвести анализ, чем максимальная синтетическая производительность.

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

Кнопка Run в napari неактивна

Плагин валидирует входы и отключает Run, если они несовместимы. Поле с ошибкой подсвечивается, а tooltip обычно объясняет причину. Проверьте Input Image, Image Axes, число каналов, Model Type и Model Axes. Частая ошибка — указать ZYX для массива, который фактически имеет форму CZYX, или выбрать одноканальную модель для слоя, содержащего канал как отдельную размерность.

Модель загружается, но объектов нет

Сначала уменьшите Probability/Score Threshold до разумного уровня и включите Show CNN Output. Если карта вероятности почти пустая, проблема находится до NMS: неподходящая модель, неверный масштаб, канал или нормализация. Если карта вероятности содержит хорошие пики, но итоговых объектов мало, тогда имеет смысл исследовать threshold и NMS.

Слишком много ложных объектов в фоне

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

Два соседних ядра сливаются

Убедитесь, что модель обучалась на соприкасающихся объектах и что их размер соответствует обучающим данным. Небольшая корректировка масштаба может дать больший эффект, чем NMS. Если кандидатные полигоны уже раздельные, исследуйте overlap threshold. Если сеть изначально рисует один набор лучей на пару ядер, NMS не сможет «разделить» объект — нужна другая модель или обучение.

Одно ядро разбивается на несколько объектов

Проверьте масштаб и неоднородность интенсивности внутри ядра. Слишком крупный объект относительно обучающих примеров может порождать несколько центров-кандидатов. Увеличение probability threshold иногда убирает слабые дубли, но если несколько частей имеют высокую вероятность, проблема структурная. Масштабирование входа или собственная модель обычно эффективнее.

Out of memory

Для inference увеличьте Number of Tiles или n_tiles. Для обучения уменьшайте train_batch_size, затем train_patch_size, сохраняя достаточный контекст. В 3D следите, чтобы патч и сетка были совместимы с архитектурой. Не лечите память переводом всех данных в 8 бит, если это разрушает полезный динамический диапазон.

Модель из другого источника не открывается

Проверьте формат. Napari ожидает обычную папку StarDist с config.json и весами .h5/.hdf5. Fiji работает с экспортированными моделями соответствующего формата. Bioimage.io-пакет может потребовать преобразования. QuPath умеет работать с моделями в нескольких форматах, но требования зависят от движка. Совпадение названия «StarDist model» не означает взаимозаменяемость всех файлов.

Форматы входных и выходных данных

Python API получает массивы NumPy, поэтому фактический набор файлов определяется библиотекой чтения: TIFF, OME-TIFF, PNG, JPEG, ND2 и другие форматы можно открыть через imageio, tifffile, Bio-Formats или специализированные пакеты, а затем передать массив в StarDist. Для научной работы предпочтительны форматы без потерь и с сохранённой битностью. JPEG удобен для демонстрации, но артефакты сжатия могут создавать мелкие границы и не подходит как исходный формат количественной микроскопии.

Fiji использует всё, что умеет открыть ImageJ/Bio-Formats, но в StarDist 2D передаётся текущая плоскость или 2D+time структура. Napari может работать с массивами и ленивыми источниками через плагины, однако сам StarDist при предсказании должен получить числовой массив подходящей формы. Большой OME-Zarr не становится автоматически «бесконечно большим» для сети — всё равно нужно продумать тайлинг и размеры блоков.

Label image следует хранить в целочисленном формате без изменения идентификаторов. При экспорте в PNG есть риск ограничиться 8 или 16 битами и потерять метки, если объектов много. TIFF или NumPy/Zarr обычно безопаснее. Для обмена с Fiji можно использовать 16/32-битные label image и ROI; для QuPath результаты чаще остаются объектами проекта и экспортируются через его таблицы или аннотации.

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

Практический сценарий: 2D-флуоресценция

Для серии DAPI-кадров сначала выберите несколько изображений, представляющих весь диапазон качества: плотная область, редкая область, слабая экспозиция, яркий участок, край поля и артефакт. На одном типичном кадре запустите Versatile (fluorescent nuclei) с нормализацией 1–99,8 и порогами модели. Не подбирайте параметры только на самом красивом поле.

Далее сравните размер ядер с ожидаемым моделью. Если ядра существенно крупнее, попробуйте умеренное масштабирование в napari или Python и снова проверьте. Когда масштаб выглядит корректным, настройте probability threshold по размеченным примерам. Задача — не максимизировать число объектов, а достигнуть приемлемого баланса пропусков и ложных детекций.

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

Из label image можно получить площадь, периметр, центроид и другие признаки через regionprops_table. Интенсивностные признаки следует измерять на исходном канале, а не на нормализованной копии, если нужны физически сопоставимые значения между кадрами. Нормализованная картинка служит входом модели; она не обязана сохранять количественную фотометрию.

Практический сценарий: H&E и цифровая патология

Для H&E важны две вещи: соответствующая модель и масштаб. Предобученная H&E-модель рассчитана на определённую морфологию и цветовую статистику. Если лабораторная окраска сильно отличается, сначала проверьте её на размеченной области. В QuPath укажите физический pixelSize, близкий к масштабу, на котором модель работает стабильно. Не путайте уровень пирамиды WSI с фактическим микрометром на пиксель.

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

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

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

Практический сценарий: 3D стек

Для конфокального Z-стека сначала проверьте физический шаг по Z и размер пикселя XY. Если они сильно различаются, сохраните эту информацию как anisotropy. В napari загрузите стек, убедитесь, что Image Axes действительно ZYX, и выберите 3D-модель. На небольшом подтоме оцените нормализацию, масштаб и память.

Запускайте Output Type = Both, чтобы получить Labels и Polyhedra. Просмотрите результат в трёх ортогональных сечениях: ошибка может быть незаметна в XY, но очевидна в XZ. Удлинённые по Z объекты, «ступенчатые» поверхности и слияния нескольких ядер часто указывают на несоответствие анизотропии или на то, что демонстрационная модель не соответствует вашему типу данных.

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

Для количественного 3D анализа сохраняйте label volume в формате, поддерживающем нужную битность и метаданные масштаба. Измерение объёма в «вокселях» мало информативно без пересчёта через физический размер вокселя. Аналогично площадь поверхности многогранника зависит от масштаба осей, поэтому после любых пересэмплирований нужно использовать актуальную калибровку.

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

В Fiji есть сценарии пакетного запуска через Jython, однако для больших серий Python обычно проще тестировать и версионировать. Независимо от интерфейса нужно сохранять конфигурацию. Минимальный журнал запуска включает имя модели, путь или идентификатор весов, процентили, масштабирование, probability threshold, NMS threshold, число плиток, оси и дату создания окружения.

Имена файлов результата должны однозначно связываться с исходником. Хорошая схема — отдельная папка на каждую серию, где лежат исходный идентификатор, label image, таблица измерений и JSON с параметрами. Не стоит встраивать пороги в имя каждого TIFF, если параметры уже записаны в метаданных пайплайна; длинные имена быстро становятся источником ошибок.

При обновлении StarDist, TensorFlow или napari повторите контрольный набор. Даже если API не изменился, различия в backend, численной реализации или постобработке могут слегка изменить границы. Для научной серии лучше не обновлять окружение в середине эксперимента без причины. Новую среду можно проверять параллельно и переключаться только после сравнения.

Для строгой воспроизводимости храните файл зависимостей или экспорт conda/mamba окружения и хэш весов пользовательской модели. Само имя папки nuclei_custom недостаточно: если модель дообучили и перезаписали веса, старый анализ нельзя точно повторить. В идеале каждая версия модели получает неизменяемый каталог.

Ограничения StarDist

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

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

Третье ограничение — StarDist не является полноценной системой анализа эксперимента. Он не выполняет трекинг сам по себе, не знает биологические группы и не заменяет статистику. Его выход нужно соединять с Fiji, napari, TrackMate, QuPath, scikit-image или собственным кодом. Это сильная сторона в гибком пайплайне, но дополнительная ответственность для пользователя.

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

Как читать вероятность и радиальные расстояния

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

Когда включён Show CNN Output, карта probability помогает отделить проблему детекции от проблемы постобработки. Если на настоящем ядре нет выраженного пика, изменение NMS почти ничего не даст: сеть не считает область объектом. Если пиков несколько, а итоговый label image содержит один экземпляр, виновником может быть NMS или слишком низкое разрешение сетки. Если вероятность хорошая, но контур систематически не захватывает углубления, это уже ограничение star-convex геометрии.

Карты distances сложнее интерпретировать визуально, потому что каждый луч — отдельный канал. Их полезность прежде всего техническая: при обучении можно увидеть, что сеть предсказывает устойчивые радиальные расстояния в центре объекта и нестабильные около границы или слабого сигнала. В 2D увеличение n_rays делает многоугольник детальнее, но одновременно повышает размер выходного тензора. Оптимальное число лучей зависит от требуемой точности контура и доступной памяти.

Важно, что probability score привязан к кандидату, а не к «качеству всей маски». Высокий score не гарантирует идеальный контур: объект может быть уверенно найден, но форма будет аппроксимирована грубо. Поэтому для морфометрии score нельзя использовать как единственный фильтр качества. Полезно отдельно оценивать IoU границы или ошибку площади на размеченной выборке.

Оси X, Y, Z, C и T: источник большинства тихих ошибок

В многомерной микроскопии форма массива сама по себе не говорит, что означает каждая размерность. Массив 30×512×512 может быть ZYX, TYX или CYX. StarDist должен знать семантику, потому что пространственные оси масштабируются и тайлятся, канал передаётся в сеть, а time обычно обрабатывается как последовательность независимых изображений. Неверная строка осей иногда вызывает явную ошибку, но иногда вычисление идёт и даёт правдоподобно плохой результат.

В napari проверяйте Image Axes сразу после выбора Input Image. Поле Model Axes показывает требования модели. Если модель ожидает YXC[1], а слой имеет форму YXC с тремя каналами, это не означает, что можно написать YX и скрыть C: лишние данные останутся в массиве. Нужно создать отдельный слой с нужным каналом или преобразовать данные в Python. Аналогично в 3D нельзя выдавать временную ось T за Z только потому, что обе имеют несколько срезов.

При пакетной обработке полезно формализовать проверку shape. Скрипт может отклонять изображение, если число измерений и число каналов не соответствуют ожидаемым, вместо того чтобы молча продолжать. Для OME-TIFF и OME-Zarr метаданные осей обычно доступны, но при чтении через разные библиотеки порядок может меняться. Сохранение исходного порядка осей в журнале анализа упрощает поиск расхождений.

Time-lapse данные с 2D-ядрами можно сегментировать покадрово. StarDist сам не связывает объект между кадрами и не присваивает постоянный трек-идентификатор. После сегментации результаты передают в TrackMate или другой трекер. Если размер клетки меняется во времени, параметры сегментации должны оставаться фиксированными либо изменение масштаба должно быть заранее обосновано, иначе динамика числа объектов смешивается с динамикой настроек.

Границы изображения и неполные объекты

Объект, пересечённый границей кадра, создаёт статистическую проблему. Если его оставить, площадь и форма будут занижены; если удалить без правила, счёт может быть смещён. В Fiji параметр Boundary Exclusion позволяет исключать экземпляры, находящиеся близко к краю. В Python аналогичную логику можно применять к label image после предсказания или использовать параметры функций, поддерживающих исключение границ.

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

В обучении есть отдельная идея shape completion: если объект обрезан патчем, сеть может обучаться восстанавливать его форму при наличии достаточного контекста. Это продвинутая настройка и не отменяет необходимость корректных масок. Если в ground truth объект действительно обрезан границей исходного изображения и неизвестно, что находится за кадром, модель не может достоверно восстановить невидимую часть.

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

Пользовательские модели: папка, веса и пороги

Обычная модель StarDist в Python хранится в каталоге, где есть config.json, файлы весов и при наличии оптимизированных порогов thresholds.json. Napari может открыть такой каталог как Custom 2D/3D. Это удобный формат для лаборатории: конфигурация и веса находятся рядом, а пользователь видит Model Axes и может загрузить сохранённые threshold без ручного переписывания.

Нужно различать веса «лучшей эпохи» и последние веса обучения. В типичном каталоге встречаются weights_best.h5, weights_last.h5 и промежуточные варианты. Для анализа выбирают конкретный проверенный файл, а не «самый новый по дате». Если validation loss в конце ухудшился, последние веса могут быть хуже лучшего checkpoint. После выбора модель фиксируют и не перезаписывают в том же каталоге.

thresholds.json появляется после оптимизации порогов и относится к конкретной модели и validation-набору. Копировать этот файл между моделями бессмысленно. Если модель дообучили на новых данных, пороги следует переоценить. Кнопка в napari, устанавливающая optimized postprocessing thresholds, читает именно сохранённые значения и не выполняет новую оптимизацию на текущем изображении.

Для передачи модели в Fiji может потребоваться экспорт в ZIP, совместимый с плагином. Для QuPath формат зависит от выбранного движка: готовые .pb-модели могут работать через OpenCV, SavedModel — через TensorFlow/DJL, модели из Bioimage Model Zoo требуют соблюдения их спецификации. Поэтому при публикации внутреннего протокола указывайте не только «StarDist model», а конкретный формат и способ загрузки.

Многоканальные и многоклассовые модели

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

StarDist поддерживает модели с несколькими входными каналами. В этом случае n_channel_in фиксируется в конфигурации, а порядок каналов становится частью модели. Если при обучении использовались DAPI и мембранный маркер в порядке [DAPI, membrane], на inference нельзя поменять их местами. Napari показывает число ожидаемых каналов в Model Axes, но не знает биологический смысл каждого канала — это должен контролировать пользователь.

Есть и многоклассовый режим, где к выходам probability и distances добавляется классификационная голова. Тогда каждый найденный экземпляр получает класс. Это отличается от последующей классификации по измерениям: класс предсказывается сетью вместе с детекцией. Для обучения нужен mapping от id экземпляра к class id. Не следует включать многоклассовый режим только ради удобной раскраски — он требует корректной разметки классов и отдельной оценки ошибок классификации.

В napari многоклассовая модель может возвращать StarDist class labels и карты вероятностей классов. В QuPath есть возможность сопоставить выходные class id с собственными классификациями объектов. При этом число лучей должно быть достаточным относительно числа классов, а пользователь обязан проверить, что mapping совпадает с тем, на чём обучалась модель.

Обработка больших массивов через Python

Для больших данных обычный predict_instances() с n_tiles подходит, пока весь массив помещается в RAM и проблема только в памяти сети. Если сам массив слишком велик, нужен блоковый процесс. StarDist содержит механизмы предсказания на больших изображениях, где данные режутся на блоки, каждый блок имеет контекст, а результаты сшиваются. Это особенно актуально для больших 2D полей и 3D томов.

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

Для whole-slide данных часто разумно сначала выделить маску ткани в низком разрешении и не запускать StarDist на пустых блоках. Это не функция самой нейросети, но эффективная оптимизация пайплайна. В QuPath аналогичный смысл имеет запуск внутри выбранных parent objects. Экономия особенно заметна на слайдах, где ткань занимает небольшую часть площади.

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

Отладка через промежуточные выходы

Когда сегментация плохая, полезно идти по цепочке: вход → нормализация → probability → distances → NMS → label image. В napari Show CNN Output делает два центральных этапа видимыми. В Python можно вызвать функции предсказания и анализировать массивы до преобразования в экземпляры. Это позволяет понять, какая настройка действительно относится к ошибке.

Если после нормализации фон имеет почти такой же диапазон, как ядра, проблема может быть в перцентилях или в том, что канал содержит сильные выбросы. Если probability-map подчёркивает настоящие ядра, но final labels пропускают их, снижайте probability threshold и смотрите NMS. Если вероятность высокая по всей ткани, предобученная модель не различает ваш домен, и порогом это лечится лишь частично.

Для нестабильных результатов на сериях полезно построить распределение нормализационных границ. Например, сохраняйте фактические значения интенсивности, соответствующие 1-му и 99,8-му процентилям каждого кадра. Резкий выброс сразу показывает поле с другой экспозицией или насыщением. Такой контроль часто объясняет «внезапно плохую нейросеть» лучше, чем смена модели.

При отладке не меняйте сразу архитектуру, пороги и preprocessing. Сначала подтвердите корректность данных и осей, затем модель и масштаб, затем нормализацию, затем postprocessing. Это порядок от крупных причин к локальным. Большинство неудачных запусков StarDist исправляется до этапа обучения новой сети.

Сегментация и последующий трекинг

StarDist выдаёт объекты в каждом кадре, но не решает задачу соответствия объекта самому себе во времени. Для time-lapse это отдельный трекер. В экосистеме Fiji существует интеграция с TrackMate, где StarDist может использоваться как детектор объектов, а затем треки строятся алгоритмами TrackMate. Такой подход позволяет разделить ответственность: StarDist отвечает за геометрию объектов, трекер — за связи между кадрами.

Качество трекинга чувствительно к ошибкам сегментации. Пропуск ядра создаёт разрыв трека, ложный объект — лишний трек, слияние двух ядер — неоднозначность при разделении в следующем кадре. Поэтому параметры StarDist для time-lapse лучше выбирать не только по IoU отдельного кадра, но и по устойчивости числа объектов между соседними кадрами, если биология не предполагает резких изменений.

При делении клеток один трек должен разветвляться, и это уже функция трекера. StarDist не классифицирует событие митоза автоматически только потому, что видит две дочерние маски. Для корректной интерпретации нужны правила или модель трекинга, способная обрабатывать split events.

Если исходный стек имеет оси TYX, не превращайте T в Z ради 3D-модели. Это разные физические измерения. 3D StarDist предполагает, что соседние срезы описывают один объём в один момент времени; временные кадры нужно сегментировать как отдельные 2D изображения или 3D объёмы для каждого T.

Как подбирать модель по типу данных

Выбор начинается с модальности. Для флуоресцентных ядер используйте модель, обученную на флуоресцентных данных, если внешний вид объектов близок. Для H&E — специализированную H&E-модель. Перенос модели между модальностями иногда даёт визуально правдоподобный результат после агрессивной предобработки, но такой перенос нужно валидировать строже, потому что сеть опирается на текстуры и контрасты, которых в новом домене не было.

Второй критерий — физический размер. Если типичный диаметр ядра в модели около нескольких десятков пикселей, а у вас он занимает сотню, сеть работает в другом масштабе. В napari можно компенсировать это Input image scaling, в Python — ресэмплировать вход или задать соответствующий workflow. Но сильное масштабирование ухудшает детализацию, поэтому при постоянном несоответствии лучше обучить модель на нужном разрешении.

Третий критерий — форма. Даже идеальное совпадение интенсивности не спасает, если объект не star-convex. Для длинных нейритов, сосудов, сетчатых мембран или объектов с отверстиями StarDist не является естественным выбором. Для приблизительно овальных ядер, гранул, спор и компактных клеток геометрическая предпосылка работает гораздо лучше.

Четвёртый критерий — плотность. Метод создавался для разделения тесно расположенных объектов, поэтому особенно полезен там, где thresholding и watershed начинают нестабильно сливать ядра. Но высокая плотность усиливает влияние NMS и качества разметки. Если training masks сами плохо разделяют касающиеся объекты, сеть воспроизведёт эту неопределённость.

Контрольный список перед массовым запуском

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

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

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

Когда настройки нельзя переносить между сериями

Одинаковый probability threshold имеет смысл только тогда, когда входы сопоставимы после предобработки. Если одна серия снята с другой экспозицией, другим объективом или после изменения шага по Z, одинаковое число в интерфейсе не гарантирует одинаковую чувствительность. Процентильная нормализация частично компенсирует яркость, но не исправляет различия в пространственном разрешении, PSF, шуме камеры и морфологии образца.

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

Особенно осторожно следует переносить optimized thresholds пользовательской модели. Эти значения оптимизировались на конкретной validation-выборке. В новой лаборатории, на другом сканере или другом биологическом типе они остаются разумной стартовой точкой, но не автоматически оптимальными. Правильная процедура — применить модель без переобучения к небольшому локальному validation-набору и заново оценить пороги.

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

Измерения после сегментации

StarDist заканчивает работу там, где получен экземпляр. Площадь, периметр, интенсивность, текстура и пространственные отношения считаются уже другими средствами. В Python удобно использовать skimage.measure.regionprops_table: label image передаётся как маска экземпляров, а исходный канал — как intensity image. В Fiji аналогичную роль выполняют ROI Manager и команды измерений, в QuPath — Measurement List и таблицы объектов.

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

При 3D нужно учитывать физический размер вокселя. Количество вокселей превращается в объём умножением на произведение размеров Z×Y×X. Если ось Z имеет другой шаг, использование одной квадратной/кубической шкалы даёт неправильные физические единицы. Аналогично расстояния между центроидами нужно вычислять в физическом пространстве, а не просто в индексах массива.

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

Для морфометрии контур следует валидировать отдельно от факта детекции. Модель может правильно посчитать количество ядер, но слегка недооценивать площадь из-за star-convex аппроксимации. Если основной итог — распределение площадей, такая систематическая ошибка критичнее, чем если нужен только cell count. Оценка качества должна соответствовать конечной биологической метрике.

Batch-обработка в Fiji и Python

Fiji-плагин можно вызывать из скрипта, что полезно, если лаборатория уже строит анализ вокруг ImageJ и Bio-Formats. В таком сценарии пользователь открывает файлы по очереди, вызывает StarDist с фиксированными параметрами, сохраняет label image или ROI и закрывает документ. Главное преимущество — доступ к форматам и плагинам Fiji; главный риск — состояние интерфейса, открытые окна и случайно изменённые параметры.

Для headless или серверной обработки Python обычно надёжнее. Цикл явно читает файл, выбирает канал, нормализует, вызывает predict_instances(), сохраняет маску и таблицу. Исключения можно ловить по каждому файлу, не прерывая всю серию. Лог должен содержать имя входа и текст ошибки, чтобы проблемный образец можно было повторить отдельно.

Не стоит загружать в память сразу всю серию из сотен TIFF, если обработка идёт последовательно. Достаточно держать один или несколько текущих массивов. Для больших данных особенно важно освобождать ссылки на временные массивы и не сохранять Show CNN Output без необходимости. В napari интерактивные слои также занимают память до удаления из viewer.

Если файлы имеют разные формы, batch-скрипт должен проверять их до inference. Например, один файл случайно может содержать RGB preview вместо одноканального TIFF. Без проверки shape он либо вызовет ошибку посередине серии, либо будет интерпретирован как многоканальный массив. Явная валидация входа экономит больше времени, чем попытка сделать скрипт «терпимым» ко всем форматам.

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

Как строить контрольную выборку

Контрольная выборка должна отвечать на вопрос, который вы реально задаёте модели. Если анализируется плотность ядер на H&E, нужно размечать участки с разной плотностью и типами ткани. Если изучаются органоиды, добавьте разные размеры и глубины. Случайные кропы полезны, но редкие трудные случаи нужно включать целенаправленно, иначе средняя метрика скроет критическую ошибку.

Разметчик должен видеть исходное изображение в достаточном масштабе и иметь правило для неоднозначных случаев. Например: считать ли фрагмент ядра у границы; как поступать с апоптотическими телами; разделять ли два ядра при слабой границе; включать ли объект с насыщенным сигналом. Эти решения становятся частью ground truth. Без инструкции расхождение между экспертами может быть больше, чем разница между моделями.

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

После автоматического сопоставления экземпляров просмотрите пары с низким IoU и все false positive/false negative. Число помогает сравнивать конфигурации, но просмотр объясняет причину. Часто оказывается, что часть «ошибок модели» связана с непоследовательной ручной разметкой, особенно на слабых границах. Исправление ground truth может быть полезнее дополнительного обучения.

Хорошая validation-выборка остаётся неизменной между версиями модели. Тогда можно объективно сравнить, улучшило ли новое обучение конкретные ошибки или просто изменило баланс precision/recall. Если каждый раз менять и модель, и контрольные данные, прогресс невозможно отделить от изменения теста.

Когда стоит отказаться от StarDist

StarDist не следует выбирать по привычке, если геометрия объектов явно противоречит star-convex предпосылке. Для сосудистой сети, длинных отростков, мембранных контуров с отверстиями и сильно изогнутых структур семантическая сегментация или другой instance-segmentation подход может дать более естественное представление. Нельзя исправить фундаментально неподходящую геометрию одним увеличением n_rays.

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

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

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

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

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

StarDist и Cellpose

Cellpose — более общий сегментатор клеток и ядер, который не привязан к звёздно-выпуклому многоугольнику как к выходной геометрии. Это полезно для объектов со сложной формой. StarDist, в свою очередь, особенно силён там, где объекты близки к округлым или звездно-выпуклым и расположены плотно. Оба инструмента имеют Python API и графические варианты, оба поддерживают пользовательские модели и требуют проверки на собственных данных.

При выборе не стоит исходить из популярности. Возьмите одинаковую размеченную тестовую выборку и сравните object-level precision/recall, качество границ и типы ошибок. Если биологически важна точная граница сильно неправильной клетки, геометрическое ограничение StarDist может быть решающим. Если главная проблема — разделить сотни тесно расположенных ядер, StarDist часто даёт очень удобное экземплярное представление.

StarDist и ilastik

ilastik строит интерактивный workflow: пользователь рисует метки классов, обучает pixel classifier, при необходимости переходит к object classification, tracking или другим этапам. Это удобно, когда нет готовой нейросетевой модели и нужно быстро научить систему отличать ткань, фон или другие структуры по пользовательским примерам. StarDist требует экземплярные label masks для полноценного обучения, зато сразу оптимизирован под отдельные объекты и выдаёт экземпляры.

Если задача — семантически разделить несколько текстурных классов без строгой границы каждого объекта, ilastik может быть естественнее. Если важны отдельные ядра, их число и геометрия, StarDist обычно даёт более прямой путь. В сложном пайплайне инструменты можно сочетать: например, ilastik выделяет область ткани, а StarDist сегментирует ядра только внутри неё.

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

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

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

Как проверить результат перед использованием в исследовании

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

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

Разделите ошибки по причинам. Слабый сигнал, перекрытие, необычная форма, объект у границы, некорректный канал и дефект окраски требуют разных решений. Один глобальный threshold редко исправляет все категории одновременно. Иногда правильное решение — обучить вторую модель или исключить конкретный тип данных по заранее заданным критериям качества.

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

Короткие ответы на практические вопросы

Можно ли использовать StarDist без GPU?

Да. Предсказание работает на CPU, хотя на больших 3D данных и при обучении GPU значительно удобнее. Для небольших 2D серий CPU может быть достаточен, особенно если окружение использует оптимизированные нативные библиотеки.

Можно ли сегментировать 3D в Fiji?

Официальный StarDist ImageJ/Fiji plugin описан как 2D и 2D+time. Для настоящего 3D используйте napari или Python. Существуют отдельные workflow вокруг TrackMate, которые связывают 2D-детекции между срезами, но это не то же самое, что нативная StarDist3D-модель.

Нужно ли менять пороги для каждого изображения?

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

Почему результат отличается между Fiji и QuPath?

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

Когда предобученной модели недостаточно?

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

Что сохранять после анализа?

Минимум: исходный идентификатор, label image, таблицу измерений, имя модели и параметры запуска. Для пользовательской модели — конфигурацию и неизменяемые веса. Для воспроизводимости полезно сохранять также окружение Python и несколько контрольных оверлеев.

Итог

StarDist — специализированный инструмент экземплярной сегментации, который особенно эффективен для плотных ядер и других объектов, хорошо описываемых звёздно-выпуклой геометрией. Его сильная сторона — не «автоматическая магия», а чёткий и проверяемый конвейер: нормализованный вход, согласованный масштаб, модель соответствующего домена, probability threshold, NMS и выход в виде отдельных меток или полигонов.

Для быстрого 2D анализа достаточно Fiji, для интерактивной 2D/3D работы удобен napari, для обучения и пакетной обработки нужен Python, а для цифровой патологии StarDist хорошо встраивается в QuPath. Независимо от интерфейса качество определяется тем, насколько внимательно пользователь контролирует оси, каналы, масштаб, нормализацию и валидацию. Если эти элементы зафиксированы, StarDist превращается из демонстрационной нейросети в воспроизводимый измерительный этап научного анализа изображений.

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