Uživatelský manuál. Revize manuálu: 1.8. Kompatibilita s verzí SmartVision: Datum uvolnění revize:

Transkript

1 Uživatelský manuál Revize manuálu: 1.8 Kompatibilita s verzí SmartVision: Datum uvolnění revize: Workswell s.r.o. SmartVision SDK 1

2 Úvod SmartVision SDK je sada vývojových nástrojů pro implementaci videoaplikací. Obsahuje širokou sadu ovladačů (SmartVision Runtime Package), dll videoknihovnu (SmartVision library) a testovací aplikace (TestApp). Knihovna SmartVision library je univerzální DLL knihovna pro získání videoobrazu, implementaci a návrh obrazových algoritmů. Knihovna podporuje připojení na protokoly GigE, USB 2.0, USB 3.0, CameraLink, Fast Ethernet MJPEG, IEEE 1394 Firewire od více jak 47 výrobců kamer a videohardwaru. Využitím formátu DLL je možné tuto knihovnu využít v programovacím jazyce C, C++, C#, Visual Basic, Matlab, Labview a všech prostředích podporujících import DLL funkcí. Díky snadnému rozhraní je možné přistupovat k příslušnému kamerovému systému vždy stejným principem a získat kompletní kontrolu nad používaným videohardwarem. Vývojář tak může použít jednu knihovnu pro návrh aplikací s odlišnými videorozhraními od protokolu GigE až po USB. SmartVision library obsahuje také pomocné aplikace pro efektivní průzkum připojeného videohardwaru. Aplikace CameraExplorer dovoluje uživateli zobrazit připojený videohardware a vypsat všechny čtecí a zápisové parametry videosystému. Pomocí sady GET a SET funkcí je možné plně ovládat a nastavovat videohardware. Otevření a ukončení videostreamu je díky funkci OpenSession a CloseSession velmi jednoduché a rychlé. Zobrazení aktuálního obrazu je umožněno jak pomocí již předpřipraveného videookna, tak i pomocí čtení z matice RGB dat z příslušného bufferu pomocí. Obraz lze zaznamenat také jednoduše pomocí vyfocení aktuální scény (funkce MakeSnap) či přímo pomocí reference přistupovat na blok dat ve videopaměti a tím dosáhnout maximální obnovovací frekvence obrazové informace z kamerového systému. Oranžové bloky níže ukazují části vývojové sady SmartVision SDK. Testovací aplikace TestApp SmartVision Vývojové prostředí IDE pro vývoj koncové aplikace (C#, C/C++, Matlab, Labview, atd.) SmartVision library (sada DLL funkcí pro ovládání a zpracování obrazu z videohardwaru) Operační systém Windows (XP, Vista, 7-32bit a 64bit) SmartVision Runtime Package (sada ovladačů a přímý přístup na videohardware) Videohardware a kamery (Ethenet, USB, CameraLink, PCI) 2 Univerzální DLL videoknihovna Workswell s.r.o.

3 SmartVision SDK - uživatelský manuál Workswell s.r.o. SmartVision SDK 3

4 Vyvázání se že záruky Všechny výrobky (software, hardware či firmware) společnosti Workswell s.r.o. mají záruku proti výrobním vadám po dobu dvou let. Tuto záruku lze uplatnit pouze, pokud byl výrobek skladován a používán podle pokynů uvedených v příslušné příručce. Záruka se vztahuje pouze na původního kupce a je nepřenositelná. Záruku nelze uplatnit na výrobek, který byl nesprávně používán, neudržován, poškozen nebo provozován při podmínkách, které manuál nestanovuje jako podmínku provozní. Jestliže dojde k poškození výrobku, který je kryt zárukou, výrobek nesmí být dále používán, aby se zabránilo dalšímu poškození. Zákazník musí neprodleně oznámit tuto závadu společnosti Workswell nebo jím autorizovanému distributorovi, jinak nebude možné záruku uplatnit. Společnost Workswell zdarma opraví nebo vymění každý vadný výrobek, jestliže bude na základě odborné prohlídky prokázána u výrobku vada materiálu či výrobku a jestliže bude tento výrobek vrácen společnosti Workswell v záruční době, tj. do dvou let od data nákupu. Výrobek nesmí být společnost Workswell otevírán nebo upravován. Společnost Workswell nenese odpovědnost za vady výrobku kromě výše uvedených a neposkytuje na ně záruku. Žádná další záruka není vyjádřena ani předpokládána. Společnost Workswell nenese odpovědnost za neodborné použití výrobku ani za škody způsobené nesprávnou činností, instalací či funkcí výrobku třetím stranám či samotnému uživateli. Autorská práva Workswell s.r.o. Všechna práva celosvětově vyhrazena. Bez předchozího písemného souhlasu společnosti Workswell s.r.o. nesmí být žádná část software či hardware včetně zdrojového kódu a zdrojových souborů reprodukována, přenášena, přepisována nebo překládána do jakéhokoli umělého či přirozeného jazyka, pokud není výsledně uvedeno jinak. Názvy a značky uvedené na výrobcích v této příručce jsou registrovanými ochrannými známkami nebo ochrannými známkami společnosti Workswell s.r.o. Všechny ostatní ochranné známky nebo názvy společností zmíněné v této příručce a manuálu se používají pouze pro identifikaci a jsou majetkem jejich příslušných vlastníků. 4 Univerzální DLL videoknihovna Workswell s.r.o.

5 Workswell s.r.o. SmartVision SDK 5

6 Obsah Úvod... 1 Obsah... 6 Varování a upozornění... 7 Obsah standardního dodání... 8 Informace pro uživatele... 9 Nápověda a dotazy Požadavky na hardware PC Aktualizace a kompatibilita Licenční systém SmartVision Instalace SmartVision SDK Spouštění TRIAL verze Popis balíku SmartVision SDK SmartVision library DLL funkce Tutoriál pro vývoj v jazyce C# Univerzální DLL videoknihovna Workswell s.r.o.

7 1 Varování a upozornění Varování Upozornění Před použitím výrobku zkontrolujte, zda nejeví viditelné známky poškození či nesprávné funkce. Pokud je zařízení poškozené či jinak vadné, nepoužívejte jej. Nepoužívejte a neskladujte zařízení v rozporu se skladovacími a provozními podmínkami stanovenými v této příručce (týká se jen hardware). Jakékoliv zásahy a necertifikované servisní úkony do výrobku vedou k automatické ztrátě záruky Workswell s.r.o. SmartVision SDK 7

8 2 Obsah standardního dodání CD Součástí standardního zakoupeného CD SmartVision SDK jsou tyto části: Sada ovladačů SmartVision Runtime Package DLL knihovna SmartVision library Testovací aplikace a tutorial TestApp Příručka SmartVision SDK - Uživatelský manuál. SmartVision Runtime Package Dokumentace Součástí standardního dodání je samoinstalační aplikace SmartVision Runtime Package, která obsahuje ovladače na kompatibilní videohardware. Tato aplikace nainstaluje na příslušný počítač sadu driverů pro videohardware a kamery. Některé z těchto ovladačů využívají také sadu MAX od společnosti National Instruments a dalších společností. Společnost Workswell s.r.o. plně uznává veškeré licenční ujednání se společností National Instruments a veškeré poplatky za užívání tohoto modulu ve svém vývojovém nástroji SmartVision SDK. S výrobkem SmartVision SDK je dodáván Uživatelský manuál (tj. dokument, který právě čtete), který je uložen na oficiálním CD. 8 Univerzální DLL videoknihovna Workswell s.r.o.

9 3 Informace pro uživatele Typografické konvence Nápověda a uživatelské fórum Aktualizace Firmware V této příručce se používají následující typografické konvence: VELKÁ PÍSMENA se používají pro názvy kláves, tlačítek a položek menu, COURIER se používá pro ukázky zdrojových kódů, názvy souborů a souborové cesty, kurzíva se používá pro důležité informace a názvy dokumentů, tučné písmo je použito při odkazu na jinou kapitolu, názvy funkcí či internetové odkazy S technickými dotazy, na které vám nepomohla najít odpověď tato příručka, se obraťte na svého prodejce, nebo přímo na stránky produktu na internetové adrese kde nejprve vyhledejte odpověď v uživatelském fóru a pokud odpověď na svůj dotaz nenaleznete, zašlete dotaz na info@workswell.cz Prioritním cílem společnosti Workswell je dodávat své výrobky v takové podobě, aby splňovala aktuální potřeby svých uživatelů a zároveň, aby byly co nejrychleji odstraněny všechny nedostatky, které byly při jejich užívání nalezeny. Z tohoto důvodu společnost Workswell ve všech svých výrobcích pravidelně uvolňuje aktualizace. Více informací naleznete v kapitole Aktualizace a kompatibilita. Firmware je interní řídicí program zařízení. Z uživatelského pohledu je podstatná pouze aktuální verze firmware, která je nahrána v právě používaném zařízení a videohardwaru. Workswell s.r.o. SmartVision SDK 9

10 4 Nápověda a dotazy Obecný postup Při hledání odpovědi na technický problém doporučujeme dodržovat následující postup: pokuste se nalézt odpověď v této příručce, obraťte se na svého prodejce zařízení, prostudujte stránky společnosti Workswell s.r.o. na adrese či napište na info@workswell.cz. 10 Univerzální DLL videoknihovna Workswell s.r.o.

11 5 Požadavky na hardware PC Verze operačního systému SmartVision SDK byl testován pro 32 a 64 bitové verze operačního systému Windows následujících verzí: Windows XP Windows 7 32bit Windows 7 64bit Na jiných verzích operačního systému Windows nebyl SmartVision SDK testován a společnost Workswell nezaručuje na těchto verzích Windows správnou funkci jednotlivých částí. V případě, že používáte Windows XP SP2 resp. Windows 7, je nutná aktualizace na vyšší verzi Windows XP SP3 resp. Windows Vista SP1 před zahájením instalace jednotlivých částí SmartVision SDK. Jako prerekvizity a správné používání DLL videoknihovny SmartVision library je potřeba do operačního systému doinstalovat:.net Framework 3.5 a vyšší (ve Windows 7 je již nainstalován) SmartVision Runtime Package (součástí SmartVision SDK) Konfigurace PC Minimální konfigurace pro SmartVision SDK na operační systém Windows 7 je následující: Procesor Intel: min. 2 GHz paměť: min. 2 GB RAM, pevný disk: min. 100 GB, Gigabitový Ethernetový port s řadičem Intel podporující Jumboframe min. 9kB, klávesnice a myš, grafický adaptér a monitor s odpovídajícím rozlišením. Workswell s.r.o. SmartVision SDK 11

12 6 Aktualizace a kompatibilita Aktualizace SmartVision SDK Nejnovější verze SmartVision SDK,tj. jak SmartVision Runtime Package, tak videoknihovny SmartVision library ale i příslušných tetovacích aplikací naleznete na webových stránkách kde je umístěna nejnovější verze těchto částí. Vzhledem k požadavku, na co nejrychlejší úpravu a opravu knihovny si společnost Workswell, vyhrazuje právo na zasílání upozornění na nejnovější update SmartVision SDK na uživatelský zákazníka. Výrazně však doporučujeme pravidelně kontrolovat nejnovější verze SmartVision Runtime Package a SmartVision library. V případě použití nových verzí stačí jednoduše přeinstalovat příslušnou stávající SmartVision library. Vždy však doporučujeme, aby zákazník stahoval současně, jak SmartVision Runtime Package tak také SmartVision library pro bezproblémový chod nových i stávajících funkcí na příslušném videohardwaru. Kompatibilni videohardware a zdroje videa SmartVision library pomocí modulu SmartVision Runtime Package umí přistupovat k několika stovkám druhů videohardwaru, ať už se jedná o kamery, termokamery či videograbbery. Základem je obsáhlá databáze ovladačů pro snadné napojení videohardwaru, ať s nutností či bez příslušného videograbberu. Uživatel tak není nucen instalovat jiné ovladače a může se věnovat samostatnému zpracování videodat. Mezi podporované protokoly patří: 1) Paralelní digitální rozhraní s příslušným videograbberem - TTL rozhraní - RS422 - LVDS 2) CameraLink protokol s příslušným videograbberem 3) Gigabit Ethernet (GigE) protokol s a bez nutnosti videograbberu 4) Fast Ethernet IP protokol s a bez videograbberu - MJPEG 5) IEEE 1394 Firewire protokol s a bez nutnosti videograbberu - IIDC (DCAM) 6) USB 2.0 protokol bez nutnosti videograbberu - DirectShow produkty jako jsou webkamery, mikroskopy, skenery, apod. 7) USB 3.0 protokol bez nutnosti videograbberu - AIA USB3 Vision produkty Všechny výše uvedené rozhraní jsou podporovány s framegrabbery společnosti National Instruments, popř. s jejími kompatibilními klony pro rozhraní PCI, PCIexpress. Pro některé druhy rozhraní není nutné dokupovat speciální videograbbery a lze použít standardní integrované porty v PC, je však nutné zajistit příslušné parametry videopřenosu, definované v jednotlivých standardech IEEE či AIA. 12 Univerzální DLL videoknihovna Workswell s.r.o.

13 Vzhledem k velkému počtu a množství každoročně vyráběných typů zařízení, nemůže společnost Workswell s.r.o. garantovat podporu všech výše uvedených protokolů u všech výrobců. Proto doporučujeme před zakoupením SmartVision SDK kontaktovat příslušného prodejce SmartVision SDK či technickou podporu společnosti Workswell ohledně výsledné kompatibility SmartVision SDK a cílového videohardwaru. Za případné nekompatibility SmartVision SDK a příslušného videohardwaru či kamery nenese společnost Workswell s.r.o. žádnou zodpovědnost. Dokumentace Na oficiálních stránkách společnosti Workswell s.r.o. naleznete všechny příslušné dokumentační listy, uživatelské manuály či technické informace. Pro technický dotaz či nápovědu postupujte dle kapitoly Nápověda a dotazy. Podporovaní výrobci Mezi podporované výrobce videohardwaru patří tyto společnosti: 1) Adimec CCD Cameras 2) Allied Vision Technologies 3) Atmel Corporation 4) Basler Vision Technologies 5) Baumer Optronic 6) Cohu Inc. 7) Costar Imaging 8) DVC Company 9) Dalsa 10) Flir Systems AB 11) Fairchild Imaging 12) Flovel Co. 13) Hamamatsu 14) Hitachi Kokusai Electronic 15) Imaging Solutions 16) Imperx 17) Indigo Systems 18) JAI 19) Jenoptik Optical System 20) Mikrotron 21) NET GmbH 22) National Instruments 23) PCO AG 24) Perkin Elmer Optoelectronics 25) Photonfocus 26) PixeLINK 27) Point Gray Research 28) Prosilica Inc. 29) Pulnix 30) QImaging Corporation 31) Raytheon Commercial Infrared 32) Redlake MASD Inc. 33) SVS Vistek 34) Sentech 35) Sensors Unlimited Workswell s.r.o. SmartVision SDK 13

14 36) Sensovation AG 37) Silicon Imaging 38) Smartek 39) Sony 40) Takex 41) The Imaging Source 42) Toshiba 43) UNIQ Vision Inc 44) VDS Vosskuhler 45) Vieworks 46) E2v 47) isvi 14 Univerzální DLL videoknihovna Workswell s.r.o.

15 7 Licenční systém SmartVision Popis licenčního systému a přidělení licence Součástí knihovny SmartVision library je také nástroj pro udělení licence pro dané PC, resp. aplikaci, která využívá knihovny SmartVision library. Lincenční nástroj je automaticky spuštěn při instalaci knihovny SmartVision library (nutné nejdříve nainstalovat modul SmartVision Runtime Package). Proto doporučujeme dokončení procesu licencování již při samotné instalaci knihovny SmartVision library. V případě budoucích změn v licenci, či zakoupení FULL verze a přechodu z TRIAL verze je možné spustit licenční systém manuálně. K těmto účelům slouží program SmartVision Activator. Odkaz na SmartVision Activator je umístěn ve Start nabídce v cestě "Všechny programy\workswell SmartVision\". Podmínkou správného spuštění je nutnost spustit SmartVision Activator s administrátorskými právy. Bez aktivace jedné z verzí (tj. FULL či TRIAL) nebude knihovna SmartVision library funkční. TRIAL verze funguje pouze s aktivním připojením k internetu a je platná po dobu 7-dní bez omezení. K aktivaci FULL verze je nutné zakoupit sériové číslo ke knihovně SmartVision library od společnosti Workswell a zadat ho buď při instalaci, či manuálně přes nástroj SmartVision Activator. Aktivaci je možné provést, pouze pokud je počítač připojen k internetu. Při zadávání zákaznických informací do formulářů si společnost Workswell vyhrazuje právo uložit tyto informace na licenčním serveru společnosti a zároveň se zavazuje, že tyto informace neposkytne třetím stranám a jiným obchodním subjektům. V následujícím průvodci jsou ukázány správné kroky pro úspěšné přidělení licence: 1) Spuštění licenčního systému pomocí aplikace SmartVision Activator Workswell s.r.o. SmartVision SDK 15

16 2) Volba typu licence TRIAL či FULL v aplikaci SmartVision Activator 3) Vyplnění informací a sériového čísla pro verzi TRIAL a FULL v aplikaci SmartVision Activator 16 Univerzální DLL videoknihovna Workswell s.r.o.

17 4) Odesílání uživatelských informací na licenční server Workswell 5) Úspěšné odeslání žádosti na licenční server Workswell Workswell s.r.o. SmartVision SDK 17

18 6) Zaslání potvrzovacího u z licenční serveru Workswell - Po zaslání žádosti o TRIAL verzi Vám přijde na zadaný potvrzovací zpráva, kterou je nutné aktivovat. 7) Úspěšné dokončení instalace a licenčního systému Workswell - Po potvrzení a odsouhlasení licenčních podmínek a potvrzení serverem se Vám zobrazí úspěšné dokončení celého procesu. 18 Univerzální DLL videoknihovna Workswell s.r.o.

19 Deaktivace platné FULL licence a přenos na jiné PC Společnost Workswell umožňuje přenos již zakoupené licence knihovny SmartVision library na jiné PC. Důvodem přenosu může být upgrade či oprava stávajícího PC, popřípadě možnost implementace videoaplikace na jiném než cílovém PC. K těmto účelům slouží aplikace SmartVision Deactivator Pokud budete chtít přenést licenci FULL verze na jiný počítač, je nutné na aktuálním počítači s instalovaným SmartVision library, kde byla licence aktivována, spustit deaktivační software SmartVision Deactivator. Tento program je nutné spustit s administrátorskými právy. Deaktivaci je možné provést pouze pokud je aktuální počítač připojen k internetu. Součástí licenčních podmínek je podmínka, že na každém počítači využívající DLL funkce z knihovny SmartVision library musí být zakoupena FULL licence či alespoň aktivní TRIAL verze knihovny. V opačném případě, se zákazník vystavuje soudnímu řízení. Na následujícím obrázku je ukázána správná deaktivace systému a postup: 1) Spuštění deaktivačního nástroje a zadání sériového čísla Workswell s.r.o. SmartVision SDK 19

20 8 Instalace SmartVision SDK Instalace SmartVision Runtime Package SmartVision SDK se skládá z několika modulů, z nichž základním je instalace sady ovladačů pro možnost připojení na videohardware, tedy před samotným používáním DLL videoknihovny SmartVision library. Tato sada ovladačů je nazývána SmartVision Runtime Package a nainstaluje na cílovou stanici či PC s operačním systémem Windows všechny potřebné ovladače. Seznam podporovaného hardwaru a zdrojů videosignálu naleznete v kapitole Aktualizace a kompatibilita. SmartVision SDK díky modulu SmartVision Runtime Package podporuje více než 47 výrobců videohardwaru a kamer. V následujícím odstavci je popsán bod po bodu instalační proces SmartVision Runtime Package: 1) Spuštění a extrakce SmartVision Runtime Package samoinstalačního balíku 2) Inicializace instalačního procesu SmartVision Runtime Package 20 Univerzální DLL videoknihovna Workswell s.r.o.

21 3) Přehled licencovaných sad ovladačů pro kompatibilní videohardware a spuštění instalace SmartVision Runtime Package 4) Instalační proces SmartVision Runtime Package Workswell s.r.o. SmartVision SDK 21

22 5) Dokončení instalace a restart počítače a opětovné spuštění operačního systému - Po instalaci SmartVision Runtime Package prosím proveďte manuální restart počítače. Během tohoto restartu se propojí a inicializují všechny potřebné ovladače pro budoucí videohardware a kamery. 22 Univerzální DLL videoknihovna Workswell s.r.o.

23 Instalace SmartVision library Po úspěšné instalaci sady SmartVision Runtime Package je nutné spustit instalaci DLL knihoven SmartVision library. Díky této instalaci se do operačního systému nainstalují DLL knihovny pro budoucí vývoj a přístup na kamerový systém a videohardware, zároveň se prováží tyto DLL knihovny s balíkem SmartVision Runtime Package. Průchod instalací popisuje následující průvodce. Na konci této instalace je potřeba provézt volbu licence. Pro zkušební účely je povoleno využívat 7denní TRIAL verzi, kde si můžete vyzkoušet chování a vývoj aplikace s knihovnou SmartVision library. Po celou dobu používání v TRIAL verzi je nutné být připojený k internetu, neboť během této doby se kontrolují licenční podmínky se serverem společnosti Workswell. V případě, že uživatel chce využívat DLL funkce pro budoucí aplikaci i v offline režimu a na dobu neomezenou, je nutné zakoupit SmartVision SDK u společnosti Workswell a aktivovat FULL verzi. Po zakoupení Vám bude zasláno sériové číslo, které bude ověřeno přes licenční server a následně povolena trvalá licence pro daný počítač. Samotná licence a nákup jednoho sériového čísla se váže vždy a pouze na jeden počítač, na kterém je SmartVision library spuštěno a využíváno. 1) Spuštění instalace a extrakce SmartVision library Workswell s.r.o. SmartVision SDK 23

24 2) Inicializace instalace SmartVision library 3) Přehled instalačních pluginů, modulů a prvků SmartVision library 24 Univerzální DLL videoknihovna Workswell s.r.o.

25 4) Zahájení instalace a správný proces kopírování SmartVision library 5) Dokončení instalace SmartVision library 6) Poinstalační spuštění licenčního systému SmartVision library - Po dokončení instalace DLL knihovny SmartVision library je potřeba projít licenčním procesem. Tento proces je automaticky spuštěn po dokončení instalace SmartVision library. Přesný postup a popis je popsán v kapitole Licenční systém SmartVision. Workswell s.r.o. SmartVision SDK 25

26 9 Spouštění TRIAL verze Spouštění TRIAL verze Pokud je na počítači aktivována TRIAL verze, při každém spuštění knihovny SmartVision library (nebo aplikace Camera Explorer) se zobrazí vyskakovací okno ovladačů videohardwaru od společnosti National Instruments oznamující, že balík ovladačů této společnosti běží také ve zkušební verzi. Okno je nutné zavřít stisknutím jednoho z tlačítek Evaluate nebo Cancel. 26 Univerzální DLL videoknihovna Workswell s.r.o.

27 10 Popis balíku SmartVision SDK SmartVision Runtime Package Součástí standardního dodání SmartVision SDK je sada ovladačů SmartVision Runtime Package. Ta obsahuje ovladače na kompatibilní videohardware a kamerový systém. Tato část zajišťuje kompatibilitu a přímý přístup na velké množství videohardwaru a jednotné rozhraní pro knihovnu SmartVision library. Kompletní soupis podporovaného hardwaru naleznete v sekci Aktualizace a kompatibilita. Některé z těchto ovladačů využívají také sadu MAX od společnosti National Instruments a dalších společností. Společnost Workswell s.r.o. plně uznává veškeré licenční ujednání se společností National Instruments a veškeré poplatky za užívání tohoto modulu ve své knihovně SmartVision library a SmartVision Runtime Package. Camera Explorer Po úspěšné instalaci SmartVision library se Vám do počítače nainstaluje také pomocná aplikace Camera Explorer. Tato aplikace slouží k vygenerování seznamu parametrů z aktuálně připojené kamery a videohardwaru. V tomto textovém souboru pak uživatel nalezne kompletní sadu XML uzlů, tedy jednotlivých atributů ve stromu příslušného videohardwaru či kamery. 1) Spuštění aplikace Camera Explorer - Po otevření aplikace si uživatel může zvolit kameru či dostupný videohardware, který je kompatibilní s knihovnou SmartVision library. Workswell s.r.o. SmartVision SDK 27

28 2) Vygenerování souboru s popisem a seznamem dostupných atributů pro budoucí využití v DLL funkcích SmartVision library 3) Výsledný textový soubor s popisem a seznamem dostupných atributů pro budoucí využití v DLL funkcích SmartVision library SmartVision library - DLL knihovny Hlavní částí SmartVision SDK je instalovaná sada DLL funkcí SmartVision library pro kompletní ovládání, čtení a přístup na data videohardwaru. Konkrétní cesta k těmto knihovnám je popsána v souboru README.RTF Popis jednotlivých funkcí je uveden v kapitole SmartVision library DLL funkce. 28 Univerzální DLL videoknihovna Workswell s.r.o.

29 11 SmartVision library DLL funkce Obecný popis DLL funkcí a záznam chyb v logu Všechny DLL funkce kromě void funkcí vrací hodnotu Integer = 1, když jsou úspěšně dokončeny. Pokud však nastala chyba, vrácí hodnotu 0 nebo -1 (typicky u funkcí get) dle typu chyby. Veškeré tyto chyby jsou zapsány do tzv. error logu, který je možné přečíst z textového souboru error_log.txt, který je vytvořen ve stejné cestě kde je spuštěná samotna DLL knihovna SmartVision library. Spuštění session a ukončení session Pro ovládání kamery je nutné nejprve spustit tzv. session pomocí funkce OpenSession. Parametrem této funkce je název rozhraní kamery, který lze zjistit v poli camera Interface v pomocném programu Camera Explorer. Otevření session chvíli trvá a proto je nutné před další prací s kamerou periodicky provádět polling pomocí funkce GetSessionStatus. Session se nepodaří spustit, pokud ke kameře již přistupuje jiný proces. Je nutné ukončit session pomocí funkce CloseSession před ukončením aplikace, ze které se volá DLL, jinak v paměti zůstane běžící proces příslušící spuštěné session. Popis příslušných DLL funkcí: void OpenSession(char camerainterface[]) o Otevírá Session o char camerainterface[]nmode - string obsahující název rozhraní kamery získaný pomocí aplikace Camera Explorer void CloseSession() o Ukončuje Session int8_t GetSessionStatus() o return: 0 = Session není spuštěná 1 = Session je spuštěná Otevření a zavření okna s videem Po spuštění session je možné otevřít okno s videem pomocí funkce OpenVideo. Dále už je možné libovolně volat ostatní funkce z knihovny SmartVision SDK. Po ukončení práce je nutné zavřít okno s videem funkcí CloseVideo a ukončit session pomocí funkce CloseSession. Popis příslušných DLL funkcí: void OpenVideo() o Otevírá okno s videem. Okno je potom nutné zapozicovat na obrazovce pomocí funkcí ze systémové User32.dll knihovny Workswell s.r.o. SmartVision SDK 29

30 void CloseVideo() o Zavírá okno s videem. Ovládání parametrů příslušného videohardwaru Veškeré hardwarové funkce příslušného videohardwaru je možné ovládat pomocí funkcí SetAttribute. Tyto funkce mají jako parametr název XML uzlu, který používá driver GigE rozhraní, případně dalších rozhraní (DirectShow a podobně). V XML každé kamery jsou uvedeny všechny hardwarové atributy, které je na kameře možné ovládat. Seznam všech dostupných atributů je možné uložit do textového souboru programem Camera Explorer, který je součástí SmartVision library. Uložený textový soubor obsahuje výpis všech atribut ve formátu: [prvnixmluzel::druhyxmluzel::n-tyxmluzel] Description = "Popis XML atributy ulozeny v XML kamery" Type = "Datovy typ" (UINT32, INT64, DBL, String, Enum, Bool, Command) Read = TRUE/FALSE (je mozne atribut cist?) Write = TRUE/FALSE (je mozne atribut zapisovat?) Min = "Minimalni hodnota rozsahu atributu" Max = "Maximalni hodnota rozsahu atributu" Value0 = "Prvni hodnota enumeratoru" Value1 = "Druha hodnota enumeratoru" ValueN = "N-ta hodnota enumeratoru" Popis příslušných DLL funkcí: int8_t SetAttribute(char activeattribute[], double valuedbl, char valuestring[]) o Funkce pro nastavování hardwarových atribut kamery o char activeattribute[] - název XML uzlu vyčtený ze souboru vygenerovaného pomocí aplikace Camera Explorer (bez složených závorek, ovšem včetně oddělovacích dvojteček) o double valuedbl - číselná hodnota atributu. GiGE XML norma specifikuje tyto datové typy UINT32, INT64, DBL, String, Enum, Bool, Command. Parametr valuedbl zahrnuje datové typy UINT32, INT64, DBL, Bool (0 = false, 1 = true) a Command (0 = off, 1 = on). Je nutné si pohlídat platný rozsah atributu, uložený opět v textovém souboru vygenerovaném aplikací Camera Explorer. o char ValueString[] - string hodnota atributu. Zahrnuje datové typy String a Enum. Pro enumerátory jsou v textovém souboru uloženy všechny platné hodnoty enumerátoru a tyto se předávají funkci jako string. o return: 1 = nastavení úspěšné 0 = nastavení úspěšné/chyba 30 Univerzální DLL videoknihovna Workswell s.r.o.

31 int8_t SetWindowSize(int16_t width, int16_t height) o Nastavuje velikost okna s videem. Okno je vždy umístěno na pozici (0,0) o int16_t width - horizontální velikost okna v px o o int16_t height - vertikální velikost okna v px return: 1 = nastavení úspěšné 0 = nastavení úspěšné/chyba Čtení parametrů příslušného videohardwaru Obdobou ovládacích funkcí jsou funkce pro čtení parametrů z videohradwaru GetAttribute, které vyčtou z parametru videohardwaru aktuální hodnotu. Tyto funkce mají jako parametr název XML uzlu, který používá driver GigE rozhraní, případně dalších rozhraní (DirectShow a podobně). V XML každé kamery jsou uvedeny všechny hardwarové atributy, které je na kameře možné ovládat. Seznam všech dostupných atributů je možné uložit do textového souboru programem Camera Explorer, který je součástí SmartVision library. Rozšířenou verzí funkce GetAttribute je funkce GetAttributeInfo, která z parametru vyčte doplňkové informace videohardwaru. Popis příslušných DLL funkcí: int8_t GetAttribute(char activeattribute[], double *valuedbl, char valuestring[], Int32 lengthin) o Vyčte hodnotu hardwarového atributu kamery o char activeattribute[] - název XML uzlu vyčtený ze souboru vygenerovaného pomocí aplikace Camera Explorer (bez složených závorek, ovšem včetně oddělovacích dvojteček) o double *valuedbl - pointer na proměnnou typu double, do které se zapíše číselná hodnota atributu. Proměnná zastupuje datové typy UINT32, INT64, DBL, Bool (0 = false, 1 = true) a Command (0 = off, 1 = on) o char valuestring[] - string hodnota atributu. Zahrnuje datové typy String a Enum o Int32 lengthin - očekávaná délka obdrženého stringu (kvůli vyhrazení paměti pro výstupní string char ValueString*+) o return: 1 = nastavení úspěšné 0 = nastavení úspěšné/chyba Workswell s.r.o. SmartVision SDK 31

32 int8_t GetAttributeInfo(char activeattribute[], int8_t *type, int8_t *readable, int8_t *writable, double *minimum, double *maximum, double *valuedbl, char valuestring[], int32_t len) o Vyčte hodnotu hardwarového atributu kamery a další doplňkové informace o atributu o char activeattribute[] - název XML uzlu vyčtený ze souboru vygenerovaného pomocí aplikace Camera Explorer (bez složených závorek, ovšem včetně oddělovacích dvojteček) o int8_t *type - pointer na proměnnou, do které se zapíše datový typ daného atributu (0 = UINT32, 1 = INT64, 2 = DBL, 3 = String, 4 = Enum, 5 = Bool, 6 = Command) o int8_t *readable - je mozne atribut cist? (0 = false, 1 = true) o int8_t *writable - je mozne atribut zapisovat? (0 = false, 1 = true) o double *minimum - pointer na proměnnou, do které se zapíše minimalni hodnota rozsahu atributu o double *maximum - pointer na proměnnou, do které se zapíše maximalni hodnota rozsahu atributu o double *valuedbl - pointer na proměnnou typu double, do které se zapíše číselná hodnota atributu. Proměnná zastupuje datové typy UINT32, INT64, DBL, Bool (0 = false, 1 = true) a Command (0 = off, 1 = on) o char valuestring[] - string hodnota atributu. Zahrnuje datové typy String a Enum o Int32 lengthin - očekávaná délka obdrženého stringu (kvůli vyhrazení paměti pro výstupní string char ValueString*+) o return: 1 = nastavení úspěšné 0 = nastavení úspěšné/chyba void GetFPS(double *AcquiredFPS, double *ProcessedFPS) o Zjistí počet snímků za vteřinu ve videu o double *AcquiredFPS - počet snímků získaných z kamery před processingem o double *ProcessedFPS - počet snímků získaných z kamery po processingu void GetVideoResolution(int16_t *ResolutionX, int16_t *ResolutionY) o zjistí aktuální rozlišení videa o int16_t *ResolutionX - pointer na proměnnou typu int16, do se zapíše horizontální rozlišení videa o int16_t *ResolutionY - pointer na proměnnou typu int16, do se zapíše vertikální rozlišení videa 32 Univerzální DLL videoknihovna Workswell s.r.o.

33 Uložení parametrů a automatické načtení v novém Session V některých případech je nutné přenastavit defaultní parametry videohardwaru pro koncovou aplikaci (typicky rozlišení kamery). V případě využití funkcí set se příslušné parametry aplikují přímo na aktuální videohardware, ale již neuloží do vnitřní paměti samotného videohardwaru. Proto v případě odpojení a opětovného zapojení dojde k načtení defaultních hodnot a tedy k přepisu již nastavených parametrů. Pro tyto případy, kdy je potřeba zajistit trvalé nastavení parametrů při opětovném připojení videohardwaru, je k dispozici speciální funkce, která uloží aktuálně nastavené parametry do paměti počítače. Ty jsou následně načteny při opětovném připojení videohardwaru: int8_t SaveCamSettings(void) o Uloží aktuální nastavení všech atributů kamery. Při zavření a novém spuštění session jsou tato nastavení obnovena. o return: 1 = nastavení úspěšné 0 = nastavení úspěšné/chyba Uložení a načtení aktuálního snímku z paměti počítače Základním a nejjednodušším způsobem zachycení aktuálního obrazu z videohardwaru je načtení aktuálního obrazu z videookna do pracovní paměti počítače. K tomuto účelu slouží funkce MakeSnap. void MakeSnap(uint8_t buffer[], int32_t length) o požadavek na vytvoření snímku aktuálního videa do bufferu (pole). Při volání je nutné parametrem length zadat požadovanou délku čteného bufferu. o int32_t length - délka čteného bufferu (vypočítá se jako horizontální vertikální rozlišení 3 (~3 barvy), rozlišení lze rychle získat funkcí GetVideoResolution) o uint8_t buffer - pointer na jednorozměrné pole datového typu byte délky length, ve kterém jsou uložena poslední snímková data. Data jsou v poli uložena po jednotlivých pixelech zleva do prava a dále po jednotlivých řádcích snímku. Každé po sobě jdoucí tři prvky pole odpovídají barevným složkám každého pixelu (R,G,B). Tedy např. pro matici pixelů *1,2;3,4+ bude pole vypadat: {R1,G1,B1,R2,G2,B2,R3,G3,B3,R4,G4,B4}. Nastavení softwarové filtrace obrazu Knihovna SmartVision obsahuje sadu softwarových filtračních algoritmů pomocí, kterých je možno softwarově přepočítat obrazovou informaci. Díky tomu je umožněno přepočítat jasové složky, kontrast, ostrost či provádět barevné transformace. void SetSwBrightness(int8_t nval) o nastavení hodnoty jasu na požadovanou úroveň, rozsah -100 až 100 o nval - hodnota jasu rozsah -100 až 100 Workswell s.r.o. SmartVision SDK 33

34 int8_t GetSwBrightness(void) o získání aktuální hodnoty jasu o return - hodnota jasu rozsah -100 až 100, výchozí hodnota 0 void SetSwContrast(double fval) o nastavení hodnoty kontrastu na požadovanou úroveň, rozsah až o nval - hodnota kontrastu rozsah až double GetSwContrast(void) o získání aktuální hodnoty kontrastu o return - hodnota jasu rozsah až 2.000, výchozí hodnota void SetSwSharpness(int8_t nsharp) o nastavení USM (unsharp mask) doostrostření obrazu na požadovanou úroveň, rozsah 0 až 100 o nsharp - hodnota doostrostření rozsah 0 až 100, výchozí hodnota 0 = doostřování vypnuto int8_t GetSwSharpness(void) o získání aktuální hodnoty doostrostření obrazu o return - hodnota doostrostření obrazu rozsah 0 až 100, výchozí hodnota 0 = doostřování vypnuto void SetSwColorTransformationValueRGB(double fr, double fg, double fb) o nastavení hodnoty násobičů barevných složek obrazu na požadovanou úroveň, rozsah každé složky až o fr - hodnota násobiče červené složky rozsah až o fg - hodnota násobiče zelené složky rozsah až o fb - hodnota násobiče modré složky rozsah až Univerzální DLL videoknihovna Workswell s.r.o.

35 void GetSwColorTransformationValueRGB(double *fr, double *fg, double *fb) o získání hodnot násobičů barevných složek obrazu. Parametry funkce jsou pointery na proměnné typu double, do kterých budou uloženy hodnoty násobičů barevných složek o double *fr - pointer na proměnnou, do které se zapíše hodnota násobiče červené složky, výchozí hodnota o double *fg - pointer na proměnnou, do které se zapíše hodnota násobiče zelené složky, výchozí hodnota o double *fb - pointer na proměnnou, do které se zapíše hodnota násobiče modré složky, výchozí hodnota void SetSwPolynomTransformation(double fconstx3, double fconstx2, double fconstx1, double fconstx0) o nastavení hodnot parametrů pro transformaci intenzit pixelů obrazu. Parametry zastupují jednotlivé koeficienty polynomu 3. řádu. o double fconstx3 - hodnota koeficientu třetího řádu rozsah - plný rozsah proměnné typu double precision float o double fconstx2 - hodnota koeficientu druhého řádu rozsah - plný rozsah proměnné typu double precision float o double fconstx1 - hodnota koeficientu prvního řádu rozsah - plný rozsah proměnné typu double precision float o double fconstx0 - hodnota koeficientu nultého řádu rozsah - plný rozsah proměnné typu double precision float Workswell s.r.o. SmartVision SDK 35

36 void GetSwPolynomTransformation(double *fconstx3, double *fconstx2, double *fconstx1, double *fconstx0) o získání hodnot parametrů pro transformaci intenzit pixelů obrazu. Parametry zastupují jednotlivé koeficienty polynomu 3. řádu. Parametry funkce jsou pointery na proměnné typu double, do kterých budou uloženy hodnoty koeficientů. o double *fconstx3 - pointer na proměnnou, do které se zapíše hodnota koeficientu třetího řádu rozsah - plný rozsah proměnné typu double precision float výchozí hodnota = 0 o double *fconstx2 - pointer na proměnnou, do které se zapíše hodnota koeficientu druhého řádu rozsah - plný rozsah proměnné typu double precision float výchozí hodnota = 0 o double *fconstx1 - pointer na proměnnou, do které se zapíše hodnota koeficientu prvního řádu rozsah - plný rozsah proměnné typu double precision float výchozí hodnota = 1 o double *fconstx0 - pointer na proměnnou, do které se zapíše hodnota koeficientu nultého řádu rozsah - plný rozsah proměnné typu double precision float výchozí hodnota = 0 Ovládání digitální stabilizace obrazu Některé aplikace pro zpracování obrazu jsou značně zatíženy nestabilitou obrazové scény. Například jako jsou vibrace automobilu či rotace ramena, na kterém je kamerový systém připevněn. K odstranění a zlepšení stability obrazové scény lze použít speciální algoritmus digitální stabilizace. Ten pomocí korelačních funkcí a sledování pohybu obrazové scény dokáže výrazně zlepšit výsledný obraz. void StabON() o zapnutí stabilizace void StabOFF() o vypnutí stabilizace 36 Univerzální DLL videoknihovna Workswell s.r.o.

37 void StabSetup(uint16_t xresolution, uint16_t sensitivity, uint8_t angle, uint8_t corrrotation, uint8_t interpolate) o nastavení pokročilých parametrů stabilizace o uint16_t xresolution - rozlišení použité pro subsampling obrazu, který je použit pro stabilizaci. Nižší xresolution znamená zrychlení algoritmu stabilizace a snížení výpočetní náročnosti za cenu ztráty detailů použitých k rozlišení oblasti pro stabilizaci. Zadává se pouze horizontální rozlišení, vertikální je dopočítáno tak, aby byl dodžen poměr stran vstupního obrazu. Při změně rozlišení je automaticky stabilizace vypnuta a je nutné ji znovu zapnout fcí StabON(). rozsah = , výchozí hodnota = 1024 o uint16_t sensitivity - citlivost vyhledávání oblasti pro stabilizaci v obrazu. Vyšší citlivost znamená více tolerantní algoritmus stabilizace, ovšem za cenu možnosti zachytit falešnou oblast používanou pro stabilizaci. Nižší citlivost je přísnější ve vyhledávání oblasti v obraze. rozsah = 0-100, výchozí hodnota = 20 o uint8_t angle - nastavení možnosti rotace oblasti používané pro stabilizaci. Zásadně ovlivňuje výpočetní náročnost stabilizace. rozsah = 0-180, výchozí hodnota = 4 o uint8_t corrrotation - zapnutí/vypnutí stabilizace rotace kamery. Má zásadní vliv na výpočetní náročnost stabilizace. 1 = zapnuto, 0 = vypnuto, výchozí hodnota = 0 o uint8_t interpolate - zapnutí/vypnutí interpolace výstupního obrazu při zapnuté stabilizaci rotace kamery. Opět má velký vliv na výpočetní náročnost stabilizace. 1 = zapnuto, 0 = vypnuto, výchozí hodnota = 0 void StabShowOrigVideo(uint8_t showorigvideo) o demonstrační funkce, která otevře přídavné okno s nestabilizovaným obrazem (pro porovnání stabilizovaného a nestabilizovaného videa) o uint8_t showorigvideo - otevře/zavře okno s nestabilizovaným obrazem 1 = zapnuto, 0 = vypnuto, výchozí hodnota = 0 Workswell s.r.o. SmartVision SDK 37

38 Získání pointeru na blok paměti s aktuálním nezpracovaným snímkem z kamery Pro přístup k aktuálním nezměněným obrazovým datům z kamery lze použít funkci GetRawImagePointer. Tato funkce vrátí pointer na blok paměti, kde je uložen aktuální nezpracovaný snímek z kamery. Jednorozměrné pole bytů v paměti obsahuje čistá obrazová data snímku. Formát dat odpovídá datovému typu obrazu. Pro rekonstrukci obrazu je nutné znát další návratové parametry funkce GetRawImagePointer. První řádek snímku zrekonstruujeme takto: začneme u PixelPointerOut a pokračujeme po blocích odpovídajících velikosti PixelSize až do XResolution (poslední pixel prvního řádku. První pixel druhého řádku získáme takto: PixelPointerOut + LineWidth a opět můžeme postupovat po blocích velikosti PixelSize. Takto postupujeme po řádcích až do YResolution (vertikální rozlišní = index posledního řádku). Černobílý snímek datového typu Mono8 má 8-bitovou hodnotu každého pixelu uloženou v jednom bytu. Každý byte pole z paměti tedy odpovídá jednomu pixelu. Radiometrický snímek datového typu Mono16 má 16-bitovou hodnotu každého pixelu uloženou ve dvou bytech. Hodnota pixelu potom odpovídá dvěma po sobě jdoucím bytům pole z paměti. Barevný snímek typu RGB32 má 32-bitovou hodnotu každého pixelu uloženou ve čtyřech bytech. Hodnota pixelu potom odpovídá čtyřem po sobě jdoucím bytům pole z paměti, přičemž první, druhý a třetí odpovídají červené, zelené a modré složce pixelu a čtvrtý byte je nulový. int8_t GetRawImagePointer(uint64_t *PixelPointerOut, int32_t *BufferSize, int32_t *PixelSize, int32_t *LineWidth, int32_t *XResolution, int32_t *YResolution) o uint64_t PixelPointerOut - pointer na první pixel snímku v paměti (ve snímku vlevo nahoře) o int32_t PixelSize - počet bytů obsahujících hodnotu jednoho pixelu o int32_t BufferSize - celkový počet bytů snímku v paměti o int32_t LineWidth - délka jednoho řádku snímku v paměti (včetně pomocných obrazových pixelů) o int32_t XResolution - skutečné horizontální rozlišení snímku o int32_t YResolution - skutečné vertikální rozlišení snímku 38 Univerzální DLL videoknihovna Workswell s.r.o.

39 Získání pointeru na blok paměti s aktuálním zpracovaným snímkem z kamery Pro přístup k aktuálním zpracovaným obrazovým datům z kamery lze použít funkci GetOutImagePointer. Tato funkce vrátí pointer na blok paměti, kde je uložen aktuální zpracovaný snímek z kamery (tedy snímek po průchodu softwarovými filtry, stabilizací, apod.). Funkce funguje totožně jako funkce GetRawImagePointer, bližší popis je tedy stejný (viz výše). int8_t GetOutImagePointer(uint64_t *PixelPointerOut, int32_t *BufferSize, int32_t *PixelSize, int32_t *LineWidth, int32_t *XResolution, int32_t *YResolution) o uint64_t PixelPointerOut - pointer na první pixel snímku v paměti (ve snímku vlevo nahoře) o int32_t PixelSize - počet bytů obsahujících hodnotu jednoho pixelu o int32_t BufferSize - celkový počet bytů snímku v paměti o int32_t LineWidth - délka jednoho řádku snímku v paměti (včetně pomocných obrazových pixelů) o int32_t XResolution - skutečné horizontální rozlišení snímku o int32_t YResolution - skutečné vertikální rozlišení snímku Workswell s.r.o. SmartVision SDK 39

40 12 Tutoriál pro vývoj v jazyce C# Testovací aplikace Readme.txt Součástí balíku SmartVision SDK je také demonstrační aplikace v jazyce C#, která ukazuje jednoznačné využití všech DLL funkcí a vyčtení videodat. Principiálně je přístup, ovládání a čtení velmi podobné ať už se jedná o jazyk C, C++ či jiné standardní textové jazyky podporující import a přístup na DLL knihovny. V textovém souboru readme naleznete instrukce, kde nakopírovat příslušné DLL knihovny a jak s nimi manipulovat. V případě dotazů prosím postupujte dle instrukcí z kapitoly Nápověda a dotazy. 40 Univerzální DLL videoknihovna Workswell s.r.o.