Documentation – Current v24.2

Imatest IT Acquisition Library

The Imatest IT Acquisition library enables the developer to directly acquire images from supported devices and is made available in the form of a Dynamic Link Library (DLL), as with Imatest IT. The images returned by the Acquisition library can then be passed to the  Imatest IT library for analysis by Imatest’s power image quality analysis routines. The Imatest IT Acquisition library supports the same devices and interfaces as Imatest Master:

*Note* As of Imatest 5.0, image acquisition capabilities can now be found in Imatest Master. Previously these capabilities were in Imatest IS which has been discontinued. 

Epiphan    STM Conduit
Omnivision   Graphin EasyLab
Toshiba   ON Semi Devware

 and many others.

 Functions Prototypes and Definitions

Use of the Acquisition library is similar to Imatest IT: programs are initiated by calling them inside of your C/C++ program. The steps (excerpted from Matlab documentation) are:

  1. Declare variables and process/validate input arguments.
  2. Call mclInitializeApplication(), and test for success. This function sets up the global MCR state and enables the construction of MCR instances.
  3. Call, once for each library, Initialize, to create the MCR instance required by the library.
  4. Invoke functions in the library, and process the results. (This is the main body of the program.)
  5. Call, once for each library, Terminate, to destroy the associated MCR.
  6. Call mclTerminateApplication() to free resources associated with the global MCR state.
  7. Clean up variables, close files, etc., and exit.

More information about handling MATLAB based C/C++ libraries can be found here under the subsection, “Libraries”. See also, mwArray.

For the imatest library, these functions have the calling form:
imatest_libraryInitialize(void) To initialize the library.
imatest_libraryTerminate(void) To close the library.
imatestPrintStackTrace(void) To resolve a stack trace within the library.
mlxAcquire_image(int nlhs, mxArray *plhs[], int nrhs, mxArray *prhs[]) C call to the acquire_image function. See parameter spec below. See Calling a (C) Shared Library.
acquire_image(int nargout, mwArray &im_orig, mwArray &vstr, const mwArray &source_id, const mwArray &varargin); To directly acquire from a supported device.
list_devices(int nargout, mwArray &devices); To list attached devices other than the standard interfaces (Epiphan, Omnivision, Toshiba, STM, Graphin, and ON Semi).

 

Parameters of type mwArray and mxArray are Matlab Array types. The parameters nargout and nlhs specify the number of output parameters, which should be set to one for both acquire_image() and list_devices() . The parameters *plhs[],  &im_orig,  &vstr, and &devices are all placeholders for data returned from acquire_image() and list_devices(), respectively. A list_devices() function call is only needed if the developer wishes to acquire from devices other than Epiphan, Omnivision, Toshiba, STM, Graphin, and ON Semi.

Table of parameter specifications

Program names and parameters should contain full path names to minimize the likelihood of error.

const mwArray &source_id [input]

The ID number (in the form of a mxDouble) for the desired device:

0-> Load a supported image file

1-> Epiphan

2-> Omnivision

3-> Toshiba 

4-> STM Conduit

5-> Graphin EasyLab

6-> ON Semi Devware 

7-> Android

or the DeviceID from a list_devices() call, which will return a value > 7

const mwArray &varargin [input]

A one to four parameter mwArray of mxClassID = mxCELL_CLASS. Only for Omnivision and Epiphan is the second parameter needed.

varargin{1}: Set to 1.0 if the image is row major and thus needs to be converted to RGB planar, column-major for analysis. Otherwise set to 0.

varargin{2}: If source_id == 2 (Omnivision) or source_id == 0 (File), then this must be the fully-qualified  Imatest *.ini file name.

                   For source_id == 1 (Epiphan), this parameter is used to select the Epiphan channel (0.0 or 1.0) corresponding to the order of devices in the Epiphan Capture tool.

varargin{3}: For source_id > 7, the device name as returned by list_devices().

                   For source_id == 0, the fully-qualified image filename.

varargin{4}: The desired image acquisition format as returned by list_devices(). Only needed if acquiring from sources with source_id > 7.

mwArray &im_orig [output]

 A mwArray to house the returned image. After the successful completion of acquire_image(), this mwArray will contain the image. This image can be passed to Imatest IT.

mwArray &vstr [output]

A mwArray to house the returned vstr Matlab structure. For those acquiring from devices other than source_id == 1 through 7, two fields of the vstr struct are of interest:

  • vid_format – The image acquisition format used for the returned im_orig
  • device_name – The name of the device acquired from for the returned im_orig

mwArray &devices [output]

 A mwArray that is a cell array of structs, i.e. an mwArray of mxClassID = mxCELL_CLASS containing mwArray’s of mxClassID = mxSTRUCT_CLASS. The Matlab structs have the following fields:

  • DefaultFormat – A string containing the default image capture format
  • DeviceName:  A string containing the device name.
  • DeviceID: A uint16 containt the device ID. This value should be the value sent to acquire_image() as the source_id.
  • SupportedFormats: A Matlab cell array of strings containing the list of supported image capture formats for the device.
  • Adaptor: A string containing the name of the adaptor used to address the device (e.g. ‘gige’, ‘winvideo’, etc.).

 Example

Loading an image file

In this example we load an image file (“C:\Sample_dir\example.jpg”) and return the image data as a row-major, interleaved image.

// Output parameters
mwArray im_orig, vstr;

// source_id

mwArray source_id((mxDouble(0));

// toRGBRows

mwArray toRGBrows = mwArray(1,1,mxDOUBLE_CLASS);
toRGBrows=1.0;// by being 1 we call for the image to be in row-major format

// Imatest INI file

std::string m_ini_file = “C:\Sample_dir\imatest-v2.ini”;

mwArray ini_file(m_ini_file.c_str());

// Image file

std::string m_image_file = “C:\Sample_dir\example.jpg”;

mwArray image_file(m_image_file.c_str());

// Set the varargin cell array
mwArray vararginParam = mwArray(1,3,mxCELL_CLASS);
vararginParam.Get(1,1).Set(toRGBrows);
vararginParam.Get(1,2).Set(ini_file); // Path to INI file
vararginParam.Get(1,3).Set(image_file); 

try
{
   acquire_image(2, im_orig, vstr, source_id, vararginParam);
}
catch (mwException& e)
{
   std::cout << “Run Error!” << std::endl;
   std::cerr << e.what() << std::endl;
   e.print_stack_trace();
}

 

Acquiring from device with source_id == 1 to 7

 For an example of this acquire_image() usage, please see the ImatestLibAcq::CaptureFrame() member function in the ImatestLibAcq.cpp file from our open source OperatorConsole.

 

Acquiring from a device with source_id > 7

Please view the sample project provided for the Acquisition library.

 Notes

  • The devices must be properly initialized by their respective control software before calling acquire_image().
  • For Imatest 4.4 & 4.5: If the device requires settings that were saved by the Imatest IS Device Manager, then the corresponding device settings JSON file needs to included with the Imatest INI file.