Посібник користувача HALCON 21.11 Progress

Швидкий доступ до функціональності HALCON, версія 21.11.0.0
Всі права захищені. Жодна частина цієї публікації не може бути відтворена, збережена в пошуковій системі або передана в будь-якій формі чи будь-яким способом, електронним, механічним, фотокопіюванням, записом чи іншим способом, без попереднього письмового дозволу видавця.

Авторські права © 2003-2021 MVTec Software GmbH, Мюнхен, Німеччина
Захищено такими патентами: US 7,239,929, US 7,751,625, US 7,953,290, US 7,953,291, US 8,260,059, US 8,379,014, US 8,830,229. Очікуються інші патенти.
Microsoft, Windows, Windows Server 2008/2012/2012 R2/2016, Windows 7/8/8.1/10, Microsoft .NET, Visual C++ і Visual Basic є товарними знаками або зареєстрованими товарними знаками Microsoft Corporation.
Linux є торговою маркою Лінуса Торвальдса.
macOS і OpenCL є товарними знаками Apple Inc.
NVIDIA, CUDA, cuBLAS і cuDNN є товарними знаками або зареєстрованими товарними знаками NVIDIA Corporation.
OpenGL є торговою маркою Silicon Graphics, Inc.
Усі інші національно та міжнародно визнані торгові марки та торгові назви визнаються цим.
Більше інформації про HALCON можна знайти за адресою: http://www.halcon.com/

Про цей посібник

Цей посібник знайомить вас з HALCON. Він призначений для початківців без попереднього знання HALCON.
Цей посібник також можна використовувати як довідник для кількох інших посібників HALCON, оскільки він пов’язує їх між собою за такими темами:

Встановлення HALCON (стор. 7)
У цьому розділі представлено MVTec Software Manager (SOM).
Архітектура HALCON (стор. 9)
Деяка теоретична підготовка, необхідна для розуміння того, що таке HALCON і як він працює.
Як розробляти програми (стор. 15)
У цьому розділі пояснюється три основні підходи до розробки за допомогою HALCON і проводиться перший приклад програмуванняample.
Як продовжити (стор. 19)
У цьому розділі йдеться про додаткові джерела інформації.

Установка HALCON

Для користувачів Linux і Windows ми рекомендуємо завантажити та встановити HALCON через MVTec Software Manager (SOM). SOM — це менеджер встановлення програмних пакетів. Він забезпечує доступ до віддаленого каталогу продуктів і підтримує, серед інших функцій, завантаження та встановлення пакетів. Покрокову інструкцію щодо встановлення HALCON через SOM можна знайти в Посібнику зі встановлення.

Архітектура HALCON

Базова архітектура HALCON зображена на малюнку 2.1. Основною частиною є бібліотека обробки зображень, яка складається з понад 2000 операторів. Ви також можете розробити власні оператори у формі так званих пакетів розширення (стор. 11). Ви використовуєте оператори у своїй програмі за допомогою мовних інтерфейсів (стор. 11), таких як HALCON/C++ або HALCON/Python. Це бібліотеки, які дозволяють безпосередньо використовувати оператори в типовому стилі програмування для різних мов програмування.

малюнок 2.1: Базова архітектура HALCON.

Для доступу до пристроїв отримання зображень HALCON надає інтерфейси отримання зображень (стор. 13), які дозволяють використовувати досить різні пристрої отримання зображень загальним способом. Бібліотеки, що містять специфічні для пристрою реалізації, завантажуються динамічно, коли це необхідно. Таким же чином доступ до пристроїв вводу/виводу здійснюється через інтерфейси вводу/виводу для конкретного пристрою (стор. 13).

Оператори

Кожного разу, коли будь-яка функція використовується з бібліотеки HALCON, це робиться через оператора. Більшість із них містить кілька методів, які вибираються за допомогою параметрів. Повний список усіх операторів можна знайти в довіднику операторів HALCON, доступному в синтаксисі HDevelop, .NET, Python, C++ і C. Важливими функціями операторів є:

Серед операторів немає ієрархії. З точки зору архітектури програмного забезпечення view, всі оператори знаходяться на одному рівні.
Звичайно, існують логічні групи операторів. наприкладample, це можна побачити в класах, запропонованих для C++ і .NET, де оператори, що обробляють той самий тип даних, є функціями-членами відповідних класів.
Конструкція операторів відповідає правилам відкритої архітектури. Тому ви можете створювати власні оператори і таким чином розширювати HALCON (див. розділ 2.2). Посібник програміста Extension Package містить детальну інформацію про розширення бібліотеки операторів.
Багато операторів можуть прозоро використовувати автоматичне розпаралелювання, що дозволяє легко пришвидшити програму при використанні великих зображень на багатопроцесорному або багатоядерному комп’ютері. Детальну інформацію про паралельне програмування можна знайти в технічній примітці Паралельне програмування, а також у посібнику програміста.
Оператори мають стандартизовані правила для впорядкування вхідних і вихідних параметрів: вхідна іконка, вихідна іконка, вхідний контроль і вихідний контроль (див. розділ 2.1.1). Не всі групи можуть знадобитися певному оператору. Загалом вхідні параметри операторів не змінюються, що забезпечує чітку та просту семантику. Існує лише кілька винятків із цього дизайну, наприклад, set_grayval, overpaint_gray і overpaint_region.

Параметри та структури даних
HALCON має два основних типи параметрів: іконічні дані та контрольні дані. Зображення, регіони та XLD (eXtented Line Description) належать до знакових даних.

Зображення складаються в основному з каналів, тобто матриць, що містять значення пікселів. Усі канали зображення мають однаковий розмір. Щоб отримати детальну інформацію про пікселі та канали, прочитайте розділ «Зображення» довідника оператора HALCON.
Для кожного зображення так звана область інтересу (ROI) визначає, яка частина зображення обробляється. ROI можна визначати дуже гнучко (від простого прямокутника до набору незв’язаних пікселів). Докладніше про обробку рентабельності інвестицій див. у Посібнику з рішень I, Область інтересу на сторінці 27.

Регіони являють собою набір пікселів. Пікселі регіону не потребують підключення. Навіть довільну колекцію пікселів можна обробляти як одну область. За допомогою оператора з'єднання область може бути розбита на її зв'язані області, тобто компоненти, що складаються зі з'єднаних пікселів.

XLD включати всі дані на основі контурів і багатокутників. Оператори з точністю до субпікселя, такі як edges_sub_pix, повертають контури як дані XLD. Контур — це послідовність двовимірних контрольних точок, з’єднаних лініями. Як правило, відстань між контрольними точками становить приблизно один піксель. Об'єкти XLD містять, крім контрольних точок, так звані локальні та глобальні атрибути. Типовий ексamples для них, наприклад, край ampглибину контрольної точки або параметри регресії сегмента контуру. Окрім вилучення об’єктів XLD, HALCON підтримує подальшу обробку. ПрampДля цього можна вибрати контури на основі заданих діапазонів ознак для сегментації контуру на лінії, дуги, багатокутники або паралелі.

Керуючі дані включають маркери та базові типи даних, такі як ціле, дійсне, рядкове.

Ручки є посиланнями на складні структури даних, наприклад, підключення до інтерфейсу отримання зображень або моделі для відповідності на основі форми. З міркувань ефективності та безпеки даних між операторами передається не вся структура, а лише дескриптор. Метки — це магічні значення, які не можна змінювати та можуть відрізнятися від виконання до виконання та версії до версії. Вони автоматично видаляються, коли всі посилання перезаписуються. Прampфайли, де використовуються маркери, є графічними вікнами, files, розетки, інтерфейси отримання зображень, OCR, OCV, вимірювання та зіставлення.

Пакети розширень

HALCON може бути продовжений новими операторами. Хоча HALCON вже містить великий набір операторів для різних завдань, ви можете захотіти реалізувати нові оператори, наприклад, для доступу до спеціального обладнання або реалізації альтернативного алгоритму. Для цього HALCON надає Extension Package Interface, який дозволяє інтегрувати нові оператори (реалізовані на C) у формі так званих пакетів розширення. Інтерфейс пакета розширень містить декілька попередньо визначених процедур і макросів для легкого поводження з даними зображення та об’єктами пам’яті в C. Після успішної інтеграції нового оператора його можна використовувати як будь-який інший оператор HALCON. Посібник програміста Extension Package містить детальну інформацію про розширення бібліотеки операторів.

Мовні інтерфейси

Як показано на малюнку 2.1 на сторінці 9, HALCON забезпечує так звані мовні інтерфейси. Це прив’язки на рідній мові, які дозволяють викликати оператори та використовувати типи даних HALCON безпосередньо з вашої програми, будь то Python, C, C++ або .NET.
Щоб розпочати розробку, рекомендуємо спочатку перевірити один із готових до запуску екзampпрограми le. Тут ви можете побачити, як потрібно налаштувати проект і як використовуються оператори та типи.
Для кожного мовного інтерфейсу назви типів, класів, домовленості про іменування операторів тощо можуть відрізнятися для відповідності типовим правилам, які застосовуються для вибраної мови. Сигнатури операторів для підтримуваних мов програмування задокументовано в Довіднику операторів HALCON.

HALCON/Python
Інтерфейс Python виділяється своєю простотою та можливістю швидкого створення прототипів. Оператори HALCON викликаються безпосередньо як окремі функції після імпорту модуля HALCON/Python. Зауважте також, що параметри операторів у HALCON/Python розділені на параметри функції (вхідні дані) та значення, що повертаються (вихідні).

Example
Наступний код читає зображення та обчислює кількість з’єднаних областей (стор. 10) у ньому.
img = ha.read_image('pcb')
регіон = ha.threshold(img, 0, 122)
num_regions = ha.count_obj(ha.connection(region))
print(f'Кількість регіонів: {num_regions}')

Попередні умови та детальну інструкцію див. у Посібнику програміста, частина 4, перший прикладample.

HALCON/C
Інтерфейс C є найпростішим інтерфейсом, який підтримує HALCON. Кожен оператор представлений однією або двома глобальними функціями, де ім’я оператора та послідовність параметрів ідентичні мові HDevelop.

Example
Наступний код читає зображення та обчислює кількість з’єднаних областей (стор. 10) у ньому.
Hobject img;
read_image(&img, “pcb”);
Об'єктний регіон;
поріг (img, ®ion, 0, 122);
Hobjectconnected_regions;
підключення(регіон, &підключені_регіони);
Hlong num_regions = 0;
count_obj(connected_regions, &num_regions);
printf(“Кількість регіонів: %” PRIdPTR “\n”, num_regions);

Попередні умови та детальну інструкцію див. у Посібнику програміста, частина 5, перший прикладample.

HALCON/C++
Інтерфейс C++ набагато складніший, ніж інтерфейс C. Ось, авансtagВикористовуються мови C++ та об'єктно-орієнтоване програмування, тобто автоматичне перетворення типів, побудова та знищення або групування функцій разом із їхніми даними в класи. Як і в інтерфейсі C, для кожного оператора HALCON надаються глобальні функції для процедурного стилю програмування.

Example
Наступний код читає зображення та обчислює кількість з’єднаних областей (стор. 10) у ньому.
HImage img{“pcb”};
Область HRegion = img.Threshold(0, 122);
Hlong numRegions = region.Connection().CountObj();
std::cout << “Кількість регіонів: ” << numRegions << '\n';

Попередні умови та детальну інструкцію див. у Посібнику програміста, частина 2, перший прикладample.

HALCON/.NET
C# і Visual Basic .NET використовують HALCON через інтерфейс .NET.
Аналогічно C++, пропонується два стилі програмування: процедурний і об'єктно-орієнтований. Для процедурного стилю клас HOperatorSet надає всі оператори HALCON, де HObject використовується для обробки іконічних даних, а HTuple використовується для керуючих даних. Для об’єктно-орієнтованого стилю такі класи, як HDataCode2d, HMeasure або HShapeModel, надаються для центральної функціональності. Крім того, доступні класи для знакових даних, наприклад, HImage або HRegion.

Example
Наступний код читає зображення та обчислює кількість з’єднаних областей (стор. 10) у ньому.
HImage img = новий HImage(“pcb”);
Область HRegion = img.Threshold(0d, 122d);
int numRegions = region.Connection().CountObj();
Console.WriteLine(“Кількість регіонів: ” + numRegions);

Попередні умови та детальну інструкцію див. у Посібнику програміста, частина 3, перший прикладample.

Інтерфейси отримання зображень

Інтерфейси отримання зображень HALCON формують міст між програмним забезпеченням, наданим виробником пристрою отримання зображень, і HALCON. Вони утворюють загальний загальний інтерфейс, який вимагає лише невеликого набору операторів. Будь ласка, зверніться до Посібника з рішень II-A для отримання докладної інформації про цю тему.
В даний час HALCON надає інтерфейси для більш ніж 50 пристроїв захоплення кадрів і сотень промислових камер у формі бібліотек, що динамічно завантажуються (Windows: DLL; Unix-подібні системи: спільні бібліотеки). Назви бібліотек починаються з префікса hAcq; бібліотеки, що закінчуються суфіксом xl, використовуються HALCON XL.
Найпоширеніші інтерфейси на основі галузевих стандартів уже встановлені разом із бібліотеками HALCON. Додаткові інтерфейси, а також останні версії вже включених інтерфейсів можна завантажити за посиланням https://www.mvtec.com/products/interfaces. Інтерфейси отримання зображень HALCON можуть змінюватися частіше, ніж сама бібліотека HALCON. Однією з причин цього є те, що MVTec постійно розробляє нові інтерфейси; крім того, якщо програмне забезпечення, що надається виробниками пристроїв для отримання зображень, змінюється, наприклад, якщо інтегруються нові функції, відповідні інтерфейси HALCON будуть адаптовані. Будь ласка, також зверніться до Довідника по інтерфейсу отримання зображень, щоб отримати повний список підтримуваних інтерфейсів отримання зображень.
Після того, як ви успішно встановили свій пристрій отримання зображень, все, що вам потрібно зробити, щоб отримати до нього доступ із HALCON, це викликати оператора open_framegrabber, вказавши назву інтерфейсу отримання зображень і деяку додаткову інформацію, наприклад, щодо підключеної камери. Потім зображення можна отримати, викликавши оператор grab_image (або grab_image_async).

Інтерфейси вводу/виводу

HALCON надає інтерфейси для кількох пристроїв вводу/виводу для отримання даних. Ці інтерфейси доступні як бібліотеки, що динамічно завантажуються (Windows: DLL; Unix-подібні системи: спільні бібліотеки). Назви бібліотек починаються з префікса hio; бібліотеки, що закінчуються суфіксом xl, використовуються HALCON XL.
Інтерфейси пристроїв введення/виведення HALCON забезпечують уніфікований доступ до різних пристроїв введення/виведення за допомогою невеликого набору операторів. Після встановлення пристрою введення-виведення встановлюється з’єднання за допомогою оператора open_io_device із зазначенням імені інтерфейсу пристрою введення-виведення та, за бажанням, деяких параметрів, що стосуються пристрою. Після встановлення з’єднання можна відкрити канал передачі, викликавши open_io_channel. Щоб читати та записувати значення на цьому каналі, використовуйте оператори read_io_channel і write_io_channel відповідно.
Зверніть увагу, що інтерфейси пристроїв вводу/виводу HALCON можуть змінюватися частіше, ніж сама бібліотека HALCON. Ви можете знайти найновішу інформацію разом із завантажуваними інтерфейсами (включаючи документацію) у розділі https://www.mvtec.com/products/interfaces. Повний список підтримуваних інтерфейсів пристроїв вводу/виводу можна знайти в Довідці по інтерфейсу пристрою вводу/виводу.

Як розробляти програми

Ми рекомендуємо вам почати зі швидкого прототипування в HDevelop, інтерактивному середовищі розробки для бібліотеки машинного зору HALCON. Ви можете використовувати HDevelop, щоб знайти оптимальні оператори та параметри для вирішення вашого завдання аналізу зображення. Після розробки програми HDevelop відповідно до заданих вимог її потрібно перевести в кінцеве середовище. Для цього ви можете вибрати один з наступних трьох підходів, залежно від ваших уподобань:

Починати з нуля: Написання програми з нуля означає переклад коду HDevelop на цільову мову програмування (C++, Python…) вручну. Як згадувалося раніше, правила іменування операторів, назви класів тощо можуть відрізнятися в різних мовах програмування. Перегляньте довідник операторів HALCON, щоб отримати підписи операторів HALCON для кожної підтримуваної мови програмування. Щоб отримати інформацію про те, як створювати програми потрібною цільовою мовою, прочитайте Посібник програміста.
Експорт коду HDevelop: Автоматично перекладіть свій код HDevelop на цільову мову програмування за допомогою експорту коду HDevelop.
Експорт бібліотечного проекту: Експорт бібліотеки HDevelop генерує готову до використання папку проекту, включно з оберненим кодом цільовою мовою та CMake file побудувати проект. Експорт бібліотеки HDevelop використовує HDevEngine, бібліотеку, яка діє як інтерпретатор. HDevEngine дозволяє безпосередньо виконувати програми або процедури HDevelop із програми, написаної мовою C++ або будь-якою іншою мовою, яка може інтегрувати об’єкти .NET. Таким чином, вам не потрібно перекомпілювати всю програму під час внесення змін до коду HDevelop.
Звичайно, ви можете використовувати HDevEngine без використання функції експорту бібліотеки HDevelop. Як використовувати HDevEngine детально описано в Посібнику програміста, частина 6 (Використання HDevEngine).

HDevelop

Давайте спочатку поглянемо на HDevelop. На малюнку 3.1 показано інтерфейс користувача HDevelop після того, як програма була завантажена та частково виконана.
За замовчуванням відображаються ці вікна, які також є важливими для розробки за допомогою HDevelop:

Вікно графіки Відображає (проміжні) результати, а саме знакові дані (стор. 10), такі як зображення, регіони та XLD.
Вікно програми Тут ви вводите програмний код, використовуючи оператори (стор. 10) для доступу до методів обробки зображень HALCON.
Вікно змінних Показує всі змінні, а саме символічні змінні та контрольні змінні. Іконічні змінні містять іконічні дані (стор. 10), а контрольні змінні містять контрольні дані (стор. 10).

Детальну інформацію про HDevelop можна знайти в посібнику користувача HDevelop. Наші навчальні відео також пропонують гарний вступ до HDevelop:

Підручник HDevelop 01: графічний інтерфейс і навігація
Підручник HDevelop 02: Змінні
Підручник HDevelop 03: Візуалізація

малюнок 3.1: Інтерфейс користувача HDevelop.

ExampПрограма

Тепер, коли ви познайомилися з інтерфейсом користувача HDevelop і основними концепціями HALCON (стор. 9), давайте розробимо програму C++ за допомогою підходу експорту бібліотеки.
Окрім наведених нижче покрокових інструкцій, ми рекомендуємо вам переглянути наші навчальні відео: Інтеграція коду HDevelop у програму C++ за допомогою експорту бібліотечного проекту
Інтегруйте код HDevelop у програму C# за допомогою експорту проекту бібліотеки
У відео демонструється експорт бібліотеки та надається додаткова інформація про тему.

Створення прототипу в HDevelop
Завдання наступного прample полягає в тому, щоб прочитати зображення та підрахувати кількість підключених до нього областей.

Відкрийте HDevelop і введіть наступний код у вікно програми:
read_image (Зображення, 'pcb')
порогове значення (зображення, регіон, 0, 122)
підключення (Region, ConnectedRegions)
count_obj (ConnectedRegions, кількість)
Перевірте свою програму, клацнувши «Запустити» на панелі інструментів або натиснувши F5.

Щоб легко інтегрувати цей код HDevelop у фактичну програму, ми інкапсулюємо частину машинного бачення в локальну процедуру.

Виділіть такі рядки коду: threshold (Image, Region, 0, 122) connection (Region, ConnectedRegions) count_obj (ConnectedRegions, Number)
Клацніть правою кнопкою миші, щоб відкрити контекстне меню.
Виберіть «Створити нову процедуру».
Назвіть його count_regions.
Виберіть «Параметри» та змініть «Схема вибору» на «Перший прийшов, останній вийшов».
Підтвердьте кнопкою ОК.
Збережіть свою програму HDevelop як hdev_count_regions.hdev

Підготуйте проект Visual Studio
У цьому ексample, ми будемо використовувати Visual Studio 2019. 1

Створіть порожній проект C++ Windows Console і назвіть його vs_count_regions. Будь ласка, активуйте опцію Розмістити рішення та проект в одному каталозі. 2
Додайте джерело C++ file (Проект меню Додати новий елемент… C++ File) і назвіть його vs_count_regions.cpp.
Виберіть платформу рішення x64 зі спадного меню на панелі інструментів.
Відкрийте властивості проекту (Меню Project vs_count_regions Properties…) і встановіть такі налаштування:
- Виберіть C/C++ General і додайте наступні додаткові каталоги для включення:$(HALCONROOT)\include;$(HALCONROOT)\include\halconcpp;
- Виберіть Linker General і додайте такий додатковий каталог бібліотеки:$(HALCONROOT)\lib\$(HALCONARCH);
- Виберіть «Введення компонувальника» та додайте наступні додаткові залежності: halconcpp.lib;hdevenginecpp.lib;

Експорт бібліотечного проекту
Далі ми експортуємо нашу програму HDevelop hdev_count_regions.hdev у папку проекту Visual Studio.

Відкрийте раніше створену програму HDevelop hdev_count_regions.hdev.
ВІДЧИНЕНО File Експорт бібліотечного проекту…
Виконайте такі налаштування:
- Введення file: Поточна програма
- Цільова мова: C++
- Назва проекту: hdev_count_regions
- Розташування проекту: виберіть розташування нашого проекту Visual Studio vs_count_regions.
- Простір імен: hdev_count_regions
Підтвердьте експорт.

Тепер ваша папка проекту Visual Studio vs_count_regions повинна містити принаймні такі дані:

vs_count_regions.cpp (Джерело File)
vs_count_regions.sln (Рішення)
hdev_count_regions (Папка з HDevelop Export)
- cmake
- res_ hdev_ count_ регіонів
- hdev _ кількість_ регіонів. hdev
джерело
- hdev_count_regions.cpp
- hdev_count_regions.h
- CMakeLists.txt

Інтегруйте бібліотечний проект у Visual Studio
Нарешті, ми повинні інтегрувати програму HDevelop у наш проект Visual Studio.

Відкрийте проект Visual Studio.
Відкрийте проект, додайте наявний елемент… і виберіть C++ file hdev_count_regions.cpp і заголовок file hdev_count_regions.h, створений програмою експорту бібліотеки HDevelop. ( files знаходяться в папці джерела hdev_count_regions.)
Введіть наступний код у vs_count_regions.cpp:
#включити
#include “HalconCpp.h”
#include “hdev_count_regions/source/hdev_count_regions.h”
int main()
{
HalconCpp::HImage Image(“pcb”);
hdev_count_regions::SetResourcePath(“hdev_count_regions/res_hdev_count_regions”);
HalconCpp::HTuple Number{};
hdev_count_regions::count_regions(Зображення, &Номер);
std::cout << “Кількість регіонів: ” << Number.L() << '\n';
}
Виконайте програму. → Відкриється консоль із результатом «Кількість регіонів: 43».

Як продовжити

Щоб глибше зануритися в HALCON, ми пропонуємо додаткову документацію та підтримку.

HDevelop Прample Програми
HALCON надає широкий набір ексample програми не лише для HDevelop, а й для різних мов програмування. Ці ексampфайли можна знайти в каталозі, позначеному змінною середовища % HALCONEXAMPLES% або, якщо змінна не встановлена, у підкаталозі exampфайли папки, у яку ви встановили HALCON.
Щоб відкрити HDevelop exampпрограму, виберіть меню File Огляд HDevelop Example Програми…. Для початківців рекомендуємо вибрати ексample з категорії Область застосування.
Послуги та підтримка
наш webсайт https://www.mvtec.com/services-support пропонує різноманітну підтримку, напрample навчальні відео, інформація про семінари та тренінги, куток розробників із порадами та підказками та багато іншого.
Документація HALCON
Документація містить величезну кількість інформації, від тем для початківців до експертних знань. наприкладample, наші посібники з рішень описують методи машинного зору та їх застосування в HDevelop. Гарною відправною точкою є Посібник з рішень I, який знайомить вас з основними методами машинного зору.
Оверview усіх посібників із коротким описом можна знайти на сторінці введення документації.

Документи / Ресурси

HALCON 21.11 Прогрес [pdfПосібник користувача
21.11 Прогрес, 21.11, Прогрес

Список літератури

Посібник користувача

HALCON 21.11 Прогрес