ALVideoDevice, formerly called Video Input Module (V.I.M.), is architectured in order to provide every module related to vision, called Generic Video Module (G.V.M.), a direct access to raw images from video source, or an access to images transformed in the requested format.
Extension name of the methods providing images depends on wether modules are local (dynamic library) or remote (executable).
string version ()
Returns the version of the module.
A string containing the version of the module.
AL::ALValue getMethodHelp (const string& methodName)
Retrieves a method's description.
The name of the method.
A structure containing the method's description.
AL::ALValue getModuleHelp ()
Retrieves the module's description.
A structure describing the module.
string getUsage (const string& name)
Gets the method usage string. This summarise how to use the method.
The name of the method.
A string that summarises the usage of the method.
int startFrameGrabber ()
Advanced method that opens and initialize video source device if it was not before.
Note that the first module subscribing to ALVideoDevice will launch it automatically.
true if success
Example in C++ :
#Create a proxy on the video input module (V.I.M.) ALPtr<ALProxy> fCamera = getParentBroker()->getProxy( "ALVideoDevice" ); #Start the frame grabber in the default mode. fCamera->startFrameGrabber();
int stopFrameGrabber ()
Advanced method that close video source device.
true if success
Example in C++ :
fCamera->stopFrameGrabber();
string subscribe (const string& gvmName, const int& resolution, const int& colorSpace, const int& fps)
Register to ALVideoDevice (formerly Video Input Module/V.I.M.). When a General Video Module(G.V.M.) registers to ALVideoDevice, a buffer of the requested image format is added to the buffers list.
Returns the name under which the G.V.M. is registered to ALVideoDevice (useful when two G.V.M. try to register using the same name
Name of the registering G.V.M.
Resolution requested. { 0 = kQQVGA, 1 = kQVGA, 2 = kVGA }
Colorspace requested. { 0 = kYuv, 9 = kYUV422, 10 = kYUV, 11 = kRGB, 12 = kHSY, 13 = kBGR }
Fps (frames per second) requested. { 5, 10, 15, 30 }
Name under which the G.V.M. is known from ALVideoDevice, 0 if failed.
Example in C++ :
#Register a G.V.M. to ALVideoDevice, starting the frame grabber if it was not started before. std::string pId, pGVMName = "my_GVM"; pId = fCamera->call<std::string>( "subscribe", pGVMName , pResolution, pColorSpace, pFps );
void unsubscribe (const string& id)
Used to unregister a G.V.M. from ALVideoDevice.
Name under which the G.V.M. is known from ALVideoDevice.
Example in C++ :
fCamera->callVoid( "unsubscribe", pId );
void * getImageLocal (const string& id)
Applies transformations to the last image from video source and returns a pointer to a locked ALImage.
When image is not necessary anymore, a call to releaseImage() is requested.
If the G.V.M. didn't release preceding image, returns NULL.
Name under which the G.V.M. is known from ALVideoDevice (formerly called V.I.M.)
Pointer of the locked image buffer, NULL if error.Warning, image pointer is valid only for C++ dynamic library.
Example in C++ :
ALImage *pointer; pointer = (ALImage*)fCamera->getImageLocal(pId);
int releaseImage (const string& id)
Release image buffer locked by getImageLocal().
If G.V.M. had no locked image buffer, does nothing.
Name under which the G.V.M. is known from ALVideoDevice.
true if success
Example in C++ :
#Release image (does nothing if image was already released). fCamera->releaseImage(pId);
AL::ALValue getImageRemote (const string& id)
Applies transformations to the last image from video source and fills pFrameOut.
Name under which the G.V.M. is known from ALVideoDevice.
Array containing image informations :
[0] : width;
[1] : height;
[2] : number of layers;
[3] : ColorSpace;
[4] : time stamp (highest 32 bits);
[5] : time stamp (lowest 32 bits);
[6] : array of size height * width * nblayers containing image data;
[7] : camera ID;
Example in C++ :
ALValue results; results.arrayReserve(8); results = fCamera->call<ALValue>( "getImageRemote", pId ); const unsigned char* imageData = static_cast<const unsigned char*>(results[6].GetBinary());
void * getDirectRawImageLocal (const string& id)
Returns a pointer to a locked ALImage, with data array pointing directly to raw data. No format conversion and no copy of the raw buffer.
When image is not necessary anymore, a call to releaseDirectRawImage() is requested.
Warning: 1. when using this mode for several G.V.M., if they need raw data for more than 25ms check that you have strictly less G.V.M. modules in this mode than the amount of kernel buffers!! 2. Release all kernel buffers before any action requesting a modification in camera running mode (e.g. resolution, switch between cameras).
Name under which the G.V.M. is known from ALVideoDevice.
Pointer to the locked image buffer, NULL if error. Warning, image pointer is valid only for C++ dynamic library.
Example in C++ :
ALImage *pointer; pointer = fCamera->getDirectRawImageLocal(pId);
int releaseDirectRawImage (const string& id)
Release image buffer locked by getDirectRawImageLocal().
If G.V.M. had no locked image buffer, does nothing.
Name under which the G.V.M. is known from the V.I.M.
true if success
Example in C++ :
#Release raw image (does nothing if image was already released). fCamera->releaseDirectRawImage(pId);
AL::ALValue getDirectRawImageRemote (const string& id)
Fills pFrameOut with data coming directly from raw buffer (no format conversion).
No need to call releaseDirectRawImage() because it is done automatically at the end of data transmission.
Name under which the G.V.M. is known from ALVideoDevice.
Array containing image informations :
[0] : width;
[1] : height;
[2] : number of layers;
[3] : ColorSpace;
[4] : time stamp (highest 32 bits);
[5] : time stamp (lowest 32 bits);
[6] : array of size height * width * nblayers containing image data;
[7] : camera ID;
Example in C++ :
ALValue results; results.arrayReserve(8); results = fCamera->call<ALValue>( "getDirectRawImageRemote", pId ); const unsigned char* imageData = static_cast<const unsigned char*>(results[6].GetBinary());
bool setResolution (const string& id, const int& size)
Set the size of the output image.
Name under which the G.V.M. is known from ALVideoDevice.
{ 0 = kQQVGA, 1 = kQVGA, 2 = kVGA }
true if success
Example in C++ :
fCamera->setResolution(pId, kQVGA);
bool setFrameRate (const string& id, const int& frameRate)
Set the required frame rate.
Name under which the G.V.M. is known from ALVideoDevice.
images per seconds { 5, 10, 15, 30 }
true if success
Example in C++ :
fCamera->setFrameRate(pId, 30);
bool setColorSpace (const string& id, const int& colorSpace)
Set the colorspace of the output image.
Name under which the G.V.M. is known from ALVideoDevice.
{ 0 = kYuv, 9 = kYUV422, 10 = kYUV, 11 = kRGB, 12 = kHSY, 13 = kBGR }
true if success
Example in C++ :
fCamera->setColorSpace(pId, kYUVColorSpace);
int getVIMResolution ()
Get the resolution of the video source image.
{ 0 = kQQVGA, 1 = kQVGA, 2 = kVGA } -1: can't access video source
Example in C++ :
int videoSourceResolution = fCamera->getVIMResolution();
int getVIMColorSpace ()
Get the color space of the video source image.
{ 0 = kYuv, 9 = kYUV422, 10 = kYUV, 11 = kRGB, 12 = kHSY, 13 = kBGR } -1 can't access video source
Example in C++ :
int videoSourceColorSpace = fCamera->getVIMColorSpace();
int getVIMFrameRate ()
Get the frame rate of the video source image.
{ 5, 10, 15, 30 } -1: can't access video source
Example in C++ :
int videoSourceFps = fCamera->getVIMFrameRate();
int getGVMResolution (const string& id)
Get the resolution of the requested G.V.M.
Name under which the G.V.M. is known from ALVideoDevice.
{ 0 = kQQVGA, 1 = kQVGA, 2 = kVGA } -1: can't access video source
Example in C++ :
int moduleResolution = fCamera->getGVMResolution(pId);
int getGVMColorSpace (const string& id)
Get the color space of the requested G.V.M.
Name under which the G.V.M. is known from ALVideoDevice.
{ 0 = kYuv, 9 = kYUV422, 10 = kYUV, 11 = kRGB, 12 = kHSY, 13 = kBGR } -1: can't access video source
Example in C++ :
int moduleColorSpace = fCamera->getGVMColorSpace(pId);
int getGVMFrameRate (const string& id)
Get the frame rate of the requested G.V.M.
Name under which the G.V.M. is known from ALVideoDevice.
{ 5, 10, 15, 30 } -1: can't access video source
Example in C++ :
int moduleFps = fCamera->getGVMFrameRate(pId);
void setParam (const int& param, const int& newValue)
Sets the value of a specific parameter for the video source.
Parameter's reference among:
kCameraBrightnessID,
kCameraContrastID,
kCameraSaturationID,
kCameraHueID,
kCameraRedChromaID,
kCameraBlueChromaID,
kCameraGainID,
kCameraHFlipID,
kCameraVFlipID,
kCameraLensXID (not managed by camera),
kCameraLensYID (not managed by camera),
kCameraAutoExpositionID,
kCameraAecAlgorithmID [0:average-based; 1:histogram-based],
kCameraExposureCorrectionID [-6; 6] (correction by n/3 EV, switch automatically in average-based AEC algorithm if n!=0 and back to histogram-based for n=0),
kCameraExposureID,
kCameraAutoWhiteBalanceID,
kCameraAutoGainID,
kCameraSelectID [0:top camera; 1:bottom camera],
kCameraResolutionID,
kCameraFrameRateID (not managed currently),
kCameraBufferSizeID,
kCameraSharpnessID (0-1: no sharpness - 2: medium sharpness - 3-5: high sharpness),
kCameraFastSwitchID : advanced method that needs both camera to run same format. Parameter value has no meaning.
Remarks: Disabled camera (freezed actually) will get back to auto gain/exposure/white balance settings after a while. This is a camera issue.
Fast switch usually switchs between cameras in 66ms (33ms for waked up sensor exposure + 33ms for data transfer) after previous image completion. However, sometimes we can observe a clipped image from the former camera after 66ms. This is an electronical issue and so we suggest to considere only images after 100ms
Parameter's new value.
Example in C++ :
fCamera->setParam(pParam, pNewValue);
void setParamDefault (const int& param)
Sets a specific parameter for the video source at its default value.
Parameter's reference.
Example in C++ :
fCamera->setParamDefault(pParam);
vector<float> getAngPosFromImgPos (const vector<float>& imgPos)
Returns angles relative to camera axis given a normalized position in the image.
normalized position in the image [0.0 - 1.0]
corresponding angles values in radians.
Example in C++ :
std::vector<float> posUV; posUV.push_back(x / imageWidth);. posUV.push_back(y / imageHeight); std::vector<float> camAngles = fCamera->getAngPosFromImgPos(posUV);
vector<float> getImgPosFromAngPos (const vector<float>& angPos)
Returns normalized image position from camera angles in radians.
camera angle values in radians.
corresponding normalized position in the image [0.0 - 1.0]
Example in C++ :
std::vector<float> camAngles; camAngles.push_back(0.1f); camAngles.push_back(0.1f); std::vector<float> imgPos = fCamera->getImgPosFromAngPos(camAngles);
vector<float> getAngSizeFromImgSize (const vector<float>& imgSize)
Returns angles relative to camera axis given a normalized position in the image.
normalized position in the image [0.0 - 1.0]
corresponding angles values in radians.
Example in C++ :
std::vector<float> posUV; posUV.push_back(sizeX / imageWidth); posUV.push_back(sizeY / imageHeight); std::vector<float> angSize = fCamera->getAngSizeFromImgSize(posUV);
vector<float> getImgSizeFromAngSize (const vector<float>& angSize)
Returns normalized image position from camera angles in radians.
camera angle values in radians.
corresponding normalized position in the image [0.0 - 1.0]
Example in C++ :
std::vector<float> camAngles; camAngles.push_back(0.1f); camAngles.push_back(0.1f); std::vector<float> imgPos = fCamera->getImgPosFromAngles(camAngles);
vector<float> getImgInfoFromAngInfo (const vector<float>& angles)
Returns normalized image info from angles info in radians (as returned by vision extractors).
camera angle values in radians.
corresponding normalized position info.
vector<float> getImgInfoFromAngInfoWithRes (const vector<float>& angInfo, const int& arg2)
Returns image info from angles info in radians (as returned by vision extractors). Express image info in the requested resolution.
camera angle values in radians.
arg
corresponding position info.
AL::ALValue resolutionToSizes (const int& resolution)
return the width and the height of a resolution
{ 0 = kQQVGA, 1 = kQVGA, 2 = kVGA }
array of sizes: (return [-1;-1] if the format is invalid)
[0] : width;
[1] : height;
Example in C++ :
ALValue size = fCamera->resolutionToSizes(kVGA);
int sizesToResolution (const int& width, const int& height)
return the resolution from sizes
width of the image
height of the image
{ 0 = kQQVGA, 1 = kQVGA, 2 = kVGA } or -1 if the inputs are invalid
Example in C++ :
int resolution = fCamera->sizesToResolution(640, 480);
bool recordVideo (const string& id, const string& path, const int& totalNumber, const int& period)
BETA - background record of an .arv raw format video from the images processed by a G.V.M.
Name under which the G.V.M. is known from the V.I.M.
path/name of the video to be recorded
number of images to be recorded. 0xFFFFFFFF for "unlimited"
one image recorded every pPeriod images
true if success
bool stopVideo (const string& id)
BETA - stop writing the video sequence
Name under which the G.V.M. is known from ALVideoDevice.
true if success
void onClientDisconnected (const string& eventName, const AL::ALValue& eventContents, const string& message)
Callback when client is disconnected
The echoed event name
The name of the client that has disconnected
The message give when subscribing.
int getParam (const int& pParam)
Get the value of a video source specific parameter.
Parameter's reference among kCameraBrightnessID,
kCameraContrastID,
kCameraSaturationID,
kCameraHueID,
kCameraRedChromaID,
kCameraBlueChromaID,
kCameraGainID,
kCameraHFlipID,
kCameraVFlipID,
kCameraLensXID,
kCameraLensYID,
kCameraAutoExpositionID,
kCameraAecAlgorithmID [0:average-based; 1:histogram-based],
kCameraExposureCorrectionID [-6; 6] (correction by n/3 IL, switch automatically in average-based AEC algorithm if n!=0 and back to histogram-based for n=0),
kCameraExposureID,
kCameraAutoWhiteBalanceID,
kCameraAutoGainID,
kCameraSelectID [0:top camera; 1:bottom camera],
kCameraResolutionID,
kCameraFrameRateID,
kCameraBufferSizeID,
kCameraFastSwitchID (need both camera to run same format/ parameter value has no signification),
kCameraSharpnessID (0-1: no sharpness - 2: medium sharpness - 3-5: high sharpness)
Parameter's value.
Example in C++ :
int pVal = fCamera->getParam(pParam); #More explanations in the documentation...
int getActiveCamera ()
Get the active camera
0: top camera - 1: bottom camera
Example in C++ :
int activeCam = fCamera->getActiveCamera();
Example in C++ :
#Create a proxy on the video input module (V.I.M.) ALPtr<ALProxy> fCamera = getParentBroker()->getProxy( "ALVideoDevice" ); #Register a Generic Video Module (G.V.M.) to the V.I.M. std::string pGVMNameId = "my_GVM"; pGVMNameId = fCamera->call<std::string>( "subscribe", pGVMNameId , pResolution, pColorSpace, pFps ); #Get a pointer to the video source image and release the image when process is finished ALImage *pointer = (ALImage*)AL::ALVideoDeviceProxy(getParentBroker()).getImageLocal(pGVMNameId); ...process... fCamera->call<int>( "releaseImage", pGVMNameId); #Unregister the G.V.M. fCamera->callVoid( "unsubscribe", pGVMNameId );
Example in Python :
#Create a proxy on the video input module (V.I.M.)
camProxy = ALProxy("ALVideoDevice", "10.8.252.149", 9559)
#Register a Generic Video Module (G.V.M.) to the V.I.M.
nameId = camProxy.subscribe("python_GVM", resolution, colorSpace, fps)
#Get a pointer to the video source image and release the image when process is finished
camProxy.getImageLocal(nameId)
...process...
camProxy.releaseImage(nameId)
#Unregister the G.V.M.
camProxy.unsubscribe(nameId)