Documentation – Current v5.2

Imatest IT: Direct Read Mode

Current Documentation

View legacy documentation

Passing Images to IT Using Direct Read Mode


Images (processed RGB or RAW) can be passed directly from the calling program to the Imatest IT C Library when opMode is set to -15 (using the default INI file) or -17 (passing in an INI file path). Passing images directly is generally much faster than reading them from files, and strongly recommended for speed-critical high-volume testing.

For direct image passing, the varargin parameter includes two extra mxArrays, one containing the image data of the appropriate type (signed or unsigned 8, 16, or 32 bit integers), and the other a char* in JSON format containing the information needed to decode (or reconstruct) the image.

The rawFile parameter is created using the mxCreateNumericMatrix() function, passing in the number of rows (1), the size of the image array, a constant representing the data format (which can be mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, or mxUINT32_CLASS), and the constant mxReal. Next, use mxFree() to deallocate the original data, and call setData() to copy your image array into the mxArray parameter.

The varargin parameter is an mxArray of type Cell Array. Use the mxCreateCellMatrix() to create the array, and then mxSetCell() to add the extra arguments to it.

For RGB and RAW images, the JSON object must contain the image width, height, ncolors (number of colors), fileroot, and an extension. If the image is processed RGB, then use the value “rgb“; if it is a RAW image, then use the extension that has been configured in your INI file using the Read Raw utility. The fileroot will be used to direct where to write output files, and what the output filenames will be. The following C code snippet passes an image array of type unsigned short and a JSON metadata string to the mlfBlemish_shell() function.

unsigned short *rawPixels;
unsigned int pixelCount;
mxArray *outputJSON = NULL, *inputFile = NULL, *rootDir = NULL, *inputKeys = NULL, *opMode = NULL, *varargin = NULL, *imageData = NULL, *jsonData = NULL;
inputFile = mxCreateString("");
rootDir = mxCreateString("C:\\ImatestSamples\\");
opMode = mxCreateString("-15");
inputKeys = mxCreateString( "JSON");
jsonData = mxCreateString("{ \"height\": 1296, \"width\": 808, \"ncolors\": 1, \"extension\": \"raw\", \"fileroot\": \"C:\\ImatestSamples\\blemish.raw\"}");

/// Load the image data from your source ...

imageData = mxCreateNumericMatrix(1, pixelCount, mxUINT16_CLASS, mxREAL );
mxFree((mxArray*)mxGetData(imageData));
mxSetData(imageData, rawPixels);

varargin = mxCreateCellMatrix(1, 2);
mxSetCell(varargin, 0, imageData);
mxSetCell(varargin, 1, jsonData);

mlfBlemish_shell(1, &outputJSON, inputFile, rootDir, inputKeys, opMode, varargin);


Images (processed RGB or RAW) can be passed directly from the calling program to the Imatest IT C++ Library when opMode is set to -15 (using the default INI file) or -17 (passing in an INI file path). Passing images directly is generally much faster than reading them from files, and strongly recommended for speed-critical high-volume testing.

For direct image passing, the varargin parameter includes two extra mwArrays, one containing the image data of the appropriate type (signed or unsigned 8, 16, or 32 bit integers), and the other a string in JSON format containing the information needed to decode (or reconstruct) the image.

The rawFile parameter is created using the mwArray constructor, passing in the size of the image array, a 1 (for a single dimension array), a constant representing the data format (which can be mxINT8_CLASS, mxUINT8_CLASS, mxINT16_CLASS, mxUINT16_CLASS, mxINT32_CLASS, or mxUINT32_CLASS), and the constant mxReal. Then use the setData() function to copy your image array into the mwArray parameter.

The varargin parameter is an mwArray of type Cell Array. Use the Get() and Set() functions to add the extra arguments to it.

For RGB and RAW images, the JSON object must contain the image width, height, ncolors (number of colors), fileroot, and an extension indicator. If the image is processed RGB, then use the value “rgb“; if it is a RAW image, then use the extension that has been configured in your INI file using the Read Raw utility. The fileroot will be used to direct where to write output files, and what the output filenames will be. The following C++ code snippet passes an image array of type unsigned short and a JSON metadata string to the blemish_shell() function.

unsigned short *rawPixels;
unsigned int pixelCount;
/// Load the image data from your source here ...

const char *jsonOptionsStr = "{ \"jstr\": {\"width\": 1296,\"height\": 808,\"ncolors\": 1,\"extension\": \"raw\", \"fileroot\": \"C:\\ImatestSamples\\blemish.raw\"}";
mwArray jsonOutput;
mwArray inputFile = mwArray("");
mwArray rootDir = mwArray("C:\\ImatestSamples\\");
mwArray inputKeys = mwArray("JSON");
mwArray opMode = mwArray("-15");
mwArray rawFile = mwArray(pixelCount, 1, mxUINT16_CLASS, mxREAL);
rawFile.SetData(rawPixels, pixelCount);
mwArray jsonOptions = mwArray(1,jsonOptionsStr);
mwArray varargin = mwArray(1,2,mxCELL_CLASS);
varargin.Get(1,1).Set(rawFile);
varargin.Get(1,2).Set(jsonOptions);

blemish_shell(1, jsonOutput, inputFile, rootDir, inputKeys, opMode, varargin); 


Images (processed RGB or RAW) can be passed directly from the calling program to IT Python when op_mode is set to ImatestLibrary.DIRECT_READ. Passing images directly is generally much faster than reading them from files, and strongly recommended for speed-critical high-volume testing.

For direct image passing, the raw_data parameter contains the image (passed as a binary string, 8, 16, or 32 bits per pixel), or as an array.array object, with a data type code of either ‘B’ (uint8), ‘H’ (uint16), or ‘I’ (uint32), and the json_args parameter contains a JSON object with information needed to decode (or reconstruct) the image.

For RGB and RAW images, the json_args object must contain the image width, height, ncolors (number of colors), filename, and an extension indicator. If the image is processed RGB, then use the value “rgb“; if it is a RAW image, then use the extension that has been configured in your INI file using the Read Raw utility. The filename will be used to direct where to write output files, and what the output filenames will be. The following Python script creates the json_args string using the ImatestLibrary.build_json_args() function, and passes it and the raw_data to the blemish_json() function. Note that this example is somewhat contrived – you normally wouldn’t read the image from disk, you would have the raw_data stream already read in from some other source.

raw_data = None
/// Load your image data here...

raw_image_path = r'C:\ImatestSamples\blemish.raw'

json_args = imatestLib.build_json_args(width=1296,
                                       height=808,
                                       ncolors=1,
                                       extension='raw',
                                       filename=raw_image_path)

result = imatestLib.blemish_json(input_file=None,
                                 root_dir=root_dir,
                                 op_mode=ImatestLibrary.OP_MODE_DIRECT_READ,
                                 ini_file=ini_file,
                                 raw_data=raw_data,
                                 json_args=json_args)


Images (processed RGB or RAW) can be passed directly from the calling program to the Imatest IT .NET Library. Passing images directly is generally much faster than reading them from files, and strongly recommended for speed-critical high-volume testing.

For direct image passing, use one of the following module method signatures:

string [module].JSON(string rootDir, byte[] inputBytes, DirectReadOptions directReadOptions)
string [module].JSON(string rootDir, byte[] inputBytes, DirectReadOptions directReadOptions, string iniFilePath)
string [module].JSON(string rootDir, ushort[] inputBytes, DirectReadOptions directReadOptions)
string [module].JSON(string rootDir, ushort[] inputBytes, DirectReadOptions directReadOptions, string iniFilePath)
string [module].JSON(string rootDir, uint[] inputBytes, DirectReadOptions directReadOptions)
string [module].JSON(string rootDir, uint[] inputBytes, DirectReadOptions directReadOptions, string iniFilePath)


[module].JSON(String rootDir, Byte() inputBytes, DirectReadOptions directReadOptions) As String
[module].JSON(String rootDir, Byte() inputBytes, DirectReadOptions directReadOptions, String iniFilePath) As String
[module].JSON(String rootDir, UInt16() inputBytes, DirectReadOptions directReadOptions) As String
[module].JSON(String rootDir, UInt16() inputBytes, DirectReadOptions directReadOptions, String iniFilePath) As String
[module].JSON(String rootDir, UInt32() inputBytes, DirectReadOptions directReadOptions) As String
[module].JSON(String rootDir, UInt32() inputBytes, DirectReadOptions directReadOptions, String iniFilePath) As String

The inputBytes parameter contains the image data of the appropriate type (unsigned 8, 16, or 32 bit integers), and the directReadOptions parameter is an object containing the information needed to decode (or reconstruct) the image.

For RGB and RAW images, the DirectReadOptions object must contain the image Width, Height, NumberOfColors, Filename, and Extension values. If the image is processed RGB, then use the value “rgb“; if it is a RAW image, then use the extension that has been configured in your INI file using the Read Raw utility. The Filename property will be used to direct where to write output files, and what the output filenames will be. The following code snippet passes an image array of type byte and a DirectReadOptions object to the blemish_shell() function.

UInt16[] imageData;

// Load the image data from your source ...

DirectReadOptions directReadOptions = new DirectReadOptions();
directReadOptions.Width = 1296;
directReadOptions.Height = 808;
directReadOptions.Extension = "raw";
directReadOptions.Filename = "C:\\ImatestSamples\\blemish.raw";
directReadOptions.NumberOfColors = 1;

string rootDir = "C:\\ImatestSamples\\";

string resultJSON = itLib.Blemish.JSON(rootDir, imageData, directReadOptions);


Dim imageData As UInt16

' Load the image data from your source ...

Dim DirectReadOptions As DirectReadOptions
directReadOptions = New DirectReadOptions()
directReadOptions.Width = 1296
directReadOptions.Height = 808
directReadOptions.Extension = "raw"
directReadOptions.Filename = "C:\\ImatestSamples\\blemish.raw"
directReadOptions.NumberOfColors = 1

Dim rootDir = "C:\\ImatestSamples\\"

Dim resultJSON = itLib.Blemish.JSON(rootDir, imageData, directReadOptions)


 

The table below lists all of the allowed JSON options fields. The fields marked as ‘Optional Pass/Fail Output’ will have their values copied into the ‘passfail’ section of the JSON output. The fields marked as ‘INI Overrides’ will override the corresponding value in the Imatest INI file.
 

JSON Element Name

Notes

Required   height The number of rows in the image array.
width The number of columns in the image array.
ncolors The number of color channels. If analyzing a Bayer RAW or grayscale image, set to 1.
extension For raw image arrays, use an extension defined in Imatest Master’s Read Raw settings dialog. Otherwise use “rgb”.
fileroot   Full image pathname for saving results (e.g. *.csv, *.png).
Optional Pass/Fail Output part_number A string containing the device’s part number. Defaults to “not entered”.
serial_number A string containing the device’s serial number. Defaults to “not entered”.
station The production station. Defaults to an empty string.
operator The station operator. Defaults to an empty string.
name This field is only present in the Pass/Fail output if a value is supplied.
operation This field is only present in the Pass/Fail output if a value is supplied.
status This field is only present in the Pass/Fail output if a value is supplied.
Optional INI Overrides [SFRplus only] crop_borders An integer array defining an image border in pixels to exclude ( [Left, Right, Top, Bottom])
lens_to_chart_distance_cm A scalar double indicating the lens-to-chart distance in cm. 
chart_height_cm A scalar double indicating the chart height in cm.
Optional INI Overrides [Blemish only] hot_pixel_type A scalar integer indicating the hot-pixel threshold type.  Set to 1 for none, 2 for absolute, or 3 for percentage.
dead_pixel_type A scalar integer indicating the dead-pixel threshold type.  Set to 1 for none, 2 for absolute, or 3 for percentage.
hot_pixel_thresholds A two-element array containing the hot-pixel thresholds in the form: [absolute threshold, percentage threshold].
dead_pixel_thresholds  A two-element array containing the dead-pixel thresholds in the form: [absolute threshold, percentage threshold].
blemish_analysis A boolean flag to toggle Blemish analysis. Set to 1 to enable Blemish analysis and 0 to disable.
uniformity_analysis A boolean flag to toggle Uniformity analysis. Set to 1 to enable Blemish analysis and 0 to disable.