Documentation – Current v24.2

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

Note

ImatestException

The base class for all of Imatest’s exceptions.

ConfigurationException

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

DataException

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

DataConstructorException

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

ImageAnalysisException

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

AutoDetectException

An exception for errors related to the automated detection algorithms.

CropException

An exception for general errors caused by improperly cropped images.

DetectionException

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

RoiFailureException

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.
        ImageSourceException

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

BadFramingException

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

ImageAcquisitionException

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

ImageException

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

BadImageSizeException

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

EmptyImageException

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

UnsupportedFormatException

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

VideoException

An exception for general errors that pertain to video files.

ImatestIOException

An exception for general problems with I/O.

ImatestCannotOpenFileException

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.

ImatestFileNotFoundException

An exception for when a specified file cannot be found.

ImatestSocketException

An exception that is thrown for errors in socket communication.
        LicenseException

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.
        OutputException

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

JsonException

An exception for errors with reading or writing JSON files.

PlottingException

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

XmlException

An exception for errors in reading or writing XML files.

ParameterException

Exception for errors related to function parameters.

IncorrectNumInputsException

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

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

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

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

UIException

An exception for general errors involving the user interface.

UserCancelException

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

A 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.