F_VN_ExportImageAsJpegExp

Syntax

Definition:

FUNCTION F_VN_ExportImageAsJpegExp : HRESULT
VAR_INPUT
    ipImage         : ITcVnImage;
    ipJpeg          : Reference To  ITcVnDataExport;
    nLumaQuality    : DINT;
    nChromaQuality  : DINT;
    eSamplingFactor : ETcVnJpegSampling;
    hrPrev          : HRESULT;
END_VAR

Inputs

Name	Type	Description
ipImage	ITcVnImage	Source image (ET_USINT or ET_UINT with 1, 3 or 4 channels). ET_UINT only supports lossless compression. 3 channel expects RGB, 4 channel RGBA (alpha is simply ignored, jpeg does not support it).
ipJpeg	Reference To ITcVnDataExport	Returns the jpeg image. The resulting data can be exported via RPC.
nLumaQuality	DINT	Luma quality, which is in a range of 0 - 100 for lossy or 101 - 107 for lossless compression (for lossless, this selects 1 - 7 as the predictor). Recommended: 90 for lossy or 101 for lossless. Lossless compression is significantly slower and leads to larger files, so usually a high-quality lossy compression is the better choice.
nChromaQuality	DINT	Chroma quality (0 - 100) or -1 to use the same as luma. Only used for lossy compression. If chroma quality is different from luma quality, chroma subsampling is disabled automatically (samplingFactor JS_444).
eSamplingFactor	ETcVnJpegSampling	Jpeg chroma sampling factor. Only used for lossy compression.
hrPrev	HRESULT	HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)

Return value

HRESULT

Weiterführende Informationen

Die Funktion F_VN_ExportImageAsJpegExp ist eine Expert-Variante von F_VN_ExportImageAsJpeg. Sie enthält zusätzliche Parameter.

Parameter

Eingangsbild

Das Eingangsbild ipImage muss als ET_USINT oder ET_UINT mit 1, 3 oder 4 Kanälen übergeben werden. Einkanalige Bilder werden als Graustufenbild interpretiert, 3-kanalige Bilder als RGB und 4-kanalige Bilder als RGBA. Der Alpha-Kanal wird bei RGBA ignoriert, da JPEG keine Transparenz unterstützt. Bilder vom Typ ET_UINT können ausschließlich mit der verlustfreien Kompression verwendet werden.

Ergebnisbild

Über ipJpeg wird das komprimierte JPEG-Bild als ITcVnDataExport zurückgegeben. Die Daten können anschließend über einen externen ADS-RPC exportiert und angezeigt oder weiterverarbeitet werden. Zum Abrufen der Daten wird die Methode GetDataIfNewRpcUnlocked() empfohlen. Damit das Interface für ADS verfügbar ist, muss im SPS-Code das folgende Interface deklariert werden:

ipAdsInterface : ITcVnDataExportRpcUnlocked;

Das Interface muss lediglich deklariert werden, im Code wird ausschließlich das ITcVnDataExport verwendet.

Kompressionsqualität

Der Parameter nLumaQuality steuert Art und Güte der Kompression und unterscheidet zwischen verlustbehafteter und verlustfreier Kompression:

Verlustbehaftete Kompression (0 - 100)
Höhere Werte bedeuten bessere Bildqualität bei größerer Datenmenge. Ein empfohlener Startwert ist 90, der einen guten Kompromiss zwischen Qualität und Dateigröße bietet.
Verlustfreie Kompression (101 - 107)
Über die Werte 101 - 107 wird der Prädiktor 1 - 7 der verlustfreien JPEG-Kompression ausgewählt, empfohlen wird 101. Die verlustfreie Kompression benötigt deutlich mehr Rechenzeit und erzeugt größere Datenmengen, sodass in der Regel eine hochwertige verlustbehaftete Kompression die bessere Wahl ist. Für Bilder vom Typ ET_UINT ist dies die einzige unterstützte Kompression.

Farbqualität

Der Parameter nChromaQuality steuert die Qualität der Farbanteile (Chroma) und wird nur bei verlustbehafteter Kompression ausgewertet. Der Standardwert -1 übernimmt die gleiche Qualität wie nLumaQuality und ist die empfohlene Einstellung. Wird ein davon abweichender Wert zwischen 0 und 100 gesetzt, wird das Chroma-Subsampling (eSamplingFactor) automatisch deaktiviert. In diesem Fall wird intern der Sampling-Faktor TCVN_JS_444 verwendet, damit die separat eingestellte Farbqualität nicht durch Unterabtastung beeinträchtigt wird.

Farbunterabtastung

Der Parameter eSamplingFactor vom Typ ETcVnJpegSampling legt fest, wie stark die Farbinformationen gegenüber der Helligkeit unterabgetastet werden. Er wird nur bei verlustbehafteter Kompression und nChromaQuality = -1 verwendet. Eine stärkere Unterabtastung reduziert die Dateigröße, kann aber die Farbschärfe verringern.

TCVN_JS_444: Sampling-Faktoren 1x1, 1x1, 1x1 (volle Chroma-Auflösung).
TCVN_JS_440: Sampling-Faktoren 1x2, 1x1, 1x1.
TCVN_JS_422: Sampling-Faktoren 2x1, 1x1, 1x1.
TCVN_JS_420: Sampling-Faktoren 2x2, 1x1, 1x1 (Standard).
TCVN_JS_411: Sampling-Faktoren 4x1, 1x1, 1x1.
TCVN_JS_410: Sampling-Faktoren 4x2, 1x1, 1x1 (geringste Chroma-Auflösung).

Required License

TC3 Vision Base

System Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT V3.1.4024.59 or later	PC or CX (x64) with min. PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision