Сегментація з підказками

Визначення

Сегментація з підказками приймає зображення разом із просторовою підказкою й повертає маску об'єкта, на який указує підказка. Нічого не класифікується: списку класів немає, а result.boxes містить щільні рамки, отримані з масок, а не самостійні виявлення. result.masks містить дані масок, а result.masks.xy, їхні полігони.

Інтерфейсом є підказка. points, це піксельні координати [x, y], по одному набору на об'єкт, де labels позначає кожну точку як додатну (1, включити) або від'ємну (0, виключити). bboxes, це [x1, y1, x2, y2], по одній масці на рамку. Точки й рамки можна поєднувати, тоді вони утворюють пари для кожного об'єкта й повинні мати однакову довжину. Відсутність усіх підказок запускає шлях сегментації всього, сітку точок на зображенні.

Одна точка навмисно неоднозначна. Клацання на рукаві може означати рукав, сорочку або людину, тому multimask=True повертає всі три маски цілого та частини для кожної підказки замість однієї найкращої. conf фільтрує за передбаченим моделлю IoU, оцінкою якості маски, а не впевненістю виявлення.

LibreYOLO не має ключа задачі promptable. Рівень реєструється як segment, той самий ключ використовує сегментація екземплярів. Його відрізняє форма виклику, тому він має власну фабрику LibreSAM(), аналог LibreYOLO(), LibreOpenVocab() і LibreVLM(). Єдина сигнатура predict(image) не може виразити цикл, для якого створено ці моделі: set_image() один раз запускає енкодер зображення й кешує ембединги, кожен наступний виклик predict() із source=None виконує лише декодування підказки, а reset_image() очищає кеш. Енкодер зображення є основною витратою й запускається один раз на зображення, тому друга підказка для того самого зображення повністю пропускає його.

Моделі

Шість сімейств завантажуються через LibreSAM за псевдонімом.

SAM, стандартне сімейство в розмірах base, large і huge, які також записуються як b, l і h.

SAM 2 має псевдоніми sam2-tiny, sam2-small, sam2-base-plus і sam2-large. LibreYOLO підтримує її шлях зображень.

SAM 3 має псевдонім sam3 і є єдиним сімейством, що приймає підказку текстового поняття: text="yellow school bus" повертає всі відповідні екземпляри. Передавання text= будь-якому іншому сімейству спричиняє помилку з назвою SAM 3. Її ваги надходять від Meta за спеціальною ліцензією SAM, а не MIT LibreYOLO, і доступ до репозиторію обмежено: прийміть умови на сторінці моделі та автентифікуйтеся через hf auth login до першого завантаження. Перед розгортанням прочитайте SAM 3.

EdgeTAM із псевдонімом edgetam, це варіант SAM 2 для пристроїв. LibreYOLO підтримує її шлях зображень.

MobileSAM із псевдонімом mobilesam замінює енкодер ViT-H у SAM на дистильований TinyViT.

PicoSAM3 із псевдонімом picosam3, це компактна CNN для областей із підказками рамками на периферійних сенсорах. Підказки рамками становлять увесь контракт: точки, текст, маска, multimask і сегментація всього спричиняють помилку з посиланням на SAM 2 або SAM 3.

Додаткова залежність рівня охоплює чотири сімейства, які завантажуються через transformers:

pip install "libreyolo[sam]"

MobileSAM і PicoSAM3 є нативними перенесеннями LibreYOLO, і для їх роботи не потрібно встановлювати transformers.

Передбачення

from libreyolo import LibreSAM, SAMPLE_IMAGE model = LibreSAM("base") # Точка має координати [x, y] у пікселях; мітки 1 додатні, 0 від'ємні.result = model.predict(SAMPLE_IMAGE, points=[640, 420], labels=[1])print(result.masks.xy)      # полігониprint(result.boxes.xyxy)    # щільні рамки, отримані з масок # Підказка рамкою дає одну маску на рамку.result = model.predict(SAMPLE_IMAGE, bboxes=[300, 200, 900, 700])

from libreyolo import LibreSAM, SAMPLE_IMAGE model = LibreSAM("base") # set_image один раз запускає важкий енкодер зображення й кешує результат.model.set_image(SAMPLE_IMAGE)first = model.predict(points=[640, 420], labels=[1])second = model.predict(bboxes=[300, 200, 900, 700])model.reset_image()

from libreyolo import LibreSAM, SAMPLE_IMAGE model = LibreSAM("base") # Без підказки використовується сітка точок на всьому зображенні. Стандартна# сітка 32 на сторону дає близько 1024 проходів декодера, що повільно на CPU.result = model.predict(SAMPLE_IMAGE, points_per_side=8)print(len(result.masks))

from libreyolo import LibreSAM, SAMPLE_IMAGE model = LibreSAM("base") # Одна точка може означати рукав, сорочку або людину. multimask=True# повертає всі три маски цілого та частини замість однієї найкращої.result = model.predict(    SAMPLE_IMAGE, points=[640, 420], labels=[1], multimask=True)print(len(result.masks))

source і set_image(), це альтернативи, а не послідовність: передайте зображення до predict() для одноразового виклику або спочатку викличте set_image(), а потім predict(source=None) для кожної підказки. Передавання device= до predict() переносить модель для цього й усіх наступних викликів і скасовує всі кешовані ембединги.

Сегментація всього є витратним режимом. Стандартне значення points_per_side, 32, що означає приблизно 1024 проходи декодера на зображенні; зменште його для інтерактивної роботи на CPU. У цьому режимі незаданий conf застосовує поріг сітки сімейства, а в режимі з підказками незаданий conf зберігає кожну маску. Передайте conf=0.0, щоб вимкнути фільтрування в будь-якому режимі, і max_det, щоб обмежити кількість масок.

Підказки масками в цій версії не підтримуються, і masks= спричиняє помилку, а не ігнорується. track() також спричиняє помилку в усьому рівні: це сегментатори зображень, тому запускайте predict() для кожного кадру. Джерела й роботу з результатами описано в розділі передбачення.

Навчання

Жодне сімейство цього рівня не навчається в LibreYOLO. train() спричиняє помилку: виконайте донавчання в upstream і завантажте отримані ваги.

Валідація

Для цього рівня немає валідатора, і val() спричиняє помилку. Маска з підказкою не має фіксованого набору класів для оцінювання, тому звичайним метрикам виявлення та сегментації немає з чим зіставляти ключі. Оцінювання маски з підказкою означає її порівняння з еталонною маскою, яку ви надаєте самостійно, за важливими для вас підказками.

Експорт

Експорт загалом не підтримується на цьому рівні, і export() спричиняє помилку, за одним винятком. PicoSAM3 експортує власну необроблену CNN області 96x96 до ONNX як roi_image -> mask_logits; обрізання рамки й повернення маски до координат зображення залишаються в Python. Кожне інше сімейство працює через predict() у PyTorch. Формати, доступні в інших частинах бібліотеки, описано в розділі експорт.