Up | 2D Area Scan | 2D LineScan | 3D camera | Scorpion Camera Interface | Other | Legacy

 

  

 
Scorpion Camera Interface

Scorpion Camera Interface (SCI) is used to write custom camera drivers. Following is a list of API calls a camera driver must implement in order to communicate with Scorpion.

Camera configuration persistance.

Each camera should maintain the configuration in text files, preferable text files as INI files or XML. These configuration files should be located at the directory given in either initialize or setSystemPath function. The configuration should be read in the openCVLPort on successfull camera open, and written in successfully configureCamera function.

In previous versions of Scorpion Camera Interface implementations, the configuration was stored with the camera name as configuration identifier. In later implementations it is recommended to store configuration with grabberno and portno as identifier, in ini files this is typically [Port.<grabberno>.<portno>], where grabberno and portno is zero indexed as in all function calls. It is also recommended to add an entry identifying the camera name in the configuration. This entry should have the identifier $Camera=<cameraname>.

As configuration identifier has changed to port based, the $Camera may be used to verify that the configuration may be used in case of camera model changes.

Special care must be taken when configuring camera before it is opened. In these cases the grabberno and portno will be unknown and configuration should not be saved or saved with camera name as identifier.

Example of typically ini file:

[Port.0.0]
$Camera=Basler acA1300-60gc (21536429)
PixelFormat=BayerRG8
ProcessedRawEnable=0
ReverseX=0
TestImageSelector=Off
Width=1280
Height=1024

The VC++ Visual Studio 2005 cameradriver SampleGrab project may be downloaded to adapt your own cameras into  Scorpions wide range of supported cameras.

Standard declarations:
typedef struct _WH {
int w;
int h;
} WH;

typedef void CallbackFunc(unsigned int grabberNo, unsigned int portNo);
typedef void CmdCallbackFunc(unsigned int grabberNo, const char* cmd, const char* params);
typedef void DebugMsgFunc(const char* msg);

#define GRABDLL_API extern "C" __declspec(dllexport)

#define RET_OK 1
#define RET_ERR 0

GRABDLL_API int initialize(char* aSystemPath, DebugMsgFunc* aDebugMsgFunc)

Camera driver initialization - called by Scorpion after DLL loads. Reference counting is strongly recommended in case of running multiple Scorpion instances where each Scorpion instance will call initialize/finalize at load/unload of the camera driver.

The drivers default SystemPath should be working directory at loading
 

Optional - recommanded

 

GRABDLL_API int finalize()

Camera driver finalization - called by Scorpion before DLL unload.

 

Optional - required if driver needs to release resources

 

GRABDLL_API void setDebugMsgProc(DebugMsgFunc* aDebugMsgFunc)

Message routing from camera driver to Scorpion console window.

 

Optional - initialize recommended instead

 

GRABDLL_API int setSystemPath(char *aSystemPath)

Set system path for configuraton files. The camera dll is responsible for camera property persistance and must store camera configuration at supplied systempath to handle multiple configurations in different directories.

Scorpion will always set the systempath to the profile directory. The driver may use any file format/subdirectories to store the individual camera configurations. The configuration files are to be used when opening a camera.

The drivers default SystemPath should be working directory at loading

 

Optional - initialize recommended instead

 

GRABDLL_API int configureCamera(HWND hParentWnd, char *cameraName)

Configures camera by name.

 

Optional - not required, but needed for configuration from Scorpion GUI.

 

GRABDLL_API int getCVLMaxNoOfGrabbers(void)

Get number of addressable grabber cards - defaults to 1 if omitted.


Optional

 

GRABDLL_API int getCVLMaxNoOfPorts(unsigned int grabberNo)

Get max number of possible concurrent cameras available - defaults to 1 if omitted.

 

Optional

 

GRABDLL_API int getCVLNoOfSupportedCameras(void)

Get number of available cameras. This method is used when iterating for available cameras in conjunction with the "getCVLCameraConfigNames" method.

Note! Return value must always return number of camera names returned by "getCVLCameraConfigNames".

Required

 

GRABDLL_API char **getCVLCameraConfigNames()

Get names of available cameras - Required

 

Should return pointers to 'static' strings. Scorpion will scan the returned **char until a NULL pointer when browsing available cameras.

 

Note! The last valid item must be followed by a NULL pointer (lpszCameraNames[nCameras]=NULL).

 

GRABDLL_API int openCVLPort(unsigned int grabberNo, unsigned int portNo, char* cameraName, WH &imageSize)

Open a camera  - Required

 

The driver must return the image size on success, otherwise (0,0).

The image size is "static" as long as the camera is open and may not be changed at runtime. Changes of image size will not be 'detected' until next time Scorpion opens the camera. Scorpion uses the grabberNo/portNo as crossindex/handle for accessing the camera.

 

GRABDLL_API void closeCVLPort(unsigned int grabberNo, unsigned int portNo)

Close a camera - Required

 

GRABDLL_API int doCVLGrab(unsigned int grabberNo, unsigned int portNo)

Grab an image from camera mapped to grabberNo/portNo. - Required

 

GRABDLL_API int getCVLGrabRow (unsigned int grabberNo, unsigned int portNo, unsigned char* rowPtr, unsigned int row, unsigned int firstPix, unsigned int lastPix)

Get the image from camera mapped to grabberNo/portNo  - Required

  • rowPtr - [IN] destination buffer where to copy image data - allocated/owned by Scorpion
  • row - [IN] range 0..height-1 image layout TOP-DOWN
  • firstPix - [IN] index of first pixel in row (normally 0)
  • lastPix - [IN] index of last pixel in row (normally width-1)

Note! since the image size is "static" at runtime, Scorpion requires image size returned in the open method. The pixelSize may be changed at runtime if the camera driver supports "set/getProperty" methods and returns current "PixelSize", see the "getProperty" method. Scorpion always checks "PixelSize" property if available before acquiring an image.

 

GRABDLL_API int setHWTrigger(unsigned int grabberNo, unsigned int portNo, unsigned int HWTrigger)

Set HW trigger mode - Optional

  • unsigned int HWTigger - boolean value of either 0 or 1
  • do NOT export/implement this function in the dll if HW trigger mode is not controlled by this function as Scorpion uses the presense of this function to enable GUI configuration elements

 

GRABDLL_API int setCompleteCallback(unsigned int grabberNo, unsigned int portNo, CallbackFunc* func)

Set a callback for image complete notifications - Required

The callback is normally called from the camera thread and only gives a notification to Scorpion when a new image is completed.

 

GRABDLL_API int getPropertyRange(unsigned int grabberNo, unsigned int portNo, char *prop, long *min, long *max)

Get range for a camera property - Optional

  • prop - [IN] name of property
  • min - [OUT] min value of property
  • max - [OUT] max value of property

 

GRABDLL_API int getProperty(unsigned int grabberNo, unsigned int portNo, char *prop, long *value)

Get current value for a camera property  - Optional

  • prop - [IN] name of property
  • value - [OUT] value of property

Note! "PixelSize" property must be always provided, since the open method does not report PixelSize. Pixelsize must be either 8 or 24.

 

GRABDLL_API int setProperty(unsigned int grabberNo, unsigned int portNo, char *prop, long value)

Set current value for a named camera property - Optional

  • prop - [IN] name of property
  • value - [IN] value of property

 

GRABDLL_API int setCmdCallback(unsigned int grabberNo, unsigned int portNo, CmdCallbackFunc *func)

Set callback functions for commands  - Optional - supported by Scorpion 8.0.0.441 and later

The callback is threadsafe and the command execution will be handled by Scorpion in the normal Windows message  queue.

  • cmd - [OUT] command - driver specific
  • params - [OUT] parameters - driver specific

 

GRABDLL_API int execCmd(unsigned int grabberNo, unsigned int portNo, const char * cmd, const char  *params, char *resp, int size)

Execute driver specific command - Optional - supported by Scorpion 8.0.0.441 and later

The function should return the response as string

  • cmd - [IN] command - driver specific
  • params - [IN] parameters - driver specific
  • resp - [OUT] the result buffer (make sure memory allocated for resp is at least size)
  • size - [IN] size of result buffer
 

Scorpion Vision Version XII : Build 646 - Date: 20170225
Scorpion Vision Software® is a registered trademark of Tordivel AS.
Copyright © 2000 - 2017 Tordivel AS.