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

Further information

The function F_VN_ExportImageAsJpegExp is an expert version of F_VN_ExportImageAsJpeg. It contains additional parameters.

Parameter

Input image

The input image ipImage must be provided as ET_USINT or ET_UINT with 1, 3, or 4 channels. 1-channel images are interpreted as grayscale images, 3-channel images as RGB, and 4-channel images as RGBA. The alpha channel is ignored in RGBA because JPEG does not support transparency. ET_UINT type images can only be used with lossless compression.

Result image

The compressed JPEG image is returned as ipJpeg via ITcVnDataExport. The data can then be exported via an external ADS-RPC and displayed or processed further. To retrieve the data, we recommend using the GetDataIfNewRpcUnlocked() method. To ensure the interface's availability to ADS, the following interface must be declared in the PLC code:

ipAdsInterface : ITcVnDataExportRpcUnlocked;

The interface simply needs to be declared; in the code, only ITcVnDataExport is used.

Compression quality

The parameter nLumaQuality controls the type and quality of compression and distinguishes between lossy and lossless compression:

Lossy compression (0–100)
Higher values mean better image quality with a larger data set. A recommended starting value is 90, which offers a good balance between quality and file size.
Lossless compression (101–107)
The values 101–107 are used to select predictors 1–7 for lossless JPEG compression; 101 is recommended. Lossless compression requires significantly more computing time and generates larger data sets, so high-quality lossy compression is generally the better choice. For images of the type ET_UINT, this is the only supported compression method.

Color quality

The nChromaQuality parameter controls the quality of the color components (chroma) and is only evaluated during lossy compression. The default value, -1, provides the same quality as nLumaQuality and is the recommended setting. If a different value between 0 and 100 is set, chroma subsampling (eSamplingFactor) is automatically disabled. In this case, the internal sampling factor TCVN_JS_444 is used to ensure that the separately configured color quality is not compromised by undersampling.

Color subsampling

The parameter eSamplingFactor, of type ETcVnJpegSampling, determines the extent to which the color information is undersampled relative to the brightness. It is used only for lossy compression and nChromaQuality = -1. Higher subsampling reduces the file size but may decrease color sharpness.

TCVN_JS_444: Sampling factors 1x1, 1x1, 1x1 (full chroma resolution).
TCVN_JS_440: Sampling factors 1x2, 1x1, 1x1.
TCVN_JS_422: Sampling factors 2x1, 1x1, 1x1.
TCVN_JS_420: Sampling factors 2x2, 1x1, 1x1 (default).
TCVN_JS_411: Sampling factors 4x1, 1x1, 1x1.
TCVN_JS_410: Sampling factors 4x2, 1x1, 1x1 (lowest chroma resolution).

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