write_image — Schreiben von Bildern in Graphikformaten.
write_image gibt das angegebene Bild (Image) in
verschiedenen Bildformaten in Dateien aus. Falls die Domäne im gewünschten
Format nicht abgespeichert werden kann (das ist der Fall bei
'bmp', 'jpeg' und 'ima'), erhalten die Pixel außerhalb der Region die durch FillColor definierte Farbe. Für Grauwertbilder muss ein Wert
zwischen 0 (Schwarz) und 255 (Weiß) angegeben werden, bei Farbbildern
können direkt die RGB-Werte angegeben werden, z.B. hexadezimal: 0xffff00
fuer einen gelben Hintergrund (Rot=255, Grün=255, Blau=0).
Derzeit werden folgende Formate unterstützt:
Alle in HALCON definierten Pixeltypen werden unterstützt. Bildobjekttupel mit bis zu 65535 Bildobjekten mit 65535 Kanälen können abgespeichert werden. Bildobjekte mit Kanälen gemischten Pixeltyps können abgespeichert werden.
Komprimierung ist möglich mit| 'deflate [num]': | Adobe-Deflate-Komprimierung (verlustfrei) |
| 'jpeg [num]': | JPEG (verlustbehaftet) |
| 'lzw': | LZW (verlustfrei) |
| 'packbits': | PackBits (verlustfrei) |
'[num]' bedeutet hier eine optionale Angabe der Komprimierung. Bei 'deflate' kann eine Zahl zwischen 0 (keine Komprimierung) und 9 (maximale Komprimierung) angegeben werden. Bei 'jpeg' kann eine Zahl zwischen 0 und 100 angegeben werden. Die Semantik ist identisch mit der unten bei 'jpeg' beschriebenen Semantik. 'jpeg' kann nur bei Bildern vom Typ byte oder int1 verwendet werden. Außerdem können nur Bilder mit höchstens vier Kanälen geschrieben werden.
Abspeichern der Region jedes Bildobjektes ist in komprimierter Form über 'mask' (Standardeinstellung) oder als Alphakanal über 'alpha' möglich. Die Region wird nur abgespeichert, falls sie nicht das gesamte Bild umfasst. Die gleichzeitige Wahl von 'jpeg' und 'alpha' ist nicht möglich, da durch die verlustbehaftete Komprimierung die Region nicht mehr korrekt rekonstruiert werden könnte. Die Optionen können durch Leerzeichen getrennt aneinander gefügt werden.
Beispiele:| 'tiff deflate 9': | Maximale Adobe-Deflate-Komprimierung, |
| die Region wird falls nötig als Maskenbild abgespeichert | |
| 'tiff jpeg 90': | JPEG-Komprimierung mit hoher Qualität, |
| die Region wird falls nötig als Maskenbild abgespeichert | |
| 'tiff lzw alpha': | LZW-Komprimierung, |
| die Region wird falls nötig als Alpha-Kanal abgespeichert | |
| 'tiff' oder 'tiff none' | Keine Komprimierung, |
| die Region wird falls nötig als Maskenbild abgespeichert |
Es ist zu beachten, dass 'bigtiff' TIFF-Dateien bezeichnet, die größer als 4 GB sein können, während 'tiff' TIFF-Dateien bezeichnet, die maximal 4 GB groß sein können. Die Dateigröße hängt von der Bildgröße und der verwendeten Kompression ab. Deshalb sollte 'bigtiff' verwendet werden, falls die Möglichkeit besteht, dass die komprimierte Datei größer als 4 GB wird.
Dieses Format kann nur Bilder mit einem Kanal (Grauwertbilder) oder mit drei Kanälen (RGB-Farbbilder) speichern.
Für dieses Format werden nur Bilder mit dem Pixeltyp byte unterstützt.
Zusammen mit dem Format kann ein Qualitätsmaß angeben werden, das die Komprimierungsrate und die Qualität des gespeicherten Bildes bestimmt. Große Werte (Maximum 100) erzeugen eine relativ große Datei mit hoher Qualität, bei kleine Werten nimmt die Qualität und die Dateigröße deutlich ab. Beispiel: 'jpeg 30'.
Dieses Format kann nur Bilder mit einem Kanal (Grauwertbilder) oder mit drei Kanälen (RGB-Farbbilder) speichern.
Für dieses Format werden nur Bilder mit dem Pixeltyp byte unterstützt.
Achtung: Bilder, die zu einem späteren Zeitpunkt noch ausgewertet werden müssen, sollten aufgrund der Verluste nicht im JPEG-Format abgespeichert werden!
Zusammen mit dem Format kann ein Maß angegeben werden, welches die Komprimierungsrate und damit die Qualität des gespeicherten Bildes bestimmt (z.B. 'jp2 40'). Der angegebene Wert entspricht ungefähr dem Verhältnis der Größe des komprimierten Bildes zur Größe des unkomprimierten Bildes (in Prozent). Da JPEG-2000 ohnehin stark komprimiert, haben erst kleinere Werte (typischerweise unter 50) Einfluss auf die Dateigröße. Wenn kein Wert angegeben wird (und nur dann), wird das Bild verlustfrei komprimiert.
Das zu speichernde Bild kann beliebig viele Kanäle enthalten. Als Typen sind byte, cyclic, direction, int1, uint2, int2 und int4 zugelassen, wobei im Falle von int4 nur eine Farbtiefe von 24 Bit möglich ist (wird diese überschritten, wird eine Fehlerbehandlung ausgelöst). Falls ein Bild mit eingeschränktem Definitionsbereich übergeben wird, wird die Region als Alphakanal mit einer Farbtiefe von einem Bit abgespeichert.
Die Kodierung eines Bildes ins JPEG-2000 Format benötigt sehr viel Speicher. Es wird deshalb empfohlen, für große Bilder ein anderes Format (z.B. 'tiff') zu verwenden. Die maximal unterstüzte Bildgröße (Breite x Höhe) für JPEG-2000 beträgt auch in HALCON-XL.
Zusammen mit dem Format kann ein Maß angegeben werden, welches die Komprimierungsrate und damit die Qualität des gespeicherten Bildes bestimmt (z.B. 'jpegxr 30' oder 'jpegxr 100' bzw. 'jpegxr' für verlustfreie Komprimierung). Alle HALCON-Bildtypen außer int8 werden unterstützt. Es können Bildobjekttupel mit einer beliebigen Anzahl von Bildobjekten geschrieben werden. Bilder können bis zu 8 Kanäle aufweisen. Im Falle von int4 und float Bildern wird die numerische Genauigkeit auf 24 Bit eingeschränkt. Dies kann zu Verlusten führen unabhängig von der Einstellung für die Qualität. Wird ein Bild mit eingeschränktem Definitionsbereich geschrieben, wird die Region verlustfrei als 1-bit Alphakanal gespeichert. Die Bildtypen complex, vector_field und Zweikanalbilder werden mit einem leeren dritten Kanal abgespeichert.
Es ist zu beachten, dass Bilder, unabhängig vom Zielverzeichnis, nicht im JPEG-XR gespeichert werden können, falls keine Schreibrechte für das aktuelle Arbeitsverzeichnis vorliegen.
Zusammen mit dem Format kann ein Komprimierungsgrad zwischen 0 und 9 angegeben werden, wobei 0 keiner Komprimierung und 9 der bestmöglichen Komprimierung entspricht. Alternativ kann die Komprimierung über folgende Konstanten ausgewählt werden: 'best', 'fastest' und 'none'. Korrekte Formatparameter sind also z.B. 'png', 'png 7' und 'png none'.
In PNG-Dateien können Bilder vom Typ byte und uint2 abgespeichert werden. Falls ein Bild mit eingeschränktem Definitionsbereich übergeben wird, wird die Region als Alpha-Kanal abgespeichert, wobei die Punkte innerhalb des Definitionsbereichs mit dem maximalen Grauwert des Eingabebildtyps abgespeichert werden und die Punkte außerhalb des Definitionsbereichs mit dem Grauwert 0. Falls ein Bild mit vollem Definitionsbereich übergeben wird, wird kein Alpha-Kanal abgespeichert.
Dieses Format kann nur Bilder mit einem Kanal (Grauwertbilder) oder mit drei Kanälen (Farbbilder) speichern. Die maximal unterstüzte Bildgröße (Breite x Höhe) für PNG beträgt auch in HALCON-XL.
Alle HALCON-Bildtypen werden unterstützt. Die Beschreibung des Operators
write_object enthält weitere Informationen über das HOBJ-Format.
Diese Format gilt als veraltet, und es sollte stattdessen das HOBJ-Format verwendet werden. Die Daten werden binär und zeilensequentiell (ohne Header oder Zeilentrenner) geschrieben. Die Größe des Bildes und der Pixeltyp wird in der Beschreibungsdatei 'FileName.exp' abgelegt. Alle HALCON-Pixeltypen außer 'complex' und 'vector_field' können geschrieben werden. Es können nur einkanalige Bilder gespeichert werden.
Image (input_object) (multichannel-)image(-array) → object (byte / direction / cyclic / int1 / complex / int2 / uint2 / vector_field / int4 / int8 / real)
Zu speichernde Bilder.
Format (input_control) string → (string)
Graphikformat.
Defaultwert: 'tiff'
Wertevorschläge: 'tiff', 'tiff mask', 'tiff alpha', 'tiff deflate 9', 'tiff deflate 9 alpha', 'tiff jpeg 90', 'tiff lzw', 'tiff lzw alpha ', 'tiff packbits', 'bigtiff', 'bigtiff mask', 'bigtiff alpha', 'bigtiff deflate 9', 'bigtiff deflate 9 alpha', 'bigtiff jpeg 90', 'bigtiff lzw', 'bigtiff lzw alpha ', 'bigtiff packbits', 'bmp', 'jpeg', 'jpeg 100', 'jpeg 80', 'jpeg 60', 'jpeg 40', 'jpeg 20', 'jp2', 'jp2 50', 'jp2 40', 'jp2 30', 'jp2 20', 'jpegxr', 'jpegxr 50', 'jpegxr 40', 'jpegxr 30', 'jpegxr 20', 'png', 'png best', 'png fastest', 'png none', 'ima', 'hobj'
FillColor (input_control) number → (integer / real)
Füllgrauwert für Bildpunkte, die nicht zur Domäne (Region) der Bilder gehören.
Defaultwert: 0
Wertevorschläge: -1, 0, 255, 65280, 16711680
FileName (input_control) filename.write(-array) → (string)
Name der Bilddatei.
Dateiendung: .hobj, .ima, .tif, .tiff, .bmp, .jpg, .jpeg, .jp2, .jxr, .png
Sind die Parameterwerte korrekt, dann liefert write_image
den Wert 2 (H_MSG_TRUE). Andernfalls wird eine Fehlerbehandlung
durchgeführt.
Foundation