Scorpion Camera Driver Interface Specification¶
Scorpion Camera Interface is used to write SCD - Scorpion 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.
Port-based configuration¶
From Scorpion Vision Software XI it is recommended to store configuration with grabberNo and portNo as identifier, in ini files this is [Port.<grabberno>.<portno>].
Note
grabberNo and portNo are 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 Port-based 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 2010 cameradriver SampleGrab project may be downloaded to adapt your own cameras into Scorpions wide range of supported cameras.
Camera properties¶
The camera properties should be accessed by either the get/setProperty functions or by execCmd function with set/get commands. The set/getProperty functions works with int64 data types only. The properties depends of camera model and accessing users responsibility to set due to camera model. Property names should not be case sensitive.
| Property | Description |
|---|---|
| pixelsize | Image depth, 8 for greyscale images, 24 or 32 for color images. 15/16 bit images are not supported. Scorpion defaults to 8 if not supported. |
| continous | Generic SCD property for setting camera videostream continous/single shot. When true, the camera should start grabbing images in free running mode at current framerate, and notify host application for each frame received without need of grab command. The host application is resposible to collect the image before a new image is received. The driver may implement a image buffer of any size as needed. If the drivber implements an image buffer, the driver should also implement a reset/flush command to clear any pending images. |
| <property> | camera model specific property. |
Commands¶
Command may be sent to camera by execCmd function. This is a text base command protocol for accessing camera and driver properties and commands.
Recommended command set to be implented.
| Command | Parameters | Description |
|---|---|---|
| flush | flush any buffered images. | |
| reset | reset camera and reload configuration, analogue with close-open | |
| get | property | return property value as string |
| set | property=value | set property value. The driver should decode the value to proper datatype due to property. |
Standard DLL interface¶
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 - recommended
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 - obsolete - 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 - obsolete - initialize recommended instead
GRABDLL_API int getCVLMaxNoOfGrabbers(void)
Get number of addressable grabber cards - defaults to 1 if omitted.
Optional - obsolete
GRABDLL_API int getCVLMaxNoOfPorts(unsigned int grabberNo)
Get max number of possible concurrent cameras available - defaults to 1 if omitted.
Optional - obsolete
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 mode4
is not controlled by this function as Scorpion uses the presence 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