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):
-
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.
-
Add function return constants.
-
Add a reference to the Thermalyze.exe file from your program. The default folder during Thermalyze installation is C:\Program Files\Optotherm\Thermalyze.
-
Declare an object variable of type Thermalyze.clsApi.
-
Check that a Thermalyze.clsApi object has not already been instantiated.
-
Instantiate a Thermalyze.clsApi object.
-
Start the Thermalyze program by calling the API function StartThermalyze.
-
(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();