Software Development Kit for X16CU Cameras by byt34827

VIEWS: 52 PAGES: 139

									Software Development Kit
          for
    X16CU Cameras


     (X16CU SDK)




      Version 1.0
                  Scientific Instrument Software Corporation Limited




Introduction

The X16CU refers to a series of USB 2.0 CMOS color cameras designed for bright-field
microscopy and short-wave near infrared imaging applications. Regardless of the ADs
adopted, all cameras output 3x8-bit bitmaps for easy integration to existing application
programs.


The X16CU Software Development Kit (SDK) is a set of functions which an application
program calls to capture images with X16CU cameras and optionally to specify how the
raw images are to be processed before they are exported to the application program.


The files contained in the X16CU SDK are:


1     Sisc_Codes.h        The header file that defines error codes that the SDK
                          functions may return. These error codes are used across all
                          SDKs.
2     Sisc_X16CU.h        The header file that defines prototypes of all functions in this
                          SDK.
3     Sisc_X16CU.lib      The import library for the dynamic link library of this SDK.
4     Sisc_X16CU.dll      The dynamic link library where all functions of this SDK
                          reside.
5     Sisc_X16CU.pdf      The reference manual of this SDK.
6     X16CU.sys           One of the two driver files needed to install an X16CU camera.
                          This file is used across all X16 cameras.
7     316CU.inf           The other driver file, besides X16CU.sys, needed to install a
                          316CU camera.
8     516CU.inf           The other driver file, besides X16CU.sys, needed to install a
                          516CU camera.




                                                                                          2
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Using the SDK

The X16CU SDK has been tested on 32-bit Windows 2000 and Windows XP platforms.
The functions work most efficiently with C/C++ programming languages.


As a first step of building a new program or upgrading an existing one to support
X16CU cameras, the header files Sisc_Codes.h and Sisc_X16CU.h must be included in
all files where SDK functions are called. The second step is to modify the build
environment. If load-time dynamic linking is intended, then the program must be
linked to the import library Sisc_X16CU.lib. If run-time dynamic linking is intended,
this step is not necessary. Before the program runs, a X16CU camera must have been
properly installed using the driver files such as X16CU.sys and 316CU.inf as in case of a
316CU camera.


The following code fragment illustrates the workflow of using the X16CU SDK.


To start working with the camera, call:


Sisc_X16_Initialize();


When the program finishes the use of the camera, call:


Sisc_X16_Uninitialize();


All other function calls must be made in between.


To capture an image, first define frame format by calling:


SISC_X16_API X16_SetDecimation(int *pFactor);


Then copy the most recently acquired bitmaps to external buffers by repeatedly calling:


SISC_X16_API X16_GetBitmap(BITMAPINFOHEADER *pInfo,BYTE *pBits);


The other functions are to customize the way raw frame data are processed and do not
have to be called. The following diagram illustrates the processing order. The pertinent


                                                                                       3
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




functions are listed to the right of each step. The functions not shown below are for the
control of the camera, hence precede all the functions shown.



                                                       X16_FFC_Create

                           Raw Data                    X16_FFC_Import

                                                       X16_FFC_Memory

                                                       X16_FFC_Get
                    Flat-Field Correction
                                                       X16_FFC_Set


                                                       X16_WhiteBalance
                       White Balance
                                                       X16_GetKelvin

                                                       X16_SetKelvin

                       Auto Exposure
                                                       X16_AutoExposure



                          Histogram                    X16_GetHistogram




                       Look Up Table                   X16_LUT




                           Gamma                       X16_GetGamma

                                                       X16_SetGamma


                         Bayer Filter


                                                       X16_GetImageFlip
                             Flip
                                                       X16_SetImageFlip

                                                       X16_GetSaturation
                   Saturation Adjustment
                                                       X16_SetSaturation


                                                       X16_GetBitmap
                       Output Bitmap




                                                                                       4
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Function Reference

Initialize


SISC_X16_API X16_Initialize();


The Initialize function allocates necessary resources, searches the USB, and connects to
the first X16CU camera it finds.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscCameraInUseError                          The camera is already being used by
                                              another application.
SiscNoCameraAvailableError                    There is no camera available.
SiscHardwareError                             The camera has responded with an error.
SiscCameraUnknownError                        The SDK does not recognize the camera.
SiscOutOfMemoryError                          The SDK can not allocate the required
                                              memory.
SiscOSVersionError                            The SDK cannot run on the current
                                              operating system.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
This function must be the first to call for working with an X16CU camera. The other
functions may be called only after Initialize has returned successfully.




                                                                                         5
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Uninitialize


SISC_X16_API X16_Uninitialize();


The Uninitialized function shuts down the camera and frees the resources previously
allocated for the camera.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.


Remarks
Call this function to clean up. After that, the camera is no longer accessible.




                                                                                         6
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetCameraID


SISC_X16_API X16_GetCameraID(             int *pModel,
                                          int *pMinorPassword,
                                          int *pMajorPassword);


The GetCameraID function retrieves identifying information of the camera.


Parameters


pModel              Points to a 32-bit signed integer that receives the model number
                    of the initialized camera. For example, if the camera in use is
                    316CU, the model number will be 0x316.
pMinorPassword      Points to a 32-bit signed integer that receives the least significant
                    32 bits of the GUID of the initialized camera.
pMajorPassword      Points to a 32-bit signed integer that receives the most significant
                    32 bits of the GUID of the initialized camera.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks


Each X16CU camera is associated with a 64-bit GUID. The GUID is implemented by
hardware and may be used as a serial number or a software dongle.




                                                                                        7
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetDecimation


SISC_X16_API X16_GetDecimation(               int *pFactor,
                                              int *pMinFactor,
                                              int *pMaxFactor);


The GetDecimation function retrieves the sub-sampling factor currently in use and
optionally the supported minimal and maximal sub-sampling factor.


Parameters


pFactor            Points to a signed 32-bit integer that receives the sub-sampling
                   factor currently in use.
pMinFactor         Points to a signed 32-bit integer that receives the supported
                   minimal sub-sampling factor.
                   This parameter can be NULL.
pMaxFactor         Points to a signed 32-bit integer that receives the supported
                   maximal sub-sampling factor.
                   This parameter can be NULL.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.


Remarks


The X16CU cameras do not support region of interest (ROI) setting. Decimation is the
only way to modify the number of output pixels.




                                                                                          8
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetDecimation


SISC_X16_API X16_SetDecimation(int *pFactor);


The SetDecimation function sets a new sub-sampling factor for the camera.


Parameters
pFrameFormat                                  A pointer to the new frame format to set.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks


All integers between the supported minimal and maximal sub-sampling factor are valid
sub-sampling factors. Decimation applies simultaneously to both rows and columns of
the camera pixel array, i.e. aspect ratio will not change with decimation settings.




                                                                                          9
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetFrameRate


SISC_X16_API X16_GetFrameRate(float* pFrameRate);


The GetFrameRate function reports the current frame rate.


Parameters
pFrameRate                                  Points to a 32-bit floating number that
                                            receives the current frame rate in FPS.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
For all X16CU cameras the frame rate changes with different sub-sampling factors. It is
always set by the X16CU camera drivers to the highest possible.




                                                                                      10
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




GetImageFlip


SISC_X16_API X16_GetImageFlip(int *pHorz,int *pVert);


The GetImageFlip function retrieves image flip status.


Parameters
pHorz         Points to a 32-bit signed integer that receives the horizontal flip state. 0
              means the output image is not flipped horizontally. 1 means the output
              image is flipped horizontally.
              This parameter can be NULL.
pVert         Points to a 32-bit signed integer that receives the vertical flip state. 0
              means the output image is not flipped vertically. 1 means the output image
              is flipped vertically.
              This parameter can be NULL.


Return Values
SiscSuccess                                     The function has completed successfully.
SiscUnknownError                                Unknown error
SiscUnInitializedError                          Camera has not yet been initialized.
SiscInvalidParameterError                       Invalid parameters
SiscBufferTooSmall                              A buffer passed as parameter is too small.
SiscHardwareError                               The camera has responded with an error.
SiscIOError                                     An error has occurred during an IO
                                                operation.


Remarks
Note that the flipping, if any, takes place after auto exposure and white balance, which
base their sub-window on the original image geometry, i.e. without flipping.




                                                                                             11
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetImageFlip


SISC_X16_API X16_SetImageFlip(int *pHorz,int *pVert);


The SetImageFlip function flips the images in the current video stream.


Parameters
pHorz     Pointer to the horizontal flip state to set. 0 means to cancel the horizontal flip
          if any. 1 means to flip the output image horizontally.
          This parameter can be NULL.
pVert     Pointer to the vertical flip state to set. 0 means to cancel the vertical flip if
          any. 1 means to flip the output image vertically.
          This parameter can be NULL.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscBufferTooSmall                             A buffer passed as parameter is too small.
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.
SiscOutOfRangeError                            A feature to set is out of range.


Remarks
Note that the flipping, if any, takes place after auto exposure and white balance, which
base their sub-window on the original image geometry, i.e. without flipping.




                                                                                              12
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetExposureTime


SISC_X16_API X16_GetExposureTime( float *pExposure,
                                            float* pMinExposure,
                                            float* pMaxExposure);


The GetExposureTime function retrieves the current exposure time and optionally the
allowable range of exposure time.


Parameters
pExposure          Points to a 32-bit floating number that receives the current
                     exposure time, in milliseconds.
pMinExposure         Points to a 32-bit floating number that receives that allowed
                     minimal exposure time, in milliseconds.
                     This parameter can be NULL.
pMaxExposure         Points to a 32-bit floating number that receives that allowed
                     maximal exposure time, in milliseconds.
                     This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
The exposure range changes with different sub-sampling factors. A previous exposure
time, even though valid at the time it was set, might be modified without warning when
a new decimation setting does not permit that exposure time.




                                                                                      13
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetExposureTime


SISC_X16_API X16_SetExposureTime(float *pExposure);


The SetExposureTime function sets the exposure time, in milliseconds, of the camera.


Parameters
pExposure                                  Pointer to a 32-bit floating number that is
                                            to be the new exposure time. The exposure
                                            time is always set in milliseconds.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
To avoid flicker, set the exposure time to multiples of 10ms for 50Hz AC or 8.33ms for
60Hz AC.




                                                                                    14
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




AutoExposure


SISC_X16_API X16_AutoExposure(int Percentage,RECT *pSubWindow);


The AutoExposure function modifies the exposure time based on the most recent frame
in the video stream and the input parameters.


Parameters
Percentage                                 Specifies the desired average intensity of
                                           the pixels in the ROI or a sub-window of it,
                                           as a percentage of the full dynamic range.
                                           Must be in the range [1, 99].
pSubWindow                                 If NULL, indicates the exposure
                                           adjustment should be based on the current
                                           ROI. If a valid pointer to RECT, specifies
                                           that the exposure adjustment should be
                                           based on the sub-window of the ROI, as
                                           given by the RECT it points to.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
This is one-push auto exposure operation. To implement continuous auto exposure, call
this function in response to a timer message. Note that the sub-window refers to the
image before it is possibly flipped.




                                                                                    15
info@softinstrument.com
                   Scientific Instrument Software Corporation Limited




GetGlobalGain


SISC_X16_API X16_GetGlobalGain(               float *pGlobalGain,
                                              float* pMinGlobalGain,
                                              float* pMaxGlobalGain);


The GetGlobalGain function retrieves the current global gain applied to the camera,
and optionally the allowed minimal and maximal global gain values.


Parameters
pGlobalGain            Points to a 32-bit floating number that receives the current global
                       gain value of the camera.
pMinGlobalGain         Points to a 32-bit floating number that receives the allowed
                       minimal global gain value of the camera.
                       This parameter can be NULL.
pMaxGlobalGain         Points to a 32-bit floating number that receives the allowed
                       maximal global gain value of the camera.
                       This parameter can be NULL.


Return Values


SiscSuccess                                     The function has completed successfully.
SiscUnknownError                                Unknown error
SiscUnInitializedError                          Camera has not yet been initialized.
SiscInvalidParameterError                       Invalid parameters
SiscBufferTooSmall                              A buffer passed as parameter is too small.
SiscHardwareError                               The camera has responded with an error.
SiscIOError                                     An error has occurred during an IO
                                                operation.


Remarks
Global gain applies to all three color channels simultaneously as a multiplicative factor.
For X16CU cameras the global gain is implemented as digital gain. Since the ADs used
by X16CU cameras are 10-bit at least but the output is always the most significant 8
bits, a global gain of 2 or greater values help to shift out less significant bits.



                                                                                        16
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetGlobalGain


SISC_X16_API X16_SetGlobalGain(float *pGlobalGain);


The SetGlobalGain function directs the camera to amplify the signal by a given factor.


Parameter
pGlobalGain                                 Pointer to a 32-bit floating number that is
                                            be set as the new global gain.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
The gain values are factors.




                                                                                     17
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetBlueGain


SISC_X16_API X16_GetBlueGain(              float *pBlueGain,
                                           Float *pMinBlueGain,
                                           Float *pMaxBlueGain);


The GetBlueGain function retrieves the current blue gain value and optionally the
allowed minimal and maximal blue gain values.


Parameters
pBlueGain                                   Points to a 32-bit floating number that
                                            receives the current blue gain value.
pMinBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed minimal blue gain
                                            value.
                                            This parameter can be NULL.
pMaxBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed maximal blue gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X16CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      18
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetBlueGain


SISC_X16_API X16_SetBlueGain(float *pBlueGain);


The SetBlueGain function directs the camera to amplify the blue channel by the given
multiplicative factor.


Parameters
pBlueGain                                  Pointer to a 32-bit floating number that
                                           will be set as the new blue gain.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
Color gains are implemented as analog gains for X16CU cameras. Green gain is fixed.




                                                                                      19
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetRedGain


SISC_X16_API X16_GetRedGain(               float *pRedGain,
                                           float *pMinRedGain,
                                           float *pMaxRedGain);


The GetRedGain function retrieves the current red gain value and optionally the
allowed minimal and maximal red gain values.


Parameters
pRedGain                                    Points to a 32-bit floating number that
                                            receives the current red gain value.
pMinRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed minimal red gain
                                            value.
                                            This parameter can be NULL.
pMaxRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed maximal red gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X16CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      20
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetRedGain


SISC_X16_API X16_SetRedGain(float *pRedGain);


The SetRedGain function directs the camera to amplify the red channel by the given
multiplicative factor.


Parameters
pRedGain                                    Pointer to a 32-bit floating number that
                                            will be set as the new red gain.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
Color gains are implemented as analog gains for X16 cameras. Green gain is fixed.




                                                                                       21
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetSaturation


SISC_X16_API X16_GetSaturation(            float *pSaturation,
                                           float *pMinSaturation,
                                           float *pMaxSaturation);


The GetSaturation function retrieves the saturation level currently applied to the
bitmaps before they are output.


Parameters
pSaturation                                  Points to a 32-bit floating number that
                                             receives the current saturation level.
pMinSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed minimal saturation
                                             level.
                                             This parameter can be NULL.
pMaxSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed maximal saturation
                                             level.
                                             This parameter can be NULL.


Return Values


SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
The function reports the default saturation value, i.e. no modification to the saturation
of output bitmaps, as the current saturation level, after the camera initializes
successfully and before the saturation level is changed by SetSaturation.



                                                                                        22
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetSaturation


SISC_X16_API X16_SetSaturation(float *pSaturation);


The SetSaturation function directs the saturation of the output bitmap be modified by
the given amount.


Parameters
pSaturation                                 Pointer to a 32-bit floating number that
                                            will be set as the new saturation level.




Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.




Remarks
Saturation adjustment is the last step of processing before a bitmap is output. It does
not affect the other intermediate image processing, in particular, the histogram
reported by the SDK function will not be changed by a new saturation setting.




                                                                                       23
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetKelvin


SISC_X16_API X16_GetKelvin(float *pKelvin,
                                  float *pMinKelvin,
                                  float *pMaxKelvin);


The GetKelvin function retrieves the image temperature currently in use as a basis to
white balance.


Parameters


pKelvin            Points to a 32-bit floating number that receives the image
                   temperature currently in use as a basis to white balance.
pMinKelvin         Points to a 32-bit floating number that receives the allowed
                   minimal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.
pMaxKelvin         Points to a 32-bit floating number that receives the allowed
                   maximal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
Image temperature is measured in Kelvin. A value of 0 means image temperature is not
considered in white balance.




                                                                                   24
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetKelvin


SISC_X16_API X16_SetKelvin(float *pKelvin);


The SetKelvin function specified a new image temperature to be used as a basis to white
balance.


Parameters
pKelvin                                      Pointer to a 32-bit floating number to be
                                             set as the new image temperature.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.
SiscOutOfRangeError                          A feature to set is out of range.


Remarks


If set to 0, the image temperature will not be considered in the white balance.


See Appendix 1 for light source examples that show various temperatures.




                                                                                         25
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetGamma


SISC_X16_API X16_GetGamma( float *pGamma ,
                                 float *pMinGamma,
                                 float *pMaxGamma);


The GetGamma function retrieves the Gamma value of the camera.


Parameters
pGamma                                    Points to 32-bit floating number that
                                          receives the current Gamma value of the
                                          camera.
pMinGamma                                 Points to 32-bit floating number that
                                          receives the allowed minimal Gamma
                                          value of the camera.
                                          This parameter can be NULL.
pMaxGamma                                 Points to 32-bit floating number that
                                          receives the allowed maximal Gamma
                                          value of the camera.
                                          This parameter can be NULL.


Return Values
SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscHardwareError                         The camera has responded with an error.
SiscIOError                               An error has occurred during an IO
                                          operation.


Remarks
The default Gamma value is 1.




                                                                                  26
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetGamma


SISC_X16_API X16_SetGamma(float *pGamma);


The SetGamma function specifies the Gamma value of the camera.


Parameters
pGamma                                       Pointer to a 32-bit floating number that
                                             will be set as the new Gamma value of the
                                             camera.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.
SiscOutOfRangeError                          A feature to set is out of range.


Remark
If set to 0, no Gamma will be applied to the camera, i.e. a Gamma value of 0 is the same
as a Gamma value of 1.




                                                                                        27
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




WhiteBalance


SISC_X16_API X16_WhiteBalance(RECT *pSubWindow);


The WhiteBalance function performs white balance based on the most recent frame in
the video stream.


Parameters
pSubWindow                                   If NULL, the white balance will be base on
                                             the current ROI. If a valid pointer, the
                                             white balance will be based on a
                                             sub-window of the current ROI, as
                                             specified by the RECT it points to.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
The white balance refers to the process of adjusting relative strength of color channel
gains based on the raw data the camera delivers and the temperature setting. This
function modifies blue and red gains only since green gain of an X16CU camera is fixed.
Note that the sub-window refers to the image before it is possibly flipped.


For a digital image to match an optical image in terms of color reproduction, it is
necessary to consider, besides white balance and light source temperature settings, the
spectral responses of the IR cutoff filter and camera sensors. Please refer to Appendix 2
and 3 for further information.




                                                                                        28
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetBitmap


SISC_X16_API X16_GetBitmap(BITMAPINFOHEADER *pInfo, BYTE *pBits);


The GetBitmap function retrieves the most recent image the camera delivers.


Parameters
pInfo                                         Points to a BITMAPINFOHEADER
                                              structure that receives the bitmap
                                              information.
pBits                                         Points to pixels stored in RGB24 format.
                                              This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscInvalidPointerError                       Invalid pointer


Remarks
This function will not return until the most recent bitmap is available. It stores the
bitmap in Windows DIB format as indicated by the parameters. Note that it is a
top-down DIB and its origin is the upper-left corner, i.e. pInfo->biHeight is negative.




                                                                                          29
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




LUT


SISC_X16_API X16_LUT(float x1,float y1,float x2,float y2);


The LUT function performs intensity windowing on the frames in the video stream.


Parameters


x1        The x coordinate of the first control point
y1        The y coordinate of the first control point
x2        The x coordinate of the second control point
y2        The y coordinate of the second control point


Return Values


SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
This function sets up a pixel value transform which maps the each value in the dynamic
range of raw data to another value in the dynamic range of the final output image. For
this function both dynamic ranges are normalized to [0, 1]. The transform is specified by
two control points (x1, y1) and (x2, y2), which means the value x1 in the original
dynamic range will be mapped to y1 in the new dynamic range and the value x2 in the
original dynamic range will be mapped to y2 in the new dynamic range. The transform
is piecewise linear, assuming 0 is mapped to 0 and 1 is mapped to 1, as illustrated below.




                                                                                       30
info@softinstrument.com
                                Scientific Instrument Software Corporation Limited




                                1

                                y2
            New Dynamic Range




                                y1




                         (0, 0)                x1          x2                        1
                                               Original Dynamic Range




Setting both (x1, y1) and (x2, y2) to either (0, 0) or (1, 1) effectively cancels the intensity
windowing. It is required that x2-x1>0.01.




                                                                                            31
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Create


SISC_X16_API X16_FFC_Create(double *pParams);


The FFC_Create function calculates the coefficients needed for Flat-Field Correction
and optionally exports the coefficients.


Parameters
pParams                                      Points to a buffer that receives the FFC
                                             calibration coefficients.
                                             This parameter can be NULL.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscBufferTooSmall                           A buffer passed as parameter is too small.
SiscCameraInUseError                         The camera is already being used by
                                             another application.
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


Flat-Field Correction (FFC) refers to the real-time image calibration for sensor’s
spatially varying response to incident light, uneven illumination and non-uniform
transmission rate of the lens or other optical systems. The FFC_Create function
computes the coefficient matrix based on the most recent frame in the video stream,
captured with the full pixel array of the sensor. It is not necessary for an application
program to explicitly switch the camera to that state as the FFC_Create function will do
that and will restore the previous frame format upon completion of the function. For
optimal result, it is recommended that before calling this function:




                                                                                        32
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




1. Shoot the camera at a slowly varying white background. The field of view should not
be obstructed by any object other than the white background.


2. Adjust the illumination, lens aperture or camera exposure time so that the image is
as bright as possible but not exceeding its dynamic range.


3. Perform white balance to remove the apparent color aberrations. The temperature
should be set to 0 before the white balance.




                                                                                   33
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Import


SISC_X16_API X16_FFC_Import(double *pParams);


The FFC_Import function loads the previously created calibration coefficients.


Parameters


pParams                                     Pointer to FFC calibration coefficients
                                            that will be loaded.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.




Remarks
The coefficients to load must have been created by the FFC_Create function.




                                                                                      34
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Memory


SISC_X16_API X16_FFC_Memory(int *pSizeInBytes);


The FFC_Memory reports the number of bytes needed to hold the calibration
coefficients.


Parameters


pSizeInBytes                                 Points to a 32-bit integer that receives the
                                             size of the memory, in bytes, to hold the
                                             FFC calibration coefficients.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


This function reports the size of the memory that an application program needs to
allocate so that the FFC_Create function can export the coefficients.




                                                                                         35
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Get


SISC_X16_API X16_FFC_Get(BOOL *pStatus);


The FFC_Get function retrieves the status of FFC.


Parameters
pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means FFC is off. 1 means
                                            FFC is on.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
FFC is a computation intensive operation.




                                                                                      36
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Set


SISC_X16_API X16_FFC_Set(BOOL *pStatus);


The FFC_Set function turns FFC on or off.


Parameters


pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means turning off FFC. 1
                                            means turning on FFC.




Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
FFC is a computation intensive operation.




                                                                                      37
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetHistogram


SISC_X16_API X16_GetHistogram(             int *pHistogramData,
                                           int *pHistogramSize);


The GetHistogram function profiles the intensity distribution of the most recent image.


Parameters
pHistogramData                              Points to the first of an array of integers
                                            that receive histogram data.
                                            This parameter can be NULL.
pHistogramSize                              Points to an integer that receives the size
                                            of the memory, in bytes, to hold the
                                            histogram data.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscInvalidPointerError                     Invalid pointer
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
The X16CU SDK uses an integer array to hold histogram. The array is divided into
three consecutive segments, to hold pixel count for blue, green and red channel
respectively. The first integer in each segment is the number of pixels with their
corresponding color value being 0. The last integer in each segment is the number of
pixels with their corresponding color being the maximum of the dynamic range.




                                                                                          38
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




Return Code List

SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscBufferTooSmall                        A buffer passed as parameter is too small.
SiscCameraInUseError                      The camera is already being used by
                                          another application.
SiscNoCameraAvailableError                There is no camera available.
SiscHardwareError                         The camera has responded with an error.
SiscCameraUnknownError                    The SDK does not recognize the camera.
SiscOutOfMemoryError                      The SDK can not allocate the required
                                          memory.
SiscOSVersionError                        The SDK cannot run on the current
                                          operating system.
SiscIOError                               An error has occurred during an IO
                                          operation.
SiscOutOfRangeError                       A feature to set is out of range.
SiscInvalidPointerError                   Invalid pointer




                                                                                  39
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Appendix 1 Common Color Temperatures


Light Source                                  Color Temperature (Kelvin)
Clear Blue Sky                                8000 to 27000
Rainy, Misty Daylight                         7200 to 8500
Overcast Daylight                             6500 to 7200
Direct Sun Clear Blue Sky                     5700 to 6500
Summer Sunlight (9am to 3pm)                  5400 to 5700
Summer Sunlight (Before 9am or After 3pm) 4900 to 5600
Electronic Flash (Typical)                    6200 to 6800
Xenon Arc (Unfiltered)                        6000
White Flame Carbon Arc                        5000
Yellow Flame Carbon Arc                       3200
“True Daylight” Color Match Tubes             6500
“Daylight” Cool White Tubes                   4300
“Warm White” Tubes                            3000
Photoflood & 3400K Tungsten-Halogen           3400
Tungsten-Halogen and Photo Lamps              3200
Projection Lamps (500 to 1000 Watts)          2900 to 3000
General Purpose Lamps (200 to 500 Watts)      2900
Household Lamps (100 to 150 Watts)            2850
Household Lamps (60 Watts)                    2800
Household Lamps (40 Watts)                    2750
Standard Candle                               2000
Candle Flame                                  1500




                                                                           40
info@softinstrument.com
                                  Scientific Instrument Software Corporation Limited




Appendix 2 Spectral Response of IR Cutoff Filter


                      100.00


                       90.00


                       80.00


                       70.00
  Transmittance [%]




                       60.00


                       50.00


                       40.00


                       30.00


                       20.00


                       10.00


                        0.00
                            200   300    400     500     600     700     800     900   1000   1100

                                                       Wavelength [nm]


Roughly speaking, the pass band is [400nm, 625nm]. Consider removing this filter for
short-wave near infrared imaging applications, or replacing it by one having the pass
band [700nm, 1100nm].




                                                                                                 41
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




Appendix 3 Spectral Response of Sensors

The relative spectral responses of X16CU cameras are plotted below against
wavelengths in nanometers.




                    Spectral Response of 316CU Camera Sensor




                    Spectral Response of 516CU Camera Sensor




                                                                       42
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




            Software Development Kit
                                     for
                          X18CU Cameras


                          (X18CU SDK)




                            Version 1.0




                                                                     43
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Introduction

The X18CU refers to a series of USB 2.0 CMOS color cameras designed for bright-field
microscopy applications. Regardless of the ADs adopted, all cameras output 3x8-bit
bitmaps for easy integration to existing application programs.


The X18CU Software Development Kit (SDK) is a set of functions which an application
program calls to capture images with X18CU cameras, and optionally to specify how
raw images are to be processed before they are exported to the application program. The
files contained in the SDK are:


1     Sisc_Codes.h        The header file that defines error codes that SDK functions
                          may return. These error codes are used across all SDKs.
2     Sisc_X18CU.h        The header file that defines prototypes of all functions in this
                          SDK.
3     Sisc_X18CU.lib      The import library for the dynamic link library of this SDK.
4     Sisc_X18CU.dll      The dynamic link library where all functions of this SDK
                          reside.
5     Sisc_X18CU.pdf      The reference manual of this SDK.
6     X18CU.sys           One of the two driver files needed to install an X18CU camera.
                          The same file is used across all X18 cameras.
7     318CU.inf           The other driver file needed to install a 318CU camera.
8     518CU.inf           The other driver file needed to install a 518CU camera.




                                                                                         44
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Using the SDK

The X18CU SDK has been tested on 32-bit Windows 2000 and Windows XP platforms.
The functions work most efficiently with C/C++ programming languages.


As a first step of building a new program or upgrading an existing one to support
X18CU cameras, the header files Sisc_Codes.h and Sisc_X18CU.h must be included in
all files where SDK functions are called. The second step is to modify the build
environment. If load-time dynamic linking is intended, then the program must be
linked to the import library Sisc_X18CU.lib. If run-time dynamic linking is intended,
this step is not necessary. Before the program runs, a X18CU camera must have been
properly installed using the driver files such as X18CU.sys and 318CU.inf as in case of a
318CU camera.


The following code fragment illustrates the workflow of using the X18CU SDK.


To start working with the camera, call:


Sisc_X18_Initialize();


When the program finishes the use of the camera, call:


Sisc_X18_Uninitialize();


All other function calls must be made in between.


To capture an image, first define frame format by calling:


Sisc_X18_SetFrameFormat(X18_FRAME_FORMAT *pFrameFormat);


Then copy the most recently acquired bitmaps to external buffers by repeatedly calling:


SISC_X18_API X18_GetBitmap(BITMAPINFOHEADER *pInfo, BYTE *pBits);


The other functions are to customize the way raw frame data are processed and do not
have to be called. The following diagram illustrates the processing order. The pertinent


                                                                                      45
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




functions are listed to the right of each step. The functions not shown below are for the
control of the camera and thus precede all the functions shown.



                                                       X18_FFC_Create

                           Raw Data                    X18_FFC_Import

                                                       X18_FFC_Memory

                                                       X18_FFC_Get
                    Flat-Field Correction
                                                       X18_FFC_Set


                                                       X18_WhiteBalance
                       White Balance
                                                       X18_GetKelvin

                                                       X18_SetKelvin

                       Auto Exposure
                                                       X18_AutoExposure



                          Histogram                    X18_GetHistogram




                       Look Up Table                   X18_LUT




                           Gamma                       X18_GetGamma

                                                       X18_SetGamma


                         Bayer Filter



                             Flip                      X18_GetImageFlip

                                                       X18_SetImageFlip


                   Saturation Adjustment               X18_GetSaturation

                                                       X18_SetSaturation

                                                       X18_GetBitmap
                       Output Bitmap




                                                                                      46
info@softinstrument.com
                   Scientific Instrument Software Corporation Limited




Data Structure Reference

X18_FRAME_FORMAT is defined in Sisc_X18CU.h and is the only data structure
unique to the X18CU SDK. All other data types are either standard C types or
pre-defined by Windows SDK.


X18_FRAME_FORMAT is used to specify a region of interest (ROI) within the full senor
pixel array and the way pixels therein are combined and decimated. Its definition is
reproduced below.


typedef struct _X18_FRAME_FORMAT
{
           USHORT xOffset;
           USHORT yOffset;
           USHORT width;
           USHORT height;


           UCHAR subSampleX;
           UCHAR binningX;


           UCHAR subSampleY;
           UCHAR binningY;
} X18_FRAME_FORMAT;


A ROI is completely specified by its:


1. Position.
xOffset is the horizontal coordinate of the leftmost column of the ROI. yOffset is the
vertical coordinate of the topmost row of the ROI. Note that the coordination system is
based on the full pixel array of the sensor, with horizontal coordinate increases from left
to right, starting from 0; and with vertical coordinate increases from top to bottom, also
starting from 0.


2. Size.
width is the number of columns the ROI intersects the full pixel array of the sensor.
height is the number of rows the ROI intersects the full pixel array of the sensor. Both


                                                                                        47
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




width and height refer to the original sensor pixel array. They are not the numbers of
columns and rows of pixels resulted from sub-sampling.


3. Sub-sampling and binning parameters.
The pixels a ROI covers on the original pixel array of the sensor may be combined and
decimated. To combine neighboring pixels, set binningX or binningY to values greater
than 1. To decimate pixels in horizontal and vertical directions, set subSampleX and
subSampleY to values greater than 1. For X18CU cameras, binning is the same as
averaging. The number of columns of the final pixel array is width/subSampleX; the
number of rows of the final pixel array is height/subSampleY.


A ROI is valid only if it meets all of the following requirements:


1. Neither xOffset nor yOffset is less than 0.


2. width is less than or equal to the width of the original pixel array of the sensor. height
is less than or equal to the height of the original pixel array of the sensor.


3. xOffset+width is less than or equal to the width of the original pixel array of the
sensor. yOffset+height is less than or equal to the height of the original pixel array of
the sensor.


4. subSampleX, subSampleY, binningX and binningY must be within the range of the
values supported by an X18 camera.


5. xOffset must be an even number and a multiple of binningX. yOffset must be an even
number and a multiple of binningY.


6. width must be a multiple of 4 x subSampleX. height must be a multiple of 2 x
subSampleY.


7. binningX is either 1 or equal to subSampleX. binningY is either 1 or equal to
subSampleY.




                                                                                          48
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Function Reference

Initialize


SISC_X18_API X18_Initialize();


The Initialize function allocates necessary resources, searches the USB, and connects to
the first X18CU camera it finds.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscCameraInUseError                          The camera is already being used by
                                              another application.
SiscNoCameraAvailableError                    There is no camera available.
SiscHardwareError                             The camera has responded with an error.
SiscCameraUnknownError                        The SDK does not recognize the camera.
SiscOutOfMemoryError                          The SDK can not allocate the required
                                              memory.
SiscOSVersionError                            The SDK cannot run on the current
                                              operating system.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
This function must be the first to call for working with an X18CU camera. The other
functions may be called only after Initialize has returned successfully.




                                                                                      49
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Uninitialize


SISC_X18_API X18_Uninitialize();


The Uninitialized function shuts down the camera and frees the resources previously
allocated for the camera.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.


Remarks
Call this function to clean up. After that, the camera is no longer accessible.




                                                                                     50
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetCameraID


SISC_X18_API X18_GetCameraID(             int *pModel,
                                          int *pMinorPassword,
                                          int *pMajorPassword);


The GetCameraID function retrieves identifying information of the camera.


Parameters


pModel              Points to a 32-bit signed integer that receives the model number
                    of the initialized camera. For example, if the camera in use is
                    318CU, the model number will be 0x318.
pMinorPassword      Points to a 32-bit signed integer that receives the least significant
                    32 bits of the GUID of the initialized camera.
pMajorPassword      Points to a 32-bit signed integer that receives the most significant
                    32 bits of the GUID of the initialized camera.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks


Each X18CU camera is associated with a 64-bit GUID. The GUID is implemented by
hardware and may be used as a serial number or a software dongle.




                                                                                      51
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetFrameFormat


SISC_X18_API X18_GetFrameFormat( X18_FRAME_FORMAT *pFrameFormat,
                                            X18_FRAME_FORMAT *pMinVals,
                                            X18_FRAME_FORMAT *pMaxVals);


The GetFrameFormat function retrieves the frame format currently in use and
optionally the ranges of values for a valid frame format.


Parameters


pFrameFormat        Points to an X18_FRAME_FORMAT that receives the frame format
                    currently in use.
pMinVals            Points to an X18_FRAME_FORMAT that receives the frame format
                    with each member set to the allowed minimal value.
                    This parameter can be NULL.
pMaxVals            Points to an X18_FRAME_FORMAT that receives the frame format
                    with each member set to the allowed maximal value.
                    This parameter can be NULL.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


This function may be used to find the initialized camera’s sensor pixel array size, the
supported minimal ROI size, and the range of binning and sub-sampling factors.




                                                                                    52
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetFrameFormat


SISC_X18_API X18_SetFrameFormat(X18_FRAME_FORMAT *pFrameFormat);


The SetFrameFormat function specifies which part of the sensor array will be
integrating incident photons and the dimension of the resulted video stream.


Parameters
pFrameFormat                                A pointer to the new frame format to set.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks


This function call succeeds only if the new frame format meets the requirements listed
in Data Structure Reference.




                                                                                    53
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetFrameRate


SISC_X18_API X18_GetFrameRate(float* pFrameRate);


The GetFrameRate function reports the current frame rate.


Parameters
pFrameRate                                  Points to a 32-bit floating number that
                                            receives the current frame rate in FPS.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
For all X18CU cameras the frame rate changes with different settings of ROI and
decimation. It is always set by the X18CU camera drivers to the highest possible.




                                                                                      54
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




GetImageFlip


SISC_X18_API X18_GetImageFlip(int *pHorz,int *pVert);


The GetImageFlip function retrieves image flip status.


Parameters
pHorz         Points to a 32-bit signed integer that receives the horizontal flip state. 0
              means the output image is not flipped horizontally. 1 means the output
              image is flipped horizontally.
              This parameter can be NULL.
pVert         Points to a 32-bit signed integer that receives the vertical flip state. 0
              means the output image is not flipped vertically. 1 means the output image
              is flipped vertically.
              This parameter can be NULL.


Return Values
SiscSuccess                                     The function has completed successfully.
SiscUnknownError                                Unknown error
SiscUnInitializedError                          Camera has not yet been initialized.
SiscInvalidParameterError                       Invalid parameters
SiscBufferTooSmall                              A buffer passed as parameter is too small.
SiscHardwareError                               The camera has responded with an error.
SiscIOError                                     An error has occurred during an IO
                                                operation.


Remarks
Note that the flips apply to the current video stream, which is completely specified by
the SetFrameFormat function. Note also that the flipping, if any, takes place after auto
exposure and white balance, which base their sub-window on the original image
geometry, i.e. without flipping.




                                                                                             55
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetImageFlip


SISC_X18_API X18_SetImageFlip(int *pHorz,int *pVert);


The SetImageFlip function flips the images in the current video stream.


Parameters
pHorz     Pointer to the horizontal flip state to set. 0 means to cancel the horizontal flip
          if any. 1 means to flip the output image horizontally.
          This parameter can be NULL.
pVert     Pointer to the vertical flip state to set. 0 means to cancel the vertical flip if
          any. 1 means to flip the output image vertically.
          This parameter can be NULL.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscBufferTooSmall                             A buffer passed as parameter is too small.
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.
SiscOutOfRangeError                            A feature to set is out of range.


Remarks


Note that the flips apply to the current video stream, which is completely specified by
the SetFrameFormat function. Note also that the flipping, if any, takes place after auto
exposure and white balance, which base their sub-window on the original image
geometry, i.e. without flipping.




                                                                                              56
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetExposureTime


SISC_X18_API X18_GetExposureTime( float *pExposure,
                                            float *pMinExposure,
                                            float *pMaxExposure);


The GetExposureTime function retrieves the current exposure time and optionally the
allowable range of exposure time.


Parameters
pExposure          Points to a 32-bit floating number that receives the current
                     exposure time, in milliseconds.
pMinExposure         Points to a 32-bit floating number that receives that allowed
                     minimal exposure time, in milliseconds.
                     This parameter can be NULL.
pMaxExposure         Points to a 32-bit floating number that receives that allowed
                     maximal exposure time, in milliseconds.
                     This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
The exposure range changes with different ROI and decimation settings. A previous
exposure time, even though valid at the time it was set, might be modified without
warning when a new ROI or decimation setting does not permit that exposure time.




                                                                                      57
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetExposureTime


SISC_X18_API X18_SetExposureTime(float *pExposure);


The SetExposureTime function sets the exposure time, in milliseconds, of the camera.


Parameters
pExposure                                  Pointer to a 32-bit floating number that is
                                            to be the new exposure time. The exposure
                                            time is always set in milliseconds.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
To avoid flicker, set the exposure time to multiples of 10ms for 50Hz AC or 8.33ms for
60Hz AC.




                                                                                    58
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




AutoExposure


SISC_X18_API X18_AutoExposure(int Percentage,RECT *pSubWindow);


The AutoExposure function modifies the exposure time based on the most recent frame
in the video stream and the input parameters.


Parameters
Percentage                                 Specifies the desired average intensity of
                                           the pixels in the ROI or a sub-window of it,
                                           as a percentage of the full dynamic range.
                                           Must be in the range [1, 99].
pSubWindow                                 If NULL, indicates the exposure
                                           adjustment should be based on the current
                                           ROI. If a valid pointer to RECT, specifies
                                           that the exposure adjustment should be
                                           based on the sub-window of the ROI, as
                                           given by the RECT it points to.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
This is one-push auto exposure operation. To implement continuous auto exposure, call
this function in response to a timer message. Note that the sub-window refers to the
image before it is possibly flipped.




                                                                                    59
info@softinstrument.com
                   Scientific Instrument Software Corporation Limited




GetGlobalGain


SISC_X18_API X18_GetGlobalGain(               float *pGlobalGain,
                                              float *pMinGlobalGain,
                                              float *pMaxGlobalGain);


The GetGlobalGain function retrieves the current global gain applied to the camera,
and optionally the allowed minimal and maximal global gain values.


Parameters
pGlobalGain            Points to a 32-bit floating number that receives the current global
                       gain value of the camera.
pMinGlobalGain         Points to a 32-bit floating number that receives the allowed
                       minimal global gain value of the camera.
                       This parameter can be NULL.
pMaxGlobalGain         Points to a 32-bit floating number that receives the allowed
                       maximal global gain value of the camera.
                       This parameter can be NULL.


Return Values


SiscSuccess                                     The function has completed successfully.
SiscUnknownError                                Unknown error
SiscUnInitializedError                          Camera has not yet been initialized.
SiscInvalidParameterError                       Invalid parameters
SiscBufferTooSmall                              A buffer passed as parameter is too small.
SiscHardwareError                               The camera has responded with an error.
SiscIOError                                     An error has occurred during an IO
                                                operation.


Remarks
Global gain applies to all three color channels simultaneously as a multiplicative factor.
For X18CU cameras the global gain is implemented as digital gain. Since the ADs used
by X18CU cameras are 10-bit at least but the output is always the most significant 8
bits, a global gain of 2 or greater values help to shift out less significant bits.



                                                                                        60
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetGlobalGain


SISC_X18_API X18_SetGlobalGain(float *pGlobalGain);


The SetGlobalGain function directs the camera to amplify the signal by a given factor.


Parameter
pGlobalGain                                 Pointer to a 32-bit floating number that is
                                            be set as the new global gain.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
The gain values are factors.




                                                                                     61
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetBlueGain


SISC_X18_API X18_GetBlueGain(              float *pBlueGain,
                                           float *pMinBlueGain,
                                           float *pMaxBlueGain);


The GetBlueGain function retrieves the current blue gain value and optionally the
allowed minimal and maximal blue gain values.


Parameters
pBlueGain                                   Points to a 32-bit floating number that
                                            receives the current blue gain value.
pMinBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed minimal blue gain
                                            value.
                                            This parameter can be NULL.
pMaxBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed maximal blue gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X18CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      62
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetBlueGain


SISC_X18_API X18_SetBlueGain(float *pBlueGain);


The SetBlueGain function directs the camera to amplify the blue channel by the given
multiplicative factor.


Parameters
pBlueGain                                     Pointer to a 32-bit floating number that
                                              will be set as the new blue gain.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
Color gains are implemented as analog gains for X18CU cameras. These gains, however,
can only change in discrete steps. For most accurate color reproduction, it is advised
that these color gains are set as large as possible, while maintaining the needed relative
strength.




                                                                                         63
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetGreenGain


SISC_X18_API X18_GetGreenGain(             float *pGreenGain,
                                           float *pMinGreenGain,
                                           float *pMaxGreenGain);


The GetGreenGain function retrieves the current green gain value and optionally the
allowed minimal and maximal green gain values.


Parameters
pGreenGain                                  Points to a 32-bit floating number that
                                            receives the current green gain value.
pMinGreenGain                               Points to a 32-bit floating number that
                                            receives the allowed minimal green gain
                                            value.
                                            This parameter can be NULL.
pMaxGreenGain                               Points to a 32-bit floating number that
                                            receives the allowed maximal green gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X18CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      64
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetGreenGain


SISC_X18_API X18_SetGreenGain(float *pGreenGain);


The SetGreenGain function directs the camera to amplify the green channel by the
given multiplicative factor.


Parameters
pGreenGain                                    Pointer to a 32-bit floating number that
                                              will be set as the new green gain.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
Color gains are implemented as analog gains for X18CU cameras. These gains, however,
can only change in discrete steps. For most accurate color reproduction, it is advised
that these color gains are set as large as possible, while maintaining the needed relative
strength.




                                                                                         65
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetRedGain


SISC_X18_API X18_GetRedGain(               float *pRedGain,
                                           float *pMinRedGain,
                                           float *pMaxRedGain);


The GetRedGain function retrieves the current red gain value and optionally the
allowed minimal and maximal red gain values.


Parameters
pRedGain                                    Points to a 32-bit floating number that
                                            receives the current red gain value.
pMinRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed minimal red gain
                                            value.
                                            This parameter can be NULL.
pMaxRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed maximal red gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X18CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      66
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetRedGain


SISC_X18_API X18_SetRedGain(float *pRedGain);


The SetRedGain function directs the camera to amplify the red channel by the given
multiplicative factor.


Parameters
pRedGain                                      Pointer to a 32-bit floating number that
                                              will be set as the new red gain.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks


Color gains are implemented as analog gains for X18CU cameras. These gains, however,
can only change in discrete steps. For most accurate color reproduction, it is advised
that these color gains are set as large as possible, while maintaining the needed relative
strength.




                                                                                         67
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetSaturation


SISC_X18_API X18_GetSaturation(            float *pSaturation,
                                           float *pMinSaturation,
                                           float *pMaxSaturation);


The GetSaturation function retrieves the saturation level currently applied to the
bitmaps before they are output.


Parameters
pSaturation                                  Points to a 32-bit floating number that
                                             receives the current saturation level.
pMinSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed minimal saturation
                                             level.
                                             This parameter can be NULL.
pMaxSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed maximal saturation
                                             level.
                                             This parameter can be NULL.


Return Values


SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
The function reports the default saturation value, i.e. no modification to the saturation
of output bitmaps, as the current saturation level, after the camera initializes
successfully and before the saturation level is changed by SetSaturation.



                                                                                        68
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetSaturation


SISC_X18_API X18_SetSaturation(float *pSaturation);


The SetSaturation function directs the saturation of the output bitmap be modified by
the given amount.


Parameters
pSaturation                                 Pointer to a 32-bit floating number that
                                            will be set as the new saturation level.




Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.




Remarks
Saturation adjustment is the last step of processing before a bitmap is output. It does
not affect the other intermediate image processing, in particular, the histogram
reported by the SDK function will not be changed by a new saturation setting.




                                                                                       69
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetKelvin


SISC_X18_API X18_GetKelvin(               float *pKelvin,
                                          float *pMinKelvin,
                                          float *pMaxKelvin);


The GetKelvin function retrieves the image temperature currently in use as a basis to
white balance.


Parameters


pKelvin            Points to a 32-bit floating number that receives the image
                   temperature currently in use as a basis to white balance.
pMinKelvin         Points to a 32-bit floating number that receives the allowed
                   minimal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.
pMaxKelvin         Points to a 32-bit floating number that receives the allowed
                   maximal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
Image temperature is measured in Kelvin. A value of 0 means image temperature is not
considered in white balance.




                                                                                   70
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetKelvin


SISC_X18_API X18_SetKelvin(float *pKelvin);


The SetKelvin function specified a new image temperature to be used as a basis to white
balance.


Parameters
pKelvin                                      Pointer to a 32-bit floating number to be
                                             set as the new image temperature.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.
SiscOutOfRangeError                          A feature to set is out of range.


Remarks


If set to 0, the image temperature will not be considered in the white balance.


See Appendix 1 for light source examples that show various temperatures.




                                                                                         71
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetGamma


SISC_X18_API X18_GetGamma( float *pGamma ,
                                 float *pMinGamma,
                                 float *pMaxGamma);


The GetGamma function retrieves the Gamma value of the camera.


Parameters
pGamma                                    Points to 32-bit floating number that
                                          receives the current Gamma value of the
                                          camera.
pMinGamma                                 Points to 32-bit floating number that
                                          receives the allowed minimal Gamma
                                          value of the camera.
                                          This parameter can be NULL.
pMaxGamma                                 Points to 32-bit floating number that
                                          receives the allowed maximal Gamma
                                          value of the camera.
                                          This parameter can be NULL.


Return Values
SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscHardwareError                         The camera has responded with an error.
SiscIOError                               An error has occurred during an IO
                                          operation.


Remarks
The default Gamma value is 1.




                                                                                  72
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetGamma


SISC_X18_API X18_SetGamma(float *pGamma);


The SetGamma function specifies the Gamma value of the camera.


Parameters
pGamma                                       Pointer to a 32-bit floating number that
                                             will be set as the new Gamma value of the
                                             camera.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.
SiscOutOfRangeError                          A feature to set is out of range.


Remark
If set to 0, no Gamma will be applied to the camera, i.e. a Gamma value of 0 is the same
as a Gamma value of 1.




                                                                                        73
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




WhiteBalance


SISC_X18_API X18_WhiteBalance(RECT *pSubWindow);


The WhiteBalance function performs white balance based on the most recent frame in
the video stream.


Parameters
pSubWindow                                    If NULL, the white balance will be base on
                                              the current ROI. If a valid pointer, the
                                              white balance will be based on a
                                              sub-window of the current ROI, as
                                              specified by the RECT it points to.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
The white balance refers to the process of adjusting relative strength of color channel
gains based on the raw data the camera delivers and the temperature setting. This
function keeps the green channel gain intact and modifies blue and red gains only. Note
that the sub-window refers to the image before it is possibly flipped.


For a digital image to match an optical image in terms of color reproduction, it is
necessary to consider, besides white balance and light source temperature settings, the
spectral responses of the IR cutoff filter and camera sensors. Please refer to Appendix 2
and 3 for further information.




                                                                                         74
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetBitmap


SISC_X18_API X18_GetBitmap(BITMAPINFOHEADER *pInfo, BYTE *pBits);


The GetBitmap function retrieves the most recent image the camera delivers.


Parameters
pInfo                                         Points to a BITMAPINFOHEADER
                                              structure that receives the bitmap
                                              information.
pBits                                         Points to pixels stored in RGB24 format.
                                              This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscInvalidPointerError                       Invalid pointer


Remarks
This function will not return until the most recent bitmap is available. It stores the
bitmap in Windows DIB format as indicated by the parameters. Note that it is a
top-down DIB and its origin is the upper-left corner, i.e. pInfo->biHeight is negative.




                                                                                          75
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




LUT


SISC_X18_API X18_LUT(float x1,float y1,float x2,float y2);


The LUT function performs intensity windowing on the frames in the video stream.


Parameters


x1        The x coordinate of the first control point
y1        The y coordinate of the first control point
x2        The x coordinate of the second control point
y2        The y coordinate of the second control point


Return Values


SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
This function sets up a pixel value transform which maps the each value in the dynamic
range of raw data to another value in the dynamic range of the final output image. For
this function both dynamic ranges are normalized to [0, 1]. The transform is specified by
two control points (x1, y1) and (x2, y2), which means the value x1 in the original
dynamic range will be mapped to y1 in the new dynamic range and the value x2 in the
original dynamic range will be mapped to y2 in the new dynamic range. The transform
is piecewise linear, assuming 0 is mapped to 0 and 1 is mapped to 1, as illustrated below.




                                                                                       76
info@softinstrument.com
                                Scientific Instrument Software Corporation Limited




                                1

                                y2
            New Dynamic Range




                                y1




                         (0, 0)                x1          x2                        1
                                               Original Dynamic Range




Setting both (x1, y1) and (x2, y2) to either (0, 0) or (1, 1) effectively cancels the intensity
windowing. It is required that x2-x1>0.01.




                                                                                            77
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Create


SISC_X18_API X18_FFC_Create(double *pParams);


The FFC_Create function calculates the coefficients needed for Flat-Field Correction
and optionally exports the coefficients.


Parameters
pParams                                      Points to a buffer that receives the FFC
                                             calibration coefficients.
                                             This parameter can be NULL.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscBufferTooSmall                           A buffer passed as parameter is too small.
SiscCameraInUseError                         The camera is already being used by
                                             another application.
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


Flat-Field Correction (FFC) refers to the real-time image calibration for sensor’s
spatially varying response to incident light, uneven illumination and non-uniform
transmission rate of the lens or other optical systems. The FFC_Create function
computes the coefficient matrix based on the most recent frame in the video stream,
captured with the full pixel array of the sensor. It is not necessary for an application
program to explicitly switch the camera to that state as the FFC_Create function will do
that and will restore the previous frame format upon completion of the function. For
optimal result, it is recommended that before calling this function:




                                                                                        78
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




1. Shoot the camera at a slowly varying white background. The field of view should not
be obstructed by any object other than the white background.


2. Adjust the illumination, lens aperture or camera exposure time so that the image is
as bright as possible but not exceeding its dynamic range.


3. Perform white balance to remove the apparent color aberrations. The temperature
should be set to 0 before the white balance.




                                                                                   79
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Import


SISC_X18_API X18_FFC_Import(double *pParams);


The FFC_Import function loads the previously created calibration coefficients.


Parameters


pParams                                     Pointer to FFC calibration coefficients
                                            that will be loaded.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.




Remarks
The coefficients to load must have been created by the FFC_Create function.




                                                                                      80
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Memory


SISC_X18_API X18_FFC_Memory(int *pSizeInBytes);


The FFC_Memory reports the number of bytes needed to hold the calibration
coefficients.


Parameters


pSizeInBytes                                 Points to a 32-bit integer that receives the
                                             size of the memory, in bytes, to hold the
                                             FFC calibration coefficients.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


This function reports the size of the memory that an application program needs to
allocate so that the FFC_Create function can export the coefficients.




                                                                                         81
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Get


SISC_X18_API X18_FFC_Get(BOOL *pStatus);


The FFC_Get function retrieves the status of FFC.


Parameters
pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means FFC is off. 1 means
                                            FFC is on.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
FFC is a computation intensive operation.




                                                                                      82
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Set


SISC_X18_API X18_FFC_Set(BOOL *pStatus);


The FFC_Set function turns FFC on or off.


Parameters


pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means turning off FFC. 1
                                            means turning on FFC.




Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
FFC is a computation intensive operation.




                                                                                      83
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetHistogram


SISC_X18_API X18_GetHistogram(             int *pHistogramData,
                                           int *pHistogramSize);


The GetHistogram function profiles the intensity distribution of the most recent image.


Parameters
pHistogramData                              Points to the first of an array of integers
                                            that receive histogram data.
                                            This parameter can be NULL.
pHistogramSize                              Points to an integer that receives the size
                                            of the memory, in bytes, to hold the
                                            histogram data.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscInvalidPointerError                     Invalid pointer
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
The X18CU SDK uses an integer array to hold histogram. The array is divided into
three consecutive segments, to hold pixel count for blue, green and red channel
respectively. The first integer in each segment is the number of pixels with their
corresponding color value being 0. The last integer in each segment is the number of
pixels with their corresponding color being the maximum of the dynamic range.




                                                                                          84
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




Return Code List

SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscBufferTooSmall                        A buffer passed as parameter is too small.
SiscCameraInUseError                      The camera is already being used by
                                          another application.
SiscNoCameraAvailableError                There is no camera available.
SiscHardwareError                         The camera has responded with an error.
SiscCameraUnknownError                    The SDK does not recognize the camera.
SiscOutOfMemoryError                      The SDK can not allocate the required
                                          memory.
SiscOSVersionError                        The SDK cannot run on the current
                                          operating system.
SiscIOError                               An error has occurred during an IO
                                          operation.
SiscOutOfRangeError                       A feature to set is out of range.
SiscInvalidPointerError                   Invalid pointer




                                                                                  85
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Appendix 1 Common Color Temperatures


Light Source                                  Color Temperature (Kelvin)
Clear Blue Sky                                8000 to 27000
Rainy, Misty Daylight                         7200 to 8500
Overcast Daylight                             6500 to 7200
Direct Sun Clear Blue Sky                     5700 to 6500
Summer Sunlight (9am to 3pm)                  5400 to 5700
Summer Sunlight (Before 9am or After 3pm) 4900 to 5600
Electronic Flash (Typical)                    6200 to 6800
Xenon Arc (Unfiltered)                        6000
White Flame Carbon Arc                        5000
Yellow Flame Carbon Arc                       3200
“True Daylight” Color Match Tubes             6500
“Daylight” Cool White Tubes                   4300
“Warm White” Tubes                            3000
Photoflood & 3400K Tungsten-Halogen           3400
Tungsten-Halogen and Photo Lamps              3200
Projection Lamps (500 to 1000 Watts)          2900 to 3000
General Purpose Lamps (200 to 500 Watts)      2900
Household Lamps (100 to 150 Watts)            2850
Household Lamps (60 Watts)                    2800
Household Lamps (40 Watts)                    2750
Standard Candle                               2000
Candle Flame                                  1500




                                                                           86
info@softinstrument.com
                                  Scientific Instrument Software Corporation Limited




Appendix 2 Spectral Response of IR Cutoff Filter




                      100.00


                       90.00


                       80.00


                       70.00
  Transmittance [%]




                       60.00


                       50.00


                       40.00


                       30.00


                       20.00


                       10.00


                        0.00
                            200   300    400     500     600     700     800     900   1000   1100

                                                       Wavelength [nm]


Roughly speaking, the pass band is [400nm, 625nm]. Consider replacing this filter by a
more appropriate one in applications where the band [625nm, 700nm] is needed.




                                                                                                 87
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




Appendix 3 Spectral Response of Sensors




                 The spectral Response of X18CU Camera Sensors




                                                                     88
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




            Software Development Kit
                                     for
                          X90CU Cameras


                          (X90CU SDK)




                            Version 1.0




                                                                     89
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Introduction

The X90CU refers to a series of USB 2.0 CCD color cameras designed for fluorescent
microscopy, deep-sky astrophotography, and other low-light imaging applications. These
cameras generate uncompressed images having 12 bits per channel. The X90CU
Software Development Kit (SDK) is a set of functions that an application program calls
to capture images, and optionally to specify how the raw images are to be processed
before they are exported to the application program. The internal computation is based
on the original bit depth of the cameras. The output is 3x8-bit bitmaps for easy
integration to existing application programs.


The files contained in the X90CU SDK are:


1     Sisc_Codes.h        The header file that defines error codes that SDK functions
                          may return. These error codes are used across all SDKs.
2     Sisc_X90CU.h        The header file that defines prototypes of all functions in this
                          SDK.
3     Sisc_X90CU.lib      The import library for the dynamic link library of this SDK.
4     Sisc_X90CU.dll      The dynamic link library where all functions of this SDK
                          reside.
5     Sisc_X90CU.pdf      The reference manual of this SDK.
6     X90CU.sys           One of the two driver files needed to install an X90CU camera.
                          The same file is used across all X90CU cameras.
7     190CU.inf           The other driver file needed to install a 190CU camera.
8     390CU.inf           The other driver file needed to install a 390CU camera.
9     590CU.inf           The other driver file needed to install a 590CU camera.




                                                                                         90
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Using the SDK

The X90CU SDK has been tested on 32-bit Windows 2000 and Windows XP platforms.
The functions work most efficiently with C/C++ programming languages.


As a first step of building a new program or upgrading an existing one to support the
X90CU cameras, the header files Sisc_Codes.h and Sisc_X90CU.h must be included in
all files where the X90 SDK functions are called. The second step is to modify the build
environment. If load-time dynamic linking is intended, the program must be linked to
the import library Sisc_X90CU.lib. If run-time dynamic linking is intended, this step is
not necessary. Before the program runs, an X90CU camera must have been properly
installed using the driver files such as X90CU.sys and 590CU.inf as in case of a 590CU
camera.


The following code fragment illustrates the workflow of using the X90 SDK.


To start working with the camera, call:


Sisc_X90_Initialize();


When the program finishes the use of the camera, call:


Sisc_X90_Uninitialize();


All other function calls must be made in between.


The X90CU cameras support two imaging modes: video imaging mode and still imaging
mode. In video imaging mode, an X90CU camera delivers images at a constant frame
rate. The exposure time in video mode is thus limited to 1000 milliseconds divided by
the frame rate. In still imaging mode, a very long exposure time may be specified. When
an X90CU camera is initialized, it is put into video imaging mode. To learn the frame
format of the video imaging mode, call:


SISC_X90_API X90_GetVideoFormat(int *pWidth,int *pHeight);


It is not possible to change the frame format, i.e. region of interest and decimation are


                                                                                      91
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




fixed.


To capture an image in the video imaging mode, call:


SISC_X90_API X90_GetVideoBitmap(BITMAPINFOHEADER *pInfo,BYTE *pBits);


It is not necessary to explicitly switch to the still imaging mode to capture an image in
that mode. In the case of 590CU cameras, the frame format in the video imaging mode
is different from that in the still imaging mode. To learn the frame format in the still
imaging mode, call:


SISC_X90_API X90_GetStillFormat(int *pWidth,int *pHeight);


As in the video imaging mode, it is not possible to change the frame format.


To capture an image in the still imaging mode, call:


SISC_X90_API X90_GetStillBitmap(BITMAPINFOHEADER *pInfo,BYTE *pBits);


The other functions are to customize the way raw frame data are processed and do not
have to be called. The following diagram illustrates the processing order. The pertinent
functions are listed to the right of each step. Those functions not shown are for the
control of the cameras and thus precede all the functions shown.




                                                                                      92
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




                                                   X90_FFC_Create

                           Raw Data                X90_FFC_Import

                                                   X90_FFC_Memory

                                                   X90_FFC_Get
                  Flat-Field Correction
                                                   X90_FFC_Set


                                                   X90_WhiteBalance
                     White Balance
                                                   X90_GetKelvin

                                                   X90_SetKelvin

                     Auto Exposure
                                                   X90_AutoExposure



                          Histogram                X90_GetHistogram




                      Bayer Filter



                            Flip                   X90_GetImageFlip

                                                   X90_SetImageFlip


                 Saturation Adjustment             X90_GetSaturation

                                                   X90_SetSaturation


                     Look Up Table                 X90_LUT




                           Gamma                   X90_GetGamma

                                                   X90_SetGamma

                                                   X90_GetVidoeBitmap
                     Output Bitmap
                                                   X90_GetStillBitmap




                                                                        93
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Function Reference

Initialize


SISC_X90_API X90_Initialize();


The Initialize function allocates necessary resources, searches the USB, and connects to
the first X90CU camera it finds.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscCameraInUseError                          The camera is already being used by
                                              another application.
SiscNoCameraAvailableError                    There is no camera available.
SiscHardwareError                             The camera has responded with an error.
SiscCameraUnknownError                        The SDK does not recognize the camera.
SiscOutOfMemoryError                          The SDK can not allocate the required
                                              memory.
SiscOSVersionError                            The SDK cannot run on the current
                                              operating system.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
This function must be the first to call for working with an X90CU camera. The other
functions may be called only after Initialize has returned successfully.




                                                                                      94
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Uninitialize


SISC_X90_API X90_Uninitialize();


The Uninitialized function shuts down the camera and frees the resources previously
allocated for the camera.


Parameters
No parameter is needed.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.


Remarks
Call this function to clean up. After that, the camera is no longer accessible.




                                                                                     95
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetCameraID


SISC_X90_API X90_GetCameraID(             int *pModel,
                                          int *pMinorPassword,
                                          int *pMajorPassword);


The GetCameraID function retrieves identifying information of the camera.


Parameters


pModel              Points to a 32-bit signed integer that receives the model number
                    of the initialized camera. For example, if the camera in use is
                    590CU, the model number will be 0x590.
pMinorPassword      Points to a 32-bit signed integer that receives the least significant
                    32 bits of the GUID of the initialized camera.
pMajorPassword      Points to a 32-bit signed integer that receives the most significant
                    32 bits of the GUID of the initialized camera.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks


Each X90CU camera is associated with a 64-bit GUID. The GUID is implemented by
hardware and may be used as a serial number or a software dongle.




                                                                                      96
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetFrameRate


SISC_X90_API X90_GetFrameRate(float *pFrameRate);


The GetFrameRate function reports the frame rate of the camera operating in the video
imaging mode.


Parameters
pFrameRate                                  Points to a 32-bit floating number that
                                            receives the current frame rate in FPS.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
The concept of frame rate applies to the video imaging mode only.




                                                                                      97
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




GetImageFlip


SISC_X90_API X90_GetImageFlip(int *pHorz,int *pVert);


The GetImageFlip function retrieves image flip status.


Parameters
pHorz         Points to a 32-bit singed integer that receives the horizontal flip state. 0
              means the output image is not flipped horizontally. 1 means the output
              image is flipped horizontally.
              This parameter can be NULL.
pVert         Points to a 32-bit signed integer that receives the vertical flip state. 0
              means the output image is not flipped vertically. 1 means the output image
              is flipped vertically.
              This parameter can be NULL.


Return Values
SiscSuccess                                     The function has completed successfully.
SiscUnknownError                                Unknown error
SiscUnInitializedError                          Camera has not yet been initialized.
SiscInvalidParameterError                       Invalid parameters
SiscBufferTooSmall                              A buffer passed as parameter is too small.
SiscHardwareError                               The camera has responded with an error.
SiscIOError                                     An error has occurred during an IO
                                                operation.


Remarks
The flipping takes place after auto exposure and white balance operations, which base
their sub-window on the original image geometry, i.e. without flipping.




                                                                                             98
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetImageFlip


SISC_X90_API X90_SetImageFlip(int *pHorz,int *pVert);


The SetImageFlip function flips the images being output to application programs.


Parameters
pHorz     Pointer to the horizontal flip state to set. 0 means to cancel the horizontal flip
          if any. 1 means to flip the output image horizontally.
          This parameter can be NULL.
pVert     Pointer to the vertical flip state to set. 0 means to cancel the vertical flip if
          any. 1 means to flip the output image vertically.
          This parameter can be NULL.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscBufferTooSmall                             A buffer passed as parameter is too small.
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.
SiscOutOfRangeError                            A feature to set is out of range.


Remarks
The flipping, if any, takes place after auto exposure and white balance operations, which
base their sub-window on the original image geometry, i.e. without flipping.




                                                                                              99
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetVideoExposureTime


SISC_X90_API X90_GetVideoExposureTime(               float *pExposure,
                                                     float *pMinExposure,
                                                     float *pMaxExposure);


The GetVideoExposureTime function retrieves the current exposure time and optionally
the range of exposure time supported by the camera in the video imaging mode.


Parameters
pExposure           Points to a 32-bit floating number that receives the current
                     exposure time, in milliseconds, of the camera in the video imaging
                     mode.
pMinExposure         Points to a 32-bit floating number that receives the minimal
                     exposure time, in milliseconds, supported by the camera in the
                     video imaging mode.
                     This parameter can be NULL.
pMaxExposure         Points to a 32-bit floating number that receives the maximal
                     exposure time, in milliseconds, supported by the camera in the
                     video imaging mode.
                     This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
The exposure range in the video imaging mode is different from that in the still imaging
mode. The two imaging modes usually share the same minimal exposure time, which is
also the increment of exposure time, i.e. an actual exposure time is some multiple of this

                                                                                      100
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




value. The maximal exposure time allowed in the video imaging mode is limited to 1000
milliseconds divided by the frame rate. The maximal exposure time allowed in the still
imaging mode can be much longer.




                                                                                  101
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetVideoExposureTime


SISC_X90_API X90_SetVideoExposureTime(float *pExposure);


The SetVideoExposureTime function sets the exposure time, in milliseconds, of the
camera in the video imaging mode.


Parameters
pExposure                                   Pointer to a 32-bit floating number that is
                                            to be the new exposure time of the camera
                                            in the video imaging mode. The exposure
                                            time is always set in milliseconds.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
To avoid flicker, set the exposure time to multiples of 10ms for 50Hz AC or 8.33ms for
60Hz AC.




                                                                                    102
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetStillExposureTime


SISC_X90_API X90_GetStillExposureTime(               float *pExposure,
                                                     float *pMinExposure,
                                                     float *pMaxExposure);


The GetStillExposureTime function retrieves the current exposure time and optionally
the range of exposure time supported by the camera in the still imaging mode.


Parameters
pExposure           Points to a 32-bit floating number that receives the current
                     exposure time, in milliseconds, of the camera in the still imaging
                     mode.
pMinExposure         Points to a 32-bit floating number that receives the minimal
                     exposure time, in milliseconds, supported by the camera in the still
                     imaging mode.
                     This parameter can be NULL.
pMaxExposure         Points to a 32-bit floating number that receives the maximal
                     exposure time, in milliseconds, supported by the camera in the still
                     imaging mode.
                     This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
The exposure range in the video imaging mode is different from that in the still imaging
mode. The two imaging modes usually share the same minimal exposure time, which is
also the increment of exposure time, i.e. an actual exposure time is some multiple of this

                                                                                      103
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




value. The maximal exposure time allowed in the video imaging mode is limited to 1000
milliseconds divided by the frame rate. The maximal exposure time allowed in the still
imaging mode can be much longer.




                                                                                  104
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetStillExposureTime


SISC_X90_API X90_SetStillExposureTime(float *pExposure);


The SetStillExposureTime function sets the exposure time, in milliseconds, of the
camera in the still imaging mode.


Parameters
pExposure                                      Pointer to a 32-bit floating number that is
                                               to be the new exposure time of the camera
                                               in the still imaging mode. The exposure
                                               time is always set in milliseconds.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscBufferTooSmall                             A buffer passed as parameter is too small.
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.
SiscOutOfRangeError                            A feature to set is out of range.


Remarks
To avoid interference by flickers in the light source, set the exposure time to multiples of
10ms for 50Hz AC or 8.33ms for 60Hz AC.




                                                                                        105
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




AutoExposure


SISC_X90_API X90_AutoExposure(int Percentage,RECT *pSubWindow);


The AutoExposure function modifies the exposure time based on the most recent frame
in the video stream and the input parameters.


Parameters
Percentage                                    Specifies the desired average intensity of
                                              the pixels in the ROI or a sub-window of it,
                                              as a percentage of the full dynamic range.
                                              Must be in the range [1, 99].
pSubWindow                                    If NULL, indicates the exposure
                                              adjustment should be based on the current
                                              ROI. If a valid pointer to RECT, specifies
                                              that the exposure adjustment should be
                                              based on the sub-window of the ROI, as
                                              given by the RECT it points to.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
This is one-push auto exposure operation for video imaging mode. To implement
continuous auto exposure, call this function in response to a timer message. Note that
the sub-window is relative to the image before it is possibly flipped.




                                                                                      106
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetGlobalGain


SISC_X90_API X90_GetGlobalGain(             float *pGlobalGain,
                                            float *pMinGlobalGain,
                                            float *pMaxGlobalGain);


The GetGlobalGain function retrieves the current global gain applied to the camera,
and optionally the allowed minimal and maximal global gain values.


Parameters
pGlobalGain           Points to a 32-bit floating number that receives the current global
                      gain value of the camera.
pMinGlobalGain        Points to a 32-bit floating number that receives the allowed
                      minimal global gain value of the camera.
                      This parameter can be NULL.
pMaxGlobalGain        Points to a 32-bit floating number that receives the allowed
                      maximal global gain value of the camera.
                      This parameter can be NULL.


Return Values


SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks
Global gain applies to all three color channels simultaneously as a multiplicative factor.




                                                                                      107
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetGlobalGain


SISC_X90_API X90_SetGlobalGain(float *pGlobalGain);


The SetGlobalGain function directs the camera to amplify the signal by a given factor.


Parameter
pGlobalGain                                 Pointer to a 32-bit floating number that is
                                            be set as the new global gain.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
The gain values are factors.




                                                                                    108
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetFrameMode


SISC_X90_API X90_GetFrameMode(int *pFrameMode);


The GetFrameMode function retrieves the current frame mode of the camera.


Parameters
pFrameMode           Points to a 32-bit signed integer that receives the current frame
                     mode.
                     If the frame mode is 1, red, green and blue channels are all
                     captured. If the frame mode is 2, only green and blue channels are
                     captured. If the frame mode is -2, only green and red channels are
                     captured.


Return Values


SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscBufferTooSmall                           A buffer passed as parameter is too small.
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
For some applications such as fluorescent microscopy, all primary colors are not needed.
Transmitting two channels instead of three actually doubles the frame rate.




                                                                                    109
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetFrameMode


SISC_X90_API X90_SetFrameMode(int *pFrameMode);


The SetFrameMode function directs the camera to capture either all 3 channels or only
2 channels.


Parameter
pFrameMode                                   Pointer to a 32-bit signed integer that is be
                                             set as the new frame mode.
                                             If the frame mode is 1, red, green and blue
                                             channels are all captured. If the frame
                                             mode is 2, only green and blue channels
                                             are captured. If the frame mode is -2, only
                                             green and red channels are captured.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.
SiscOutOfRangeError                          A feature to set is out of range.


Remarks
For some applications such as fluorescent microscopy, all primary colors are not needed.
Transmitting two channels instead of three actually doubles the frame rate.




                                                                                       110
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetBlueGain


SISC_X90_API X90_GetBlueGain(              float *pBlueGain,
                                           float *pMinBlueGain,
                                           float *pMaxBlueGain);


The GetBlueGain function retrieves the current blue gain value and optionally the
allowed minimal and maximal blue gain values.


Parameters
pBlueGain                                   Points to a 32-bit floating number that
                                            receives the current blue gain value.
pMinBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed minimal blue gain
                                            value.
                                            This parameter can be NULL.
pMaxBlueGain                                Points to a 32-bit floating number that
                                            receives the allowed maximal blue gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X90CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      111
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetBlueGain


SISC_X90_API X90_SetBlueGain(float *pBlueGain);


The SetBlueGain function directs the camera to amplify the blue channel by the given
multiplicative factor.


Parameters
pBlueGain                                  Pointer to a 32-bit floating number that
                                           will be set as the new blue gain.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
Color gains are implemented as digital multiplications for X90CU cameras.




                                                                                  112
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetGreenGain


SISC_X90_API X90_GetGreenGain(             float *pGreenGain,
                                           float *pMinGreenGain,
                                           float *pMaxGreenGain);


The GetGreenGain function retrieves the current green gain value and optionally the
allowed minimal and maximal green gain values.


Parameters
pGreenGain                                  Points to a 32-bit floating number that
                                            receives the current green gain value.
pMinGreenGain                               Points to a 32-bit floating number that
                                            receives the allowed minimal green gain
                                            value.
                                            This parameter can be NULL.
pMaxGreenGain                               Points to a 32-bit floating number that
                                            receives the allowed maximal green gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X90CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      113
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetGreenGain


SISC_X90_API X90_SetGreenGain(float *pGreenGain);


The SetGreenGain function directs the camera to amplify the green channel by the
given multiplicative factor.


Parameters
pGreenGain                                 Pointer to a 32-bit floating number that
                                           will be set as the new green gain.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
Color gains are implemented as digital multiplications for X90CU cameras.




                                                                                  114
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetRedGain


SISC_X90_API X90_GetRedGain(               float *pRedGain,
                                           float *pMinRedGain,
                                           float *pMaxRedGain);


The GetRedGain function retrieves the current red gain value and optionally the
allowed minimal and maximal red gain values.


Parameters
pRedGain                                    Points to a 32-bit floating number that
                                            receives the current red gain value.
pMinRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed minimal red gain
                                            value.
                                            This parameter can be NULL.
pMaxRedGain                                 Points to a 32-bit floating number that
                                            receives the allowed maximal red gain
                                            value.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
If the function is employed for another implementation of white balance, the histogram
function in the X90CU SDK should be used as the basis to determine color gain values.
The output bitmap, on the other hand, may not be proportional to the raw pixel values
due to possible intermediate processing.



                                                                                      115
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetRedGain


SISC_X90_API X90_SetRedGain(float *pRedGain);


The SetRedGain function directs the camera to amplify the red channel by the given
multiplicative factor.


Parameters
pRedGain                                   Pointer to a 32-bit floating number that
                                           will be set as the new red gain.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.


Remarks
Color gains are implemented as digital multiplications for X90CU cameras.




                                                                                  116
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetSaturation


SISC_X90_API X90_GetSaturation(            float *pSaturation,
                                           float *pMinSaturation,
                                           float *pMaxSaturation);


The GetSaturation function retrieves the saturation level currently applied to the
bitmaps before they are output.


Parameters
pSaturation                                  Points to a 32-bit floating number that
                                             receives the current saturation level.
pMinSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed minimal saturation
                                             level.
                                             This parameter can be NULL.
pMaxSaturation                               Pointes to a 32-bit floating number that
                                             receives the allowed maximal saturation
                                             level.
                                             This parameter can be NULL.


Return Values


SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
The function reports the default saturation value, i.e. no modification to the saturation
of output bitmaps, as the current saturation level, after the camera initializes
successfully and before the saturation level is changed by SetSaturation.



                                                                                       117
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetSaturation


SISC_X90_API X90_SetSaturation(float *pSaturation);


The SetSaturation function directs the saturation of the output bitmap be modified by
the given amount.


Parameters
pSaturation                                Pointer to a 32-bit floating number that
                                           will be set as the new saturation level.




Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                           Unknown error
SiscUnInitializedError                     Camera has not yet been initialized.
SiscInvalidParameterError                  Invalid parameters
SiscHardwareError                          The camera has responded with an error.
SiscIOError                                An error has occurred during an IO
                                           operation.
SiscOutOfRangeError                        A feature to set is out of range.




Remarks
The histogram reported by the SDK function will not be changed by a new saturation
setting.




                                                                                      118
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetKelvin


SISC_X90_API X90_GetKelvin(               float *pKelvin,
                                          float *pMinKelvin,
                                          float *pMaxKelvin);


The GetKelvin function retrieves the image temperature currently in use as a basis to
white balance.


Parameters


pKelvin            Points to a 32-bit floating number that receives the image
                   temperature currently in use as a basis to white balance.
pMinKelvin         Points to a 32-bit floating number that receives the allowed
                   minimal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.
pMaxKelvin         Points to a 32-bit floating number that receives the allowed
                   maximal image temperature to be used as a basis to white balance.
                   This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
Image temperature is measured in Kelvin. A value of 0 means image temperature is not
considered in white balance.




                                                                                   119
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




SetKelvin


SISC_X90_API X90_SetKelvin(float *pKelvin);


The SetKelvin function specified a new image temperature to be used as a basis to white
balance.


Parameters
pKelvin                                     Pointer to a 32-bit floating number to be
                                            set as the new image temperature.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
Image temperature is measured in Kelvin. If set to 0, the image temperature will not be
considered in the white balance.


See Appendix 1 for light source examples that show various temperatures.




                                                                                   120
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetGamma


SISC_X90_API X90_GetGamma( float *pGamma ,
                                 float *pMinGamma,
                                 float *pMaxGamma);


The GetGamma function retrieves the Gamma value of the camera.


Parameters
pGamma                                    Points to 32-bit floating number that
                                          receives the current Gamma value of the
                                          camera.
pMinGamma                                 Points to 32-bit floating number that
                                          receives the allowed minimal Gamma
                                          value of the camera.
                                          This parameter can be NULL.
pMaxGamma                                 Points to 32-bit floating number that
                                          receives the allowed maximal Gamma
                                          value of the camera.
                                          This parameter can be NULL.


Return Values
SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscHardwareError                         The camera has responded with an error.
SiscIOError                               An error has occurred during an IO
                                          operation.


Remarks
The default Gamma value is 1.




                                                                                  121
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




SetGamma


SISC_X90_API X90_SetGamma(float *pGamma);


The SetGamma function specifies the Gamma value of the camera.


Parameters
pGamma                                        Pointer to a 32-bit floating number that
                                              will be set as the new Gamma value of the
                                              camera.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remark
If set to 0, no Gamma will be applied to the camera, i.e. a Gamma value of 0 is the same
as a Gamma value of 1. Gamma settings affect the ways a digital image is displayed and
processed. If the captured image is for visual inspection only, it is probably best to set
the Gamma of the camera to the reciprocal of the display device. If the captured image
is the input to further processing, it is probably best to set the Gamma of the camera to
1. More sophisticated Gamma settings are possible, for example, setting Gamma to 0.4
for live image preview on CRT screen in the video imaging mode and resetting Gamma
to 1 just before switching to the still imaging mode to capture a high-resolution
long-exposure image to feed to some image restoration programs.




                                                                                      122
info@softinstrument.com
                    Scientific Instrument Software Corporation Limited




WhiteBalance


SISC_X90_API X90_WhiteBalance(RECT *pSubWindow);


The WhiteBalance function performs white balance based on the most recent frame in
the video stream.


Parameters
pSubWindow                                   If NULL, the white balance will be base on
                                             the current ROI. If a valid pointer, the
                                             white balance will be based on a
                                             sub-window of the current ROI, as
                                             specified by the RECT it points to.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks
The white balance refers to the process of adjusting relative strength of color channel
gains based on the raw data the camera delivers and the temperature setting. This
function keeps the green channel gain intact and modifies blue and red gains only. Note
that the sub-window refers to the image before it is possibly flipped. For X90CU
cameras the white balance is performed against the most recent frame in the video
imaging mode. The resulted color channel gains, however, are applied to images in both
the video and the still imaging mode.


For a digital image to match an optical image in terms of color reproduction, it is
necessary to consider, besides white balance and light source temperature settings, the
spectral responses of the IR cutoff filter and camera sensors. Please refer to Appendix 2
and 3 for further information.

                                                                                        123
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetVideoBitmap


SISC_X90_API X90_GetVideoBitmap(BITMAPINFOHEADER *pInfo,BYTE *pBits);


The GetVideoBitmap function retrieves the most recent image the camera delivers in
video imaging mode.


Parameters
pInfo                                       Points to a BITMAPINFOHEADER
                                            structure that receives the bitmap
                                            information.
pBits                                       Points to pixels stored in RGB24 format.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscInvalidPointerError                     Invalid pointer


Remarks
If the camera is in the video imaging mode, this function will hang the calling thread
until the most recent bitmap is available. If the camera is in still imaging mode, this
function will return immediately the last image captured in the video imaging mode.
It stores the bitmap in Windows DIB format as indicated by the parameters. Note that
it is a top-down DIB and its origin is the upper-left corner, i.e. pInfo->biHeight is
negative.




                                                                                   124
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




GetStillBitmap


SISC_X90_API X90_GetStillBitmap(BITMAPINFOHEADER *pInfo,BYTE *pBits);


The GetStillBitmap function switches the camera to the still imaging mode, captures an
image, and switches the camera back to the video imaging mode.


Parameters
pInfo                                          Points to a BITMAPINFOHEADER
                                               structure that receives the bitmap
                                               information.
pBits                                          Points to pixels stored in RGB24 format.
                                               This parameter can be NULL.


Return Values
SiscSuccess                                    The function has completed successfully.
SiscUnknownError                               Unknown error
SiscUnInitializedError                         Camera has not yet been initialized.
SiscInvalidParameterError                      Invalid parameters
SiscBufferTooSmall                             A buffer passed as parameter is too small.
SiscHardwareError                              The camera has responded with an error.
SiscIOError                                    An error has occurred during an IO
                                               operation.
SiscInvalidPointerError                        Invalid pointer


Remarks
Use this function to capture an image of the highest resolution and greatest exposure
range. In some cases such as 590CU camera, the still imaging mode offers higher
resolution than video imaging mode. In all cases, the still imaging mode offers greater
exposure range than the video imaging mode. The captured image is in Windows DIB
format as indicated by the parameters. Note that it is a top-down DIB and its origin is
the upper-left corner, i.e. pInfo->biHeight is negative.




                                                                                      125
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




LUT


SISC_X90_API X90_LUT(float x1,float y1,float x2,float y2);


The LUT function performs intensity windowing on the captured images.


Parameters


x1        The x coordinate of the first control point
y1        The y coordinate of the first control point
x2        The x coordinate of the second control point
y2        The y coordinate of the second control point


Return Values


SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.
SiscOutOfRangeError                           A feature to set is out of range.


Remarks
This function sets up a pixel value transform which maps each value in the dynamic
range of raw data to another value in the dynamic range of the final output image. For
this function both dynamic ranges are normalized to [0, 1]. The transform is specified by
two control points (x1, y1) and (x2, y2), which means the value x1 in the original
dynamic range will be mapped to y1 in the new dynamic range and the value x2 in the
original dynamic range will be mapped to y2 in the new dynamic range. The transform
is piecewise linear, assuming 0 is mapped to 0 and 1 is mapped to 1, as illustrated below.




                                                                                      126
info@softinstrument.com
                                Scientific Instrument Software Corporation Limited




                                1

                                y2
            New Dynamic Range




                                y1




                         (0, 0)                x1          x2                        1
                                               Original Dynamic Range




Setting both (x1, y1) and (x2, y2) to either (0, 0) or (1, 1) effectively cancels the intensity
windowing. It is required that x2-x1>0.01.




                                                                                           127
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Create


SISC_X90_API X90_FFC_Create(double *pParams);


The FFC_Create function calculates the coefficients needed for Flat-Field Correction
and optionally exports the coefficients.


Parameters
pParams                                       Points to a buffer that receives the FFC
                                              calibration coefficients.
                                              This parameter can be NULL.


Return Values
SiscSuccess                                   The function has completed successfully.
SiscUnknownError                              Unknown error
SiscUnInitializedError                        Camera has not yet been initialized.
SiscInvalidParameterError                     Invalid parameters
SiscBufferTooSmall                            A buffer passed as parameter is too small.
SiscCameraInUseError                          The camera is already being used by
                                              another application.
SiscHardwareError                             The camera has responded with an error.
SiscIOError                                   An error has occurred during an IO
                                              operation.


Remarks


Flat-Field Correction (FFC) refers to the real-time image calibration for sensor’s
spatially varying response to incident light, uneven illumination and non-uniform
transmission rate of the lens or other optical systems. The FFC_Create function
computes the coefficient matrix based on a new image captured with the full pixel array
of the sensor in the video imaging mode. It is not necessary for an application program
to explicitly switch the camera to that state as the FFC_Create function will do that and
will restore the previous frame format upon completion of the function. For optimal
result, it is recommended that before calling this function:




                                                                                     128
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




1. Shoot the camera at a slowly varying white background. The field of view should not
be obstructed by any object other than the white background.


2. Adjust the illumination, lens aperture or camera exposure time so that the image is
as bright as possible but not exceeding its dynamic range.


3. Perform white balance to remove the apparent color aberrations. The temperature
should be set to 0 before the white balance.




                                                                                  129
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Import


SISC_X90_API X90_FFC_Import(double *pParams);


The FFC_Import function loads the previously created calibration coefficients.


Parameters


pParams                                     Pointer to FFC calibration coefficients
                                            that will be loaded.


Return Values


SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                          A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.




Remarks
The coefficients to load must have been created by the FFC_Create function.




                                                                                      130
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




FFC_Memory


SISC_X90_API X90_FFC_Memory(int *pSizeInBytes);


The FFC_Memory reports the number of bytes needed to hold the calibration
coefficients.


Parameters


pSizeInBytes                                 Points to a 32-bit integer that receives the
                                             size of the memory, in bytes, to hold the
                                             FFC calibration coefficients.


Return Values
SiscSuccess                                  The function has completed successfully.
SiscUnknownError                             Unknown error
SiscUnInitializedError                       Camera has not yet been initialized.
SiscInvalidParameterError                    Invalid parameters
SiscHardwareError                            The camera has responded with an error.
SiscIOError                                  An error has occurred during an IO
                                             operation.


Remarks


This function reports the size of the memory that an application program needs to
allocate so that the FFC_Create function can export the coefficients.




                                                                                     131
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Get


SISC_X90_API X90_FFC_Get(BOOL *pStatus);


The FFC_Get function retrieves the status of FFC.


Parameters
pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means FFC is off. 1 means
                                            FFC is on.


Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
FFC is a computation intensive operation.




                                                                                    132
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




FFC_Set


SISC_X90_API X90_FFC_Set(BOOL *pStatus);


The FFC_Set function turns FFC on or off.


Parameters


pStatus                                     Points to a 32-bit integer that receives the
                                            FFC status. 0 means turning off FFC. 1
                                            means turning on FFC.




Return Values
SiscSuccess                                 The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscHardwareError                           The camera has responded with an error.
SiscIOError                                 An error has occurred during an IO
                                            operation.
SiscOutOfRangeError                         A feature to set is out of range.


Remarks
FFC is a computation intensive operation.




                                                                                    133
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




GetHistogram


SISC_X90_API X90_GetHistogram(            int *pHistogramData,
                                          int *pHistogramSize);


The GetHistogram function profiles the intensity distribution of the most recent image
captured in the video imaging mode.


Parameters
pHistogramData                              Points to the first of an array of integers
                                            that receive histogram data.
                                            This parameter can be NULL.
pHistogramSize                             Points to an integer that receives the size
                                            of the memory, in bytes, to hold the
                                            histogram data.
                                            This parameter can be NULL.


Return Values
SiscSuccess                                The function has completed successfully.
SiscUnknownError                            Unknown error
SiscUnInitializedError                      Camera has not yet been initialized.
SiscInvalidParameterError                   Invalid parameters
SiscBufferTooSmall                         A buffer passed as parameter is too small.
SiscHardwareError                           The camera has responded with an error.
SiscInvalidPointerError                     Invalid pointer
SiscIOError                                 An error has occurred during an IO
                                            operation.


Remarks
The X90 SDK uses a 32-bit signed integer array to hold histogram. The array is divided
into three consecutive segments, to hold pixel count for blue, green and red channel
respectively. The first integer in each segment is the number of pixels with their
corresponding color value being 0. The last integer in each segment is the number of
pixels with their corresponding color being the maximum of the dynamic range.




                                                                                     134
info@softinstrument.com
                 Scientific Instrument Software Corporation Limited




Return Code List

SiscSuccess                               The function has completed successfully.
SiscUnknownError                          Unknown error
SiscUnInitializedError                    Camera has not yet been initialized.
SiscInvalidParameterError                 Invalid parameters
SiscBufferTooSmall                        A buffer passed as parameter is too small.
SiscCameraInUseError                      The camera is already being used by
                                          another application.
SiscNoCameraAvailableError                There is no camera available.
SiscHardwareError                         The camera has responded with an error.
SiscCameraUnknownError                    The SDK does not recognize the camera.
SiscOutOfMemoryError                      The SDK can not allocate the required
                                          memory.
SiscOSVersionError                        The SDK cannot run on the current
                                          operating system.
SiscIOError                               An error has occurred during an IO
                                          operation.
SiscOutOfRangeError                       A feature to set is out of range.
SiscInvalidPointerError                   Invalid pointer




                                                                                  135
info@softinstrument.com
                  Scientific Instrument Software Corporation Limited




Appendix 1 Common Color Temperatures


Light Source                                  Color Temperature (Kelvin)
Clear Blue Sky                                8000 to 27000
Rainy, Misty Daylight                         7200 to 8500
Overcast Daylight                             6500 to 7200
Direct Sun Clear Blue Sky                     5700 to 6500
Summer Sunlight (9am to 3pm)                  5400 to 5700
Summer Sunlight (Before 9am or After 3pm) 4900 to 5600
Electronic Flash (Typical)                    6200 to 6800
Xenon Arc (Unfiltered)                        6000
White Flame Carbon Arc                        5000
Yellow Flame Carbon Arc                       3200
“True Daylight” Color Match Tubes             6500
“Daylight” Cool White Tubes                   4300
“Warm White” Tubes                            3000
Photoflood & 3400K Tungsten-Halogen           3400
Tungsten-Halogen and Photo Lamps              3200
Projection Lamps (500 to 1000 Watts)          2900 to 3000
General Purpose Lamps (200 to 500 Watts)      2900
Household Lamps (100 to 150 Watts)            2850
Household Lamps (60 Watts)                    2800
Household Lamps (40 Watts)                    2750
Standard Candle                               2000
Candle Flame                                  1500




                                                                           136
info@softinstrument.com
                                  Scientific Instrument Software Corporation Limited




Appendix 2 Spectral Response of IR Cutoff Filter


                      100.00


                       90.00


                       80.00


                       70.00
  Transmittance [%]




                       60.00


                       50.00


                       40.00


                       30.00


                       20.00


                       10.00


                        0.00
                            200   300    400     500     600     700     800     900   1000   1100

                                                       Wavelength [nm]


Roughly speaking, the pass band is [400nm, 625nm]. Consider replacing this filter by a
more appropriate one in applications where the band [625nm, 700nm] is needed.




                                                                                               137
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




Appendix 3 Spectral Response of Sensors




                    Spectral Response of 190CU Camera Sensor




                    Spectral Response of 390CU Camera Sensor




                                                                     138
info@softinstrument.com
                Scientific Instrument Software Corporation Limited




                    Spectral Response of 590CU Camera Sensor




                                                                     139
info@softinstrument.com

								
To top