TSI Camera API Manual Application Programming Interface Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 31
| Download | |
| Open PDF In Browser | View PDF |
Application Programming
Interface (API)
TSI Camera SDK
Chapter 1: Description
Table of Contents
Chapter 1
Description ........................................................................................................................... 4
1.1. TSI Camera SDK .............................................................................................................. 4
1.1.1. Imaging Concepts ................................................................................................................. 4
Chapter 2
C++ API ................................................................................................................................. 5
2.1. Enumerations .................................................................................................................. 5
2.1.1. TS_ATTR_ID ......................................................................................................................... 5
2.1.2. TSI_DATA_TYPE .................................................................................................................. 5
2.1.3. TSI_PARAM_FLAGS ............................................................................................................ 5
2.1.4. TSI_CAMERA_STATUS ....................................................................................................... 6
2.1.5. TSI_ERROR_CODE ............................................................................................................. 6
2.1.6. TSI_ACQ_STATUS_ID ......................................................................................................... 7
2.1.7. TSI_CAMERA_CONTROL_EVENT_ID ................................................................................ 7
2.1.8. TSI_IMAGE_NOTIFICATION_EVENT_ID ............................................................................ 7
2.1.9. TSI_PARAM_ID .................................................................................................................... 7
2.1.10.TSI_IMAGE_MODE .............................................................................................................. 9
2.1.11.TSI_HW_TRIG_SOURCE..................................................................................................... 9
2.1.12.TSI_HW_TRIG_POLARITY .................................................................................................. 9
2.1.13.TSI_OP_MODE ..................................................................................................................... 9
2.1.14.TSI_EXPOSURE_UNITS .................................................................................................... 10
2.1.15.TSI_ADDRESS_SELECT ................................................................................................... 10
2.2. Data Types ..................................................................................................................... 10
2.2.1.
2.2.2.
2.2.3.
2.2.4.
2.2.5.
2.2.6.
TSI_ROI_BIN ...................................................................................................................... 10
TSI_FUNCTION_CAMERA_CONTROL_INFO .................................................................. 10
TSI_FUNCTION_CAMERA_CONTROL_CALLBACK ........................................................ 11
TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX ................................................. 11
TSI_FUNCTION_IMAGE_NOTIFICATION_CALLBACK .................................................... 11
TSI_FUNCTION_IMAGE_CALLBACK ............................................................................... 11
2.3. TsiSdk Class .................................................................................................................. 11
2.3.1. Constructor / Destructor ...................................................................................................... 11
2.3.2. Methods............................................................................................................................... 12
TsiSdk::Open _____________________________________________________________12
TsiSdk::Close _____________________________________________________________12
TsiSdk::GetNumberOfCameras _______________________________________________12
TsiSdk::GetCamera ________________________________________________________12
TsiSdk::GetCameraInterfaceTypeStr ___________________________________________13
TsiSdk::GetCameraAddressStr _______________________________________________13
TsiSdk::GetCameraName ___________________________________________________13
TsiSdk::ElapsedTime _______________________________________________________13
TsiSdk::GetLastErrorStr _____________________________________________________13
TsiSdk::GetErrorCode ______________________________________________________14
TsiSdk::ClearError _________________________________________________________14
TsiSdk::GetErrorString ______________________________________________________14
TsiSdk::GetUtilityObject _____________________________________________________14
2.4. TsiCamera Class ........................................................................................................... 15
2.4.1. METHODS .......................................................................................................................... 15
TsiCamera::Open__________________________________________________________15
TsiCamera::Close _________________________________________________________15
TsiCamera::Status _________________________________________________________15
TsiCamera::GetCameraName ________________________________________________16
TsiCamera::SetCameraName ________________________________________________16
ITN000195-D02 Rev. A June 12, 2014
Page 2
TSI Camera SDK
Chapter 1: Description
TsiCamera::GetParameter ___________________________________________________16
TsiCamera::GetDataTypeSize ________________________________________________16
TsiCamera::SetTextCommand _______________________________________________17
TsiCamera::SetTextCallback _________________________________________________17
TsiCamera::SetParameter ___________________________________________________17
TsiCamera:: SetCameraControlCallback ________________________________________17
TsiCamera:: SetCameraControlCallbackEx ______________________________________18
The TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX type definition above describes
the function header for the callback function._____________________________________18
TsiCamera:: SetImageNotificationCallback ______________________________________18
TsiCamera:: SetImageCallback _______________________________________________19
TsiCamera::ResetCamera ___________________________________________________19
TsiCamera::FreeImage _____________________________________________________19
TsiCamera::FreeAllPendingImages ____________________________________________19
TsiCamera::GetPendingImage _______________________________________________20
TsiCamera::GetLastPendingImage ____________________________________________20
TsiCamera::StartAndWait ___________________________________________________20
TsiCamera::Start __________________________________________________________20
TsiCamera::Stop __________________________________________________________21
TsiCamera::GetAcquisitionStatus _____________________________________________21
TsiCamera::GetExposeCount ________________________________________________21
TsiCamera::GetFrameCount _________________________________________________21
TsiCamera::WaitForImage ___________________________________________________22
TsiCamera::ResetExposure __________________________________________________22
TsiCamera::GetErrorCode ___________________________________________________22
TsiCamera::ClearError ______________________________________________________22
TsiCamera::GetErrorStr _____________________________________________________23
TsiCamera::GetLastErrorStr _________________________________________________23
2.4.2. List of Camera Parameters ................................................................................................. 24
2.5. TsiImage Class .............................................................................................................. 28
2.5.1. DATA MEMBERS ............................................................................................................... 28
2.5.2. METHODS .......................................................................................................................... 28
TsiImage::Copy ___________________________________________________________28
TsiImage::Clone ___________________________________________________________29
2.6. TsiUtil Class ................................................................................................................... 29
2.6.1. METHODS .......................................................................................................................... 29
TsiUtil:WriteImageToTIFF ___________________________________________________29
TsiUtil:WriteImageToPNG ___________________________________________________29
Chapter 3
Thorlabs Worldwide Contacts ..........................................................................................30
ITN000195-D02 Rev. A June 12, 2014
Page 3
TSI Camera SDK
Chapter 1
1.1.
Chapter 1: Description
Description
TSI Camera SDK
The TSI Imaging SDK consists of Libraries, Drivers, Documentation, and Examples that make it easy to
incorporate a TSI camera into your system.
1.1.1. Imaging Concepts
Basic steps to get image from camera:
1) TsiSDK *sdk = get_tsi_sdk(0); //Obtain a reference to the sdk using the static function
2) bool success = sdk->Open(); //Open the SDK
3) int numCameras = sdk->GetNumberOfCameras(); //Get the number of available cameras
4) TsiCamera *cam = sdk->GetCamera(0..numCameras-1); //Get a reference to a camera
a. cam->Open(); //Open the camera
b. Register for desired events (ImageNotification, ControlCallback, etc)
c.
Set/Get desired camera parameters
d. cam->Start();
e. Acquire images (see step 5)
f.
cam->Stop();
5) Access the TsiImage from the appropriate callback and use the pointer to the data.
a. TsiImage *image = cam->GetPendingImage(); //Call GetPendingImage in Notify Callback
i. Alternatively, just receive the image in the parameters of Image Callback
ii. Make sure image pointer isn’t null
iii. Check error codes in callbacks as necessary
b. Remember to call cam->FreeImage(image); ASAP to clear the buffer for incoming images
6) cam->Close(); //Close the camera when you are done
7) sdk->Close(); //Close the SDK when done
8) release_tsi_sdk(sdk); //Release the resources used by the SDK
ITN000195-D02 Rev. A June 12, 2014
Page 4
TSI Camera SDK
Chapter 2
2.1.
Chapter 2: C++ API
C++ API
Enumerations
2.1.1. TS_ATTR_ID
typedef enum _TSI_ATTR_ID
{
TSI_ATTR_NAME,
TSI_ATTR_DATA_TYPE,
TSI_ATTR_ARRAY_COUNT,
TSI_ATTR_FLAGS,
TSI_ATTR_MIN_VALUE,
TSI_ATTR_MAX_VALUE,
TSI_ATTR_DEFAULT_VALUE,
TSI_MAX_ATTR
} TSI_ATTR_ID, *PTSI_ATTR_ID;
2.1.2. TSI_DATA_TYPE
typedef enum _TSI_DATA_TYPE
{
TSI_TYPE_NONE,
TSI_TYPE_UNS8,
TSI_TYPE_UNS16,
TSI_TYPE_UNS32,
TSI_TYPE_UNS64,
TSI_TYPE_INT8,
TSI_TYPE_INT16,
TSI_TYPE_INT32,
TSI_TYPE_INT64,
TSI_TYPE_TEXT,
TSI_TYPE_FP,
TSI_MAX_TYPES
} TSI_DATA_TYPE;
2.1.3. TSI_PARAM_FLAGS
typedef enum _TSI_PARAM_FLAGS
{
TSI_FLAG_READ_ONLY
TSI_FLAG_WRITE_ONLY
TSI_FLAG_UNSUPPORTED
TSI_FLAG_VALUE_CHANGED
=
=
=
=
0x00000001,
0x00000002,
0x00000004,
0x00000008
} TSI_PARAM_FLAGS;
ITN000195-D02 Rev. A June 12, 2014
Page 5
TSI Camera SDK
Chapter 2: C++ API
2.1.4. TSI_CAMERA_STATUS
typedef enum _TSI_CAMERA_STATUS
{
TSI_STATUS_CLOSED,
TSI_STATUS_OPEN,
TSI_STATUS_BUSY,
TSI_STATUS_MAX
} TSI_CAMERA_STATUS;
2.1.5. TSI_ERROR_CODE
typedef enum _TSI_ERROR_CODE
{
TSI_NO_ERROR,
TSI_ERROR_UNKNOWN,
TSI_ERROR_UNSUPPORTED,
TSI_ERROR_PARAMETER_UNSUPPORTED,
TSI_ERROR_ATTRIBUTE_UNSUPPORTED,
TSI_ERROR_INVALID_ROI,
TSI_ERROR_INVALID_BINNING,
TSI_ERROR_INVALID_PARAMETER_UNDERFLOW,
TSI_ERROR INVALID_PARAMETER_OVERFLOW,
TSI_ERROR_CAMERA_COMM_FAILURE,
TSI_ERROR_CAMERA_INVALID_DATA,
TSI_ERROR_NULL_POINTER_SUPPLIED,
TSI_CAMERA_INVALID_DATA_SIZE_OR_TYPE,
TSI_MAX_ERROR
} TSI_ERROR_CODE, *PTSI_ERROR_CODE;
ITN000195-D02 Rev. A June 12, 2014
Page 6
TSI Camera SDK
Chapter 2: C++ API
2.1.6. TSI_ACQ_STATUS_ID
typedef enum _TSI_ACQ_STATUS_ID
{
TSI_ACQ_STATUS_IDLE,
TSI_ACQ_STATUS_WAITING_FOR_TRIGGER,
TSI_ACQ_STATUS_EXPOSING,
TSI_ACQ_STATUS_READING_OUT,
TSI_ACQ_STATUS_DONE,
TSI_ACQ_STATUS_ERROR,
TSI_ACQ_STATUS_TIMEOUT,
TSI_MAX_ACQ_STATUS_ID
} TSI_ACQ_STATUS_ID;
2.1.7. TSI_CAMERA_CONTROL_EVENT_ID
typedef enum _TSI_CAMERA_CONTROL_EVENT_ID
{
TSI_CAMERA_CONTROL_EXPOSURE_START
,
TSI_CAMERA_CONTROL_EXPOSURE_COMPLETE ,
TSI_CAMERA_CONTROL_SEQUENCE_START
,
TSI_CAMERA_CONTROL_SEQUENCE_COMPLETE ,
TSI_CAMERA_CONTROL_READOUT_START
,
TSI_CAMERA_CONTROL_READOUT_COMPLETE ,
TSI_MAX_CAMERA_CONTROL_EVENT_ID
} TSI_CAMERA_CONTROL_EVENT_ID;
2.1.8. TSI_IMAGE_NOTIFICATION_EVENT_ID
typedef enum _TSI_IMAGE_NOTIFICATION_EVENT_ID
{
TSI_IMAGE_NOTIFICATION_PENDING_IMAGE,
TSI_IMAGE_NOTIFICATION_ACQUISITION_ERROR,
TSI_MAX_IMAGE_NOTIFICATION_EVENT_ID
} TSI_IMAGE_NOTIFICATION_EVENT_ID;
2.1.9.
TSI_PARAM_ID
typedef enum _TSI_PARAM_ID
{
TSI_PARAM_CMD_ID_ATTR_ID
TSI_PARAM_ATTR
TSI_PARAM_PROTOCOL
TSI_PARAM_FW_VER
ITN000195-D02 Rev. A June 12, 2014
,
,
,
,
Page 7
TSI Camera SDK
Chapter 2: C++ API
TSI_PARAM_HW_VER
,
TSI_PARAM_HW_MODEL
,
TSI_PARAM_HW_SER_NUM
,
TSI_PARAM_CAMSTATE
,
TSI_PARAM_CAM_EXPOSURE_STATE
,
TSI_PARAM_CAM_TRIGGER_STATE
,
TSI_PARAM_EXPOSURE_UNIT
,
TSI_PARAM_EXPOSURE_TIME
,
TSI_PARAM_ACTUAL_EXPOSURE_TIME ,
TSI_PARAM_HSIZE
,
TSI_PARAM_VSIZE
,
TSI_PARAM_ROI_BIN
,
TSI_PARAM_FRAME_COUNT
,
TSI_PARAM_CURRENT_FRAME
,
TSI_PARAM_OP_MODE
,
TSI_PARAM_CDS_GAIN_INDEX
,
TSI_PARAM_CDS_GAIN = TSI_PARAM_CDS_GAIN_INDEX,
TSI_PARAM_VGA_GAIN
,
TSI_PARAM_GAIN
,
TSI_PARAM_OPTICAL_BLACK_LEVEL ,
TSI_PARAM_PIXEL_OFFSET
,
TSI_PARAM_READOUT_SPEED_INDEX ,
TSI_PARAM_READOUT_SPEED
,
TSI_PARAM_FRAME_TIME
,
TSI_PARAM_FRAME_RATE
,
TSI_PARAM_COOLING_MODE
,
TSI_PARAM_COOLING_SETPOINT
,
TSI_PARAM_TEMPERATURE
,
TSI_PARAM_QX_OPTION_MODE
,
TSI_PARAM_TURBO_MODE
,
TSI_PARAM_TURBO_CODE_MODE = TSI_PARAM_TURBO_MODE,
TSI_PARAM_XORIGIN
,
TSI_PARAM_YORIGIN
,
TSI_PARAM_XPIXELS
,
TSI_PARAM_YPIXELS
,
TSI_PARAM_XBIN
,
TSI_PARAM_YBIN
,
TSI_PARAM_IMAGE_ACQUISTION_MODE,
TSI_PARAM_NAMED_VALUE
,
TSI_PARAM_TAPS_INDEX
,
TSI_PARAM_TAPS_VALUE
,
TSI_PARAM_RESERVED_1
,
TSI_PARAM_RESERVED_2
,
TSI_PARAM_RESERVED_3
,
TSI_PARAM_RESERVED_4
,
TSI_PARAM_GLOBAL_CAMERA_NAME
,
TSI_PARAM_CDS_GAIN_VALUE
,
TSI_PARAM_PIXEL_SIZE
,
TSI_PARAM_BITS_PER_PIXEL
,
TSI_PARAM_BYTES_PER_PIXEL
,
TSI_PARAM_READOUT_TIME
,
TSI_PARAM_HW_TRIGGER_ACTIVE
,
TSI_PARAM_HW_TRIG_SOURCE
,
TSI_PARAM_HW_TRIG_POLARITY
,
TSI_PARAM_TAP_BALANCE_ENABLE
,
ITN000195-D02 Rev. A June 12, 2014
Page 8
TSI Camera SDK
Chapter 2: C++ API
TSI_MAX_PARAMS
} TSI_PARAM_ID;
2.1.10. TSI_IMAGE_MODE
typedef enum _TSI_IMAGE_MODES
{
TSI_IMAGE_MODE_ALLOCATE ,
TSI_IMAGE_MODE_STREAM
,
TSI_IMAGE_MODE_TRIGGER ,
TSI_MAX_IMAGE_MODES
} TSI_IMAGE_ACQUISTION_MODES;
2.1.11. TSI_HW_TRIG_SOURCE
typedef enum _TSI_HW_TRIG_SOURCE
{
TSI_HW_TRIG_OFF,
TSI_HW_TRIG_AUX,
TSI_HW_TRIG_CL,
TSI_HW_TRIG_MAX
} TSI_HW_TRIG_SOURCE, *PTSI_HW_TRIG_SOURCE;
2.1.12. TSI_HW_TRIG_POLARITY
typedef enum _TSI_HW_TRIG_POLARITY
{
TSI_HW_TRIG_ACTIVE_HIGH,
TSI_HW_TRIG_ACTIVE_LOW,
TSI_HW_TRIG_POL_MAX
} TSI_HW_TRIG_POLARITY, *PTSI_HW_TRIG_POLARITY;
2.1.13. TSI_OP_MODE
typedef enum _TSI_OP_MODE
{
TSI_OP_MODE_NORMAL,
TSI_OP_MODE_PDX,
TSI_OP_MODE_TOE,
TSI_OP_MODE_RESERVED_1,
} TSI_OP_MODE, *PTSI_OP_MODE;
ITN000195-D02 Rev. A June 12, 2014
Page 9
TSI Camera SDK
Chapter 2: C++ API
2.1.14. TSI_EXPOSURE_UNITS
typedef enum _TSI_EXPOSURE_UNITS
{
TSI_EXP_UNIT_MICROSECONDS,
TSI_EXP_UNIT_MILLISECONDS,
TSI_EXP_UNIT_MAX
} TSI_EXPOSURE_UNITS, *PTSI_EXPOSURE_UNITS;
2.1.15. TSI_ADDRESS_SELECT
typedef enum _TSI_ADDRESS_SELECT
{
TSI_ADDRESS_SELECT_IP,
TSI_ADDRESS_SELECT_MAC,
TSI_ADDRESS_SELECT_ADAPTER_ID,
TSI_ADDRESS_SELECT_MAX
} TSI_ADDRESS_SELECT;
2.2.
Data Types
2.2.1. TSI_ROI_BIN
typedef struct _TSI_ROI_BIN {
UNS32
UNS32
UNS32
UNS32
XOrigin;
YOrigin;
XPixels;
YPixels;
UNS32 XBin;
UNS32 YBin;
//
//
//
//
X Origin in sensor array
Y Origin in sensor array
Frame width in pixels
Frame height in pixels
// Binning factor in the X dimension
// Binning factor in the Y dimension
} TSI_ROI_BIN, *PTSI_ROI_BIN;
2.2.2. TSI_FUNCTION_CAMERA_CONTROL_INFO
typedef struct _TSI_FUNCTION_CAMERA_CONTROL_INFO {
uint32_t FrameNumber;
struct {
uint32_t
uint32_t
uint32_t
uint32_t
uint32_t
Year;
Month;
Day;
Hour;
Min;
ITN000195-D02 Rev. A June 12, 2014
Page 10
TSI Camera SDK
Chapter 2: C++ API
uint32_t Sec;
uint32_t MS;
uint32_t US;
} TimeStamp;
} TSI_FUNCTION_CAMERA_CONTROL_INFO,
*PTSI_FUNCTION_CAMERA_CONTROL_INFO;
2.2.3. TSI_FUNCTION_CAMERA_CONTROL_CALLBACK
typedef void (*TSI_FUNCTION_CAMERA_CONTROL_CALLBACK)
(int ctl_event,
void *context);
2.2.4. TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX
typedef void (*TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX )
(int ctl_event,
TSI_FUNCTION_CAMERA_CONTROL_INFO
*ctl_event_info, void *context);
2.2.5. TSI_FUNCTION_IMAGE_NOTIFICATION_CALLBACK
typedef void (*TSI_FUNCTION_IMAGE_NOTIFICATION_CALLBACK)
(int notification,
void *context);
2.2.6. TSI_FUNCTION_IMAGE_CALLBACK
typedef void (*TSI_FUNCTION_IMAGE_CALLBACK)
(TsiImage *tsi_image, void *context);
2.3.
TsiSdk Class
This class provides a framework for all the other classes in the API to exist within.
Instantiating an object of this type and then calling the OpenSDK method instructs the API to examine your
system, searching for and building a list of cameras that it finds.
The CloseSDK (coupled with a subsequent call to OpenSDK) can be used to handle instances where the list of
cameras changes dynamically.
The destructor for the TsiSdk class will first close and delete any camera objects that were allocated, and then
close and clean up the SDK.
2.3.1. Constructor / Destructor
The constructor for the TsiSDK class initializes the library but does not actually build a list of cameras – this
functionality is implemented in the OpenSDK method so that the TsiSdk class does not have to be deleted and
recreated when the list of cameras changes.
ITN000195-D02 Rev. A June 12, 2014
Page 11
TSI Camera SDK
Chapter 2: C++ API
The destructor for this class contains an implicit call to the CloseSDK (see below) method.
2.3.2. Methods
TsiSdk::Open
bool Open();
This method must be called before any other
TsiSdk::Close
bool Close();
This method iterates over the list of cameras, first closing any cameras that have been left open, then
deleting their objects. After calling this method (or destructing an object of type TsiSdk), make sure your
program does not access any TsiCamera objects.
TsiSdk::GetNumberOfCameras
int GetNumberOfCameras ();
This method is used after the OpenSDK method to get a count of the number of cameras the OpenSDK
method found.
TsiSdk::GetCamera
TsiCamera* GetCamera (int CameraNumber);
This method fails if the value returned is NULL.
Otherwise, the pointer returned is to a camera object of type TsiCamera. See TsiCamera class definition
below for more details.
ITN000195-D02 Rev. A June 12, 2014
Page 12
TSI Camera SDK
Chapter 2: C++ API
TsiSdk::GetCameraInterfaceTypeStr
char* GetCameraInterfaceTypeStr (int camera_number );
This method returns a string describing the interface type of the camera.
TsiSdk::GetCameraAddressStr
char* GetCameraAddressStr (int camera_number,
TSI_ADDRESS_SELECT address_select );
This method returns the specified address type for a specified camera.
TsiSdk::GetCameraName
char* GetCameraName (int camera_number );
This method returns a string with the name of the selected camera.
TsiSdk::ElapsedTime
uint64 ElapsedTime (uint64 StartTime);
This method provides a convenient way to calculate the elapsed time in milliseconds between successive
calls to this method.
Calling this method with a start time of zero establishes the start time. Calling the method again, using
the results of the first call will result in the elapsed time in millisconds between those calls being returned.
TsiSdk::GetLastErrorStr
ITN000195-D02 Rev. A June 12, 2014
Page 13
TSI Camera SDK
Chapter 2: C++ API
char* GetLastErrorStr();
Returns the string describing the last error.
TsiSdk::GetErrorCode
TSI_ERROR_CODE GetErrorCode();
Returns the current error code for the SDK, a returned value of zero indicates success. Clears any nonzero error code.
TsiSdk::ClearError
bool ClearError ();
Clears any existing error code for the SDK without having to read it using GetErrorCode.
TsiSdk::GetErrorString
bool GetErrorString(TSI_ERROR_CODE ErrorCode, char
*StringBuffer, int &StringLength)
Returns the non-localized ASCII string description of the supplied error code.
Passing a NULL pointer and pointer to a variable containing a length of zero length results in the length of
the string associated with the supplied error code being returned so that a buffer of appropriate length can
be dynamically allocated.
TsiSdk::GetUtilityObject
TsiUtil* GetUtilityObject ();
ITN000195-D02 Rev. A June 12, 2014
Page 14
TSI Camera SDK
Chapter 2: C++ API
Returns a pointer to an instance of TsiUtil which has some functions for saving out 16-bit tif and png
image formats.
2.4.
TsiCamera Class
Objects of this class are used to control and acquire data from the cameras in your system. You cannot simply
instantiate an object of this type. Instead, instantiate an object of the TsiSdk class, call the OpenSDK method,
and then use the GetCamera method in that class to get a pointer to an object of this type.
2.4.1. METHODS
TsiCamera::Open
bool Open ();
Opens this camera for subsequent communications. The reason for opening and closing cameras is to
conserve resources for cameras that have been enumerated, but are not currently in use.
This method must be called (once) before any other methods other than GetCameraName can be used.
TsiCamera::Close
bool Close ();
This method is called implicitly by the TsiSdk method CloseSDK and it’s destructor, but one can call this
method directly to close the camera to conserve resources when a camera is not needed.
TsiCamera::Status
bool Status (TSI_CAMERA_STATUS *CameraStatus);
This method returns the current status of the camera (see the definition of TSI_CAMERA_STATUS
above). The intent of this method is to return the overall state of the camera (open, closed, busy, etc.).
For the status of an acquisition, use the GetStatus method of the TsiAcquistion object below.
ITN000195-D02 Rev. A June 12, 2014
Page 15
TSI Camera SDK
Chapter 2: C++ API
TsiCamera::GetCameraName
char* GetCameraName ();
This function returns a pointer to the camera name. If no name has been previously assigned to the
camera, a generic camera name will be returned.
TsiCamera::SetCameraName
bool SetCameraName (char *CameraName);
This function allows the caller to give the camera a user generated name. This function is intended for
use in multi-camera systems where the user may want to assign a name to a particular camera that may
have a particular function or be connected to a particular part of their system. This name is persistant
and is tied to the model and serial number of the camera.
TsiCamera::GetParameter
bool GetParameter (TSI_PARAM_ID ParameterID, size_t Length, void
*data);
This method is the main way of querying the various camera parameters, discovering whether a particular
setting is supported on a camera, and other attributes about the parameter, such as it’s data type, length
(in the case of vector or array type), and any other flags the parameter might have.
To use this method, you must supply a parameter identifier (see TSI_PARAMETER_ID as defined
above), the size of the variable to hold the data, and a pointer to the variable to hold the data returned.
Attributes about the parameter, with the exception of the minimum and maximum values a parameter
may have all have fixed sizes. The actual value, the min and the max values will all have the same type,
and that type can be discovered by using the TSI_ATTR_DATA_TYPE attribute identifier. The value
retuned will be a TSI_DATA_TYPE enumerated type, The GetDataTypeSize method can be used to
determine the scalar size for the type. The total storage required for a parameter will be the size for the
data type multiplied by the value returned by TSI_ATTR_DATA_COUNT attribute id.
TsiCamera::GetDataTypeSize
ITN000195-D02 Rev. A June 12, 2014
Page 16
TSI Camera SDK
Chapter 2: C++ API
int32 GetDataTypeSize (TSI_DATA_TYPE DataType);
This method returns the size in bytes of any of the SDK defined data types.
TsiCamera::SetTextCommand
bool SetTextCommand (char *str);
This method sends a serial text command directly to the camera.
TsiCamera::SetTextCallback
bool SetTextCommand (TSI_TEXT_CALLBACK_FUNCTION func, void
*context);
Using this method, you can register for a callback to receive serial text responses to serial text commands
issued via SetTextCommand(char *str).
TsiCamera::SetParameter
bool SetParameter (TSI_PARAM_ID ParameterID, void *data);
This method is a sister function to the GetParameter function described above and is used to set any
parameter that is does not have the TSI_FLAG_READ_ONLY flag set.
A parameter’s setting may be cached (unless the API determines it’s value is volatile and must be sent to
the camera each time, even if the value does not actually change). This is used to cut down on
unnecessary traffic to / from the camera.
TsiCamera:: SetCameraControlCallback
bool SetCameraControlCallback (
ITN000195-D02 Rev. A June 12, 2014
Page 17
TSI Camera SDK
TSI_FUNCTION_CAMERA_CONTROL_CALLBACK
void *
);
Chapter 2: C++ API
func,
context
This method allows the caller to specify a callback function for interesting events about the camera.
See the TSI_CAMERA_CONTROL_EVENT_ID enumeration above for the supported list of events.
The TSI_FUNCTION_CAMERA_CONTROL_CALLBACK type definition above describes the function
header for the callback function.
TsiCamera:: SetCameraControlCallbackEx
bool SetCameraControlCallbackEx (
TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX
func,
void *
context
);
This method allows the caller to specify a callback function for interesting events about the camera.
See the TSI_CAMERA_CONTROL_EVENT_ID enumeration above for the supported list of events.
The TSI_FUNCTION_CAMERA_CONTROL_CALLBACK_EX type definition above describes the
function header for the callback function.
TsiCamera:: SetImageNotificationCallback
bool SetImageNotificationCallback (
TSI_FUNCTION_IMAGE_NOTIFICATION_CALLBACK func,
Void *
context
);
Using this method, you can register callbacks for events such as cameras being unplugged or other
asynchronous events occurring on the camera.
See the TSI_IMAGE_NOTIFICATION_EVENT_ID enumeration above for the supported list of events.
The TSI_FUNCTION_IMAGE_NOTIFICATION_CALLBACK type definition above describes the function
header for the callback function.
ITN000195-D02 Rev. A June 12, 2014
Page 18
TSI Camera SDK
Chapter 2: C++ API
TsiCamera:: SetImageCallback
bool SetImageCallback (
TSI_FUNCTION_IMAGE_CALLBACK
Void *
);
func,
context
This method allows the caller to specify a callback function that will be called whenever there is a new
frame of image data available.
The TSI_FUNCTION_IMAGE_CALLBACK type definition above describes the function header for the
callback function.
TsiCamera::ResetCamera
bool ResetCamera ();
This method is used to set the camera to it’s power-on state. The application will have to query the
camera parameters to determine what the current camera settings are.
This can be accomplished by iterating over all the camera settings calling a GetParameter with the
Parameter IDs the application cares about, specifying the TSI_ATTR_FLAGS attribute, and checking for
the ATTR_VALUE_CHANGED flag. Any parameter that has changed as a result of restoring the camera
to it’s power on state will have this flag set.
TsiCamera::FreeImage
bool FreeImage (TsiImage *Image);
This method frees the image data object. The Close method and the destructor for this class will close
and free up any image data objects that have been created. Any pointers to TsiImage objects that have
been created must not be accessed after the object has been freed by the TsiCamera FreeImageData or
Close methods or the TsiSdk object’s CloseSDK method or destructor.
TsiCamera::FreeAllPendingImages
ITN000195-D02 Rev. A June 12, 2014
Page 19
TSI Camera SDK
Chapter 2: C++ API
bool FreeAllPendingImages (TsiImage *Image);
This method frees all of the the pending images in the buffer.
TsiCamera::GetPendingImage
TsiImage* GetPendingImage (void);
This method will return a pointer to the next available image.
TsiCamera::GetLastPendingImage
TsiImage* GetLastPendingImage (void);
This method will return a pointer to the last available image.
TsiCamera::StartAndWait
bool StartAndWait (int32 Timeout);
This method starts an aquistition of one or more frames using the current camera parameters and waits
for it to finish. If the elapsed time to acquire the image data exceeds the timeout value (in milliseconds),
the acquisition will be cancelled and the function will return FALSE.
Also, if the combination of current camera parameters do not permit proper operation of the camera,
FALSE will be returned.
An example would be calling StartAcquistionAndWait with the
TSI_PARAM_FRAME_COUNT parameter set to 0 (which indicates acquire until a StopCamera call is
made).
This method is intended for use in simple applications that could be simple command line applications
that are going to be invoked periodiocally.
TsiCamera::Start
ITN000195-D02 Rev. A June 12, 2014
Page 20
TSI Camera SDK
Chapter 2: C++ API
bool Start ();
This method starts an acquisition, but does not block.
The application may specify a callback function that will be called as each frame is completed and ready
for retrieval using the ReadXxxxImage functions.
The application must call the StopCamera method before issuing another StartAcquistion call.
TsiCamera::Stop
bool Stop ();
This method is used to either cancel and / or clean up after an acquisition. This method must be called
between subsequent calls to the StartCamera method.
TsiCamera::GetAcquisitionStatus
TSI_ACQ_STATUS_ID GetAcquisitionStatus ();
Returns the current status of the acquisition for applications that wish to poll for completion.
TsiCamera::GetExposeCount
int32 GetExposeCount ();
The GetExposeCount method returns the number of exposures that have been completed since a
StartCamera call.
TsiCamera::GetFrameCount
int32 GetFrameCount ();
ITN000195-D02 Rev. A June 12, 2014
Page 21
TSI Camera SDK
Chapter 2: C++ API
The GetFrameCount method returns the number of frames that have been completetly transferred to host
memory since a StartCamera call.
TsiCamera::WaitForImage
bool WaitForImage ();
An application that wishes to poll for frame completion can call this function that will return TRUE when
the next frame is available.
TsiCamera::ResetExposure
bool ResetExposure ();
If the camera is waiting for a trigger or in the middle of a long exposure, this method can be used to dump
the charge on the sensor, and reset the camera state to the beginning of the exposure.
TsiCamera::GetErrorCode
TSI_ERROR_CODE GetErrorCode();
Returns the current error code for the camera, a returned value of zero indicates success. Clears any
non-zero error code.
TsiCamera::ClearError
VOID ClearError ();
Clears any existing error code for the camera without having to read it using GetErrorCode.
ITN000195-D02 Rev. A June 12, 2014
Page 22
TSI Camera SDK
Chapter 2: C++ API
TsiCamera::GetErrorStr
bool GetErrorStr(TSI_ERROR_CODE ErrorCode, char *StringBuffer,
int32 &StringLength)
Returns the non-localized ASCII string description of the supplied error code.
Passing a NULL pointer and pointer to a variable containing a length of zero length results in the length of
the string associated with the supplied error code being returned so that a buffer of appropriate length can
be dynamically allocated.
TsiCamera::GetLastErrorStr
char* GetLastErrorStr (void)
Returns a pointer to the non-localized ASCII string description of the current error code.
ITN000195-D02 Rev. A June 12, 2014
Page 23
TSI Camera SDK
Chapter 2: C++ API
2.4.2. List of Camera Parameters
This list of parameters are used by the TsiCamera.GetParameter and TsiCamera.SetParameter methods.
TSI_PARAM_ATTR
TSI_TYPE_UNS8: For expert use only, contact us for
more info.
TSI_PARAM_PROTOCOL
TSI_TYPE_UNS32: Obsolete
TSI_PARAM_FW_VER
TSI_TYPE_TEXT: Returns the firmware revision of the
camera. The format of the returned data is
MM.mm.rr.build, where MM is a two digit major version,
mm is a two digit minor version, rr is a two digit revision,
and build is a sequential number used internally by TSI
supplied utilities.
TSI_PARAM_HW_VER
TSI_TYPE_TEXT: Returns the hardware rev of the
camera. The format of the returned data is
MM.mm.rr.build, where MM is a two digit major version,
mm is a two digit minor version, rr is a two digit revision,
and build is a sequential number used internally by TSI
supplied utilities.
TSI_PARAM_HW_MODEL
TSI_TYPE_TEXT: Returns the hardware model name of
the camera, format TBD.
TSI_PARAM_HW_SER_NUM
TSI_TYPE_TEXT: Returns the serial number of the
camera, format TBD.
TSI_PARAM_CAMSTATE
TSI_TYPE_UNS32 (enum): Get the current state of the
camera (IDLE / RUN)
TSI_PARAM_CAM_EXPOSURE_STATE
TSI_PARAM_CAM_TRIGGER_STATE
TSI_TYPE_UNS32 (enum): Get the camera's current
trigger state (NONE/ARMED/DISARMED/TRIGGERED)
TSI_PARAM_EXPOSURE_UNIT
TSI_TYPE_UNS32 (enum): Set the camera's exposure
time unit of measurement.
TSI_PARAM_EXPOSURE_TIME
TSI_TYPE_UNS32: Set the camera's exposure time in the
current unit of measurement. See
TSI_PARAM_EXPOSURE_UNIT above.
TSI_PARAM_ACTUAL_EXPOSURE_TIME
TSI_TYPE_UNS32: Gets the actual exposure time in
microseconds for a commanded exposure time.
TSI_PARAM_FRAME_TIME
TSI_TYPE_UNS32: Get the camera frame readout time in
milliseconds.
TSI_PARAM_VSIZE
TSI_TYPE_UNS32: Get the camera sensor’s number of
active rows.
TSI_PARAM_HSIZE
TSI_TYPE_UNS32: Get the camera sensor’s maximum
number of active columns.
ITN000195-D02 Rev. A June 12, 2014
Page 24
TSI Camera SDK
TSI_PARAM_ROI_BIN
Chapter 2: C++ API
TSI_TYPE_UNS32 [6]: Get/Set ROI and Binning Factors –
ROI and binning are returned as an array of six UNS32
values, which can be encoded/decoded using the $$$
structure type defined above.
TSI_PARAM_FRAME_COUNT
TSI_TYPE_UNS32: Sets number of frames to acquire
before going to the TSI_ACQ_DONE state.
TSI_PARAM_CURRENT_FRAME
TSI_TYPE_UNS32: Gets the number of frames
completely read out in an "N" frame sequence.
TSI_PARAM_OP_MODE
TSI_TYPE_UNS32 (enum): Sets the current operating
mode
TSI_PARAM_CDS_GAIN
TSI_TYPE_UNS32 (enum): Gets or Sets CDS gain
setting
TSI_PARAM_VGA_GAIN
TSI_TYPE_UNS32: Gets or Sets VGA gain
TSI_PARAM_GAIN
TSI_TYPE_UNS32: Gets or Sets linear gain (x1 – xN)
TSI_PARAM_OPTICAL_BLACK_LEVEL
TSI_TYPE_UNS32: Sets the optical black level
TSI_PARAM_PIXEL_OFFSET
TSI_TYPE_UNS32: The offset for each pixel
TSI_PARAM_READOUT_SPEED_INDEX
TSI_TYPE_UNS32: Selects the index into the set of
readout speeds the camera supports.
TSI_PARAM_READOUT_SPEED
TSI_TYPE_UNS32: Returns the digitization rate in MHz
for the given speed index.
TSI_PARAM_FRAME_RATE
TSI_TYPE_UNS32: Returns the frame rate in frames per
second. Value is returned as one 32 bit number. The
upper 16 bits represent the whole number of frames per
second. The lower 16 bits represent the fractional part in
hundredths of frames per second.
TSI_PARAM_COOLING_MODE
TSI_TYPE_UNS32 (enum): Sets the cooling mode.
TSI_PARAM_COOLING_SETPOINT
TSI_TYPE_INT32: Sets the current CCD chamber
temperature set point in hundredths of degrees centigrade
(if supported by the camera). This value contains an
implied decimal point, to convert to floating point degrees
centegrade, divide by 100.0. Inversely, to convert from
floating point degrees celcius, multiply that value by 100.0
and round or truncate (cast) as desired.
TSI_PARAM_TEMPERATURE
TSI_TYPE_INT32: Gets the current CCD chamber
temperature (if supported by camera). Uses the same
format / data type as
TSI_PARAM_COOLING_SETPOINT.
TSI_PARAM_QX_OPTION_MODE
TSI_TYPE_UNS32 (enum): Sets the QX mode
TSI_PARAM_TURBO_CODE_MODE
TSI_TYPE_UNS32 (bool): Sets TURBO Code Output
On/Off
TSI_PARAM_XORIGIN
TSI_TYPE_UNS32: Gets or sets the X component of the
upperleft corner of the specified ROI.
ITN000195-D02 Rev. A June 12, 2014
Page 25
TSI Camera SDK
Chapter 2: C++ API
TSI_PARAM_YORIGIN
TSI_TYPE_UNS32: Gets or sets the Y component of the
upperleft corner of the specified ROI.
TSI_PARAM_XPIXELS
TSI_TYPE_UNS32: Gets or sets the width in pixels of the
desired ROI.
TSI_PARAM_YPIXELS
TSI_TYPE_UNS32: Gets or sets the height in pixels of
the desired ROI.
TSI_PARAM_XBIN
TSI_TYPE_UNS32: Used to set or query the current
horizontal binning factor.
TSI_PARAM_YBIN
TSI_TYPE_UNS32: Used to set or query the current
horizontal binning factor.
TSI_PARAM_IMAGE_ACQUISITION_MODE TSI_TYPE_UNS32: Obsolete, do not use
TSI_PARAM_NAMED_VALUE
TSI_TYPE_TEXT: For internal use only.
TSI_PARAM_TAPS_INDEX
TSI_TYPE_UNS32: Used to select or query the current
tap setting.
TSI_PARAM_TAPS_VALUE
TSI_TYPE_UNS32: Used to query the number of taps for
the current tap setting (See TSI_PARAM_TAPS_INDEX
above).
TSI_PARAM_RESERVED_1
Reserved for internal use.
TSI_PARAM_RESERVED_2
Reserved for internal use.
TSI_PARAM_RESERVED_3
Reserved for internal use.
TSI_PARAM_RESERVED_4
Reserved for internal use.
TSI_PARAM_GLOBAL_CAMERA_NAME
TSI_TYPE_TEXT: Returns the camera name stored in the
camera thats visible to users on the network and software
loading the camera.
TSI_PARAM_CDS_GAIN_VALUE
TSI_TYPE_UNS32: For expert use only, contact us for
details.
TSI_PARAM_PIXEL_SIZE
TSI_TYPE_FP: Size of the pixel width in microns (pixel
assumed square).
TSI_PARAM_BITS_PER_PIXEL
TSI_TYPE_UNS32: Number of bits per pixel in raw data.
TSI_PARAM_BYTES_PER_PIXEL
TSI_TYPE_UNS32: Number of bytes per pixel (1 or 2).
TSI_PARAM_READOUT_TIME
TSI_TYPE_FP: Readout time of the camera in seconds.
TSI_PARAM_HW_TRIGGER_ACTIVE
TSI_TYPE_UNS32: Gets or sets the hardware active
trigger state. 1 = Active, 0 = Not Active.
TSI_PARAM_HW_TRIG_SOURCE
TSI_TYPE_UNS32 (enum): Gets or sets the HW trigger
source.
TSI_PARAM_HW_TRIG_POLARITY
TSI_TYPE_UNS32 (enum): Gets or sets the HW trigger
polarity.
TSI_PARAM_TAP_BALANCE_ENABLE
TSI_TYPE_UNS32 : Gets or sets the tap balance enable.
1 = Active, 0 = Not Active.
ITN000195-D02 Rev. A June 12, 2014
Page 26
TSI Camera SDK
ITN000195-D02 Rev. A June 12, 2014
Chapter 2: C++ API
Page 27
TSI Camera SDK
2.5.
Chapter 2: C++ API
TsiImage Class
2.5.1. DATA MEMBERS
unsigned int m_Width;
unsigned int m_Height;
unsigned int m_BitsPerPixel;
unsigned int m_BytesPerPixel;
unsigned
unsigned
unsigned
unsigned
unsigned
int
int
int
int
int
m_SizeInPixels;
m_SizeInBytes;
m_XBin;
m_VBin;
m_ROI[4];
unsigned int m_ExposureTime_ms;
unsigned int m_FrameNumber;
union
{
void
char
unsigned char
short
unsigned short
unsigned int
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
Width of image in pixels.
Height of image in pixels.
The number of significant
bits per pixel in the
pixel data.
The number of bytes
consumed by a pixel.
Size of image in pixels.
Size of image in bytes.
Horizontal binning value.
Vertical binning value.
The region of interest
(subimage) that the pixels
were gathered from.
Format: [x0, y0, x1, y1]
Exposure time in
milliseconds.
// Frame number returned from
frame grabber.
*vptr;
*i8;
*ui8;
*i16;
*ui16;
*ui32;
} m_PixelData;
2.5.2. METHODS
TsiImage::Copy
bool Copy(TsiImage *src)
Copies an existing TsiImage's data.
ITN000195-D02 Rev. A June 12, 2014
Page 28
TSI Camera SDK
Chapter 2: C++ API
TsiImage::Clone
TsiImage* Clone(TsiImage *src)
Creates a new duplicate of the specified TsiImage.
2.6.
TsiUtil Class
2.6.1. METHODS
TsiUtil:WriteImageToTIFF
bool WriteImageToTIFF (char *file_name, TsiImage *image)
Saves the TsiImage with the specified name into a 16-bit Tiff image.
TsiUtil:WriteImageToPNG
bool WriteImageToPNG (char *file_name, TsiImage *image)
Saves the TsiImage with the specified name into a 16-bit PNG image.
ITN000195-D02 Rev. A June 12, 2014
Page 29
TSI Camera SDK
Chapter 3
Chapter 3: Thorlabs Worldwide Contacts
Thorlabs Worldwide Contacts
USA, Canada, and South America
Thorlabs, Inc.
56 Sparta Avenue
Newton, NJ 07860
USA
Tel: 973-579-7227
Fax: 973-300-3600
www.thorlabs.com
www.thorlabs.us (West Coast)
Email: sales@thorlabs.com
Support: techsupport@thorlabs.com
Europe
Thorlabs GmbH
Hans-Böckler-Str. 6
85221 Dachau
Germany
Tel: +49-(0)8131-5956-0
Fax: +49-(0)8131-5956-99
www.thorlabs.de
Email: europe@thorlabs.com
UK and Ireland
Thorlabs Ltd.
1 Saint Thomas Place, Ely
Cambridgeshire CB7 4EX
Great Britain
Tel: +44 (0)1353-654440
Fax: +44 (0)1353-654444
www.thorlabs.com
Email: sales.uk@thorlabs.com
Support: techsupport.uk@thorlabs.com
France
Thorlabs SAS
109, rue des Côtes
78600 Maisons-Laffitte
France
Tel: +33 (0) 970 444 844
Fax: +33 (0) 825 744 800
www.thorlabs.com
Email: sales.fr@thorlabs.com
Scandinavia
Thorlabs Sweden AB
Mölndalsvägen 3
412 63 Göteborg
Sweden
Tel: +46-31-733-30-00
Fax: +46-31-703-40-45
www.thorlabs.com
Email: scandinavia@thorlabs.com
Japan
Thorlabs Japan, Inc.
Higashi-Ikebukuro Q Building, 1F
2-23-2, Higashi-Ikebukuro,
Toshima-ku, Tokyo 170-0013
Japan
Tel: +81-3-5979-8889
Fax: +81-3-5979-7285
www.thorlabs.jp
Email: sales@thorlabs.jp
China
Thorlabs China
Room A101, No. 100
Lane 2891, South Qilianshan Road
Putuo District
Shanghai
China
Tel: +86 (0)21-60561122
Fax: +86 (0)21-32513480
www.thorlabs.hk
Email: chinasales@thorlabs.com
ITN000195-D02 Rev. A June 12, 2014
Page 30
www.thorlabs.com
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : Yes Author : GHavenga@thorlabs.com Company : Thorlabs, Inc. Content Type Id : 0x010100ECD834F0A1D9B046B167EC0DB6FE7639 Create Date : 2014:06:12 11:32:26-05:00 Doc Type : 112;#Programming Reference|bdaa40f6-93d2-48d0-89de-e6f096799b2d Keywords : ITN000195-D02 Modify Date : 2014:06:12 11:32:36-05:00 Source Modified : TSI Document Number : 86-9000-000 TSI Document Revision : Draft 0.30 Dlc Doc Id Item Guid : b8f70a52-41d3-46df-9594-17282ec12df4 Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26 Metadata Date : 2014:06:12 11:32:36-05:00 Creator Tool : Acrobat PDFMaker 10.1 for Word Document ID : uuid:4590ef32-a0cf-43b4-a6b6-dbf1af7e7620 Instance ID : uuid:f126c227-df99-49ca-adab-3cc2ad44efa0 Subject : 2 Format : application/pdf Title : TSI Camera API Manual Creator : GHavenga@thorlabs.com Producer : Adobe PDF Library 10.0 TSI0020 Document 0020 Number : 86-9000-000 TSI0020 Document 0020 Revision : Draft 0.30 Tag dlc Doc Id Item Guid : b8f70a52-41d3-46df-9594-17282ec12df4 Page Layout : OneColumn Page Count : 31EXIF Metadata provided by EXIF.tools