Documentation – Current v24.1

Imatest IT Exception hierarchy

Beginning with Imatest IT 4.2 an exception hierarchy has been implemented with the intent of providing the API user an improved method for handling errors. This page is meant as reference for the exceptions that Imatest can throw as well as how to handle them in Imatest IT/DLL.

Exception hierarchy

Shown below is the exception hierarchy defined for Imatest. In this table an increasing indentation indicates that a given exception inherits from the exception above with less indentation. Note that the Imatest IT library can also throw exceptions that are generated by the underlying MATLAB routines. Imatest IT provides the function necessary to distinguish between Imatest exceptions and MATLAB exceptions.

All of the exceptions that are thrown by our library are instances of the mwException class, a MATLAB class that inherits from std::exception.


Exception name



The base class for all of Imatest’s exceptions.


An exception for handling errors related to invalid configuration of Imatest, e.g. a supplied INI file that has invalid entries.


This is an exception to be thrown for problems with Imatest data objects.


This is an exception to be thrown for problems with the constructor of Imatest data objects.


An exception for errors that are due to the source of the user supplied image.


An exception for errors related to the automated detection algorithms.


An exception for general errors caused by improperly cropped images.


This exception is for errors occurring within Imatest’s feature detection algorithms.


An exception for errors in cases where there are problems with the ROI, e.g. the detected edge is too close to either end of the ROI.


An exception for errors that are due to the source of the user supplied image.


An exception for cases where the test chart in the image was not properly aligned with the camera, or framed, in other words.


An exception for errors caused by an image aquisition interface, e.g. Android or Omnivision API functions.


An exception for errors that are unique to image files (as opposed to video files).


An exception for situations where the image size is too small to be useful for analysis.


An exception for situations where an image array was supposed to be available for analysis, but an empty image array was detected instead.


An exception for when an unsupported image or video format is supplied.


An exception for general errors that pertain to video files.


An exception for general problems with I/O.


An exception for when Imatest cannot open a file, i.e. it cannot gain reading or writing privileges for reasons other than it cannot find the file.


An exception for when a specified file cannot be found.


An exception that is thrown for errors in socket communication.


Exception for errors related to external calls to third-party licensing libraries or systems e.g. A call to a Nalpeiron library returns an error code.


Exception for errors related to the output supplied to users, e.g errors with plots or text-based output.


An exception for errors with reading or writing JSON files.


An exception for errors in plots that Imatest outputs to the user.


An exception for errors in reading or writing XML files.


Exception for errors related to function parameters.


An exception for when an incorrect number of inputs is supplied to a function.


An exception for when an incorrect number of outputs is supplied to a function.


Exception for errors related to input parameters that are formatted incorrectly (wrong length, etc…)


Exception for errors related to input parameters that are the wrong type or class.


An exception for general errors involving the user interface.


An exception that can be thrown when the user hits a cancel button.

Function prototype and other library resources

Since the mwException class does not have a member that indicates the exception, included in the Imatest IT library is a function that retrieves the identifier for the last exception to have been thrown. The function getExceptionID() is meant to be called within a catch block (see example below).

getExceptionID(int nargout, mwArray& errID, mwArray& errName)  Call to retrieve the identifier and name for the last exception.


The errID parameter is a mwArray, which is a MATLAB array class, and contains a signed integer that identifies the exception. The errName contains a string with the name of the exception.  The input argument nargout should be two. 

Included with the Imatest IT library is an extra header file (imatest_exception_IDs.h) in which an enum and const char* declarations of identifiers for the Imatest exception hierarchy. The values defined in imatest_exception_IDs.h correspond to values that would be returned by getExceptionID().

Example: how to determine the exception type

 In order to distinguish Imatest exceptions from those issued by Matlab, you will need to retrieve the exception identifier using  getExceptionID. The full list of identifiers for Imatest’s exceptions are defined in the imatest_exception_IDs.h header file that is included with Imatest IT. An example of retrieving the exception identifier is shown below:


try {

   // call an Imatest library function ...

} catch(mwException& mwe) {
   std::cout << "Error!" << std::endl;
   std::cout << mwe.what() << std::endl;
   mwe.print_stack_trace(); // print the stack trace to std::cerr

   mwArray errName, errID; 
   getExceptionID(2, errID, errName); 
   std::string exceptName((const char*)errName.ToString());
   int exceptID = errID.Get(1,1);
   // Handle exceptions using definitions in imatest_exception_IDs.h...

} catch(const std::exception& ex) {
   // Handle exceptions ...

Relevant INI file settings

continue_on_error INI key has been added to the [api] section of the Imatest INI file. The continue_on_error can be used to suppress Imatest exceptions that could occur when batch processing images in Imatest IT. When continue_on_error is set to one, exceptions will be suppressed, and when set to zero, exceptions can be thrown. For further reference please read the following: Parameters that affect Imatest IT.