F_VN_ExportImageAsJpeg

Syntax

Definition:

FUNCTION F_VN_ExportImageAsJpeg : HRESULT
VAR_INPUT
    ipImage      : ITcVnImage;
    ipJpeg       : Reference To  ITcVnDataExport;
    nLumaQuality : DINT;
    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.
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_ExportImageAsJpeg compresses the passed image into JPEG format and returns the result as an exportable data object. The image of the result in JPEG format can then be retrieved from the controller via an ADS Remote Procedure Call (RPC).

The use case involves the transmission of compressed images. Since JPEG uses lossy compression, it can significantly reduce the amount of data compared to uncompressed images. For cases where compression artifacts are not acceptable, lossless JPEG compression is also available.

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.

Expert parameters

The expert variant F_VN_ExportImageAsJpegExp contains additional parameters.

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