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
|