ExportImageAsJpeg

Syntax

Definition:

HRESULT ExportImageAsJpeg(
    HRESULT           hrPrev,
    ITcVnImage*       ipImage,
    ITcVnDataExport*& ipJpeg,
    LONG              nLumaQuality,
    LONG              nChromaQuality = -1,
    ETcVnJpegSampling eSamplingFactor = JS_420
)

Parameters

Name	Type	Default	Description
hrPrev	HRESULT		HRESULT indicating the result of previous operations (If SUCCEEDED(hrPrev) equals false, no operation is executed.)
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	ITcVnDataExport*&		Returns the jpeg image. The resulting data can be exported via RPC.
nLumaQuality	LONG		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	LONG	-1	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	JS_420	Jpeg chroma sampling factor. Only used for lossy compression.

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.4026 or later	PC or CX (x64) with min. PL50, e.g. Intel 4-core Atom CPU	Tc3_Vision