Documentation – Current v25.1

Imatest IT: Direct Read Mode

Current Documentation

All documentation versions

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 it is a RAW image, then use the extension that has been configured in your INI file using the Read Raw utility, otherwise see the table below for options.  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.

[cpp]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);
[/cpp]

 

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

  • “row_major_interleaved” or “row_major_interleaved_rgb”: data arranged in RGB triplets of the form [R11G11B11 R12G12B12 … R1mG1mB1m … Rn1Gn1Bn1 … RnmGnmBnm]
  • “row_major_interleaved_bgr”: data arranged in BGR triplets of the form [B11G11R11 B12G12R12 … B1mG1mR1m … Bn1Gn1Rn1 … BnmGnmRnm]
  • “row_major_interleaved_rgba”: data arranged in RGBA quadruplets of the form [R11G11B11A11 R12G12B12A12 … R1mG1mB1mA1m … Rn1Gn1Bn1An1 … RnmGnmBnmAnm]
  •  “row_major_interleaved_bgra”: data arranged in BGRA quadruplets of the form [B11G11R11A11 B12G12R12A12 … B1mG1mR1mA1m … Bn1Gn1Rn1An1 … BnmGnmRnmAnm]
  • “row_major_planar”: data arranged in R,G,B planes of the form [R11 R12 … R1m R21… Rnm G11 … Gnm B11 … Bnm]
  • “column_major_planar”: data arranged in R,G,B planes of the form  [R11 R21 … Rn1 R12 … Rnm G11 … Gnm B11 … Bnm]

Note: The row-major formats are more common, so if in doubt try those first.

Note: For monochrome, row-major data use “row_major_planar”.

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.
Optional Diagnostic Fields show_image A boolean flag that if set to true (or 1) will display the supplied image after it has been read in and decoded, if needed.