test_itifg(1)

NAME
test_itifg, swtrig_itifg, extime_itifg, ioport_itifg, config_pcdig - Test- und Hilfsprogramme zum itifg(4) Gerätetreiber für Linux

ÜBERSICHT
test_itifg [-# Programmanzahl] [-a Aufnahmemodus] [-b Kartenindex] [-c Kameranummer] [-d Farbtiefe] [-e] [-f Konfigurationsdatei] [-g Graustufen] [-i] [-k] [-l] [-m] [-n Pufferanzahl] [-o Zugriffsmodus] [-r Bildrate] [-s Synchronisationsart] [-t Bildanzahl] [-v] [-z Verkleinerung] [Dateiname bei Bildspeicherung]

swtrig_itifg [-b Kartenindex] [-k]

extime_itifg [-b Kartenindex] [-e Belichtungszeit] [-m Kameramodus]

ioport_itifg [-b Kartenindex] [-t Wiederholzeit] [-w Ausgabewert]

config_pcdig [-b Kartenindex] [-d Bildtiefe] [-t Kanalanzahl] [-r] [Konfigurationsdatei]

BESCHREIBUNG
Diese Handbuchseite hat in Kern das Testprogramm test_itifg mit den verschiedenen Hilfsprogrammen swtrig_itifg, extime_itifg, ioport_itifg und dem Konfigurationsprogramm config_pcdig zum Inhalt. All diese Programme sollen dem Anwender zeigen, was für spezielle Möglichkeiten der ITI-FG Gerätetreiber bietet und wie diese sinnvoll zu nutzen, bzw. zu programmieren sind.
Die Programme swtrig_itifg und extime_itifg haben dabei direkt auf das von test_itifg angezeigte Videobild Einfluß, während ioport_itifg zur Ansteuerung der als völlig eigenständiges Gerät zu wertenden Eingabe-/Ausgabe- Kanäle auf der Karte und config_pcdig als Hilfsmittel zur initialen Konfiguration des PCDig (meistens während des Systemstarts) zu werten sind.
Ist einmal eine Bildaufnahme angestartet, so kann mittels swtrig_itifg per Software-Trigger das angezeigte Bild aktualisiert werden. Handelt es sich bei dem verwandten Aufnahmemodul zusätzlich um ein AM-DIG oder ein PCDig, kann zusätzlich die Belichtungszeit (und der Arbeitsmodus) der Kamera mit Hilfe von extime_itifg gesteuert werden. Beides ist natürlich nur möglich, wenn test_itifg mit den entsprechenden Optionen gestartet wurde und die verwandte Konfigurationsdatei die richtigen Einträge enthält.

OPTIONEN

  gemeinsame OPTIONEN

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    Hier kann ein Wert zwischen 0 und 7 ( angegeben werden, welcher bei mehreren im Rechner befindlichen Bildverarbeitungskarten die entsprechende auswählt. Standardmäßig wird beim Fehlen dieser Option auf Karte 0 zurückgegriffen. Ob die Durchnummerierung der Karten jeweils von links oder von rechts beginnt, ist vom installierten BIOS des Rechners abhängig und bei manchen Produkten auch einstellbar. Generell muß beachtet werden, daß bei der Erkennung (und Numerierung) der Karten zuerst alle IC-PCI's und danach alle PCDig's erkannt werden.

-?  Es wird eine Kurzbeschreibung der Programmoptionen ausgegeben.

  test_itifg OPTIONEN

-#  Anzahl der zu startenden Programme.
    Sind in einem Rechner mehrere Bildverarbeitungskarten installiert, besteht oft der Wunsch, von allen angeschlossenen Kameras ein Bild zu bekommen. Mit diesem Parameter wird die Anzahl der zu erzeugenden identischen Kopien des test_itifg Programms angegeben.
    Sollen spezielle Kommandozeilenparameter an eine der Kopien übergeben werden, müssen diese mehrfach und in entsprechender Reihenfolge angegeben werden. Automatisch wird nur der Kartenindex pro Programminstanz um eins erhöht.

-a  Spezielle Art der Aufnahme.
    Diese Option ist für zukünftige Erweiterungen reserviert. Im Einzelnen ist dabei an eine Einfache Umschaltung zwischen unsynchronisierter und getriggerter Aufnahme gedacht.

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    siehe gemeinsame OPTIONEN

-c  Nummer der zu verwendenden Kamera.
    Da das AM-VS Aufnahmemodul und das PCVision den Anschluß mehrerer analoger Kameras mittels Eingangsmultiplexers ermöglichen, kann beim Einsatz dieser auch eine andere Kamera als 0 (Standardwert) ausgewählt werden. Grenzen dieses Parameters sind also bei allen ‘analogen’ Bildverarbeitungskarten 0 bis 3, während bei den ‘digitalen’ nur Kamera 0 gültig, und damit diese Option unnütz ist.

-d  Farbtiefe (in bit) der angeschlossenen Kamera.
    Wenn die genutzte Kamera nicht 8 bit Farbtiefe hat, dann muß diese spezifiziert werden. Dies trifft insbesondere für die digitalen Module zu, wo sowohl Kameras mit 10, 12, 14 oder 16 Bit angeschlossen werden können. Wenn solch eine Kamera in Gebrauch ist, man gibt aber auf der Kommandozeile nichts oder [-b 8] an, erfolgt ein Rückrechen der Bitwerte auf 8 Bit.

-e  Da meistens Bildaufnahme und Anzeige (schon aus Geschwindigkeitsgründen) auf ein und demselben Rechner erfolgen, kann durch Nutzung der vom X-Windows System zur Verfügung gestellten Shared Memory Erweiterung die Bildanzeigerate erheblich gesteigert werden, da eine Kopieroperation entfällt.
    Arbeitet man nicht lokal oder möchte zu Vergleichszwecken diese Erweiterung nicht nutzen, schaltet diese Option den Modus aus.

-f  Name der Kamera-Konfigurationsdatei.
    Zu jeder Kamera muß eine entsprechende Datei mit Konfigurationsinformationen zur Verfügung gestellt werden. Diese kann sowohl absolut als auch relativ spezifiziert werden. Bei Angabe eines relativen Pfades wird nur das Verzeichnis INSTALL_PREFIX/itifg/conffiles durchsucht. INSTALL_PREFIX ist vor der Installation im Makefile auszuwählen, der Standardpfad ist /usr/local/share/itifg/conffiles. Wird diese Option weggelassen, wird versucht die Datei ‘programmname’. cam im o.g. Verzeichnis zu öffnen.

        WENN DIE OPTION [ -m ] GESETZT IST, IST ZU BEACHTEN, DASS DIE
        KONFIGURATIONSDATEI AN DIE BEI DEN OPTIONEN [ -b ] UND [ -c ]
        ANGEGEBENEN  PARAMETER UND DEN ENTSPRECHEND AUF DER KARTE
        INSTALLIERTEN MODULTYP ANGEPASST SEIN MUSS!

-g  Graustufen im Anzeigebild.
    Bei 8 Bit X-Servern ist es nicht sinnvoll, alle 256 Graustufen einer 8 Bit Kamera darstellen zu wollen, da somit keine freien Farbzellen für andere Anwendungen (den Fenster-Manager o.ä.) übrig bleiben, oder schon belegt sind. Im letzteren Falle würde das Anstarten des Testprogrammes sogar scheitern.
    Diese Option ermöglicht es, ohne größere Einbußen in der Anzeigequalität mehrere Graustufen der Kamera auf einen Grauwert in der Anzeige abzubilden. Neben dem Standardwert von 64 können Werte von 8 bis 256 (nur Potenzen von 2) ausgewählt werden.
    Bei 16 Bit Servern werden sowieso nur 32 Grauwerte angezeigt (5 Bit für jede Farbe) und bei 24/32 Bit Servern wäre diese Option unsinnig, gilt aber trotzdem.

-i  Mit diesem Parameter wird erzwungen, daß ein Bild nur abgespeichert und nicht angezeigt wird. Das macht nur Sinn, wenn die Leistungsfähigkeit des Rechners nicht ausreicht. Um zusätzlich zur Anzeige auch abspeichern zu können, bitte den Schalter [-v] nutzen. [-k] Falls das Abspeichern von Bildern aufgrund er Anzeige dieser entschieden werden soll, kann mit dieser Option eine speichern/verwerfen/beenden Auswahl nach jedem Bildzyklus eingeschaltet werden.

-l  Befindet man sich in der Speicherzugriffsart ‘read’ (Standard), kann entschieden werden, ob der für den Transfer bereitgestellte Speicher vom Anwendungsprogramm per mlock(2) gelockt wird, oder ob dies der Treiber selbst für jeden Aufruf übernimmt. Letztere Variante ist zeitintensiver. Die erste Variante benötigt root Rechte.

-m  Falls gewünscht ist, daß nur auf die mit [-f] angegebene Kamera und Kartenkonfiguration zugegriffen werden soll, kann dies mit dieser Option erzwungen werden.

-n  Anzahl der im Speicher anzulegenden Puffer.
    Ist wichtigstes Ziel bei der Bildaufnahme, daß in einem Aufnahmezyklus kein Bild ausgelassen wird, faßt man diesen zu einer einzigen Aufnahme in mehrere Puffer zusammen. Dies gilt für die Speicherzugriffsart ‘read’. Im Gegensatz dazu ergibt sich im ‘mmap’ Modus durch das kontinuierliche füllen der Puffer eine Art Ringspeicher, in dem eine Auswertung ohne Zeitverzögerung möglich ist.

-o  Abkürzung der anzuwendenden Aufnahmeart.
    Es gibt - begründet durch Konventionen, die Linux (*NIX) dem Gerätetreiber-Programmierer durch die Systemaufruf-Schnittstelle auferlegt - verschiedene Möglichkeiten, wie der Benutzer letztendlich an sein Bild gelangt. Es muß dabei ein Kompromiß zwischen Geschwindigkeit, Aufwand und Einhaltung Schnittstelle gefunden werden. Die folgende Auflistung nennt die zur Verfügung stehenden Aufnahmearten und beschreibt ihr Einsatzgebiet und deren Vor- und Nachteile.

    read:
        Hier erfolgt die gesamte Bildaufnahme über den Systemaufruf read(2) Dabei legt der Benutzer einen Speicherbereich an und veranlaßt den Treiber, diesen mit Bilddaten zu füllen. Sinnvoll ist dieser Aufruf besonders dann, wenn verschiedene Bilder in verschiedene Speicherbereiche zu späteren Verarbeitung direkt kopiert werden sollen. Standardmäßig ist dieser Aufruf blockierend , was auch benutzt werden sollte. Zwar ist auch ein setzten von O_NONBLOCK möglich, worauf aber verzichtet werden sollte, solange das Betriebssystem noch keine asynchrone Ein-/Ausgabe direkt unterstützt.
        Dies ist der Standardmodus.

    mmap:
        Falls nun ein Gegensatz zur vorherigen Zugriffsart ein dauernder Transfer in ein- und denselben Bereich gewünscht ist, kann man die dauernde Neudefinition des Zielbereiches umgehen. Man tut dies, indem man den Treiber im Kernsegment einen Speicherbereich anlegen und füllen läßt. Das Anlegen erfolgt dabei mittels mmap(2). Einen kontinuierlichen Datentransfer startet man mit dem ioctl(2) Aufruf GE_SET_START (siehe auch itifg_ioctl(4)). Da bei dieser Methode keine direkte Synchronisation gegeben ist, muß ein Verfahren mittels signal(2) oder select(2) / poll(2) genutzt werden. Siehe dazu auch Option [-s.]

-p  Bildwiederholrate der Kamera.
    Sämtlichen Aufnahme- [-o] und Synchronisations- [-s] Arten ist gemein, daß sie die Bildaufnahme bei Nichtvorhandensein des Kamerasignales nach einer bestimmten Zeit abbrechen und eine entsprechende Fehlermeldung geben. Die Dauer bis zur Zeitüberschreitung wird direkt durch diesen Parameter beeinflußt, ein Standardwert von 1 Bild/Sekunde ist vorgegeben. Kennt man die Bildrate der Kamera nicht, ist man mit diesem Standard gut beraten, da durch eine Verringerung des Wertes kein ernsthaftes Problem, nur eine Verlängerung der Wartezeiten auftritt. Will man aber eine genaue Überprüfung des Kamerasignales auf Unregelmäßigkeiten (z.B. bei verrauschten analogen Signalen) erreichen, sollte man schon genau spezifizieren.

-s  Abkürzung der Art der Synchronisation zum nächsten Bild
    Im allgemeinen ist jedes Anzeige- und Auswerte-Programm darauf angewiesen, daß es weiß, wann ein neues Bild angekommen ist, und es wieder in Aktion treten muß. Man sollte es tunlichst vermeiden, dies mit einer Art ständiger Abfrage (des Bildinhaltes) oder einer anderen Art von aktivem Warten ermitteln zu wollen, das andere Benutzer (oder Prozesse) die Rechenleistung des Prozessors möglicherweise sinnvollen nutzen könnten.
    Bei der Zugriffsart im [-o read] Modus ist die Art der Synchronisation schon implizit durch ein Blockieren des Systemaufrufs vorgegeben. Der Benutzer muß also keine eigenen Anstrengungen zur Synchronisation unternehmen, sein Programm läuft nur, wenn auch Daten zur Verfügung stehen.
    Bei einem Zugriff mittels [-o mmap] muß man dagegen selber in Aktion treten, da die Bildaufnahmekarte in einen kontinuierlichen Modus geschaltet wird. Die im Folgenden genannten Möglichkeiten orientieren sich dabei direkt an den ihnen zugrunde liegenden Systemaufrufen.

    signal:
        Nach erfolgreicher Aufnahme eines Bildes wird dem Benutzer ein Signal (SIGIO) gesendet. Dieses muß auch abgefangen werden, da die Standard-Aktion zu SIGIO die Beendigung des entsprechenden Programms ist.
        Um nun dem Gerätetreiber mitzuteilen, daß man an der Auslieferung von SIGIO interessiert ist, muß man ihm dies mit fcntl(2) mitteilen.

    select:
        Der select(2) Systemruf wurde im BSD-UNIX eingeführt, um auf mehreren Dateideskriptoren gleichzeitig auf Ereignisse (Eingabe - Ausgabe - Ausnahmesituationen) warten zu können. Zusätzlich zu dieser Funktionalität kann auch noch eine Zeitbegrenzung des Wartens spezifiziert werden. Vorteil von select(2) im Zusammenhang mit dem X-Windows System ist, daß sich das Gerät, welches die Bildverarbeitungskarte repräsentiert elegant als zusätzlicher Eingabekanal in die Hauptschleife Ereignisbehandlung einfügen läßt.

    poll:
        poll(2) ist das SYSV-UNIX Pendant zu select(2) und tut überblicksmäßig dasselbe bei leicht geänderten Aufruf-Parametern.

-t  Anzahl der zu verarbeitenden Bilder.
    Werden Bilder neben der Anzeige mit abgespeichert [-v] , kann eine Angabe der Bildanzahl sinnvoll sein. Auch ein Abbruch nach einer bestimmten Zeit ist mit dieser Option denkbar. Als Standardwert ist keine Begrenzung der Anzahl vorgesehen.

-v  Wird ein Abspeichern der Bilder gewünscht, muß dies mit dieser Option angegeben werden. Der Start des Speicherns erfolgt allerdings erst, wenn das Programm ein SIGQUIT (allgemein ^\) empfangen hat. Dies ermöglicht einen Beginn der Speichersequenz anhand des aktuellen Live-Bildes.
    Wird ein spezieller Dateiname zum Speichern der Bilder gewünscht, kann dieser ohne Option am Ende der Kommandozeile angegeben werden. Weiterhin werden Bildfolgen durchnumeriert und Bilder aus Aufnahmefolgen [-n] und Mehrfachprogrammanwendungen [-#] automatisch gekennzeichnet.

-z  Faktor der Bildverkleinerung bei Bus Master Transfer.
    Eine der erweiterten Funktionalitäten der IC-PCI Bildverarbeitungskarten der Serie II und aller PCDig's ist es, während des Bus-Master Transfers das Bild verkleinern zu können. Dies eignet ich insbesondere zur komfortableren Anzeige des Videobildes.
    Dabei lassen sich nur die Werte 1, 2, 4, eingeschränkt 8 und 16 (letzterer nur beim PCDig) angeben. Um keine Inkonsistenzen beim Einsatz von älteren IC-PCI Karten hervorzurufen, ist der Standardwert dieser Option 1 (keine Verkleinerung).

Dateiname bei Bildspeicherung.
    Wird eine der Optionen [-i] [-v] gewählt, können auch Bilder abgespeichert werden. Der Stamm des Dateinamens zur Bildspeicherung wird hierbei ohne Option angegeben. test_itifg erweitert diesen Namensstamm noch dahingehend, daß eine Programm- und Sequenz-, bzw. Untersequenznummer verwendet werden.

  swtrig_itifg OPTIONEN

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    siehe gemeinsame OPTIONEN

-k  Mit dieser Option kann erzwungen werden, daß vor dem Triggern per Software auf einen Tastendruck gewartet wird. Ohne diese Option triggert das Programm sofort und beendet sich dann.

  extime_itifg OPTIONEN

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    siehe gemeinsame OPTIONEN

-e  Belichtungszeit in μ s.
    Soll die Belichtungszeit nicht interaktiv, sondern einmalig gesetzt werden, (z.B. in Shell-Skripten), ist diese Option anzuwenden.

-m  Kameramodus.
    Hat die angeschlossene Kamera TTL-Eingänge zum Steuern verschiedener Funktionen (meistens Binning oder Anheben der Verstärkung) und sind diese mit den Kamerakontrollausgängen am Stecker der BV-Karte verbunden, kann man so den Arbeitsmodus der Kamera beeinflussen.

interaktiver Modus.
    Ohne Angabe einer festen Belichtungszeit [-e] geht das Programm nach der Initialisierung in einen Modus zum interaktiven Einstellen der Belichtungszeit über. In diesem haben folgende Tasten eine Bedeutung:

    q | Programm beenden
    < > | minimalen, bzw. maximalen Wert anwählen
    + - | um einen Schritt verlängern, bzw. verkürzen
    0-6 | grobe Vorwahl des Bereiches

  ioport_itifg OPTIONEN

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    siehe gemeinsame OPTIONEN

-t  Wiederholzeit der Abfrage
    Es bestehen zwei Möglichkeiten zum Einlesen der Werte vom Eingabekanal: ereignisgesteuert und im Abfragebetrieb. Ereignisgesteuert wird dabei mit der speziellen Abfragezeit ‘0’ spezifiziert. Dazu muß natürlich das Ereignis am Interrupt und Strobe Pin anliegen. Alle anderen Werte geben die Zeit zwischen zwei aufeinanderfolgenden Abfragen an.

-w  Wert zur Ausgabe
    Soll nicht vom Eingabekanal gelesen, sondern ein Wert am Ausgabekanal gesetzt werden, ist er so zu spezifizieren. Beide Aktionen schließen sich aus, es kann also entweder eingelesen (Standardaktion) oder ausgegeben werden.

  config_pcdig OPTIONEN

-b  Nummer (Index) der entsprechenden Einsteckkarte.
    siehe gemeinsame OPTIONEN
    Ohne eine Angabe der Nummer der Einsteckkarte wird auf allen Karten probiert, ob es sich um ein PCDig handelt und danach die FPGA Konfigurationsdatei heruntergeladen.

-d  Bittiefe der Kamera
    Es können hier Werte von 8 (Standard), 16, 24 oder 32 angegeben werden.

-t  Datenkanäle der Kamera
    Es werden Kameras mit 1 bis 4 Datenkanälen unterstützt. Zu beachten ist, daß dies nur für 8 bit Kameras gilt. Bei 16 bit Kameras sind nur noch 2 Kanäle möglich. Bei 24 oder 32 bit gar nur noch ein Kanal.

-r  Da über die Konfigurationsdatei auch eingestellt wird, bei welcher Taktflanke das Datensignal gültig ist, besteht hiermit die Möglichkeit, gegenüber der fallenden Flanke (Standard) auch die steigende Flanke auszuwählen.

Konfigurationsdatei
    Wird die zu nutzende Konfigurationsdatei nicht implizit über Bittiefe, Datenkanäle und Taktflanke ausgewählt, kann auch explizit ein Dateiname angegeben werden. Wird dieser ohne Pfand spezifiziert, wird immer im Standardverzeichnis danach gesucht. INSTALL_PREFIX ist vor der Installation im Makefile zu setzen. Konfigurationsdateien sind im Allgemeinen an der Endung .exo zu erkennen.