Thermalyze Operation


Thermalyze API

The topics in this section explain .

Overview Calling Functions                       Running Thermalyze from Your Program                       Function Return Values Running Thermalyze                       ThermalyzeStart                       ThermalyzeStop Capturing Images                       CameraLinkBoardInitialize                       CameraLinkBoardFree                       CameraLinkPowerOn                       CameraLinkPowerOff                       CameraCommunicationStart                       CameraCommunicationStop                       CapturingStart                       CapturingStop                       TouchupCalEnable                       TouchupCalPerform  Images                       DisplayedImageGet                       SaveImage                       OpenImage                       ExportImageTemperature                       ExportImageRadiance                       ExportImage Camera Settings                       SetCalibrationRange Image Processing                       EnableImageAveraging                       SetImageAveragingLevel Regions                       CreateRegion                       SelectRegion                       SetSelectedRegionSettings                       DeleteSelectedRegion                       DeleteAllRegions                       MoveSelectedRegion                       GetRegionStatistics                       SaveRegions                       OpenRegions Emissivity Settings                       SetBackgroundTemperature                       SetUseCameraTemp Emissivity Tables                       ETablesWindowOpen                       ETablesWindowClose                       SetETablesControlTemp                       CreateETable                       ETableAmbientCorrection                       SetETableAmbientCorrectionActive                       SelectActiveETable                       ReadActiveETable                       SaveETable                       OpenETable Lock-in Thermography                       LITWindowOpen                       LITWindowClose                       LITCycleFrequencySet                       LITCycleTimeSet                       LITTestStart                       LITTestStop                       LITAmplitudeImageGet                       LITSinglePhaseAngleSet                       LITSinglePhaseImageGet                       LITTestClear

Overview

Description

Thermalyze API is a set of functions that can be called from your custom program that is written in a programming language such as C#, C++, or Visual Basic.  These functions enable you to startup Thermalyze, operate the software, and return images and data from Thermalyze to your program for additional processing and analysis.

 The API functions were designed to operate the software in the same manner as when a user operates the Thermalyze program.  Consistency in operation between the Thermalyze program and the API functions makes your custom program easier to develop and troubleshoot.  After calling an API function in your program, you can quickly verify correct operation by viewing the Thermalyze program window.

Program Settings: Unlike operating Thermalyze manually, many program settings can be altered without opening the window in which the parameter displayed (e.g., changing the Background Temperature in the Emissivity Settings window).  However, there is functionality that can only be accessed when a particular window is opened (e.g., creating emissivity tables in the Emissivity Tables window).  In these cases, there are API functions to open and close these windows. Setting cannot be altered using an API function if the setting is disabled within Thermalyze.

Naming conventions

  • Constants are named in all upper case letters (i.e., THERMALYZE_ERROR_NONE).

  • Public variables begin with an upper case letter and end with an underscore (i.e., ThermalyzeExe_).

  • Private variables and function parameters begin with a lower case letter and end with an underscore (i.e., newCapturedImage_).

Definitions

  • Passed Parameters: Values that are passed to the function

  • Returned Parameters: Values that are returned from the function

Calling Functions

The topics in this section explain how to run Thermalyze from an external program.

                      Running Thermalyze from Your Program

Procedure

Follow this procedure to start Thermalyze from within your custom program (see the code below for examples):

  1. Copy the Calibration, Config, Cursors, Databases, Graphics, Help, and Sounds folders (including their contents) to the same directory in which your custom program resides.  These folders are located in the same directory as the Thermalyze.exe file.  The default folder during Thermalyze installation is C:\Program Files\Optotherm\Thermalyze.

  2. Add function return constants.

  3. Add a reference to the Thermalyze.exe file from your program.  The default folder during Thermalyze installation is C:\Program Files\Optotherm\Thermalyze.

  4. Declare an object variable of type Thermalyze.clsApi.

  5. Check that a Thermalyze.clsApi object has not already been instantiated.

  6. Instantiate a Thermalyze.clsApi object.

  7. Start the Thermalyze program by calling the API function StartThermalyze.

  8. (Optional) Bring your custom program window to the front to prevent it from being hidden by the Thermalyze window.  This can be performed each time a Thermalyze window is opened.

Start Thermalyze: In order to call the API functions from your own program, Thermalyze must be started by calling the API function StartThermalyze so that the Thermalyze executable will run in the same process space as the calling program.  When Thermalyze is started by double-clicking the icon on the desktop, Thermalyze will run in its own process space and your program will not have access to the API functions.

C# Example

class YourClassName
{
    private const Int16 THERMALYZE_ERROR_NONE = 0;
    private const Int16 THERMALYZE_ERROR_INVALID_PARAMETER = 1;
    private const Int16 THERMALYZE_ERROR_UNAVAILABLE = 2;
    private const Int16 THERMALYZE_ERROR_CANNOT_PERFORM = 3;
    private const Int16 THERMALYZE_ATTEMPT_FAILED = 4;
    private const Int16 THERMALYZE_ERROR_INTERNAL = 5;
    private const Int16 THERMALYZE_ERROR_PROGRAM_MINIMIZED = 6;
    private const Int16 THERMALYZE_ERROR_PROGRAM_CLOSED = 7;
    private Thermalyze.clsApi ThermalyzeExe_;
    public void YourMethodName()
    {
        Int16 return_;
        if (ThermalyzeExe_ != null) return;
        ThermalyzeExe_= new Thermalyze.clsApi();
        return_ = ThermalyzeExe_.StartThermalyze();
        Application.OpenForms["YourFormName"].BringToFront();
    }
}

                      Function Return Values

Description

After each API function is called, it returns one of the following values:

Name
Value
Description
THERMALYZE_ERROR_NONE
0 The function completed with no errors.
THERMALYZE_ERROR_INVALID_PARAMETER
1 An invalid parameter was passed to the function (e.g., sending a parameter value that is not in the acceptable range).
THERMALYZE_ERROR_REDUNDANT
2 The function action is redundant (e.g., attempting to set a parameter to its current value).
THERMALYZE_ERROR_UNAVAILABLE
3 The function action is currently unavailable (e.g., requested data is not available, required window is closed, controls are disabled, or a modal dialog box is open).
THERMALYZE_ERROR_CANNOT_PERFORM
4 The function could not be performed (e.g., attempting to change a parameter that could interfere with existing test data).
THERMALYZE_ATTEMPT_FAILED
5 An attempt at performing the function failed (e.g., the function failed to correctly perform the intended action).
THERMALYZE_ERROR_INTERNAL
6 An internal error occurred in the function (e.g., an unexpected error occurred during execution of the function).
THERMALYZE_ERROR_PROGRAM_MINIMIZED
7 The Thermalyze program is minimized and windows cannot be opened properly (e.g., attempting to open a window, such as the Emissivity Tables window, while the main Thermalyze window is minimized).
THERMALYZE_ERROR_PROGRAM_CLOSED
8 The Thermalyze program has been closed (e.g., calling a function after the Thermalyze program has been closed).

After calling each API function, you can then call code in your custom program to handle the different errors as shown in the following examples.

C# Example

Int16 return_ = ThermalyzeExe_.FunctionName();
switch (return_)
{
    case THERMALYZE_ERROR_NONE:
    //add error code
    break;
    case THERMALYZE_ERROR_INVALID_PARAMETER:
    //add error code
    break;
    case THERMALYZE_ERROR_REDUNDANT:
    //add error code
    break;
    case THERMALYZE_ERROR_UNAVAILABLE:
    //add error code
    break;
    case THERMALYZE_ERROR_CANNOT_PERFORM:
    //add error code
    break;
    case THERMALYZE_ATTEMPT_FAILED;
    //add error code
    break;
    case THERMALYZE_ERROR_INTERNAL:
    //add error code
    break;
    case THERMALYZE_ERROR_PROGRAM_MINIMIZED:
    //add error code
    break;
    case THERMALYZE_ERROR_PROGRAM_CLOSED:
    //add error code
    break;
}

Running Thermalyze

The API functions in this section control starting and stopping Thermalyze.

                      ThermalyzeStart

Description

Start the Thermalyze program and open the main Thermalyze window.

C# Declaration

public Int16 ThermalyzeStart()

C# Example

Int16 return_ = ThermalyzeExe_.ThermalyzeStart();

                      ThermalyzeStop

Description

Stop the Thermalyze program and close all Thermalyze windows.

C# Declaration

public Int16 ThermalyzeStop()

C# Example

Int16 return_ = ThermalyzeExe_.ThermalyzeStop();

Capturing Images

The API functions in this section control capturing thermal images.

                      CameraLinkBoardInitialize

Description

Setup the Matrox Solios camera link video board for image capture.

This function has the same functionality as pressing the Initialize Camera Link Board button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraLinkBoardInitialize()

C# Example

Int16 return_ = ThermalyzeExe_.CameraLinkBoardInitialize();

                      CameraLinkBoardFree

Description

Free the Matrox Solios camera link video board computer resources.

This function has the same functionality as unpressing the Initialize Camera Link Board button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraLinkBoardFree()

C# Example

Int16 return_ = ThermalyzeExe_.CameraLinkBoardFree();

                      CameraLinkPowerOn

Description

Enable power over camera link (PoCL) via the Matrox Solios camera link video board.

This function has the same functionality as pressing the Camera Link Power button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraLinkPowerOn()

C# Example

Int16 return_ = ThermalyzeExe_.CameraLinkPowerOn();

                      CameraLinkPowerOff

Description

Disable power over camera link (PoCL) via the Matrox Solios camera link video board.  This function has the same functionality as unpressing the Camera Link Power button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraLinkPowerOff()

C# Example

Int16 return_ = ThermalyzeExe_.CameraLinkPowerOff();

                      CameraCommunicationStart

Description

Establish communication between the camera and computer.

This function has the same functionality as pressing the Establish Camera Communication button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraCommunicationStart()

C# Example

Int16 return_ = ThermalyzeExe_.CameraCommunicationStart();

                      CameraCommunicationStop

Description

Stop communication between the camera and computer.

This function has the same functionality as unpressing the Establish Camera Communication button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CameraCommunicationStop()

C# Example

Int16 return_ = ThermalyzeExe_.CameraCommunicationStop();

                      CapturingStart

Description

Start capturing and displaying images from the camera.

This function has the same functionality as pressing the Capture Images button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CapturingStart()

C# Example

Int16 return_ =ThermalyzeExe_.CapturingStart();

                      CapturingStop

Description

Stop capturing and displaying images from the camera.

This function has the same functionality as unpressing the Capture Images button on the top toolbar within Thermalyze.

C# Declaration

public Int16 CapturingStop()

C# Example

Int16 return_ =ThermalyzeExe_.CapturingStop();

                      TouchupCalEnable

Description

Enable or disable periodic camera touchup calibrations.  The value of the passed parameter determines if touchup calibrations will be enabled or disabled.  Pass the value of 0 to disable touchup calibrations and 1 to enable.

This function has the same functionality as pressing the Enable Automatic Touchup Calibrations button on the top toolbar within Thermalyze.

C# Declaration

public Int16 TouchupCalEnable(Byte value_)

C# Example

Byte value_ = 0; //disable camera touchup calibrations
Int16 return_ = ThermalyzeExe_.TouchupCalEnable(value_);

                      TouchupCalPerform

Description

Perform a camera touchup calibration.

This function has the same functionality as pressing the Touchup Calibration button on the top toolbar within Thermalyze.

C# Declaration

public Int16 TouchupCalPerform()
          

C# Example

Int16 return_ = ThermalyzeExe_.TouchupCalPerform(); 

 Images

The API functions in this section control displaying, saving and opening, and exporting thermal images.

                      DisplayedImageGet

Description

Retrieve the most recently displayed thermal image.  When this function returns THERMALYZE_ERROR_NONE, the returned parameter imageArray_ contains the most recently displayed image in the form of a two-dimensional array of unsigned 16 bit integer pixel values.  Pixel values can be converted to units of degrees Celsius or radiant emittance [W/m²].

When the returned parameter newCapturedImage_ contains the value of 1, the returned parameter image_ contains a newly captured image that has not yet been read using this function.  A value of 0 indicates that the image is not a captured image (i.e., it was opened from file) or it has already been read previously using this function.

The programing examples below demonstrate how to read the currently displayed thermal image.  If you need to continuously read captured images (for example, at the maximum frame rate of 60 images per second) place the GetDisplayedImage function in a continuous loop so that it is called repeatedly and check the returned parameter newCapturedImage_ to determine if the current image is a newly captured image.

C# Declaration

public Int16 DisplayedImageGet(ref UInt16[,] imageArray_, ref Byte newCapturedImage_)

C# Example

public UInt16 [,] imageArray_ = new UInt16 [480, 640];    //640 rows, 480 columns
Byte newCapturedImage_ = 0;
Int16 return_ = ThermalyzeExe_.DisplayedImageGet(ref imageArray_, ref newCapturedImage_);
const Double STEFAN_BOLTZMANN_CONSTANT = 5.6704E-8;
for (Int32 y_ = 0; y_ < 480; y_++)
{
    for (Int32 x_ = 0; x_ < 640; x_++)
    {
        Double pixTempC_ = (imageArray_[y_, x_] - 10000) / (Double)100;
        //pixTempC_ now holds the image pixel value in units of temperature in
        //degrees C at location [y_, x_]
        Double pixTempK_ = pixTempC_ + 273.16;
        Double pixRadiance_ = STEFAN_BOLTZMANN_CONSTANT * Math.Pow(pixTempK_, 4);
        //pixRadiance_ no holds the image pixel value in units of radiant emittance in
        //Watts per square meter
    }
}

                      SaveImage

Description

Save the currently displayed thermal image in Portable Network Graphics (PNG) format with .png extension.  PNG is a 16 bit lossless format that preserves temperature resolution of 0.01°C and is the native format for saving thermal images within Thermalyze.  This function has the same functionality as selecting the Save Image menu item within Thermalyze.

Overwrite: This function will overwrite existing files.

C# Declaration

public short SaveImage(String filename_)

C# Example

String filename_ = null;
filename_ = "c:\\Optotherm\\Thermalyze\\Images\image1.png";
Int16 return_ = ThermalyzeExe_.SaveImage(filename_);

                      OpenImage

Description

Open and display an image from file.  Image files must be in Portable Network Graphics (PNG) format with .png extension.  PNG is a 16 bit lossless format that preserves temperature resolution of 0.01°C and is the native format for saving thermal images within Thermalyze.

When this function returns THERMALYZE_ERROR_NONE, the returned parameter backTempC_ contains the background temperature that is displayed in the Emissivity Settings window (see the function SetBackgroundTemperature).  In order to accurately measure the temperature of an opened image with regions having emissivity less than 1.00 or when using an emissivity table, you must first call the SetBackgroundTemperature function with the parameter value of backTempC_ to set the background temperature to the value of the ambient background temperature as when the image was originally captured.

This function has the same functionality as selecting the Open Image menu item within Thermalyze.

C# Declaration

public short OpenImage(string filename_, ref Double backTempC_)

C# Example

String filename_ = null;
Double backTempC_;
filename_ = "c:\\Optotherm\\Thermalyze\\Images\\image1.png";
Int16 return_ = ThermalyzeExe_.OpenImage(filename_, ref backTempC_);

                      ExportImageTemperature

Description

Save the individual image pixel temperature values in the currently displayed thermal image to file in ASCII text or binary file formats.  Image pixel temperature values are saved in degrees Celsius.  The first row of image pixels is saved to file from left to right and then each subsequent row is saved likewise.

ASCII text files are saved with a ".txt" extension as text temperature values (for example, 37.54) with a newline character (carriage return/line feed) separating each value.  Binary files are saved with an ".imb" extension, as four-byte floating-point values in little endian format.

This function has the same functionality as selecting the Export Image Temperature menu item within Thermalyze.

Overwrite: This function will overwrite existing files.

C# Declaration

public Int16 ExportImageTemperature(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\Optotherm\Thermalyze\Export\Image Temperature\imageTemp1.txt";
//save the image temperature file as an ASCII text file
Int16 return_ = ThermalyzeExe_.ExportImageTemperature(filename_);

                      ExportImageRadiance

Description

Save the individual image pixel radiant emittance values in the currently displayed thermal image to file in ASCII text or binary file formats.  Image pixel radiance values are saved in units of [Watts/ m²].  The first row of image pixels is saved to file from left to right and then each subsequent row is saved likewise.

ASCII text files are saved with a ".txt" extension, as text radiance values (for example, 542.7) with a newline character (carriage return/line feed) separating each value.  Binary files are saved with an ".imb" extension, as four-byte floating-point values in little endian format.

This function has the same functionality as selecting the Export Image Radiance menu item within Thermalyze.

Overwrite: This function will overwrite existing files.

C# Declaration

public Int16 ExportImageRadiance(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\Optotherm\Thermalyze\Export\Image Radiance\imageRad1.txt";
//save the image radiance file as an ASCII text file
Int16 return_ = ThermalyzeExe_.ExportImageRadiance(filename_);

                      ExportImage

Description

Save the currently displayed thermal image in the following formats: bmp, jpeg, gif, png, or tiff.  The value of the passed parameter includeData_ determines if data from the Region Data Grid and any existing notes (if the Notes window is open) will be included below the image.  Pass the value of 0 to not include Region data and notes and pass 1 to include these items.

This function has the same functionality as selecting the Export Image or Export Image and Data item within Thermalyze.

Overwrite: This function will overwrite existing files.

C# Declaration

public short ExportImage(string filename_, Byte includeData_)

C# Example

String filename_ = null;
Byte includeData_ = 0; //do not include region data or notes
filename_ = "c:\\Optotherm\\Thermalyze\\Export\image1.bmp";
Int16 return_ = ThermalyzeExe_.ExportImage(filename_, includeData_);

Camera Settings

The API functions in this section control setting the thermal camera Calibration Range.

                      SetCalibrationRange

Description

Set the calibration range of the camera.  The value of the passed parameter range_ determines the calibration range of the camera.  Pass the value of 1 to set the camera to low range and 2 to set the camera to high range.

This function has the same functionality as selecting an entry from the Calibration Range drop-down box in the Camera Settings window.

Open Window: The Camera Settings window must be open when calling this function.

C# Declaration

public Int16 SetCalibrationRange(Byte range_)

C# Example

Byte range_ = 1; //set calibration range to low range
Int16 return_ = ThermalyzeExe_.SetCalibrationRange(range_);

Image Processing

The API functions in this section control thermal image averaging.

                      EnableImageAveraging

Description

Enable or disable image averaging.  The value of the passed parameter enable_ determines if image averaging will be enabled or disabled.  Pass the value of 0 to disable image averaging and 1 to enable.

This function has the same functionality as checking the Enable Image Averaging box in the Image Processing window.

Open Window: The Image Processing window must be open when calling this function.

C# Declaration

public Int16 EnableImageAveraging(Byte enable_)

C# Example

Byte enable_ = 1; //enable image averaging
Int16 return_ = ThermalyzeExe_.EnableImageAveraging(enable_);

                      SetImageAveragingLevel

Description

Set the number of captured images to average in real time.  The value of the passed parameter level_ determines the number of image to average.  Acceptable values for this parameter are shown in the table below.

This function has the same functionality as entering a value into the Image Averaging drop-down box in the Image Processing window.

level_
Image Averaged
1 2
2 4
3 8
4 16
5 32
6 64
7 128

Open Window: The Image Processing window must be open when calling this function.

C# Declaration

public Int16 SetImageAveragingLevel(Byte level_)

C# Example

Byte level_ = 4; //set image averaging to 16 images
Int16 return_ = ThermalyzeExe_.SetImageAveragingLevel(level_);

Regions

The API functions in this section control creating and using regions.

                      CreateRegion

Description

Create a point, line, rectangle, or oval region.  The value of the passed parameter shape_ determines the shape of the region: 1 for a point, 2 for a line, 3 for a rectangle, and 4 for an oval.  The values of the passed parameter par1_, par2_, par3_, and par4_ determine the location (and in some cases the size) of the Rgion created according to the following table.  Parameters must have values that allow the Region to be created within the image.

New Regions: Regions are added to the bottom of the list of Regions.

Region Shape
par1_
Par2_
par3_
par4_
Point
left location
top location
not used
not used
Line
left location of first point
top location of first point
left location of second point
top location of second point
Rectangle
left location left location of upper left corner
top location of upper left corner
rectangle width
rectangle height
Oval
left location of center
top location of center
oval width
oval height

Image origin: The top left corner of the image has values of left = 0 and top = 0.

C# Declaration

public short CreateRegionRectangle(Byte shape_, Int32 par1_, Int32 par2_, Int32 par3_, Int32 par4_)

C# Example

Byte shape_ = 3; //create a rectangle region
Int32 par1_ = 10;
Int32 par2_ = 50;
Int32 par3_ = 60;
Int32 par4_ = 100;
Int16 return_ = ThermalyzeExe_.CreateRegion(shape_, par1_, par2_, par3_, par4_);

                      SelectRegion

Description

Select a Region.  The value of the passed parameter regionIndex_ determines the index of the region to be selected (1 is the index of the first region).  Pass the value of 0 to select no region.

This function has the same functionality as clicking a Region row in the Region Data Grid within Thermalyze.

C# Declaration

public short SelectRegion(Byte regionIndex_)

C# Example

Byte regionIndex_ = 1; //select the first region
Int16 return_ = ThermalyzeExe_.SelectRegion(regionIndex_);

                      SetSelectedRegionSettings

Description

Assign the settings for the currently selected Region (or the default Region when no Region is selected).  The acceptable values of the passed parameter name_, emissivity_, statistic_, highLimit_, lowLimit_, highLimitSub_ and lowLimitSub_ are listed in the following table.

name_
20 ASCII characters including letters, numbers, underscores, dashes, and spaces
emissivity_
0.01 to 1.00
statistic_
0 = none, 1 = max, 2 = min, 3 = mean, 4 = max and min
highLimit_
-40 to 500°C
lowLimit_
-40 to 500°C
highLimitSub_
-40 to 500°C
lowLimitSub_
-40 to 500°C

New Regions: The Region Settings window must be open when calling this function.  The value of highLimit_ cannot be equal to or below the value of lowLimit_.  Likewise, the value of highLimitSub_ cannot be equal to or below the value of lowLimitSub_.

C# Declaration

public short SetSelectedRegionSettings(String name_, Double emissivity_, Byte statistic_, Double highLimit_, Double lowLimit_, Double highLimitSub_, Double lowLimitSub_)

C# Example

String name_ = “Capacitor U51”;
Double emissivity_ = 0.95;
Byte statistic_ = 1; //max statistic
Double highLimit_ = 100; //100°C
Double lowLimit_ = 0; //0°C
Double highLimitSub_ = 10; //10°C
Double lowLimitSub_ = -10; //-10°C
Int16 return_ = ThermalyzeExe_.SetSelectedRegionSettings(name_, emissivity_, statistic_, highLimit_, lowLimit_, highLimitSub_, lowLimitSub_);

                      DeleteSelectedRegion

Description

Delete the currently selected a region.  A Region must first be selected before it can be deleted (see the function SelectRegion).

This function has the same functionality as pressing the Delete Region button on the Region toolbar within Thermalyze.

C# Declaration

public Int16 DeleteSelectedRegion()

C# Example

Int16 return_ = ThermalyzeExe_.DeleteSelectedRegion();

                      DeleteAllRegions

Description

Delete all existing Regions.  This function has the same functionality as pressing the Delete All Regions button on the Region toolbar within Thermalyze.

C# Declaration

public Int16 DeleteAllRegions()

C# Example

Int16 return_ = ThermalyzeExe_.DeleteAllRegions();

                      MoveSelectedRegion

Description

Move the currently selected region.  A Region must first be selected before it can be moved (see the function SelectRegion).  The value of the passed parameter direction_ determines the direction to move the region: 1 is left, 2 is right, 3 is up, and 4 is down. The value of the passed parameter pixels_ determines the number of pixels to move the region.  Regions can be moved a maximum of 1000 pixels in any direction.

C# Declaration

public Int16 MoveSelectedRegion(Byte direction_, Int32 pixels_)

C# Example

Byte direction_ = 2; // move to the right
Int32 pixels_ = 10; // move 10 pixels
Int16 return_ = ThermalyzeExe_.MoveSelectedRegion(direction_, pixels_);

                      GetRegionStatistics

Description

Read the maximum, minimum, and mean temperature statistics of a Region drawn on the thermal image.  The value of the passed parameter regionIndex_ determines the index of the Region (1 is the index of the first region).  The returned parameters max_, min_, and mean_ contain the statistics as signed 16 bit integer values.  These values can easily be converted to units of degrees Celsius or radiant emittance [W/m²].

C# Declaration

public Int16 GetRegionStatistics(Byte regionIndex_, ref Int16 max_, ref Int16 min_, ref Int16 mean_)

C# Example

Byte regionIndex = 0;
Int16 max_ = 0;
Int16 min_ = 0;
Int16 mean_ = 0;
Int16 return_ = ThermalyzeExe_.GetRegionStatistics(regionIndex_, ref max_, ref min_, ref mean_);
Double maxDegreesC_ = (max_ + 18000) / 100;

                      SaveRegions

Description

Save the currently existing Regions to file in ASCII text format with .rgn extension.  This function has the same functionality as selecting the Save Regions menu item within Thermalyze.

Note: This function will overwrite existing files.

C# Declaration

public Int16 SaveRegions(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\\Optotherm\\Thermalyze\\Regions\regions1.rgn";
Int16 return_ = ThermalyzeExe_.SaveRegions(filename_);

                      OpenRegions

Description

Open and display Regions from file.  Regions must be in ASCII text formate format with .rgn extension.  This function has the same functionality as selecting the Open Regions menu item within Thermalyze.

C# Declaration

public Int16 Open Regions(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\\Optotherm\\Thermalyze\\Regions\\regions1.rgn";
Int16 return_ = ThermalyzeExe_.OpenRegions(filename_);

Emissivity Settings

The API functions in this section control emissivity settings.

                      SetBackgroundTemperature

Description

Set the temperature of the ambient environment surrounding the object to be measured.  The value of the passed parameter backTempC_ is the background temperature in degress Celsius.  The acceptable range for this parameter is -40 to 500°C.

This function has the same functionality as entering a value into the Background Temperature field in the Emissivity Settings window.

Open Window: The Emissivity Settings window must be open when calling this function.

C# Declaration

public Int16 SetBackgroundTemperature(Double backTempC_)

C# Example

Double backTempC_ = 23.5; //set background temperature to 23.5°C
Int16 return_ = ThermalyzeExe_.SetBackgroundTemperature(backTempC_);

                      SetUseCameraTemp

Description

Set the camera temperature to be used as the background temperature (see SetBackgroundTemperature).  The value of the passed parameter useCamTemp_ determines if the camera temperature will not be used (0) or will be used (1) for the background temperature.

This function has the same functionality as checking or unchecking the Use Camera Temp box in the Emissivity Settings window.

Open Window: The Emissivity Settings window must be open when calling this function.

C# Declaration

public Int16 SetUseCameraTemp(Byte useCamTemp_)

C# Example

Byte useCamTemp_ = 1; //use the camera temperature for the background temp
Int16 return_ = ThermalyzeExe_.SetUseCameraTemp(useCamTemp_);

Emissivity Tables

The API functions in this section control creating and applying emissivity tables.

                      ETablesWindowOpen

Description

Open the Emissivity Tables window.  Many of the functions involving emissivity tables require that the Emissivity Tables window is open while calling the function.

This function has the same functionality as selecting the Emissivity Tables item under the Tools menu within Thermalyze.

C# Declaration

public Int16 ETablesWindowOpen()

C# Example

Int16 return_ = ThermalyzeExe_.ETablesWindowOpen();

                      ETablesWindowClose

Description

Close the Emissivity Tables window.

C# Declaration

public Int16 ETablesWindowClose()

C# Example

Int16 return_ = ThermalyzeExe_.ETablesWindowClose();

                      SetETablesControlTemp

Description

Set the emissivity table control temperature.  The value of the passed parameter controlTempC_ is the emissivity tables control temperature in degrees Celsius.  The acceptable range for this parameter is -40 to 500°C.

This function has the same functionality as entering a value into the Control Temp field in the Emissivity Tables window.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 SetETablesControlTemp(Double controlTempC_)

C# Example

Double controlTempC_ = 60; //set the control temperature to 60°C
Int16 return_ = ThermalyzeExe_.SetETablesControlTemp(controlTempC_);

                      CreateETable

Description

Create a single or double temperature point emissivity table.  The value of the passed parameter eTableType_ determines which emissivity table to create: 1 to create single point table one, 2 to create single point table two, and 3 to create the double point table.

This function has the same functionality as pressing the Create Single Point 1, Create Single Point 2, or Create Double Point button in the Emissivity Tables window.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 CreateETable(Byte eTableType_)

C# Example

Byte eTableType_= 1; //create single point table one
Int16 return_ = ThermalyzeExe_.CreateETable(eTableType_);

                      ETableAmbientCorrection

Description

Correct for any changes in ambient background characteristics since emissivity tables were created.  This function has the same functionality as pressing the Ambient Correction button in the Emissivity Tables window.

Note: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 ETableAmbientCorrection()

C# Example

Int16 return_ = ThermalyzeExe_.ETableAmbientCorrection();

                      SetETableAmbientCorrectionActive

Description

Apply the ambient correction to the emissivity tables.  The value of the passed parameter activate_ determines if the ambient correction will be activated or not: 0 to deactivate, and 1 to activate.

This function has the same functionality as checking the Active box in the Emissivity Tables window.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 SetETableAmbientCorrectionActive(Byte activate_)

C# Example

Byte activate_= 1; //activate the ambient correction
Int16 return_ = ThermalyzeExe_.SetETableAmbientCorrectionActive(activate_);

                      SelectActiveETable

Description

Select the emissivity table to apply to the displayed thermal image.  The value of the passed parameter activeETable_ determines which emissivity table to select: 0 to select no table, 1 to select single point table one, 2 to select single point table two, 3 to select the double point table, and 4 to select the table opened from file.

This function has the same functionality as selecting an option in the Select Active Table group in the Emissivity Tables window.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 SelectActiveETable(Byte activeETable_)

C# Example

Byte activeETable_= 1; //select single point table one
Int16 return_ = ThermalyzeExe_.SelectActiveETable(activeETable_);

                      ReadActiveETable

Description

Read the emissivity table that is currently active.  When this function returns THERMALYZE_ERROR_NONE, the returned parameter eTable_ contains the active emissivity table in the form of a two-dimensional array of signed 16 bit integer pixel values.  These pixel values can easily be converted to emissivity with resolution of 0.001.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 ReadActiveETable(ref PixelValue2D eTable_)

C# Example

PixelValue2D eTable_ = null;
Int16 return_ = ThermalyzeExe_.ReadActiveETable(ref eTable_);
for (Int32 row_ = 0; row_ <= 239; row_++)
{
    for (Int32 column_ = 0; column_ <= 319; column_++)
    {
        Double emissivity_ = (eTable_.I16[row_, column_] / 1000);
        // emissivity_ now holds the pixel emissivity value with range from 0 to 1 with
        // resolution of 0.001 at location [row_, column_]
    }
}

                      SaveETable

Description

Save the active emissivity table in Portable Network Graphics (PNG) format with .png extension.  PNG is a 16 bit lossless format that preserves emissivity value resolution of 0.001 and is the native format for saving emissivity tables within Thermalyze.

This function has the same functionality as selecting the Save Table item on the Emissivity Tables window menu.

Open Window: The Emissivity Tables window must be open when calling this function.

Overwrite: This function will overwrite existing files.

C# Declaration

public Int16 SaveETable(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\\Optotherm\\Thermalyze\\Emissivity Tables\etable1.png";
Int16 return_ = ThermalyzeExe_.SaveETable (filename_);

                      OpenETable

Description

Open an emissivity table from file.  Emissivity table files must be in Portable Network Graphics (PNG) format with .png extension.  PNG is a 16 bit lossless format that preserves emissivity value resolution of 0.001 and is the native format for saving emissivity tables within Thermalyze.

This function has the same functionality as selecting the Open Table item on the Emissivity Tables window menu.

Open Window: The Emissivity Tables window must be open when calling this function.

C# Declaration

public Int16 OpenETable(string filename_)

C# Example

String filename_ = null;
filename_ = "c:\\Optotherm\\Thermalyze\\Emissivity Tables\\etable1.png";
Int16 return_ = ThermalyzeExe_.OpenETable(filename_);

Lock-in Thermography

The API functions in this section control running lock-in thermography tests.

                      LITWindowOpen

Description

Open the Lock-in Thermography window.

C# Declaration

public Int16 LITWindowOpen()

C# Example

Int16 return_ = ThermalyzeExe_.LITWindowOpen();

                      LITWindowClose

Description

Open the Lock-in Thermography window.

C# Declaration

public Int16 LITWindowClose()

C# Example

Int16 return_ = ThermalyzeExe_.LITWindowClose();

                      LITCycleFrequencySet

Description

Cycle Frequency is the number of power cycles performed per second.  Acceptable values for this parameter are shown in the table below.

This function has the same functionality as choosing an option from the Cycle Frequency frame in the LIT Test Setup window.

Value
Cycle Frequency
0 1 Hz
1 1.25 Hz
2 1.5 Hz
3 1.875 Hz
4 2.5 Hz
5 3 Hz
6 3.75 Hz
7 5 Hz
8 7.5 Hz
9 15 Hz
10 Cycle Time

C# Declaration

public Int16 LITCycleFrequencySet(Byte value_)

C# Example

Byte value_ = 0; //set Cycle Frequency to 1 Hz
Int16 return_ = ThermalyzeExe_.LITCycleFrequencySet(value_);

                      LITCycleTimeSet

Description

For frequencies below 1 Hz, set Cycle Time to the length of one cycle. Values range from 2 to 60 seconds.

This function has the same functionality as entering a value in the Cycle Time box in the LIT Test Setup window.

C# Declaration

public Int16 LITCycleTimeSet(Byte value_)

C# Example

Byte value_ = 4; //set Cycle Time to 4 seconds
Int16 return_ = ThermalyzeExe_.LITCycleTimeSet(value_);

                      LITTestStart

Description

Start a Lock-in Thermography tests.

This function has the same functionality as pressing the ON button in the Testing frame of the Lock-in Thermography window.

C# Declaration

public Int16 LITTestStart()

C# Example

Int16 return_ = ThermalyzeExe_.LITTestStart();

                      LITTestStop

Description

Stop the Lock-in Thermography tests.

This function has the same functionality as pressing the OFF button in the Testing frame of the Lock-in Thermography window.

C# Declaration

public Int16 LITTestStop()

C# Example

Int16 return_ = ThermalyzeExe_.LITTestStop();

                      LITAmplitudeImageGet

Description

Create and retrieve the Lock-in Thermography amplitude image.  An amplitude image displays all temperature increases on a device at any time during the cycle and is commonly used to determine fault location in the xy direction.   The returned parameter imageArray_ contains the amplitude image in the form of a two-dimensional array of unsigned 16 bit integer pixel values.  Pixel values can be converted to units of degrees mK (0.001°C).

Units: Image units are in degrees mK when Test Resolution is set to 10 microK.  If Test Resolution is set to 10 mK, image units will be in degrees C.

C# Declaration

public Int16 LITAmplitudeImageGet(ref UInt16[,] imageArray_)

C# Example

public UInt16 [,] imageArray_ = new UInt16 [480, 640];    //640 rows, 480 columns
Int16 return_ = ThermalyzeExe_.LITAmplitudeImageGet(ref imageArray_);
for (Int32 y_ = 0; y_ < 480; y_++)
{
    for (Int32 x_ = 0; x_ < 640; x_++)
    {
        Double pixTemp_mK_ = (imageArray_[y_, x_] - 10000) / (Double)100;
        //pixTempC_ now holds the amplitude image pixel value in units of temperature in
        //degrees mK (0.001°C) at location [y_, x_]
    }
}

                      LITSinglePhaseAngleSet

Description

Set the Single Phase Angle.

This function has the same functionality as dragging the Single Phase Angle trackbar handle in the Lock-in Thermography window.

The available phase angles depend on Cycle Frequency and are equally distributed within the range of 0 to -360 degrees. The number of phase angle increments is determined by the following equation: Number Phase Increments = Camera Frame Rate / Test Cycle Frequency. For example, the number of phase increments when Cycle Frequency is set to 5Hz = 60Hz / 5Hz = 12. Dividing the range of 0 to -360 by 12 yields 30 degrees. Therefore, the available phase angles are 0, -30, -60, -90, -120, -150. -180, -210, -240, -270, -300, -330, and -360 degrees.  Note that for Cycle Frequency of 1Hz and all values of Cycle Time, the number of phase angle increments is equal to 60.  In the table below, the phase angle increments and available phase angles are show for each Cycle Frequency.

Cycle Frequency
# Increments
Increment [degrees]
Available Phase Angles
1Hz and all Cycle Times
60
6
-360, -354, -348, -342, -336, -330
1.25Hz
48
7.5
-360, -352.5, -345, -337.5, -330, -322.5, -315, -307.5, -300, -292.5, -285, -277.5, -270, -262.5, -255, -247.5, -240, -232.5, -225, -217.5, -210, -202.5, -195, -187.5, -180, -172.5, -165, -157.5, -150, -142.5, -135, -127.5, -120, -112.5, -105, -97.5, -90, -82.5, -75, -67.5, -60, -52.5, -45, -37.5, -30, -22.5, -15, -7.5, 0
1.5Hz
40
9
-360, -351, -342, -333, -324, -315, -306, -297, -288, -279, -270, -261, -252, -243, -234, -225, -216, -207, -198, -189, -180, -171, -162, -153, -144, -135, -126, -117, -108, -99, -90, -81, -72, -63, -54, -45 ,-36, -27, -18, 9, 0
1.875Hz
32
11.25
-360, -348.75, -337.5, -326.25, -315, -303.75, -292.5, -281.25, -270, -258.75, -247.5, -236.25, -225, -213.75, -202.5, -191.25, -180, -168.75, -157.5, -146.25, -135, -123.75, -112.5, -101.25, -90, -78.75, -67.5, -56.25, -45, -33.75, -22.5, -11.25, 0
2.5Hz
24
15
-360, -345, -330, -315, -300, -285, -270, -255, -240, -225, -210, -195, -180, -165, -150, -135, -120, -105, -90, -75, -60, -45, -30, -15, 0
3Hz
20
18
-360, -342, -324, -306, -288, -270, -252, -234, -216, -198, -180, -162, -144, -126, -108, -90, -72, -54, -36, -18, 0
3.75Hz
16
22.5
-360, -337.5, -315, -292.5, -270, -247.5, -225, -202.5, -180, -157.5, -135, -112.5, -90, -67.5, -45, -22.5, 0
5Hz
12
30
-360, -330, -300, -270, -240, -210, -180, -150, -120, -90, -60, -30, 0
7.5Hz
8
45
-360, -315, -270, -225, -180, -135, -90, -45, 0
15Hz
4
90
-360, -270, -180, -90, 0

C# Declaration

public Int16 LITSinglePhaseAngleSet(Int16 value_)

C# Example

Int16 value_ = -12; //set Single Phase Angle to -12 degrees
Int16 return_ = ThermalyzeExe_.LITSinglePhaseAngleSet(value_);

                      LITSinglePhaseImageGet

Description

Create and retrieve the Lock-in Thermography single phase image.  A single phase image displays temperature increases at a specific time in the cycle. The time within the cycle can be expressed as a phase angle with 0 degrees representing the beginning of the cycle when a device is powered and -180 degrees representing when power is removed. A phase angle of 360 degrees represents the end of the cycle and is equivalent to a phase angle of 0 degrees. Single phase images are is used to locate faults in the xy direction. They can also identify areas that heat up at different times within the cycle providing a correlation with defect depth. Single phase images typically produce the highest xy spatial resolution of all LIT images.

The returned parameter imageArray_ contains the single phase image in the form of a two-dimensional array of unsigned 16 bit integer pixel values.  Pixel values can be converted to units of degrees mK (0.001°C).

Units: Image units are in degrees mK when Test Resolution is set to 10 microK.  If Test Resolution is set to 10 mK, image units will be in degrees C.

C# Declaration

public Int16 LITSinglePhaseImageGet(ref UInt16[,] imageArray_, Byte phaseAngle_)

C# Example

public UInt16 [,] imageArray_ = new UInt16 [480, 640];    //640 rows, 480 columns
Int16 return_ = ThermalyzeExe_.LITSinglePhaseImageGet(ref imageArray_, Byte phaseAngle_);
for (Int32 y_ = 0; y_ < 480; y_++)
{
    for (Int32 x_ = 0; x_ < 640; x_++)
    {
        Double pixTemp_mK_ = (imageArray_[y_, x_] - 10000) / (Double)100;
        //pixTempC_ now holds the single phase image pixel value in units of temperature in
        //degrees mK (0.001°C) at location [y_, x_]
    }
}

                      LITTestClear

Description

Clear all existing test data from memory in order to begin a new test.

This function has the same functionality as pressing the Clear Test button in the Testing frame of the Lock-in Thermography window.

C# Declaration

public Int16 LITTestClear()

C# Example

Int16 return_ = ThermalyzeExe_.LITTestClear();