Home

FGI and plFGI Report 2002 - Center for Machine Perception

1. tmpU32 BAYER 3BY3 COLOR buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen check whether this is a known value if strcemp tmpstring BAYER 2BY2 COLOR tmpU32 BAYER 2BY2 COLOR else if strcomp tmpstring BAYER 3BY3 COLOR tmpU32 BAYER 3BY3 COLOR else if stremp tmpstring BAYER 3BY3GGRAD COLOR tmpU32 BAYER 3BY3GGRAD COLOR else if stremp tmpstring BAYER 2PASSGRAD COLOR tmpU32 BAYER 2PASSGRAD COLOR else if stremp tmpstring BAYER 2PASSADAPT COLOR tmpU32 BAYER_2PASSADAPT_COLOR else if stremp tmpstring BAYER_VARGRAD_COLOR tmpU32 BAYER_VARGRAD_COLOR lu oct i ct ict ct DI DI DI DH FI ct 101 FGI and plFGI Report 2002 September 2002 else if stremp tmpstring BAYER 2BY2 MONO tmpU32 BAYER 2BY2 MONO else if strcemp tmpstring BAYER 3BY3 MONO tmpU32 BAYER 3BY3 MONO else if strcemp tmpstring BAYER ADAPT MONO tmpU32 BAYER ADAPT MONO else if strcomp tmpstring BAYER NO CONVERSION tmpU32 BAYER NO CONVERSION eise mexPrintf plSetValue Error setting PreviewColorConversion unknown value n plPrintPossibleValues PreviewColorConversion mexErrMsgTxt Mn set the value nRetValue PimMegaSetImagerClocking deviceld tmpU32 if plE
2. grab an image n destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 ZC mexPrintf V sync search position precedes V sync insert position n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT_IMG_DEV_ID DevicelId FrameId M Bakker 2002 07 03 mexPrintf Frame height granularity is illegal Wn mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Frame top granularity is illegal n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf White level cannot be set n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEM ID DeviceId FrameId M Bakker 2002 07 03 aad mexPrintf Unsupported or unknown message passed to the device driver n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Mode conflict n m mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 40 FGI and plFGI Report 2002 case OLC GIG NULL default September 2002 mexP
3. parameterValue plDevices getpar serialnumber parametername returns the value of the specified parameter Input prhs 0 string getpar prhs 1 2 U32 serialnumber prhs 2 string parametername plhs 0 value of the specified parameter Example parameterValue plDevices getpar 75122 GrabOutputType This task reads the value of the given device parameter from the open device array First the third argument which should be a string with the name of the requested parameter is loaded into the parName variable Then the return value which should be a double is initialised It is determined which parameter should be returned by using strcmp in an if then else if else construction The procedure is the same for every parameter A temporary boolean variable t is used to indicate whether a matching serial number was not found It is set to 1 then a fori 0 to deviceCount 1 loop is entered As soon as a matching serial number is found the requested parameter is stored as return value t is set to 0 and the for loop is terminated using a break statement Finally if t still has value 1 an error message is printed stating that the requested serial number could not be found e darguments setpar Syntax plDevices setpar serialnumber parametername parametervalue sets the value of the specified parameter Input prhs 0 string setpar prhs 1 U32 serialnumber prhs 2
4. tmpBOOL TRUE else mexPrintf plSetValue Error setting ExposureTime unknown value n mexPrintf Second value should be TRUE or FALSE n mexErrMsgTxt Mn set the value nRetValue PimMegaSetExposureTime deviceld tmpfloat tmpBOOL if plError nRetValue setting ExposureTime mexErrMsgTxt Mn Gamma else if stromp parametername Gamma tmpfloat float mxGetScalar values 0 nRetValue PimMegaSetGamma deviceld tmpfloat if plError nRetValue setting Gamma mexErrMsgTxt Mn GPO else if strcmp parametername Gpo tmpU32 0 get Value buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen if strcmp tmpstring On tmpU32 1 else if stremp tmpstring Off tmpU32 0 else mexPrintf plSetValue Error setting Gpo unknown value n mexPrintf First value should be On or Off n mexErrMsgTxt Mn get PulseLength tmpfloat 0 if nvalues gt 2 tmpfloat float mxGetScalar values 1 99 FGI and plFGI Report 2002 September 2002 set the value nRetValue PimMegaSetGpo deviceld tmpU32 tmpfloat if plError nRetValue setting Gpo mexErrMsgTxt Mn Green Gain else if strcemp parametername Gr
5. 26 plFGI Technical Guide September 2002 Bibliography Vitana 2002 1 VITANA CORPORATION 2000 2002 PixeLINK Megapixel FireWire Camera Developer s Manual Release 3 0 online version Vitana Corporation Ottawa Ontario Canada Vitana 2002 2 VITANA CORPORATION 2000 2002 PixeLINK Megapixel FireWire Camera User s Manual Release 3 0 online version Vitana Corporation Ottawa Ontario Canada 21 plFGI Technical Guide September 2002 Appendix A Parameters in the device s handle structure GPS Gi HardwareVersion ProductID HardwareVersion SerialNumber Hardware Version Firmware Version Hardware Version FpgaVersion Preview WindowPos Top Preview WindowPos Left Preview WindowSize Height Preview WindowSize Width SubWindow Decimation Sub Window StartRow SubWindow StartColumn SubWindow NumberRows SubWindow NumberColumns SubWindowPos StartRow SubWindowSize Decimation SubWindowSize Height SubWindowSize Width Table 1 A list of all parameters that are present in the handle structure of the device 28 plFGI Technical Guide September 2002 Appendix B Parameters for use with get and set n ay larity mem woes L3 RE es Ee DataTransferSize STRING DATA_8BIT_SIZE SBIT meme emper exposure __ a EE ExposureTime Time FLOAT ChangeClockSpeed TRUE FALSE FALSE Gamma nor or 1 rr Go 1 U2 ol J O NEEN GeenG n U3
6. Updating FGI 2000 One part of the assignment was to update and bug fix the original FGI system The clear all bug was a bug which resulted in the loss of handles to open devices when typing clear all or clear mex This problem was solved by calling the function mexLock from mainfg Polishing was another task This implied that the device information structure should also show the settings for device specific functions which are not shared by all types of Data Translation frame grabbers Unfortunately we did not solve this problem The next problem was that sometimes the device driver s resources were not released properly For this a subroutine was added which is called in those places where problems used to occur In addition to this we also added more descriptive error messages and improved the documentation of grabfg which was incomplete FGI and plFGI Report 2002 September 2002 Original design of the new system Originally we designed a new system which provides a uniform interface to the Matlab users for frame grabbers of all different families It is composed of three layers The command layer is the layer with functions visible to the Matlab users This layer only provides a uniform interface for all types of cameras almost no functionality is implemented here The control layer consists of two functions fgcontrol passes all commands to the correct device specific interface fedevices maintains
7. mexErrMsgTxt Mn if index lt 32 availableSerialNumbers index thisSerialNumber check whether this is the device we re looking for if serialNumber thisSerialNumber found true break if the correct device is found break if this was not the correct device uninitialize the device nRetValue PimMegaUninitialize amp deviceId if plError nRetValue closing the device mexErrMsgTxt Mn if found mexPrintf plOpen No device found with serial number lu n serialNumber mexPrintf Available serial numbers Nn for ioe Oy X M r d if availableSerialNumbers i unsigned long 0 break mexPrintf Slu n availableSerialNumbers i mexErrMsgTxt Mn update the open device array in plDevices rhs 0 mxCreateString add 86 FGI and plFGI Report 2002 rhs 1 mxCreateDoubleMatrix 1 px mxGetPr rhs 1 px 0 U32 serialNumber rhs 2 mxCreateDoubleMatrix 1 px mxGetPr rhs 2 px 0 int deviceld mexCallMATLAB 1 lhs 3 rhs pl end of opening the device else device was already open handle mexPrintf plOpen print a create the device handle plCreateDeviceHandle lhs plhs 0 Lis OQ else nrhs 1 mexPrintf PixeLINK Interface error mexPrintf plOpen number n mexErrMsgTxt n ifdef _ cplusplus extern
8. mexErrMsgTxt in break remove isopen get have 2 arguments task serialnumber case 2 if strcmp task remove for i 0 i lt deviceCount i if deviceArray i serialNumber serialnumber for t i t lt deviceCount deviceArray t serialNumber deviceArray t 1 serialNumber deviceArray t deviceID deviceArray tt 1 deviceID deviceCount else if strcmp task isopen initialise return value plhs 0J mxCreateDoubleMatrix 1 1 mxREAL y mxGetPr plhs 0 return 0 unless the loop finds a matching serialnumber y 0 0 for i 0 i lt deviceCount i c if deviceArray i serialNumber serialnumber y 0 1 found matching serialnumber return 1 break else if strcmp task get initialise return value plhs 0J mxCreateDoubleMatrix 1 1 mxREAL y mxGetPr plhs 0 return 1 unless the loop finds a matching serialnumber yl0 1 for i 0 i lt deviceCount i c if deviceArray i serialNumber serialnumber y 0 double deviceArray i devicelID break found a matching serialnumber end search 57 FGI and plFGI Report 2002 September 2002 else mexPrintf Internal error call to plDevices failed n mexPrintf Wrong number of arguments 2 is given or unknown task s task mexErrMsgTxt Mn break add has 3 argume
9. FGI and plFGI Report 2002 September 2002 tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 exposureTimeValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 ExposureTime tmp Gamma nRetValue PimMegaGetGamma devicelId amp gammaValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 gammaValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 Gamma tmp Gpo nRetValue PimMegaGetGpo deviceld amp gpoValue if ApiSuccess nRetValue if gpoValue 0 tmp mxCreateString Off else if gpoValue 1 tmp mxCreateString On else tmp mxCreateString Unknown value else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 Gpo tmp Green Gain nRetValue PimMegaGetGreenGain deviceld amp greenGainValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 greenGainValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else 47
10. found a matching serialnumber end search if t mexPrintf Internal error setpar called with unknown serial number d serialnumber mexErrMsgTxt Mn else mexPrintf getpar called with unknown parameter name s parName mexErrMsgTxt Mn else mexPrintf Internal error call to plDevices failed n mexPrintf Wrong number of arguments 4 is given or unknown A task s task 59 FGI and plFGI Report 2002 September 2002 mexErrMsgTxt Mn break default mexPrintf Internal error call to plDevices failed n mexErrMsgTxt Number of arguments out of range n else mexPrintf Internal error call to plDevices failed n mexPrintf First argument should be a string with the name of the task to be performed n mexErrMsgTxt in ifdef _ cplusplus extern C endif 60 FGI and plFGI Report 2002 September 2002 D 5 plError cpp ORK RK KR RK kk kk kOk Ck Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k Ck kc k Ck k kc k k kc k k k kc k kokock ck kok ck kokok ck k k x kx A x d Filename plError cpp 5 Description Source code for the error checking of the pl FGI Authors M A E Bakker L I Oei Gd L maarten panic et tudelft nl l i oeiGits tudelft nl Sa Date 2002 08 02 Updates 7 ORK kk Ck kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck k kc k k kc k Ck k kc K Ck k Ck Ck k kc k Ck kc k Ck
11. mexPrintf plClose Wrong arguments given One argument needed device handle or serial number n mexErrMsgTxt Mn 42 FGI and plFGI Report 2002 September 2002 check whether the device has been opened rhs 0 mxCreateString isopen rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices isOpen int mxGetScalar lhs 0 if isOpen get the deviceId rhs 0 mxCreateString get rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices deviceld HANDLE int mxGetScalar lhs 0 uninitialize the device nRetValue PimMegaUninitialize amp deviceId if plError nRetValue closing the device mexErrMsgTxt in update the open device array in plDevices rhs 0 mxCreateString remove rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices else isOpen mexPrintf plClose cannot close device with serial number d n serialNumber mexPrintf Device has not been opened n mexErrMsgTxt Mn else nrhs 1 amp amp mxIsStruct prhs 0 ifdef endif mexPrintf PixeLINK Interface error n mexPrintf plClose Wrong arguments given One argument
12. px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs deviceId plDevices HANDLE int mxGetScalar lhs 0 KOK KR KR KCkCkCk kOk Ck k kc k Ck k kc k Ck k kc Ck kCk k Ck k kc k Ck kc k Ck k kc k k kc k Ck kck k k k ck k kok ck kokock ck kok ck ck ok ok k k ke xe kx kx fj Get the value of the given parameter A KOK RR KK KK RR k kc k Ck kk k Ck kc k Ck k kc k Ck k kc Kk Ck k k Ck k kc k Ck k k Ck k kc k Ck k ck k kck ck e ck ck kok ck Ee k ke x kx A x fj if strcmp parametername DeviceID DeviceID m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 int deviceld else if strcmp parametername BlueGain Blue Gain nRetValue PimMegaGetBlueGain deviceld amp blueGainValue if plError nRetValue getting BlueGain value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 blueGainValue else if stromp parametername CurrentFrameRate Current Frame Rate nRetValue PimMegaGetCurrentFrameRate deviceld amp currentFrameRateValue if plError nRetValue getting CurrentFrameRate value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 currentFrameRateValue else if stromp parametername DataTransferSize Data Transfer Size nRetValue PimMegaGetDataTransferSize deviceld amp dataTransferSizeValue if plError nRetValu
13. After the serial number has been obtained it is checked whether the device is open by calling plDevices If not an error message is given and plGet is terminated If the device is open it is determined whether one or two arguments were given when calling plGet If only one argument was given a call to the plCreateDeviceHandle subroutine is made and the result of that is returned If two arguments were given it is checked whether the second argument is a string If it is not an error message is given and plGet is terminated If it is the name of the parameter is copied into a string variable and the subroutine plGetValue is called and the result of that is returned 2 FGI and plFGI Report 2002 September 2002 6 4 3 plGrab Description plGrab grabs a frame from the PixeLINK camera device and places it into an mxArray plGrab is the MEX function that grabs a frame from the PixeLINK device and takes care of the required postprocessing before delivering it to Matlab Currently only one calling syntax is supported so it is checked whether there is exactly one input argument and one output argument If not the else part of the check is executed resulting in an error message and the termination of plGrab by using the Matlab call mexErrMsgTxt The input argument is either a serial number or a device handle structure If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumbe
14. CENTER FOR MACHINE PERCEPTION CZECH TECHNICAL UNIVERSITY Ss O A Lu as zje U Bs lt LI Un Lu ag ISSN 1213 2365 FGI and plFGI Maarten Bakker Lian Ien Oei Vladim r Smutny smutny cmp felk cvut cz CTU CMP 2002 19 October 24 2002 Available at ftp cmp felk cvut cz pub cmp articles smutny Bakker TR 2002 19 pdf This work has been supported by the Czech Ministry of Health under project NN6333 3 2000 and in part by the European Union under project IST 2001 33266 by the Czech Ministry of Education under project MSM 212300013 and by the Grant Agency of the Czech Republic under projects GACR 102 00 1679 GACR 102 01 0971 and GACR 102 01 1371 Research Reports of CMP Czech Technical University in Prague No 19 2002 Published by Center for Machine Perception Department of Cybernetics Faculty of Electrical Engineering Czech Technical University Technick 2 166 27 Prague 6 Czech Republic fax 420 2 2435 7385 phone 420 2 2435 7637 www http cmp felk cvut cz FGI and plFGI Report 2002 Assignment Bug fixing FGI and implementing pIFGI Date June September 2002 Authors Maarten Bakker Lian Ien Oei Copyright 2002 Czech Technical University in Prague s Faculty of Electrical Engineering Center for Machine Perception axe Delft University of Technology T Faculty Information Technology and Systems U D e Ift Sub faculty Technical Informatics FGI and plFGI Report 2
15. Copyright 2002 Czech Technical University in Prague Czech Republic M A E Bakker L I Oei plFGI User Manual amp Technical Guide September 2002 Index PARTI U SERMANUJAL ise eo ce eee vo aeo enses ee ees Pos asias Sno eate GEN E 1 1 GENERAL INTRODUCTION ccccccsscccscscccscccscsccccscccssccescsccesccecssccsssccsescees 1 1 1 SHORT DESCRIPTION OF MATLAB Ne 1 1 2 SHORT DESCRIPTION OF THE PIXELINK CAMERA cette eee eene eren ens 1 1 3 SHORT DESCRIPTION OF PLOT 1 1 4 HARDWARE AND SOFTWARE REQUIREMENTS ssssseessessseossenssesseeseesseesseesseess 2 2 INTRODUCTION TO PLELPGL eet ui eo reos eo eee po aao o nin en e eoe o Sene e eese Paetos oe eO 3 2 1 ABOUT DATA RY PES 3 2 2 ABOUT THE CAMERA S SERIAL NUMBER pp 3 2 3 THE PLEFGIEFUNGTIONS 2 c eed EE Debe a ae cet 4 2 4 NOTES ON PLORAR nd a ed a ee ee a 8 2 5 NOTES ON PLGET AND PLSET 9 2 6 NOTE ON USING HANDEES 25 eege eeh eg Ree AAA 9 3 WORKING WITH PE EGL ee eo ve ee e er F oan on e SE Ee EEN Ee ISP eo Ungu oor no hee 10 3 1 GETTING STARTED esd dy E E A SAA T 10 3 2 SOME ESAMDPLES e ee eae 10 PARTH TECHNICALGUIDE dn 12 1 INTRODUCTION TO PLFGI DEVELOPMENT sooo 12 1 1 THE PLFGI DISTRIBUTION BACKAGE eee Rhe hehe ee erese ese eser sehen rsen 12 1 2 BU IEDINGPPEGI et A a da a emet a d A caf t m 12 1 3 GENERAL NOTES ON PLFGI DEVELOPMENT pp 14 2 TECHNICAL DESCRIPTION OF PLEIGL
16. Gpo else if strcmp parametername Gpo mexPrintf Gpo string Value float PulseLength n mexPrintf Value should be On or Off n mexPrintf If PulseLength 0 GPO is set to Value n mexPrintf If PulseLength gt 0 A pulse of PulseLength milliseconds is sent via the GPO n mexPrintf the value of the pulse is set by Value n 88 FGI and plFGI Report 2002 September 2002 GreenGain else if stromp parametername GreenGain mexPrintf GreenGain U32 n mexPrintf Value should not exceed lu n PCS2112 MAX GAIN ImagerClocking else if strcmp parametername ImagerClocking mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf ImagerClocking string n Valid values are n 0x00 Oscilator type External 16MHz n u Max clock rate divided by no division n Qx01 Oscilator type External 16MHz n Max clock rate divided by 2 n 0x02 Oscilator type External 16MH Max clock rate divided by 4 n 0x80 Oscilator type Internal 24MH id Max clock rate divided by no 0x81 Oscilator type Internal 24MHz d Max clock rate divided by 2 n 0x82 Oscilator type Internal 24MHz n in Es d n division in 3 n mexPrintf Max clock rate divided by 4 n ImagerName
17. GrabColorConversion string n Valid values are n mexPrintf mexPrintf mexPrintf BAYER 2BY2 COLOR Fastest n mexPrintf BAYER 3BY3 COLOR Fast default n mexPrintf BAYER 3BY3GGRAD COLOR Best quality for real time n mexPrintf BAYER 2PASSGRAD COLOR Best for captured images n mexPrintf BAYER 2PASSADAPT COLOR Best for captured images n mexPrintf BAYER VARGRAD COLOR Best for captured images Mn mexPrintf BAYER 2BY2 MONO Fastest converts to monochrome Nn mexPrintf BAYER 3BY3 MONO Best quality for real time to mono Wn mexPrintf BAYER ADAPT MONO Best for caputured images to mono Wn mexPrintf BAYER NO CONVERSION No Bayer conversion n GrabOutputType else if stromp parametername GrabOutputType mexPrintf GrabOutputType string n mexPrintf Valid values are n mexPrintf RAW Image exactly as produced by the camera n mexPrintf IMAGE 24 bpp colour bitmap converted to Matlab image format n mexPrintf RGB24 24 bpp colour bitmap in RGB24 format n else mexPrintf plSet Unknown parameter name n mexErrMsgTxt Mn 90 FGI and plFGI Report 2002 September 2002 D 14 plPrintPossibleValues h ORK RK KR KK kk Ck Ck kOkCk kk k Ck k kc k Ck kc k Ck k kc K Ck k kc Ck k Ck Ck k kc k Ck kc k Ck k kc k k k ck k kok ck kokock ck kok ck kokok I ke x x A x d Filename plPrintPossibleValues h Description Header file for plP
18. In the next figure we give an overview of the original design of the new system Sep un device layer array Device EET Vo Gg cific OL DT Interface PixeLINK Interface Epix Interface Future extensions ayer Ee ED eege UR 1 _ _ R 2 2 2 2 2 2 2 1 Frame pique Grabber OL DT SDK PixeLINK API Epix XCLIB Future extensions Drivers TE gt gt ew ewes Figure 7 Overview of the original design of the new system In the new system there are three layers We have taken all device specific functionality out of the top layer functions that are callable from Matlab and moved it into a lower level device specific layer This way it becomes easy to implement new frame grabbing devices When adding new frame grabbers one only has to add a new device specific interface to the device specific layer The command and control layers will stay the same In the command layer no functions are implemented It only provides a uniform interface for all types of cameras to the Matlab environment The control layer takes care of updating the open device structure loading the appropriate device specific code for the requested device and passing calls to the device specific interfaces In the device specific layer all functions are implemented separately for each type of camera ll FGI and plFGI Report 2002 September 2002 5 2 Description of the three layers 5
19. buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen check whether this is a known value if strcemp tmpstring STILL MODE tmpU32 STILL MODE else if strcemp tmpstring VIDEO MODE tmpU32 VIDEO MODE else mexPrintf plSetValue Error setting VideoMode unknown value n mexPrintf Valid values are STILL MODE and VIDEO_MODE n mexErrMsgTxt Mn set the value nRetValue PimMegaSetVideoMode deviceld tmpU32 if plError nRetValue setting VideoMode mexErrMsgTxt Mn else if strcmp parametername GrabColorConversion tmpU32 BAYER_3BY3_COLOR buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char 105 FGI and plFGI Report 2002 September 2002 mxGetString values 0 tmpstring buflen check whether this is a known value if strcmp tmpstring BAYER 2BY2 COLOR tmpU32 BAYER 2BY2 COLOR else if strcemp tmpstring BAYER 3BY3 COLOR tmpU32 BAYER 3BY3 COLOR else if strcemp tmpstring BAYER 3BY3GGRAD COLOR tmpU32 BAYER 3BY3GGRAD COLOR else if strcomp tmpstring BAYER 2PASSGRAD COLOR tmpU32 BAYER 2PASSGRAD COLOR else if strcemp tmpstring BAYER 2PASSADAPT COLOR tmpU32 B
20. get the serial number serialNumber U32 mxGetScalar prhs 0 check whether the device has been opened before rhs 0 mxCreateString isopen rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices isOpen int mxGetScalar lhs 0 open the device if it hasn t already been opened 85 FGI and plFGI Report 2002 September 2002 if isOpen get the number of attached imaging devices nRetValue PimMegaGetNumberDevices deviceAlias amp numberDevices if ApiSuccess nRetValue mexPrintf PixeLINK Interface error n mexPrintf plOpen Error on checking number of available devices n mexErrMsgTxt Mn if numberDevices lt unsigned long 1 mexPrintf plOpen No devices available n mexErrMsgTxt Mn initialize array with available serial numbers with 0 for i 0 i lt 32 i availableSerialNumbers i 0 open the device with the correct serial number for index unsigned long 0 index lt numberDevices amp amp found index t initialize the device nRetValue PimMegaInitialize deviceAlias index amp deviceId if plError nRetValue initializing device mexErrMsgTxt Mn get the device s serial number nRetValue PimMegaGetSerialNumber deviceld amp thisSerialNumber if plError nRetValue getting serial number
21. if gpoValue 0 m mxCreateString Off else if gpoValue 1 m mxCreateString On else m mxCreateString Unknown value else if stromp parametername GreenGain Green Gain nRetValue PimMegaGetGreenGain deviceld amp greenGainValue if plError nRetValue getting GreenGain value mexErrMsgTxt Mn 68 FGI and plFGI Report 2002 September 2002 tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 greenGainValue else if strcmp parametername HardwareVersion Hardware Version nRetValue PimMegaGetHardwareVersion deviceld amp hardwareVersionValue if plError nRetValue getting HardwareVersion value mexErrMsgTxt Mn tmp mxCreateString const char hardwareVersionValue ProductID tmp2 mxCreateString const char hardwareVersionValue SerialNumber tmp3 mxCreateString const char hardwareVersionValue FirmwareVersion tmp4 mxCreateString const char hardwareVersionValue FpgaVersion fieldnames 0 ProductID fieldnames 1 SerialNumber fieldnames 2 FirmwareVersion fieldnames 3 FpgaVersion m mxCreateStructMatrix 1 1 4 const char fieldnames mxSetField m 0 ProductID tmp mxSetField m 0 SerialNumber tmp2 mxSetField m 0 FirmwareVersion tmp3 mxSetField m 0 FpgaVersion tmp4 else if stromp param
22. mexPrintf Active line count exceeds total lines per field NXn mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Frame left exceeds active pixel count n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 xy mexPrintf Difference between whitelevel and blacklevel too large n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEM ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Frame top exceeds active line count n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 Zb mexPrintf Frame width not multiple of 4 or exceeds active pixel count Wn mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 xf mexPrintf Frame height will cause digitalisation to exceed active pixel count n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker mexPrintf H sync search insert position n mexErrMsgTxt Unable to return 2002 07 03 position precedes H sync
23. string parametername prhs 3 value of the specified parameter Output Example plDevices setpar 75122 GrabOutputType RAW in which case RAW is defined as 0x0 This task writes the given value of the given device parameter in the open device array Its internal structure is almost the same as that of getpar but the parameter value is written not read e Suggestions for improvement In remove the inner for loop tries to copy one entry more than needed When having 32 camera s open this could result in a segfault The inner loop for condition should be t i t lt deviceCount 1 t 23 plFGI Technical Guide September 2002 29 Description of plCreateDeviceHandle plCreateDeviceHandle is a subroutine which is linked to the plOpen and plGet MEX functions When given the serial number of a PixeLINK device it will create a Matlab struct matrix containing all the device s parameter names with their respective values This is the so called handle structure which is returned by plOpen and plGet After declaration of the necessary variables and structures the device ID for calling the PixeLINK API functions is obtained by calling plDevices Then for every parameter the appropriate API call is made to obtain its value If the API call returns the value for unsupported function the string Unsupported is stored as parameter value If the API returns any other error code the string Could not get
24. t 0 break found a matching serialnumber end search i EE mexPrintf Internal error getpar called with unknown serial number d serialnumber mexErrMsgTxt Mn else 58 FGI and plFGI Report 2002 September 2002 mexPrintf getpar called with unknown parameter name s parName mexErrMsgTxt Mn else mexPrintf Internal error call to plDevices failed n mexPrintf Wrong number of arguments 3 is given or unknown task s task mexErrMsgTxt Mn break setpar has 4 arguments case 4 AE strcmp task setpar allocate memory for parName string and get the 3rd argument buflen mxGetM prhs 2 mxGetN prhs 2 sizeof mxChar 1 parName char mxCalloc buflen sizeof char mxGetString prhs 2 parName buflen if strcmp parName GrabColorConversion t 1 for i 0 i lt deviceCount i if deviceArray i serialNumber serialnumber deviceArray i grabColorConversion U32 mxGetScalar prhs 3 t 0 break found a matching serialnumber end search Tf EN mexPrintf Internal error setpar called with unknown serial number d serialnumber mexErrMsgTxt Mn else if strcmp parName GrabOutputType t 1 for i 0 i lt deviceCount i if deviceArray i serialNumber serialnumber deviceArray i grabOutputType U32 mxGetScalar prhs 3 t 0 break
25. tmp4 mxCreateString Could not get value tmp5 mxCreateString Could not get value D mxSetField mxSetField m SubWindow Decimation tmp m mxSetField m m m SubWindow StartColumn tmp2 SubWindow StartRow tmp3 SubWindow NumberColumns tmp4 SubWindow NumberRows tmp5 mxSetField mxSetField o oo OOO Sub Window Pos nRetValue PimMegaGetSubWindowPos deviceId amp subWindowPosStartColumnValue amp subWindowPosStartRowValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 subWindowPosStartColumnValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 subWindowPosStartRowValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value mxSetField m 0 SubWindowPos StartColumn tmp mxSetField m 0 SubWindowPos StartRow tmp2 Sub Window Size nRetValue PimMegaGetSubWindowSize deviceld amp subWindowSizeDecimationValue amp subWindowSizeWidthValue amp subWindowSizeHeightValue if ApiSuccess nRetValue 52 FGI and plFGI Report 2002 September 2002 if subWindowSizeDecimationValue PCS2112 NO DECIMATION tmp mxCreateString PCS2112 NO D
26. These have a lot of functions in common but some functions are specifically for one type of frame grabber With the original FGI it was not possible to see the settings for these specific functions Only the settings for the shared functions were stored in the device information structure With polishing we mean that the device information structure also will show the settings for device specific functions When studying the source code of the original FGI system we determined that it would be easiest to immediately redesign the system in order to integrate the support for the PixeLINK camera When implementing the new system we could solve this problem at the same time instead of solving this first and then possibly having to do it again with the implementation of the new system Therefore we postponed the solution to this problem We designed the new system as described in chapter 5 After a while we decided not to implement that design but to implement the system described in chapter 6 Unfortunately after implementing that system we didn t have enough time left to polish the original FGI system Therefore this problem still remains unsolved 43 Proper release of the device driver s resources The original complaint was that in grabfg when an error was encountered some of the device driver s resources were not properly released This resulted in a new error message and the need to close and re open Matlab after the error had occu
27. U32 U32 U32 n parametername mexErrMsgTxt Mn if mxIsChar values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects 5 parameters of types string U32 U32 U32 U32 n parametername mexErrMsgTxt Mn for i 1 i lt 5 it if mxIsDouble values i mexPrintf plSetValue wrong parametertype given n mexPrintf s expects 5 parameters of types string U32 U32 U32 U32 n parametername mexErrMsgTxt Mn U32 U32 else if stromp parametername SubWindowPos if nvalues 234 mexPrintf plSetValue wrong number of parameters given n mexPrintf s expects 2 parameters n parametername mexErrMsgTxt Mn if mxIsDouble values 0 amp amp mxIsDouble values 1 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a two arguments of type U32 n parametername mexErrMsgTxt Mn string U32 U32 else if strcmp parametername SubWindowSize if nvalues 3 mexPrintf plSetValue wrong number of parameters given n mexPrintf s expects 3 parameters n parametername mexErrMsgTxt Mn if mxIsChar values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a 3 arguments of types string U32 U32 n parametername mexErrMsgTxt Mn if mxIsDouble values 1 amp amp mxIsDouble values 2
28. else if strcmp parametername ImagerName mexPrintf ImagerName string max 80 characters Nn MonoGain else if strcmp parametername MonoGain mexPrintf MonoGain U32 n mexPrintf Value should not exceed lu n PCS2112 MAX GAIN OverlayCallBack else if strcmp parametername OverlayCallBack TODO mexPrintf PimMegaSetOverlayCallBack not supported yet n PreviewColorConversion else if stromp parametername PreviewColorConversion PreviewColorConversion string n Valid values are n mexPrintf mexPrintf mexPrintf BAYER 2BY2 COLOR Fastest Nn mexPrintf BAYER 3BY3 COLOR Fast default n mexPrintf BAYER 3BY3GGRAD COLOR Best quality for real time n mexPrintf BAYER 2PASSGRAD COLOR Best for captured images n mexPrintf BAYER 2PASSADAPT COLOR Best for captured images n mexPrintf BAYER VARGRAD COLOR Best for captured images n mexPrintf BAYER 2BY2 MONO Fastest converts to monochrome n mexPrintf BAYER 3BY3 MONO Best quality for real time to mono n mexPrintf BAYER ADAPT MONO Best for caputured images to mono n mexPrintf BAYER NO CONVERSION No Bayer conversion Nn PreviewWindow else if strcmp parametername PreviewWindow TODO mexPrintf PimMegaSetPreviewWindow not supported yet n RedGain else if strcmp parametername RedGain mexPrintf RedGa
29. mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 plhs 2 rhs plDevices else nrhs 1 mexPrintf PixeLINK Interface error n 83 FGI and plFGI Report 2002 September 2002 mexPrintf pllIsOpen Wrong arguments given One argument needed device handle or serial number n mexErrMsgTxt Mn ifdef cplusplus extern C endif 84 FGI and plFGI Report 2002 September 2002 D 12 plOpen cpp ROKK KKK KK KK kOkCk kk k Ck k kc k Ck kc k Ck A k kc k Ck kc k Ck k kc k k k ck k Ck k ck k kck ck kok ck kokok ck k kx x A x d Filename plOpen cpp 5 Description Source code for the function plOpen Authors M A E Bakker L I Oei Gd L maarten panic et tudelft nl l i oei its tudelft nl Sa Date 2002 08 08 Updates 7 RR KKK KK kk Ck Ck kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k kok ck kokock ck kok ck kokok Kk k ke xe x k x f plOpen opens a pixelink device and returns the device s handle Ey ORK KKK kk Ck kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc K Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k k Ck k kc k kckock ck kok ck kokok ck eR I x Input prhs 0 int serial number of the device to be opened Output plhs 0 struct handle for the device SA Syntax m plOpen serialnumber ROR KR KK KK Ck kOkCk Ck kCk Ck k kc k Ck kc k Ck k k
30. parametername prhs 0 should be the device handle struct or serial number int prhs 1 should be the parameter name optional if nrhs 1 nrhs 2 get the serialNumber if mxIsStruct prhs 0 serialNumberField mxGetField prhs 0 0 SerialNumber serialNumber U32 mxGetScalar serialNumberField else if mxIsDouble prhs 0 serialNumber U32 mxGetScalar prhs 0 else mexPrintf PixeLINK Interface error n mexPrintf plGet Wrong argument given n mexPrintf First argument should be the device handle or the serial number n mexErrMsgTxt Mn FGI and plFGI Report 2002 September 2002 check whether the device has been opened rhs 0 mxCreateString isopen rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices isOpen int mxGetScalar lhs 0 if isOpen mexPrintf plGet Device with serial number lu has not been opened n serialNumber mexPrintf Cannot get settings n mexErrMsgTxt Mn if nrhs 1 1 argument return device handle create the device handle return structure plCreateDeviceHandle lhs serialNumber plhs 0 lhs 0 else nrhs 2 2 arguments return parameter value get the parameter name if mxIsChar prhs 1 2nd argument parametername should be a string mexPrintf plGet
31. supports functionality to open and close a device check whether a device is opened get and set a number of parameters and grab an image from the camera This chapter starts with an overview of the structure of the new system Then it gives a short description of all functions Finally it describes the functions in detail 6 1 Structure of pIFGI In the next figure we give an overview of the structure of pIFGI open device array plPrintPossible Values plDevices plGrab plOpen plClose plCreateDevice Handle plGetValue plSetValue PixeLINK Camera Application Programming Interface plIsOpen Figure 9 Structure of pIFGI The system is composed of several functions plIsOpen plGrab plGet plOpen plClose and plSet which can be called from Matlab These functions call the appropriate functions from the PixeLINK Camera Application Programming Interface API plDevices maintains the open device array in which the device ID s handles to open devices are stored In figure 9 the relations between the internal and external pIFGI functions are shown An arrow indicates that a function is called by another function The arrow between plDevices and the open device array means that data is exchanged in two directions 14 FGI and plFGI Report 2002 September 2002 62 Short description of the plFGI functions plFGI supports the following functions e plClose closes a PixeLINK camera
32. 28 29 30 FGI and plFGI Report 2002 September 2002 include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib ifdef _ cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs implement the MEX function here ifdef _ cplusplus extern C endif Code example 2 Template for a pIFGI MEX function We used the libraries of Matlab version 6 1 and the PixeLINK Camera API Release 3 0 The MEX files are implemented as C files instead of C because the PixeLINK Camera API is implemented in C and it uses language constructions that cannot be used with C files With the extern c command the mexFunction is exported as a C function so it will be possible to call the function from within Matlab just like normal C MEX files The PixeLINK dll is load time linked This means that when the MEX file is loaded into memory the PixeLINK dll is loaded at the same time Therefore to use the MEX files it is necessary that the file PimMegaApi dll is in the Windows path not the Matlab path Otherwise Matlab will give an error message like Unable to load mex file g fgi bin plOpen dll The specified module could not be found 2 Invalid MEX file For us this caused some confusion because we thought that there was something wrong with our code But instead the error message was generated be
33. DEM ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Clamp start exceeds clamp end n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Vertical increment not equal to 1 n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit O FrameId mexPrintf First active pixel M Bakker 2 or clamp start n mexErrMsgTxt Unable to g return destroyFrameOnErrorExit O FrameId mexPrintf Active line area and total pixels start M Bakker 2 LT IMG DEV ID DeviceId 002 07 03 exceeds backporch start rab an image Wn LT IMG DEV ID DeviceId 002 07 03 is not between backporch per line n 39 FGI and plFGI Report 2002 case case case case case case case case case case case case case case OLC_STS_ACTLINECOUNT OLC_STS_FRAMELEFT OLC_STS_RANGE OLC_STS_FRAMETOP OLC_STS_FRAMEWIDTH OLC_STS_FRAMEHEIGHT OLC_STS_HSYNCSEARCHPOS OLC_STS_VSYNCSEARCHPOS OLC_STS_INTERLACEDHGTGRAN OLC_STS_INTERLACEDTOPGRAN OLC_STS_WHITELEVEL OLC_STS_NONOLMSG OLC_STS_MODECONFLICT OLC_STS_BUFSIZ September 2002 mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03
34. ER improved error messages after acquire frame 2002 07 04 ORK KK KR Ck k Ck Ck kk k Ck kc kc Ck k kc k Ck k kc Ck kc k Ck kc kc k k kc k Ck k kc k k k ck k kck ck kokck kokok e ke e x kA amp x d This C file contains the source code to grab an image Xy ORK RK KR Eh kOk Ck Ck kCk Ck k kc k Ck kc k Ck k kc k Ck kk KCk kc k Ck kc kc k k k k Ck kck k k kc k kckok ck kokck kokok ck ko k e x kA x x d Input device information structure devinfo Z Output Matlab mxArray imgmatrix Ey Syntax imgmatrix grabfg devinfo ZE ZE moviematrix grabfg devinfo imgmatrix imgmatrix moviematrix grabfg devinfo PO fA grabfg devinfo imgmatrix xx grabfg devinfo imgmatrix moviematrix grabfg devinfo imgmatrix moviematrix scaling factor Jak kk kOkCk Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc Ck k kc k Ck kCk Ck kc k k kc kc k k kc k Ck k kc k k k ck k kok k kokck kokok kk ke e x kA x x d include include include include include include include mex h stdlib h windows h olwintyp h olimgapi h olfgapi h Dtcolors h Added by M Bakker 2002 07 03 18 25 this subroutine calls OlFgDestroyFrame to release resources that were not properly released when another error was encountered during the grabbing void destroyFrameOnErrorExit OLT_IMG_DEV_ID DeviceId OLT_FG_FRAME_ID FrameId OLT_APISTATUS result resu swit lt OlFgDestroyFrame DeviceI
35. FGI and plFGI Report 2002 September 2002 tmp mxCreateString Could not get value mxSetField m 0 GreenGain tmp Hardware Version nRetValue PimMegaGetHardwareVersion deviceld amp hardwareVersionValue if ApiSuccess nRetValue tmp mxCreateString const char hardwareVersionValue ProductID tmp2 mxCreateString tmp3 mxCreateString tmp4 mxCreateString const char hardwareVersionValue SerialNumber const char hardwareVersionValue FirmwareVersion const char hardwareVersionValue FpgaVersion else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported tmp3 mxCreateString Unsupported tmp4 mxCreateString Unsupported else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value tmp3 mxCreateString Could not get value tmp4 mxCreateString Could not get value mxSetField m 0 HardwareVersion ProductID tmp mxSetField m 0 HardwareVersion SerialNumber tmp2 mxSetField m 0 HardwareVersion FirmwareVersion tmp3 mxSetField m 0 HardwareVersion FpgaVersion tmp4 Imager Chip ID nRetValue PimMegaGetImagerChipId deviceld amp imagerChipIdValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 imagerChipIdValue else if ApiNotSupportedError nRetValue tm
36. RGB24 PimMegaStopVideoStream deviceId mexErrMsgTxt in number of memory locations needed for storing the raw image rawImgSize pixelWidth pixelHeight RGB24ImgSize rawImgSize 3 allocate memory for the matlab and capture arrays Switch dataTransferSize dimension matrix for pixeldepth case DATA_8BIT_SIZE 8 bit pixel depth use 8 bit integer per pixel plhs 0 mxCreateNumericArray dim size mxUINT8 CLASS mxREAL imgCapturePtr U8 mxCalloc rawImgSize sizeof U8 rawlImgByteSize rawImgSize break case DATA 16BIT SIZE 10 bit pixel depth use 16 bit integer per pixel if grabOutputType RAW plhs 0 mxCreateNumericArray dim size mxUINT16 CLASS mxREAL else IMAGE or RGB24 is always 8 bit subpixel plhs 0 mxCreateNumericArray dim size mxUINT8 CLASS mxREAL imgCapturePtr U16 mxCalloc rawlImgSize sizeof U16 rawImgByteSize rawImgSize 2 break default mexPrintf plGrab Unknown pixel depth should be DATA 8BIT SIZE or DATA 16BIT SIZE in PimMegaStopVideoStream deviceId mexErrMsgTxt Mn return if plhs 0 NULL mxCreateNumericArray returns NULL in case of problems mxCalloc doesn t return at all A PimMegaStopVideoStream deviceId mexErrMsgTxt plGrab Cannot allocate enough MatLAB memory to store the captured image n return imgOutPtr int mxGetPr plhs 0 al
37. Wrong argument given n mexPrintf Second argument should be a string with the parametername n mexErrMsgTxt Mn buflen mxGetM prhs 1 mxGetN prhs 1 sizeof mxChar 1 parametername char mxCalloc buflen sizeof char mxGetString prhs 1 parametername buflen get the settings for this parameter plGetValue lhs serialNumber parametername plhs 0 lhs 0 else nrhs 1 nrhs 2 ifdef endif mexPrintf PixeLINK Interface error n mexPrintf plGet Wrong number of arguments given One or two arguments needed n mexPrintf handle or serial number and optional a parametername n mexPrintf Example plGet handle or plGet handle parametername n mexPrintf or plGet serialnumber or plGet serialnumber parametername n mexErrMsgTxt in cplusplus extern C 65 FGI and plFGI Report 2002 September 2002 D 8 plGetValue cpp ORK KK RK kk Ck Ck kOkCk Ck kCk Ck k kc k Ck kc kc k k kc k Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k k kc k k kok ck k kok ck kok ck ck kok ck k kx I kx fj Filename plGetValue cpp f Description Source code for plGetValue Authors M A E Bakker L I Oei ST maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 08 Updates Si ORK kk hh kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc Kk Ck k Ck Ck kc kc k Ck kc k Ck k kc k Ck k kc k k kc k kokok ck
38. a set of functions to control the camera With these functions you can set imaging parameters view images and capture frames and store them as image files The API functions can be called from a C program User Application API PimMegaApi dll DirectShow User space Kernel space Stream Class Driver FireWire Minidriver FireWire Bus Driver Legend Created by the User Provided by PixeLINK Provided by Microsoft OHCI FireWire Driver PixeLINK PL A6xx Camera OHCI FireWire Firmware Figure 5 PixeLINK Software Architecture FGI and plFGI Report 2002 September 2002 3 The original Frame Grabber Interface The original Frame Grabber Interface FGI was a Matlab interface for Data Translation Frame Grabbers With this interface it was possible to grab pictures from a Data Translation camera into Matlab You could open and close a device check whether it has been opened or not grab an image into Matlab get and set various variables load a settings file and reset an opened device This chapter explains the structure of the original FGI and gives a short description of all existing FGI functions 31 Structure of the original system In the next figure we give an overview of the structure of the original Frame Grabber Interface device structure DEF checkError Ge Control Data Translation Frame Grabber SDK Figure 6 Overview of the original Frame Grabber Interface
39. amp tmpU324 amp tmpU325 if tmpU324 tmpU322 gt PCS2112 MAX WIDTH mexPrintf plSetValue Error setting Subwindow size value too large n mexPrintf Current start column uWidth should not exceed lu n PCS2112 MAX WIDTH mexErrMsgTxt Mn if tmpU325 tmpU323 gt PCS2112 MAX HEIGHT mexPrintf plSetValue Error setting Subwindow size value too large n 104 FGI and plFGI Report 2002 September 2002 mexPrintf Current start row uHeight should not exceed lu n PCS2112 MAX HEIGHT mexErrMsgTxt Mn if tmpU322 lt PCS2112 MIN WIDTH mexPrintf plSetValue Error setting Subwindow size value too small n mexPrintf uWidth must be at least lu n PCS2112 MIN WIDTH mexErrMsgTxt Mn if tmpU323 PCS2112 MIN HEIGHT mexPrintf plSetValue Error setting Subwindow size value too small n mexPrintf uHeight must be at least than lu n PCS2112 MIN HEIGHT mexErrMsgTxt Mn set the values nRetValue PimMegaSetSubWindowSize deviceld tmpU32 tmpU322 tmpU323 if plError nRetValue setting SubWindowSize mexErrMsgTxt Mn Timeout else if strcmp parametername Timeout tmpU32 U32 mxGetScalar values 0 nRetValue PimMegaSetTimeout deviceld tmpU32 if plError nRetValue setting Timeout mexErrMsgTxt Mn VideoMode else if stromp parametername VideoMode tmpU32 STILL_MODE
40. and vector formulations With Matlab it is possible to make analyses and computations on images grabbed by a frame grabber device To interact with data and programs external to the Matlab environment Matlab provides an Application Program Interface API A part of the API are MEX files dynamically linked subroutines that the Matlab interpreter can automatically bad and execute With these it is possible to call your own C subroutines from Matlab as if they were built in functions A MEX file is just like a regular C file It only has a compulsory gateway routine to interface with Matlab the mexFunction with its parameters nlhs plhs nrhs and prhs where prhs is an array of right hand input arguments nrhs is the number of right hand input arguments plhs is an array of left hand output arguments and nlhs is the number of left hand output arguments void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs You can access the data in the mxArray structure and manipulate it Most files in the original FGI were MEX files FGI and pIFGI Report 2002 September 2002 23 Data Translation Frame Grabbers Data Translation DT Frame Grabbers are frame grabber boards for the Peripheral Component Interconnect PCI bus You can use them for image analysis and machine vision application The next picture gives an example of such a board Figure 2 DT3152 Frame Grabber To a frame grabber one can connect several cameras dep
41. argument n parametername mexErrMsgTxt Mn if nvalues 2 amp amp mxIsChar values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a string as 2nd argument n parametername mexErrMsgTxt Mn float if strcmp parametername Gamma if nvalues 1 amp amp mxIsDouble values 0 mexPrintf plSetValue wrong number of parameters given or wrong paramtertype n mexPrintf s expects 1 parameter of type float n parametername mexErrMsgTxt Mn U32 float else if strcmp parametername Gpo if nvalues 1 nvalues 2 mexPrintf plSetValue wrong number of parameters given n mexPrintf s expects 1 or 2 parameters n parametername mexErrMsgTxt Mn if mxIsDouble values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a U32 as 1st argument n parametername mexErrMsgTxt Mn if nvalues 2 amp amp mxIsDouble values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a float as 2nd argument n parametername mexErrMsgTxt Mn 96 FGI and plFGI Report 2002 September 2002 string U32 U32 U32 U32 if strcemp parametername SubWindow if nvalues 5 mexPrintf plSetValue wrong number of parameters given n mexPrintf s expects 5 parameters of types string U32
42. else part of the if isOpen construction is executed and the function terminates with an error message If it is open again a call to plDevices is made this time to obtain the PixeLINK API s device ID Then the PixeLINK API function pimMegaUninitialize is made to close the device When an error occurs closing the device the standard error handling code in plError returns a non false value and the plClose function exits If all went well the device should now be closed and a call to plDevices is made to update the list of open devices 6 4 2 plGet Description plGet returns the device s up to date handle if 1 argument is given or returns the value of the given parameter if 2 arguments are given plGet is the MEX function which is used for obtaining the value of a parameter a set of parameters or a complete device handle for a PixeLINK device First it is tested whether 1 or 2 arguments were given If not the else part of the check is executed resulting in an error message and the termination of plGet by using the Matlab call mexErrMsgTxt The first argument is either a serial number or a device handle structure If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGet is terminated
43. grabbers is given It starts with an overview of the system architecture Then it describes all plFGI functions Chapter 7 describes the programming environment used FGI and plFGI Report 2002 September 2002 2 Background The people at the Center for Machine Perception want to be able to grab images with a camera from within the Matlab environment Therefore a Frame Grabber Interface is needed to provide a communication layer between Matlab and the frame grabbers This chapter first gives an overview of the global architecture Then it describes the communication interfaces with Matlab and the Data Translation and PixeLINK frame grabbers 2 1 Overview The Frame Grabber Interface is a set of functions which can be called from Matlab to communicate with a frame grabber This frame grabber can either be a Frame Grabber Interface plug in board communicating with a camera or a camera with an integrated board The interface between Matlab and FGI Frame Grabber Libraries consists of MEX functions which are callable directly from the Matlab user interface For communication between FGI and the frame grabber the manufacturer of the frame grabber device provides special libraries with functions that can be called from an application program Figure 1 Global architecture 22 Matlab Matlab is a mathematical program for technical computing It can be used to solve many technical computing problems especially those with matrix
44. indicate the first return value of the MEX function e plClose piCiosedi plClose handle orplClose serialnumber plClose closes an open PixeLINK camera device Input prhs 0 struct handle of the device or U32 serial number of the device Remarks It will be verified whether the input amp a valid handle or number plClose will then try to close the device If the device was not open does not exist or returns an error code an error message is printed and plClose exits Output No return value the device is closed and the internal list d open devices is updated Examples plClose m plClose 75122 plFGI User Manual September 2002 e plGet SS Syntax plGet handle plGet handle parametername plGet serialnumber OrplGet serialnumber parametername Description plGet returns the device s up to date handle if 1 argument is given or returns DEUM tsa oP the given paneer erer Input prhs 0 struct handle for the device or U32 serial number of the device prhs 1 string name of the parameter optional Remarks It will be verified whether the input is a valid handle or number plGet will then try to get the requested parameter If the parameter is not valid the device is not open does not exist or returns an error code and error message is printed and plGet exits Output plhs 0 struct handle for the device with 1 input argument plhs 0 value s of the given parameter with 2 i
45. k kc k k k kc k kok ck kokok ck kok ck kokok ck He I x f plError translates a PixeLINK API status code into a useful error x message S ROKK RK KR KK KK RR Ck k kc k Ck kc k Ck k kc k Ck k kc Ck kc k Ck k kc k k kc k Ck k kc K e k ck e ck ck kok ck kokok ck k ke x x A x Input PXL RETURN CODE the API s return code that should be wf checked e string description when the possible fault occurred Output int 0 if no error LS 1 on an error that should be interpreted as a warning 2 on an error that should be interpreted as fatal Syntax i plError PXL RETURN CODE result char error ORK KK KR KR kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc K Ck k kc k Ck kc e k kc k Ck kc k Ck k kc k Ck k ck k kok ck kokok ck kok ck ck kok I k e kx k x d define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows include windows h include Y soft95 matlab6 extern include mex h include Y software framegrag pixelink api pimmegaapiuser h int plError PXL_RETURN_CODE result char error char errorStr 49 33 strcpy errorStr The device s API encountered a problem while strncat errorStr error 33 strcat errorStr n if result ApiSuccess mexPrintf errorStr switch result case ApiSuccess return 0 case ApiNullHandleError mexPrintf NULL handle the device was not sucessfully initialised n return 2 case ApiNullPointerError mexPrintf NULL po
46. kc K Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k kok ck kokok ck kok ck ck kok I ke kx d plGrab grabs a frame from the PixeLINK device and places it into a Ey mxArray ORK KK KK hh E Ck k kc k Ck kc k Ck k kc kCk kCk Ck Ck kc k Ck k kc k k kc k Ck k kc k k kc k k kck ck k kock ck kok ck kokok ck k ke x x A x fj Input prhs 0 U32 serialnumber for the device pe struct handle for the device Output plhs 0 mxArray grabbed image Syntax imagematrix plGrab serialnumber ZS imagematrix plGrab handle J ORK RK KR KK kk kk kOk Ck Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc Ck k Ck Ck k kc k k kc k Ck k kc k k kk k k kc k k k ck ck kok ck kokok ck k ke x x A x fj define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows include windows h include Y soft95 matlab6 extern include mex h link with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and libmx lib include yY software framegrag pixelink api pimmegaapiuser h link with Y software framegrag pixelink api pimmegaapi lib include plError h the pixelink error checking subroutine include plTypes h ifdef cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs PXL_RETURN_CODE nRetValue the return codes of the pixelink functions mxArray serialNumberField U32 serialNumber 1 the s
47. list of known parameter names to the screen 2 12 Description of plSetValue plSetValue is a subroutine linked to the plSet MEX function It needs 4 or more input arguments the serial number of the device the name of the parameter to be set the number of values that are passed all values that are needed to set the parameter First the serial number is used to obtain the PixeLINK device ID by calling plDevices For every parameter name it is checked using an if stremp construction whether the right number and type of values are given If not a descriptive error message is printed and plSetValue is terminated using a call to mexErrMsgTxt After this another if elseif stremp construction is used to distinguish between the different parameter names For every parameter name the passed values are copied into a variable parsed if necessary and a call is made to the relevant PimMegaSet function For the GrabColorConversion and the GrabOutputType parameters a call is made to plDevices as these are stored there instead of in the PixeLINK API e Errors found in the PixeLINK API documentation Vitana 2002 1 p 92 PimMegaSetSubWindow uStartColumn uNumberColumns must be less than PCS2112 MAX WIDTH uStartRow uNumberRows must be less than PCS2112 MAX HEIGHT less than should be less than or equal to Vitana 2002 1 p 94 PimMegaSetSubWindowPos uStartColumn current number of columns must be
48. mexFunction e Implement Projectname cpp starting with the following template 12 plFGI Technical Guide September 2002 define WIN32 LEAN AND MEAN This excludes rarely used stuff from Windows headers We don t know what that means exactly but it is generated by MS Visual C when you create a project and we just copied it S include windows bz include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib ifdef _ cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs implement the MEX function here ifdef _ cplusplus L extern C endif Code example 1 Template for a pIFGI MEX function The libraries of Matlab version 6 1 and the PixeLINK Camera API Release 3 0 were used for the development of the pIFGI 13 plFGI Technical Guide September 2002 1 3 General notes on plFGI development The MEX files are implemented as C files instead of C because the PixeLINK Camera API is implemented in C and it uses language constructions which cannot be used with C files With the extern c command the mexFunction is exported as a C function so it will be possible to ca
49. mxArray tmp tmp2 tmnmp3 tmp4 tmp5 double tmppr tmppr2 tmppr3 tmppr4 tmppr5 variables used for receiving the settings U32 blueGainValue 1 float currentFrameRateValue 1 U32 dataTransferSizeValue 1 U32 exposureValue 1 float exposureTimeValue 1 float gammaValue 1 U32 gpoValue 1 FGI and plFGI Report 2002 U32 greenGainValue 1 HARDWARE VERSION hardwareVersionValue U32 imagerChipIdValue 1 U32 imagerClockingValue 1 LPSTR imagerNameValue U32 imagerTypeValue 1 U32 monoGainValue 1 long previewWindowPosLeftValue 1 long previewWindowPosTopValue 1 U32 previewWindowSizeWidthValue 1 U32 previewWindowSizeHeightValue 1 U32 redGainValue 1 U32 saturationValue 1 U32 serialNumberValue 1 U32 softwareVersionValue 1 U32 subWindowDecimationValue 1 U32 subWindowStartColumnValue 1 U32 subWindowStartRowValue 1 U32 subWindowNumberColumnsValue 1 U32 subWindowNumberRowsValue 1 U32 subWindowPosStartColumnValue 1 U32 subWindowPosStartRowValue 1 U32 subWindowSizeDecimationValue 1 U32 subWindowSizeWidthValue 1 U32 subWindowSizeHeightValue 1 U32 timeoutValue 1 U32 videoModeValue 1 U32 grabColorConversion 1 U32 grabOutputType 1 KOK KR KK KK Ck kOk Ck k kc k k kk k Ck kc k Ck k kc k Ck k kc Ck kc k Ck k kc k Ck k k Ck kck k k k ck k kok ck kokock ck kok ck ck kok ok k
50. needed device handle or serial number n mexErrMsgTxt Mn Cplusplus extern C B FGI and plFGI Report 2002 D 2 plCreateDeviceHandle cpp September 2002 ORK RK KR kk Ck kk Ck Ck kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k kok ck k kck ck kok ck kokok ck oe x A x d Filename plCreateDeviceHandle cpp e Description Source code for plCreateDeviceHandle uy Authors M A E Bakker L I Oei maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 09 uA Updates Si ROKK KKK RR Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Kk k kc k Ck k kc k kok ck e E kok ck kokok I ke kx d plCreateDeviceHandle creates the device handle i e the structure with settings which has to be returned to the matlab user SZ ORK RK KR KK hh kOkCk Ck k Ck Ck k kc k Ck kc k Ck k kc k E Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k A e E kok ck ck Ee k ke x kx rd Input returnarray mxArray mxArray for receiving the structure pe serialNumber U32 serial number of the device wy Output xy Syntax plCreateDeviceHandle returnArray serialNumber ROKK kk Ck kk Ck Ck kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck k Ck Ck k kc k k kc k Ck k kc k Ck k kc k kok ck k kock ck kok ck kokok ck k kx kx k x d include windows h include Y Nsoft95Nmatlab6NexternNVincludeWMmex h include Y
51. not get value Unsupported Unsupported 75122 16777984 PCS2112 NO DECIMATION 0 0 1024 320 0 0 PCS2112 NO DECIMATION 1024 320 1000 VIDEO MODE BAYER 3BY3 COLOR RAW 34
52. that is suitable for direct viewing with the Matlab image command In case of colour images the Bayer pattern is first translated into a suitable RGB format The conversion method is determined by the setting of GrabColorConversion e RGB2A returns a single column mxArray that is filled according to the standardised RGB24 format It can be used for example to save pictures to a file as many image file formats are in one way or the other based on this format In case of colour images the Bayer pattern is first translated into a suitable RGB format The conversion method is determined by the setting of GrabColorConversion The setting of GrabColorConversion default BAYER_3BY3_COLOR determines in case of colour images that are returned as IMAGE or RGB24 what method should be used to convert the Bayer pattern of the camera to a suitable image Possible values are e BAYER 2BY2 COLOR Fastest e BAYER 3BY3 COLOR Fast Default e BAYER 3BY3GGRAD COLOR Best quality for realtime e BAYER 2PASSGRAD COLOR Best for captured images e BAYER 2PASSADAPT COLOR Best for captured images e BAYER VARGRAD COLOR Best for captured images e BAYER 2BY2 MONO Fastest converts to monochrome e BAYER 3BY3 MONO Best quality for rea time to mono e BAYER ADAPT MONO Best for captured images to mono e BAYER NO_CONVERSION No Bayer conversion The captured image is returned in an mxArray To arrange things in a bit more convenient way let s define Height
53. the open device array in which the device ID s from open devices are stored The device specific layer consists of a separate dll file for every type of device This dll file implements the commands and provides communication with the frame grabber libraries When studying the PixeLINK API we discovered that it differs more from the DT Frame Grabber SDK than we thought originally To deal with these differences it would either be necessary to move device specific code to the control layer which is not very nice or to move fgdevices to the device specific layer which would take a functionality out of the command layer and result in more overhead than benefits from the uniform user interface Considering this we decided in the end not to implement our original design Implementation of the PixeLINK Frame Grabber Interface Finally we implemented the PixeLINK Frame Grabber Interface plFGI in a way very similar to the original FGI system It is composed of several MEX functions which are callable from Matlab It supports functionality to open and close a device check whether a device is opened get and set a number of parameters and grab an image from the camera The function plDevices maintains the open device array in which the device ID s are stored Programming environment The updated FGI system is written in C for Matlab version 5 3 1 For compiling and linking we used the Mile buildall m written by our prede
54. the effect on overall capturing speed of the camera itself became apparent reducing the number of columns in the picture did not affect the capture time very much as the camera scans row by row Reducing the number of rows reduced the time needed for capturing accordingly As a last experiment the exposure time was variated Strangely enough capturing 100 images would take less time than 100 times the exposure time As there was not much time to take a closer look at these tests and do some more advanced testing this might be a good subject for future examination In Appendix E the test results are included 14 plFGI Technical Guide September 2002 2 Technical description of pIFGI This chapter describes the implementation of the plFGI the structure of which is similar to the original FGI system for the DataTranslation frame grabbers The system is composed of several MEX functions which are callable from Matlab It supports functionality to open and close a device check whether a device is opened get and set a number of parameters and grab an image from the camera This chapter starts with an overview of the structure of the plFGI after that follow descriptions of the individual source files For a functional specification from the user s point of view please refer to the first section of this document 21 Structure diagram The system is composed of several functions plIsOpen plGrab plGet plOpen plClose and plSet which c
55. the parameter name if mxIsChar prhs 1 2nd argument parametername should be a string mexPrintf plSet Wrong argument given n mexPrintf Second argument should be a string with the parametername Nn mexErrMsgTxt Mn buflen mxGetM prhs 1 mxGetN prhs 1 sizeof mxChar 1 parametername char mxCalloc buflen sizeof char mxGetString prhs 1 parametername buflen 2 arguments give possible values for this parameter if nrhs 2 plPrintPossibleValues parametername 3 or more arguments set value for this parameter else copy value arguments into an mxArray for i 2 i lt nrhs itt rhs i 2 struct mxArray tag prhs i call plSetValue to set these values plSetValue serialNumber parametername nrhs 2 rhs else nrhs 1 93 FGI and plFGI Report 2002 September 2002 ifdef endif PixeLINK Interface error n plSet Wrong number of arguments given n One or more arguments needed n LA handle or serial number n d parametername optional n n parametervalue optional Nn xample plSet handle plSet handle parametername or n A plSet handle parametername value n or plSet serialnumber plSet serialnumber parametername or n mexPrintf plSet serialnumber parametername value Nn mexErrMsgTxt Mn mexPrintf mexPrintf mexP
56. to be SubWindowSize Height SubWindowSize Decimation and define Width to be SubWindowSize Width SubWindowSize Decimation Then the image is returned as described below e For RAW images an mxArray of size Width Height filled with uint8 or uint16 is returned Whether the contents of the mxArray consist of uint8 or uint16 depends on the setting of the DataTransferSize parameter e For IMAGE images an mxArray of size Height Width 3 filled with uint8 is returned This is true for colour and black amp white images both are returned in the Matlab colour image format e For RGB24 format an array of size Height Width 3 1 of uint8 is returned plFGI User Manual September 2002 25 Notes on plGet and plSet Care should be taken on the following points e Not all combinations of parameter values are valid for example setting ImagerClocking to 0x00 16MHz no division while DataTransferSize is set to DATA_l16BIT_SIZE will result in an error message e Some values have a certain granularity br example setting SubWindowSize Height to 475 will result in a value of 472 being set e Parameter names are case sensitive e For a complete list of parameters refer to Appendix B of this document and to the PixeLINK documentation 26 Note onusing handles The handle obtained when using plOpen will of course not automatically be updated to reflect the recent settings of the device This is not important for the pIFGI fun
57. values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen if strcmp tmpstring PCS2112_NO_DECIMATION tmpU32 PCS2112_NO_DECIMATION else if stremp tmpstring PCS2112 DECIMATE BY 2 tmpU32 PCS2112 DECIMATE BY 2 else if strcemp tmpstring PCS2112 DECIMATE BY 4 tmpU32 PCS2112 DECIMATE BY 4 eise mexPrintf plSetValue Error setting SubWindow unknown value n mexPrintf uDecimation should be PCS2112 NO DECIMATION Mn mexPrintf PCS2112 DECIMATE BY 2 or PCS2112 DECIMATE BY 4 Mn mexErrMsgTxt Mn tmpU322 U32 mxGetScalar values 2 uStartColumn tmpU323 U32 mxGetScalar values 1 uStartRow tmpU324 U32 mxGetScalar values 4 uNumberColumns tmpU325 U32 mxGetScalar values 3 uNumberRows check whether the given values are within the correct range if tmpU322 tmpU324 gt PCS2112_MAX_WIDTH mexPrintf plSetValue Error setting SubWindow value too large n mexPrintf uStartColumn uNumberColumns should not exceed lu n PCS2112 MAX WIDTH mexErrMsgTxt Mn if tmpU323 tmpU325 gt PCS2112 MAX HEIGHT mexPrintf plSetValue Error setting SubWindow value too large n mexPrintf uStartRow uNumberRows should not exceed lu n PCS2112 MAN HEIGHT mexErrMsgTxt Mn if tmpU324 lt PCS2112_MIN_WIDTH
58. 002 September 2002 Preface In 1998 D J Oei and A Kapoerchan implemented a Frame Grabber Interface FGI for the people at the Center for Machine Perception CMP of the Czech Technical University in Prague This FGI provides a communication layer between Matlab and the Frame Grabber SDK of Data Translation s DT Open Layers family In 2000 R Heil and C L Wauters extended the FGI Now the people at CMP needed a similar interface for the PixeLINK Camera Also they wanted some bugs fixed in the existing FGI We have been working on this assignment as a training period for our study of Computer Science at Delft University of Technology from June until September 2002 During this period Assistant Professor Vladim r Smutny has supervised us The exchange between TUD and EVUT was organized by Professor V clav Hlav and Dr Drs Rothkrantz We would like to thank everyone who supported us during our project especially Professor Vaclav Hlav e Assistant Professor Vladimir Smutn and Miss Eva Matyskov from the Center for Machine Perception Czech Technical University in Prague and Dr Drs Rothkrantz from the Faculty of Information Technology and Systems Delft University of Technology Also we would like to thank D J Oei A Kapoerchan R Heil and C L Wauters for building FGI and providing documentation on that system so we did not have to invent everything ourselves Maarten Bakker and Lian Ien Oei September 2002 FGI and plFGI Report
59. 1 float exposureTimeValue 1 float gammaValue 1 U32 gpoValue 1 U32 greenGainValue 1 HARDWARE VERSION hardwareVersionValue U32 imagerChipIdValue 1 U32 imagerClockingValue 1 LPSTR imagerNameValue U32 imagerTypeValue 1 U32 monoGainValue 1 long previewWindowPosLeftValue 1 long previewWindowPosTopValue 1 U32 previewWindowSizeWidthValue 1 U32 previewWindowSizeHeightValue 1 U32 redGainValue 1 U32 saturationValue 1 U32 serialNumberValue 1 U32 softwareVersionValue 1 U32 subWindowDecimationValue 1 U32 subWindowStartColumnValue 1 U32 subWindowStartRowValue 1 U32 subWindowNumberColumnsValue 1 U32 subWindowNumberRowsValue 1 66 FGI and plFGI Report 2002 U32 subWindowPosStartColumnValue U32 subWindowPosStartRowValue U32 subWindowSizeDecimationValue U32 subWindowSizeWidthValue 1 U32 subWindowSizeHeightValue U32 timeoutValue 1 U32 videoModeValue 1 U32 grabColorConversionValue U32 grabOutputTypeValue 1 September 2002 a KOK RRR KKK KK Ck kc k Ck kCk k Ck k kc Ck kc k Ck k kc k Ck k k Ck k kc e A I ke x kx k x Get the devicelId J KCKCKCKCkCKCkCkCk kOk Ck Ck k k Ck k kc k Ck k kc k k kc k Ck k kc k Ck kc k Ck kc kc k Ck k k Ck k kc k k k ck k kck ck kokck ck kok ck ck ok ok ck k ke x kx kx fj rhs 0 mxCreateString get rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1
60. 16 to 24 bpp else if dataTransferSize DATA 16BIT SIZE amp amp imagerType PCS2112C_IMAGER Z 16 bit color y 81 FGI and plFGI Report 2002 September 2002 nRetValue PimMegaConvertColorl16BppTo24Bpp deviceId PU8 imgCapturePtr pixelWidth pixelHeight PU8 img24BppPtr grabColorConversion plError nRetValue converting raw colour 16 to 24 bpp else mexPrintf plGrab Error while postprocessing image n mexPrintf Unknown imager type or pixel depth n mexErrMsgTxt n return if grabOutputType IMAGE transpose the RGB24 array rgbrgbrgb to a MatLAB image array rrrgggbbb copy image into the matlab array in such a way that it is displayed correctly ZS for i 0 i lt pixelHeight i for j 0 j lt pixelWidth j PU8 imgOutPtr j 1 pixelHeight i 1 PU8 img24BppPtr i pixelWidth j 3 PU8 imgOutPtr j 1 pixelHeight i 1 pixelWidth pixelHeight PU8 img24BppPtr i pixelWidth j 3 1 PU8 imgOutPtr j 1 pixelHeight i 1 pixelWidth pixelHeight 2 PU8 img24BppPtr i pixelWidth j 3 2 else if grabOutputType RGB24 just copy the RGB24 image into the matlab array memcpy imgOutPtr img24BppPtr RGB24ImgSize else grabOutputType is neither RAW RGB24 nor IMAGE mexPrintf plGrab unknown value of GrabOu
61. 2 1 Command layer This layer provides a uniform Matlab command interface to any frame grabber In this layer almost no functionality is implemented It only deak with those parts of the functions which are common to all frame grabber interfaces All function calls like fgopen fgclose etc are passed through to fgcontrol in the control layer 5 2 2 Control layer The control layer consists of two functions fgcontrol and fgdevices fgcontrol passes all commands fgopen fgclose etc to the correct device specific interface DSI fgdevices maintains the open device array in which the device ID s from open devices are stored The Matlab mexLock function is used to protect the open device structure and the pointer s to the DSI from the Matlab commands clear mex or clear all F gcontrol Fgcontrol is the main MEX function that is called by the command layer functions with both the name of the task to be performed and the needed parameters as arguments It uses the device alias to determine which DSI has to be called If the DSI is called for the first time it loads the correct dll into memory Then it calls the DSI and passes the command to the device specific layer Fgdevices Fgdevices keeps track of opened frame grabbing devices Therefore it maintains the open device array in which a list of the aliases and handles of all open devices is kept If needed in the future this structure could be extended to contain other
62. 2002 September 2002 Abstract Introduction The people at the Center for Machine Perception of the Czech Technical University in Prague wanted to be able to grab images with a number of cameras from within the Matlab environment Therefore they needed an interface between Matlab and the frame grabbers they were using They already had such an interface called FGI for the frame grabbers of Data Translation s DT Open Layers family Our task was to update and bug fix this FGI and to build an interface for cameras from the PixeLINK family Background Matlab is a mathematical program which can be used to make analyses and computations on images grabbed with a frame grabber The Frame Grabber Interface provides a communication layer between Matlab and the frame grabber libraries It is composed of MEX files dynamically linked subroutines which can be called from Matlab as if they were built in functions The original Frame Grabber Interface The original FGI was a Matlab interface for Data Translation Frame Grabbers With this interface it was possible to grab pictures from a Data Translation camera into Matlab You could open and close a device check whether it has been opened or not grab an image into Matlab get and set various variables load a settings file and reset an opened device It was composed of separate MEX files for each function and an additional function mainfg which was used as a central place to store the device handles
63. 24 FGI and plFGI Report 2002 September 2002 containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGet is terminated After the serial number has been obtained it is checked whether the device is open by calling plDevices If not an error message is given and plGet is terminated If only one argument was given a list of parameter names is printed on the screen and plSet terminates If a second argument was given it is checked whether this is a string If not plSet is terminated with an appropriate error message If it is a string it is stored in the parametername variable Depending on whether 2 or 3 arguments were given plPrintPossiblevalues is called 2 parameters or plSetValue is called 3 arguments e Suggestions for improvement o Implementation of PimMegaSetOverla yCallBack o Implementation of PimMegaSetPreviewWindow o Implementation of PimMegaAutoExposure 6 4 7 plDevices Description plDevices maintains the open device array in which the device ID s handles to open devices are stored Also some settings which are not stored in the PixeLINK Camera API itself are stored in plDevices Since a rather detailed description of plDevices is given in paragraph 6 3 already here we only added the additional information on the internal working of the function
64. 9 8 3 1 HardwareVersion ProductID SerialNumber FirmwareVersion STRIN FpgaVersion STRIS ee ee dE EES Ox80 0x81 0x82 HmagmName SmNG O imeX me leese I DL PCS2112C IMAGER Ra E ND EE sees ee egen unen T PreviewWindow IM BARDEM Top LONG 200 SINT I ES PreviewWindowsSize Height U32 1024 wan u vm ssl FRE A E d 5 ah fuac us pe EE SE Ne Ux SctwaeVeson Um 11 4 SubWindow Decimation see table 4 table 4 StartRow StartColumn NumberRows 0 1024 NumberColumns NER SubWindowPos StartRow U32 StartColumn U32 SubWindowSize Decimation STRING see table NEM WE 4 Height U32 480 Width U32 VideoMode sie MODE VIDEO_MODE GrabColorConversion STRING see table 3 table3 N I means Not Implemented INE C CA m i 29 plFGI Technical Guide September 2002 GrabOutputType STRING RAWIMAGERGBM RAW Table 2 BAYER 2BY2 COLOR Table 3 PCS2112 NO DECIMATION Original resolution Default PCS2112 DECIMATE BY 2 Resolution 2 resulting height and width may be rounded down to accommodate the camera s decimation algorithms PCS2112 DECIMATE BY 4 Resolution 4 resulting height and width may be rounded down to accommod
65. AYER 2PASSADAPT COLOR else if strcemp tmpstring BAYER VARGRAD COLOR tmpU32 BAYER VARGRAD COLOR else if strcomp tmpstring BAYER 2BY2 MONO tmpU32 BAYER 2BY2 MONO else if strcomp tmpstring BAYER 3BY3 MONO tmpU32 BAYER 3BY3 MONO else if strcemp tmpstring BAYER ADAPT MONO tmpU32 BAYER ADAPT MONO else if strcomp tmpstring BAYER NO CONVERSION tmpU32 BAYER NO CONVERSION else mexPrintf plSetValue Error setting GrabColorConversion unknown value n plPrintPossibleValues GrabColorConversion mexErrMsgTxt Mn set the value rhs 0 mxCreateString setpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 U32 serialNumber 2 mxCreateString GrabColorConversion 3 mxCreateDoubleMatrix 1 1 mxREAL px 0 tmpU32 mexCallMATLAB 0 lhs 4 rhs plDevices else if stromp parametername GrabOutputType buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char else mxGetString values 0 tmpstring buflen check whether this is a known value if strcmp tmpstring RAW tmpU32 RAW else if strcemp tmpstring IMAGE tmpU32 IMAGE else if strcemp tmpstring RGB24 tmpU32 RGB24 else mexPrintf plSetValue Error setting GrabOutputType unknown value n plPrintPossibleValues GrabOutputType mex
66. AYER NO CONVERSION break default m mxCreateString Unknown value strcmp parametername GrabOutputType GrabOutputType is kept in plDevices and used in plGrab rhs 0 1 2 mxCreateString getpar mxCreateDoubleMatrix 1 1 mxREAL mxGetPr rhs 1 U32 serialNumber mxCreateString GrabOutputType mexCallMATLAB 1 lhs 3 rhs plDevices grabOutputTypeValue U32 mxGetScalar lhs 0 switch grabOutputTypeValue case RAW m mxCreateString RAW break case IMAGE m mxCreateString IMAGE break case RGB24 m mxCreateString RGB24 break default m mxCreateString Unknown value 74 FGI and plFGI Report 2002 else retu retu mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf mexPrintf ExposureTime n mexPrintf Gamma n mexPrintf Gpo n mexPrintf GreenGain n mexPrintf HardwareVersion n mexPrintf ImagerChipIdNn mexPrintf ImagerClocking n possible parameters are n mexPrintf ImagerName n DeviceID n BlueGain n CurrentFrameRate n DataTransferSize n ExposureMn mexPrintf ImagerTypeNn mexPrintf MonoGain Nn mexPrintf PreviewWindowPos Nn mexPrintf PreviewWindowSizeNn mexPrintf RedGain n mexPrintf Saturation n mexPrintf SerialNumber n mex
67. Array plhs int nrhs const mxArray prhs double y int buflen i t char task parName U32 serialnumber make sure plDevices stays in memory even when doing clear all or clear mex bays mexLock if nrhs gt 0 amp amp mxIsChar prhs 0 1st argument task should be a string allocate memory for task string and get the lst argument buflen mxGetM prhs 0 mxGetN prhs 0 sizeof mxChar 1 task char mxCalloc buflen sizeof char mxGetString prhs 0 task buflen if nrhs gt 2 if it exists the 2nd argument is the serial number 56 FGI and plFGI Report 2002 September 2002 if mxIsDouble prhs 1 mexPrintf Internal error call to plDevices failed n mexPrintf 2nd argument should be the serial number n mexErrMsgTxt n get the 2nd argument serial number serialnumber U32 mxGetScalar prhs 1 switch nrhs print has 1 argument task case 1 if strcmp task print for i 0 i lt deviceCount i mexPrintf Device nr d d d GrabColorConversion d GrabOutputType d n i deviceArray i serialNumber deviceArray i deviceID deviceArray i grabColorConversion deviceArray i grabOutputType else mexPrintf Internal error call to plDevices failed n mexPrintf Wrong number of arguments 1 is given or unknown task s task
68. B nlhs plhs nrhs prhs plDevices Description plDevices maintains the open device array in which the device ID s handles to open devices are stored Also some settings which cannot be stored in the PixeLINK Camera API are stored in plDevices Input prhs 0 string name of task to be performed print remove isopen get add getpar setpar prhs 1 U32 serial number of device Only for remove isopen get add getpar setpar prhs 2 int deviceID Only for add string name of the parameter Only for getpar setpar prhs 3 value of the parameter Only for setpar Output plhs 0 double 1 if device open 0 if closed Only for isopen int devicelD if open 1 if closed Only for get parameter value 1 if not found Only for getpar 6 3 1 The open device array plDevices maintains the open device array This is an array of structures of type struct U32 serialNumber int deviceID U32 grabColorConversion int grabOutputType In this array the device ID handle to the device and the parameters GrabColorConversion and GrabOutputType are stored for each open device The serial number of the device is used to uniquely identify the device This is the number returned by PimMegaGetSerialNumber which is called by plOpen immediately after initialising the device 6 3 2 MEX function plDevices is implemented as a MEX function because of two reasons First this makes it possible to use the functi
69. Ck k Ck Ck k kc k Ck kc kc k k kc k k kc kc k k k ck kokok ck kok ck ck kok ck k ke x x k x Input prhs 0 struct handle for the device or SECH yx U32 serial number of the device prhs 1 string name of the parameter optional Output plhs 0 struct handle for the device with 1 argument plhs 0 value of the given parameter with 2 arguments Syntax plGet serialnumber or plGet serialnumber parametername plGet handle or plGet handle parametername RR KKK KR RR Ck k kc k Ck k kc k k kc k Ck k kc K Ck k Ck Ck k kc k k kc k Ck k kc k k ko k k kok ck kokok ck kok ck kokok ck k ke xe I define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows headers include windows h include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib include plCreateDeviceHandle h include plGetValue h ifdef cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs mxArray serialNumberField U32 serialNumber 1 the serial number of the device mxArray lhs 1 rhs 2 to call fgdevices double px int isOpen 0 int buflen char
70. ECIMATION else if subWindowSizeDecimationValue PCS2112 DECIMATE BY 2 tmp mxCreateString PCS2112 DECIMATE BY 2 else if subWindowSizeDecimationValue PCS2112 DECIMATE BY 4 tmp mxCreateString PCS2112 DECIMATE BY 4 eise tmp mxCreateString Unknown value tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 subWindowSizeWidthValue tmp3 mxCreateDoubleMatrix 1 1 mxREAL tmppr3 mxGetPr tmp3 tmppr3 0 U32 subWindowSizeHeightValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported tmp3 mxCreateString Unsupported else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value tmp3 mxCreateString Could not get value mxSetField m 0 SubWindowSize Decimation tmp mxSetField m 0 SubWindowSize Width tmp2 mxSetField m 0 SubWindowSize Height tmp3 Timeout nRetValue PimMegaGetTimeout deviceld amp timeoutValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 timeoutValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 Timeout tmp Video Mode nRetValue PimMegaGetVideoMode deviceld amp
71. ER INTERFACE ee ee eee eee eene nete e noie 5 3 1 STRUCTURE OF THE ORIGINAL SYSTEM Ne 5 3 2 DESCRIPTION OF THE EXISTING FGI FUNCTIONS ecce 6 4 UPDATING FGI 2000 o eee ee eo ore KENNEN NENNEN ee KEES due o SE eese Panos e o DEUS 9 4 1 THE CLEEAR ALL BUG EE 9 4 2 ELOI A S INC A Dn EE Ae reote aedes Pee eri eere vet A 10 4 3 PROPER RELEASE OF THE DEVICE DRIVER S RESOURCES ccce eene 10 4 4 OTHER CHANGES TO THE ORIGINAL FGI SYSTEM pp 10 5 ORIGINAL DESIGN OF THE NEW SYSTEM soso nnn 11 5 1 OVERVIEW ENEE 11 5 2 DESCRIPTION OF THE THREE LAYERS pp 12 5 3 WHY WE DID NOT IMPLEMENT THIS SYSTEM pp 12 6 IMPLEMENTATION OF THE PIXELINK FRAME GRABBER INTERFACE 14 6 1 STRUGTUREORPLEGLS a a N S 14 6 2 SHORT DESCRIPTION OF THE PLFGI POUNCTIONS ecce e eene enne 15 6 3 IBEX 18 6 4 DETAILED DESCRIPTION OF THE PLFGI POMCTIONS cene eene 21 7 PROGRAMMING ENVIRONMENT oon 30 7 1 UPDATED FGI sven 30 EEC 30 7 3 TESTING Ee TM X 31 CONCLUSION ees eeo rore eno Poena eo eee e oor o aoa eoo ee eo va eos Ua udo Guo o Piae cuve a Tuo euo eoo ee oue o eo Un Pe Eo UE e e PET 33 TABLE OF FIGURES EE 34 BIBEIOGRAPLLY ckc ce ecee de UTE E rope o dn 35 Iv FGI and plFGI Report 2002 September 2002 APPENDIX A LIST OF UPDATES ss 36 APPENDIX B TOPICS FOR IMPROVEMENT ccccccsscccsssccsscccsssccscssccescceees 37 RI DATATRANSLATION EG ce irte eode ete ee resp ee eot ded
72. ErrMsgTxt Mn set the value rhs 0 mxCreateString setpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 U32 serialNumber rhs 2 mxCreateString GrabOutputType rhs 3 mxCreateDoubleMatrix 1 1 mxREAL px 0 tmpU32 mexCallMATLAB 0 lhs 4 rhs plDevices mexPrintf plSetValue Unknown parameter name n 106 FGI and plFGI Report 2002 September 2002 mexErrMsgTxt in 107 FGI and plFGI Report 2002 September 2002 D 17 plSetValue h ORK ROKK KK kk Ck Ck kOkCk kk k Ck k kc k Ck kc k Ck k kc k Ck k kc Ck kc k Ck k kc k k kc k Ck k kc k k kc k k k k ck kckock ck kok ck kokok ck he x fj Filename plSetValue h 5 Description Header file for plSetValue cpp As Authors L I Oei M A E Bakker Date 2002 08 06 Updates ORK KKK kk Ck kk Ck Ck kOkCk Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k k k ck kokok ck kok ck kokok ck k kx kx k x fj void plSetValue U32 serialNumber char parametername int nvalues mxArray values 108 FGI and plFGI Report 2002 September 2002 D 18 plTypes h ORK RK KK hh kOkCk Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k kok ck kokock ck kok ck kokok ck k k x x A x d Filename plTypes h 5 Description Header file containing type definitions As Authors M A E Bakker L I Oei Date 2002 08 06 XJ U
73. For every open device the following information is stored in the open device array The device s serial number the device s ID which is used by the PixeLINK API to identify the device the GrabColorConversion parameter and the GrabOutputType parameter Another global variable deviceCount is incremented every time a device is opened and decremented every time a device is closed thus counting the number of open devices First mexLock is called to make sure plDevices containing the open device array stays in memory Then it is checked whether any arguments are given and if the first argument is a text string If not the error message in the else part of the check is displayed and plDevices terminates If it is the first argument is stored in the task variable If there is a second argument it should always be the serial number of a device If it is not a number plDevices is terminated with an error message A case construction is used to make a first selection between the different tasks based on the number of arguments given For every number of arguments from 1 to 4 a different case exists the default case gives an error message Inside a case the different tasks are selected using an if else if construction together with strcmp When the strcmp fails an appropriate error message is given and plDevices terminates e largument print This task is mainly intended for testing and debugging purposes It prints all entries of the open device
74. FrameRate deviceld amp currentFrameRateValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 currentFrameRateValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 CurrentFrameRate tmp Data Transfer Size nRetValue PimMegaGetDataTransferSize deviceld amp dataTransferSizeValue if ApiSuccess nRetValue if dataTransferSizeValue DATA_8BIT_SIZE tmp mxCreateString DATA 8BIT SIZE else if dataTransferSizeValue DATA 16BIT SIZE tmp mxCreateString DATA 16BIT SIZE tmp mxCreateString Unknown value else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 DataTransferSize tmp Exposure nRetValue PimMegaGetExposure deviceld amp exposureValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 exposureValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 Exposure tmp Exposure Time nRetValue PimMegaGetExposureTime deviceld amp exposureTimeValue if ApiSuccess nRetValue 40
75. GHT less than should be less than or equal to 28 FGI and plFGI Report 2002 September 2002 6 4 12 plPrintPossibleValues plPrintPossibleValues is a subroutine linked to the plGet and plSet MEX functions When given the name string of a parameter it will use strcmp in an if else if construction to determine what should be printed Then a short description of the given parametername and its possible values is printed to the screen using mexPrintf 6 4 13 plTypes plTypes h contains all definitions that are used by the plFGI program Currently the only values that are defined here are those used to store the GrabOutputType variable 29 FGI and plFGI Report 2002 September 2002 7 Programming environment This chapter describes the programming environment which was used to create the updated FGI system and plFGI We used two different ways to build the MEX files for the FGI system and for pIFGI 7 1 Updated FGI system The updated FGI system was built in the same way as Ronald Heil and Chris Wauters did The Microsoft Visual C editor was only used for syntax highlighting For compiling and linking of the MEX files we used their Mfile buildall m For more information on this we refer to Matlab Interface For Data Translation Mach Frame grabbers User Manual amp Technical Guide We used Matlab version 5 3 1 with the Microsoft 6 0 compiler in C Program Files Microsoft Visual Studio 72 plFGl F
76. Mn pixelWidth U32 width decimation pixelHeight U32 height decimation get postprocessing method from stored configuration in plDevices needed with processed color images grabColorConversion plDevices getpar serialNumber GrabColorConversion rhs 0 mxCreateString getpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber rhs 2 mxCreateString GrabColorConversion mexCallMATLAB 1 lhs 3 rhs plDevices which Bayer conversion should be used grabColorConversion U32 mxGetScalar lhs 0 get raw output flag from stored configuration in plDevices grabOutputType plDevices getpar serialNumber GrabOutputType rhs 0 mxCreateString getpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber rhs 2 mxCreateString GrabOutputType mexCallMATLAB 1 lhs 3 rhs plDevices what sort of data should be returned to Matlab grabOutputType int mxGetScalar lhs 0 ROR KR KK KR RK I Ck kc kc k Ck k k Ck k kc K Ck kc e k kc k Ck kc k Ck k kc k k k ck k kok ck kokok ck kok ck ke k ke x kx kx d Allocate memory for the arrays in which the image is stored ROR KR KK KR I A k kc k Ck k kc k k kc k k ko k k kok ck kokok ck kok ck ke k ke x kx kx d calculate array properties 3 arrays are used caputure array array returne
77. Printf SoftwareVersion n mexPrintf SubWindowNn mexPrintf SubWindowPos Nn mexPrintf SubWindowSizeNn mexPrintf Timeout Wn mexPrintf VideoMode n mexPrintf GrabColorConversion n mexPrintf GrabOutputType n mexErrMsgTxt Mn rnArray 0 m rng 73 plGetValue Unknown parameter n September 2002 FGI and plFGI Report 2002 September 2002 D 9 plGetValue h Jak kk kk kk kOkCk Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k k kc k Ck k kc k Ck kc k kk k ck kokock ck kok ck kokok ck He kx A x fj Filename plGetValue h 5 Description Header file for plGetValue cpp As Authors L I Oei M A E Bakker Date 2002 08 06 Updates ORK ROKK KK KR kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k ck kok ck ck kok ck kokok ck k kb xe kx A x void plGetValue mxArray returnArray U32 serialNumber char parametername 16 FGI and plFGI Report 2002 September 2002 D 10 plGrab cpp ROKK RK KR kk Ck kk kk kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc K Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k k k ck kckok ck kok ck kokok ck k ke x x A x Filename plGrab cpp f Description Source code for the function plGrab x Authors M A E Bakker L I Oei ST maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 08 Updates Si ORK kk hh kOkCk E k kc k Ck kc kc k k kc k Ck k
78. RGB24 array must be transposed in order for matlab to display it properly This is done using two nested for loops Within the for loops the bytes for R G and B are copied to the appropriate locations in the matlab array All above mentioned case and if constructions contain a default case resulting in an appropriate error message when the distinguishing variable is not recognised e Suggestions for improvement o Implementation of the 5 other ways to call plGrab moviematrix plGrab handle imgmatrix imgmatrix moviematrix plGrab handle plGrab handle imgmatrix plGrab handle imgmatrix movie matrix plGrab handle imgmatrix moviematrix scaling factor o Addition of RGB48 format for 16 bit captures o Testing the plGrab function with a colour camera this should work o Loop optimalisations o Capture a RAW image directly into the matlab array 6 4 4 pllsOpen Description plIsOpen checks whether the device has been opened It returns 0 if the device has not been opened and 1 if it has been opened plisOpen is the MEX function for checking if certain PixeLINK device is open Vitana 2002 2 Appendix C 23 FGI and plFGI Report 2002 September 2002 First it is tested whether only 1 argument was given If not the else part of the check is executed resulting in an error message and the termination of plIsOpen by using the Matlab call mexErrMsgTxt The argument is either a serial number or a device handle structu
79. The system was composed of several functions closefg isopenfg openfg which could be called from within the Matlab environment Each of these functions called the appropriate function from the Frame Grabber SDK to perform the action needed Mainfg was used as a central place to store the device handles FGI and plFGI Report 2002 September 2002 3 2 Description of the existing FGI functions We give a short description of each of the existing FGI functions For a more detailed description we refer to Matlab Interface For Data Translation Mach Frame grabbers User Manual amp Technical Guide e Openfg Openfg di Devinfo openfg alias This function opens a DT frame grabber device The alias of the frame grabber The user is supposed to know this alias The function will return a structure with the device information m openfeDT3155 e Closefg SES closefg devinfo OR closefg alias This function closes a DT frame grabber device Input The device information structure devinfo or the alias alias of the opened frame grabber closefg m or closefg DT3155 These descriptions were copied from the FGI Report 2000 Heil Waut 2000 p 28 31 and slightly adjusted to represent the actual situation more accurately Oei Kap 1998 FGI and plFGI Report 2002 September 2002 e Grabfg DLL name Grabfg dll Syntax imgmatrix grabfe devinfo OR moviematrix grabfg devinfo imgm
80. X files in which the handles to open devices are stored are cleared from memory and the reference to any open devices is lost However the underlying Frame Grabber SDK still regards the device as being opened When one tried to reopen the device after using clear all an error message was generated instead This meant that the user had to close and restart Matlab continue working with the camera We solved this problem by calling the mexLock function from within the mainfg function mexLock locks a MEX file so that it cannot be cleared from memory This means that mainfg remains in memory even after calling clear all or clear mex which clears all MEX files from memory Since the device array in which the handles to open devices are stored is stored in mainfg the handles will remain available The following code example shows the use of the mexLock function in mainfg void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs int buflen int i double y char task char name bool found false Added by M Bakker 2002 06 24 12 35 Use mexLock to prevent clear all or clear mex from clearing mainfg dll from Matlab memory The deviceArray stays intact WS mexLock Code example 1 The use of the mexLock function in mainfg FGI and plFGI Report 2002 September 2002 42 Polishing The Data Translation Frame Grabber family has several different frame grabbers
81. Y2 MONO break tmp mxCreateString BAYER 3BY3 MONO break tmp mxCreateString BAYER ADAPT MONO break tmp mxCreateString BAYER NO CONVERSION break tmp mxCreateString Unknown value break mxSetField m 0 GrabColorConversion tmp GrabOutputType rhs 0 mxCreateString getpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber rhs 2 mxCreateString GrabOutputType mexCallMATLAB 1 lhs 3 rhs plDevices grabOutputType U32 mxGetScalar lhs 0 Switch grabOutputType case RAW tmp mxCreateString RAW break case IMAGE tmp mxCreateString IMAGE break case RGB24 tmp mxCreateString RGB24 break default tmp mxCreateString Unknown value break mxSetField m 0 GrabOutputType tmp return the device handle array returnArray 0 m return 54 FGI and plFGI Report 2002 September 2002 D 3 plCreateDeviceHandle h ORK ROKK KK KR Ck k kc k Ck kc k Ck k kc K Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k kc k k k k ck kokck ck kok ck kokok ck He x A x Filename plCreateDeviceHandle h Description Header file for plCreateDeviceHandle cpp As Authors L I Oei M A E Bakker Date 2002 07 31 Updates uA ROR KKK kk Ck kk Ck Ck kOkCk Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k Ck k ck kokok ck kok ck kokok c
82. ZE else mexPrintf plSetValue Error setting DataTransferSize unknown value n mexPrintf Valid values are DATA 8BIT SIZE and DATA 16BIT SIZE Wn mexErrMsgTxt Mn set the value nRetValue PimMegaSetDataTransferSize deviceld tmpU32 if plError nRetValue setting DataTransferSize mexErrMsgTxt Mn Exposure else if strcmp parametername Exposure tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt PCS2112_MAX_EXPOSURE mexPrintf plSetValue Error setting Exposure value too large n mexPrintf Exposure value should not exceed lu n PCS2112 MAX EXPOSURE mexErrMsgTxt Mn set the value nRetValue PimMegaSetExposure deviceld tmpU32 if plError nRetValue setting Exposure mexErrMsgTxt Mn ExposureTime else if strcmp parametername ExposureTime tmpfloat float mxGetScalar values 0 98 FGI and plFGI Report 2002 September 2002 tmpBOOL FALSE if nvalues gt 2 if a second value is given get the value buflen mxGetM values 1 mxGetN values 1 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 1 tmpstring buflen check whether this is a known value if stromp tmpstring FALSE tmpBOOL FALSE else if stremp tmpstring TRUE
83. almost the same as that of getpar but the parameter value is written not read e Suggestions for improvement In remove the inner for loop tries to copy one entry more than needed When having 32 camera s open this could result in a segfault The inner loop for condition should be t i t lt deviceCount 1 t 26 FGI and plFGI Report 2002 September 2002 6 4 8 plCreateDeviceHandle plCreateDeviceHandle is a subroutine which is linked to the plOpen and plGet MEX functions When given the serial number of a PixeLINK device it will create a Matlab struct matrix containing all the device s parameter names with their respective values This is the so called handle structure which is returned by plOpen and plGet After declaration of the necessary variables and structures the device ID for calling the PixeLINK API functions is obtained by calling plDevices Then for every parameter the appropriate API call is made to obtain its value If the API call returns the value for unsupported function the string Unsupported is stored as parameter value If the API returns any other error code the string Could not get value is stored as parameter value No other error checking is being done If everything went okay the value of the requested parameter is stored in a temporary variable by the PixeLINK API and immediately after that it is stored into the handle structure using mxSetField The only exception to this are the para
84. an be called from Matlab These functions call the appropriate functions from the PixeLINK Camera Application Programming Interface API plDevices maintains the open device array in which the device ID s handles to open devices are stored In the diagram below the relations between the internal and external plFGI functions are shown An arrow indicates that a function is called by another function The lt arrow between plDevices and the open device array means that data is exchanged in two directions open device array plPrintPossible Values plDevices plCreateDevice Handle plGetValue plSetValue PixeLINK Camera Application Programming Interface plIsOpen Figure 1 Structure of plFGI 15 plFGI Technical Guide September 2002 22 Description of plClose plClose is the MEX function which takes care of closing an opened PixeLINK device First it is tested whether one and only one argument was given using if nrhs 1 If not the else part is executed printing an error message with mexPrintf and exiting with mexErrMsgTxt If the argument is a device handle structure the device s serial number is extracted from it If the argument is a number this is treated as the serial number If the argument is something else again an error message will be shown and the function will exit Now it can be assumed that a serial number is present It is checked whether the device is registered a
85. array to the screen one device per line by using a for loop for i 0 to deviceCount 1 25 FGI and plFGI Report 2002 September 2002 e 2arguments remove isopen get This task removes a device from the open device list Using a for loop for i 0 to deviceCount 1 the given serial number is compared to every serial number in the open device array As soon as a matching entry is found a new for loop is entered for t 2 number of matching entry to deviceCount 1 to overwrite every entry from the matching entry up to the last entry with the entry immediately following it this goes wrong if the last entry is 31 see Suggestions for improvement After the inner for loop finishes deviceCount is decremented This task returns 0 if the device is not open 1 if it is open First the return value is set to 0 then a for loop for i 0 to deviceCount 1 is entered The given serial number is compared to every serial number in the open device array As soon as a matching entry is found the return value is set to 1 and the loop is left using a break statement This task returns the device ID for a given serial number It works the same way as isopen except that the return value is set to 1 and as soon as a matching entry is found the return value is set to the appropriate device ID e 3 arguments add getpar This task adds a new device to the open device array First it is checked whether there is still ro
86. at values of 255 and above will be interpreted as maximum white level by the Matlab image function To be able to view the image correctly use some scaling 32 Someexamples The following example will open a camera having serial number 75122 get the current value of the gamma correction parameter displaying it on the screen set the gamma correction parameter then get the new value of the gamma correction parameter displaying it on the screen then close the camera To have the parameter not display on the screen just put a behind the plGet lines plOpen 75122 plGet m Gamma LSet m Gamma 0 65 plGet m Gamma lClose m O Q o0us 10 plFGI User Manual September 2002 The following example will open a black amp white camera having serial number 75122 grab an image using the default settings 480 rows 640 columns amp bit raw image display it and then close the camera m plOpen 75122 im plGrab m colormap gray 255 image im plClose m The following example will open a colour camera having serial number 98765 set the image size to 200 rows 320 columns decimation factor 2 set the GrabOutputType set the GrabColorConversion and capture an image Then it will set the GrabColorconversion to another value and capture another image It will then close the camera display the first image wait for a key to be pressed then display the second image m plOpen 98765
87. ate the camera s decimation algorithms Table 4 30 plFGI Technical Guide September 2002 Appendix C Source file dependencies plClose plClose cpp plError cpp plError h plDevices cpp plTypes h plGet plGet cpp plCreateDeviceHandle cpp plGetValue cpp plError cpp plCreateDeviceHandle h plGetValue h plError h plTypes h plGrab plGrab cpp plError cpp plError h plTypes h pllsOpen plIsOpen cpp plOpen plOpen cpp plCreateDeviceHandle cpp plError cpp plCreateDeviceHandle h plError h plSet plSet cpp plPrintPossibleValues cpp plSetValue cpp plError cpp plPrintPossibleValues h plSetValue h plError h plTypes h Table 5 3l plFGI Technical Guide Appendix D Topics for improvement This is a full list of all topics for improvement on plFGI plGrab Implementation of the 5 other ways to call plGrab moviematrix plGrab handle imgmatrix imgmatrix moviematrix plGrab handle plGrab handle imgmatrix plGrab handle imgmatrix moviematrix plGrab handle imgmatrix moviematrix scaling factor plGrab Addition of RGB48 format for 16 bit captures plGrab Testing the plGrab function with a colour camera this should work plGrab Loop optimalisations plGrab Capture a RAW image directly into the left hand array plhs of the mexFunction plOpen Use plError after the call to PimMegaGetNumberDevices instead of non standard error code plSet Implementation of PimMegaSetOverlayCallBac
88. atrix OR imgmatrix moviematrix grabfg devinfo OR grabfg devinfo imgmatrix OR grabfg devinfo imgmatrix moviematrix OR grabfg devinfo imgmatrix moviematrix scaling factor Description This function grabs an image from an opened frame grabber device The user has to give the frame grabbers device information structure devinfo as input argument When used with the moviematrix argument a standard bitmap will be returned according to the Matlab movie format The scaling factor can be used for scaling down this bitmap Input The device information structure devinfo of an opened frame grabber device and optionally the pre allocated image matrix imgmatrix a movie matrix moviematrix and a scaling factor for movies The movie matrix has size m 1 and consists of doubles Calculate m as follows m 388 img height scaling factor img width scaling factor 8 The default value for the movie scaling factor is 2 Output If the input isn t valid or the frame grabber isn t able to grab an image some error message will be shown to the user If everything s okay it will return the grabbed image stored in a Matlab matrix imgmatrix The image is stored in transposed way To show the image correctly in Matlab you can use the accent on the imgmatrix to correct it image imgmatrix im grabfg m or im uint8 zeros 768 576 and grabfg m im Getfg DLL name Getfg dll Getfg devinfo OR getfg devinfo pa
89. ault The inner loop for condition should be t i t lt deviceCount 1 t e plCreateDeviceHandle Convert some of the if constructions to switch constructions for example the one used for SubWindowSize e plError The entire building of the string used in The device s API encountered can be moved within the following if result ApiSucces condition Function to check whether the camera is connected to the computer Reset function to set all parameters to their default value Demo M files Additional tests on the performance of pIFGI 37 FGI and plFGI Report 2002 September 2002 Appendix C Updated source code of FGI 2000 This is a part of the source of grabfg to show the changes to FGI 2000 which are described in paragraphs 4 3 Proper release of the device driver s resources and 4 4 Other changes to the origin al FGI ORK RK KK kk Ck Ck kOk Ck k k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck kc kc k Ck kc k Ck k kc k k k ck kckok ck kokock kokok kk ke e x kA amp x d Filename grabfg c NU Authors D J Oei A Kapoerchan Xx Date 10 July 1998 EET Last update by original authors 17 August 1998 NU Modified by R Heil C L Wauters 17 April 2000 ko Last update by R Heil C L Wauters 01 June 2000 xx Modified by L I Oei M A E Bakker Updates source cleaned up and properly indented 2002 07 02 destroy frame on errorexit 2002 07 03
90. bber SDK Data Translation Inc Marlboro HEIL RONALD amp WAUTERS CHRIS April June 2000 FGI Report 2000 Czech Technical University Prague amp University of Technology Delft THE MATHWORKS INC September 1998 Matlab Application Program Interface Reference Version 5 online version The MathWorks Inc THE MATHWORKS INC October 1998 Matlab Application Program Interface Guide Version 5 online version The MathWorks Inc OEI D J amp KAPOERCHAN A 1998 Modified by HEIL R amp WAUTERS C L June 2000 Matlab Interface For Data Translation Mach Frame grabbers User Manual amp Technical Guide Czech Technical University Czech Republic PLANZ ALAN C 1989 De kleine C gids Academic Service Schoonhoven VITANA CORPORATION 2000 2002 PixeLINK Megapixel FireWire Camera Developer s Manual Release 3 0 online version Vitana Corporation Ottawa Ontario Canada VITANA CORPORATION 2000 2002 PixeLINK Megapixel FireWire Camera User s Manual Release 3 0 online version Vitana Corporation Ottawa Ontario Canada 35 FGI and plFGI Report 2002 September 2002 Appendix A List of updates These are all updates made to FGI in June August 2002 Added a call to mexLock in mainfg so the handles to open devices will survive the clear all and clear mex commands Added the function destroyFrameOnErrorExit in grabfg to properly release the device driver s resources Cha
91. by calling plDevices If not an error message is given and plGet is terminated If the device is open it is determined whether one or two arguments were given when calling plGet If only one argument was given a call to the plCreateDeviceHandle subroutine is made and the result of that is returned If two arguments were given it is checked whether the second argument is a string If it is not an error message is given and plGet is terminated If it is the name of the parameter is copied into a string variable and the subroutine plGetValue is called and the result of that is returned 2 4 Description of plGrab plGrab is the MEX function that grabs a frame from the PixeLINK device and takes care of the required postprocessing before delivering it to Matlab Currently only one calling syntax is supported so it is checked whether there is exactly one input argument and one output argument If not the else part of the check is executed resulting in an error message and the termination of plGrab by using the Matlab call mexErrMsgTxt The input argument is either a serial number or a device handle structure If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGrab is terminated 16 plFGI Technical Guide Sep
92. c k Ck k kc Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k ck e ck ck kok ck kokok ck k ke kx k kx f define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows headers include windows h include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib include plCreateDeviceHandle h include plError h ifdef _ cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs PXL_RETURN_CODE nRetValue the return codes of the pixelink functions int isOpen 0 char deviceAlias PixeLINK tm 1394 Camera device alias the number of attached imaging devices with the specified alias U32 numberDevices 1 U32 index 0 index of the device default 0 bool found false HANDLE deviceId 0 the deviceId PimMegaInitialize returns U32 serialNumber 1 the serial number of the device U32 thisSerialNumber 1 int i 0 U32 availableSerialNumbers 32 to store all available serial numbers mxArray lhs 1 rhs 3 to call fgdevices double px prhs 0 should be the serial number if nrhs 1 amp amp mxIsDouble prhs 0
93. cause the file PimMegaApi dll could not be found 7 3 Testing During development frequent testing helped us to find bugs in plFGI After the program reached a stable working state we have run a few other tests in the limited time that was still available On suggestion of Assistant Professor Smutny it was tested how much time the capturing of multiple frames takes This could possibly be used as an indication of the quality of the code memory leaks and resources that are not released would have become apparent this way Also the performance of the code the PixeLINK API and the PixeLINK camera could be verified First some basic tests were performed showing that capturing the images resulted in a frame rate a bit lower than that of the demo application but that could be contributed to the 31 FGI and plFGI Report 2002 September 2002 overhead of calling functions from Matlab and the lack of loop optimalisation in plFGI When testing different resolutions the effect on overall capturing speed of the camera itself became apparent reducing the number of columns in the picture did not affect the capture time very much as the camera scans row by row Reducing the number of rows reduced the time needed for capturing accordingly As a last experiment the exposure time was variated Strangely enough capturing 100 images would take less time than 100 times the exposure time As we did not have much time to take a closer look at
94. cccccccssscccssscccscsccssccscsccsscccesscees 15 2 1 STRUCTURE DIAGRAM EE 15 2 2 DESCRIPTION OE PECEOSE EE 16 2 3 DESCRIPTION OF PIGET nnen a a a a aa ea Te tais 16 2 4 DESCRIPTION OF PLGRAB Ne 16 2 5 DESCRIPTION OF PISO N 0 a a a E AE E TERDA 18 2 6 DESCRIPTION OF PLOPEN pp 18 2 7 DESCRIPTION OF PLSET ss sl en ES 19 2 8 DESCRIPTION OF PLDEVICES Ne 20 2 9 DESCRIPTION OF PLCREATEDEVICEHANDDLE eee e e Renee ense rennen 24 2 10 DESCRIPTION OF PEBRROR 5 oe AANEREN cea ee pete Pope Tace EEN 24 2 11 DESCRIPTION OF PLGETYALUE eee eene eee eene estes es esr se sese ae 25 2 12 DESCRIPTION OF PISETVAL E ee eee eee earita e ese es re sese eus 25 2 13 DESCRIPTION OF PLPRINTPOSSIBLEV ALUES pp 26 2 14 DESCRIPTION OF PLTYPES pt 26 2 15 GENERAL HINTS ON MODIFYING RN 26 BIBEIOGRAPLHDNY 5 5 eoe ovra nee o e eo eoo ao ee ro eR e eoe ve soe e eror e re eeu e eno rPrE E ceo e eae eo Ve vaa Oe oe uou 27 plFGI User Manual amp Technical Guide September 2002 APPENDIX A PARAMETERS IN THE DEVICE S HANDLE STRUCTURE 28 APPENDIX B PARAMETERS FOR USE WITH GET AND SET 29 APPENDIX C SOURCE FILE DEPENDENCIES eere eene entente nnne otn nano 31 APPENDIX D TOPICS FOR IMPROVEMENT eese eren nennen nnne tn nasse tn naso n 32 plFGI User Manual September 2002 PARTI UsER MANUAL 1 General introduction This manual describes the Matlab interface pIFGI for V
95. ce prhs 1 2 string name of the parameter optional Output plhs 0 struct handle for the device with 1 input argument plhs 0 value s of the given parameter with 2 input arguments Examples m plGet m value plGet m Timeout m plGet 75122 value plGet 75122 Timeout 15 FGI and plFGI Report 2002 September 2002 e plGrab piGrab dll Syntax imagematrix plGrab handle or imagematrix plGrab serialnumber Description plGrab grabs a frame from the PixeLINK camera device and places it into an mxArray Input prhs 0 struct handle for the device or U32 serial number of the device plhs 0 mxArray grabbed frame Examples im plGrab m im plGrab 75122 o plisOpen pliIsOpen handle OrplIsOpen serialnumber Description plIsOpen checks whether the device has been opened It returns 0 if the device DM Ve o C o E T Input prhs 0 struct device handle or U32 serial number of the device Output plhs 0 double 0 if the device has not been opened 1 if the device has been opened Examples boolean plIsOpen m boolean plIsOpen 75122 e plOpen DLL name plOpen dll handle plOpen serialnumber Description plOpen opens a PixeLINK camera device and returns the device s handle If there is no camera with the given serial number a list of available serial numbers is printed prhs 0 int serial number of the device to be opened plhs 0 struct han
96. cessors For creating plFGI which is written in C we used Microsoft Visual C 6 0 with the libraries of Matlab version 6 1 and the PixeLINK Camera API Release 3 0 Conclusion The original FGI system is updated The clear dl bug is fixed and the device driver s resources are released properly More descriptive error messages are added and the documentation of grabfg is improved The polishing problem still remains unsolved though For the PixeLINK cameras plFGI is imple mented It supports most basic functionality to open and close a device check whether a device is opened get and set a number of parameters and grab an image from the camera Unlike the original FGI system it only provides 1 way to call plGrab instead of the 6 ways to call grabfg Also it has no reset function because the PixeLINK API does not provide this A full list of topics for improvement is given in Appendix B FGI and plFGI Report 2002 September 2002 Index PREFACE a vo eese ove EE EE ge GE I ABSTRAC E 0 ocs va niero oies stessa iee ea s ioeo e Seeus o aaau resesi a ooa ra esio soies II E INTRODUCTIQN eret ee ENER NENNEN 1 2 JBACKGROUND 5 5 Segengtdee eege L en ee ed Se eege Eed 2 2 1 OVERVIEW CH 2 2 2 MATLAB E EE 2 2 3 DATA TRANSLATION PRAMEOGRARBERS 2 2 4 PIXELINK GAMERAS iiie octies a ee ewes i De trie oe eee a vete i e cesi rre Se 3 3 THE ORIGINAL FRAME GRABB
97. ctions as they only use non settable parameters from the handle When you want to view the most recent settings please use plOpen or plGet to obtain the most recent information It is even possible to make use of the construction m piGet m to update the handle to reflect changed settings if one wants to plFGI User Manual September 2002 3 Working with pIFGI 3 1 Getting started To be able to use pIFGI functions Matlab should be able to find and load the right files First make sure the PixeLINK API library file PimMegaApi dll is in a directory that is in the Windows path If it is not the following error message will occur whenever you try to use a pIFGI function Unable to load mex file g fgi bin plOpen dll The specified module could not be found 2 Invalid MEX file This can be quite confusing as it doesn t directly point to the actual cause of the error Also Matlab should be able to find the plFGI executable files If the pIFGI distribution is stored on the network path Y Software pIFGI for example the following commands should be typed into the Matlab command window System dependent RemotePathPolicy Reload System dependent RemoteCWDPolicy Reload addpath Y NsoftwareNplFGI bin To view black and white RAW images with the Matlab image function make sure the right colour map is set by typing colormap gray 255 When viewing raw images in 16 bit format it should be taken into consideration th
98. d ch result case OLC STS NORMAL case OLC STS BUSY Frameld break mexPrintf Still busy with acquisition Wn mexPrintf Failed to destroy allocated resources while recovering from the error displayed below n break case OLC STS INVALIDFRAMEHANDLE mexPrintf Invalid frame handle n case OLC STS FRAMENOTALLOCATED case OLC STS NONOLMSG mexPrintf Failed to destroy allocated resources while recovering from the error displayed below n break mexPrintf Frame not allocated Anni mexPrintf Failed to destroy allocated resources while recovering from the error displayed below n break mexPrintf Unsupported or unknown message passed to the device driver n mexPrintf Failed to destroy allocated 38 a MA M FGI and plFGI Report 2002 case case case case case case case case case case case OLC STS FRAMEISMAPPED default return OLC STS BUSY OLC_STS_SYSERROR OLC_STS_TIMEOUT OLC_STS_FIFO_OVERFLOW OLC_STS_FIELD_OVERFLOW OLC_STS_INVALIDFRAMEHANDLE DLC STS CLAMP DLC STS VERTICALINC OLC_STS_FIRSTACTPIX OLC_STS_ACTPIXCOUNT resources while September 2002 recovering from the error displayed below n break mexPrintf Cannot destroy a frame that is still mapped in mexPrintf Failed to destroy allocated resources while recovering from the error displayed below n break mexPrin
99. d plGet is terminated After the serial number has been obtained it is checked whether the device is open by calling plDevices The result of the call to plDevices is stored in the return array of plIsOpen 26 Description of plOpen plOpen is the MEX function which takes care of opening a PixeLINK device for use with the other pIFGI functions First it is tested whether the input argument is a number if it is not the function terminates printing an appropriate error message using mexErrMsgTxt Then it is Vitana 2002 2 Appendix C 18 plFGI Technical Guide September 2002 checked whether the device is open by calling plDevices If the device is already open the else part of the if construction is executed printing a warning message then calling plCreateDeviceHandle and returning the handle If the device was not open a call to PimMegaGetNumberDevices is made to get the amount of available devices When no devices are attached plOpen exits with an appropriate error message When one or more devices are attached a for loop is entered to open every device store the serial number in the array of available serial numbers check if the serial number matches the requested serial number then close it and loop If the serial number matches the requested serial number the variable found is set to true and the loop is exited by using a break statement If found is not true the array containing all available serial numbers is printed to
100. d by the pixelink camera size pixelWidth iE pixelHeight matlab array array returned to matlab size depends on postprocessing RGB24 array array in which the output of the PimMegaConvert function is stored not with raw images size array used to build the Matlab array with mxCreateNumericArray Gaim number of dimensions of the Matlab array switch grabOutputType case RAW raw output image is returned to matlab exactly the way it is captured matlab array should be pixelWidth pixelHeight for both colour and monochrome x size int mxCalloc 2 sizeof int size 0 pixelWidth size 1l pixelHeight dim 2 Raw image array has 2 dimensions break case IMAGE 19 FGI and plFGI Report 2002 September 2002 processed output image is processed before it is returned to matlab matlab array should be 3 pixelWidth pixelHeight x Size int mxCalloc 3 sizeof int size 0 pixelHeight size 1 pixelWidth size 2 3 dim 3 RGB image array has 3 dimensions break case RGB24 RGB24 output image is returned as a consequent piece of memory of size 3 pixelWidth pixelHeight 7 size int mxCalloc 2 sizeof int Size 0 pixelWidth pixelHeight 3 size 1 1 dim 2 RGB image array has 2 dimensions break default mexPrintf plGrab unknown GrabOutputType should be RAW IMAGE or
101. device information for the open device It provides functionality for manipulating the open device array and getting information stored in the array Fgdevices is called from control layer as well as the device specific layer 5 2 3 Device specific layer This layer consists of a separate dll file for every type of device one dll for DT grabbers one for Pixelink etc This dll file is composed of a control function which is called by fgcontrol and several other functions which implement the different top layer calls fgopen fgclose etc When the control function is called by fgcontrol Pippen PICs ee it passes the command to the correct function e g plOpen which in tum implements the command and provides communication with the PixeLINK Camera API frame grabber libraries Figure 8 Implementation of a DSI 12 FGI and plFGI Report 2002 September 2002 53 Whywe did not implement this system We had already implemented most of the command layer and control layer functions when we started studying the PixeLINK Camera Application Programming Interface API more closely Then we discovered that unlike the DataTranslation Frame Grabber SDK the PixeLINK API doesn t use a unique device alias to identify a specific camera Also handles to open devices device ID s are stored in a slightly different way Implementing this in our original design of the new system would mean that fgdevices would have to be able to treat diffe
102. dle plOpen serialnumber Description plOpen opens a PixeLINK camera device and returns the device s handle If there is no camera with the given serial number a list of available serial numbers is printed Input prhs 0 int serial number of the device to be opened Remarks It will be verified whether the input is a number If it is a valid serial number plOpen will try to open the camera device and return a handle structure If the camera is already open a warning will be printed and the handle structure will be returned If the input was not a number or the camera could not be opened an error message is printed If there is no camera with the given serial number a list of available serial numbers is printed plhs 0 struct handle for the device plFGI User Manual e plSet September 2002 SES W WW NN ul plSet handle plSet handle parametername plSet handle parametername value plSet serialnumber plSet serialnumber parametername Or plSet serialnumber parametername value plSet sets the value of a given parameter When 1 argument is given a list of all possible parameters is given When 2 arguments are given the possible values of the given parameter are given When called with 3 or more arguments the device s parameter given in the second argument will be set to the value s given in the other argument s prhs 0 struct handle for the device or int serial number
103. dle for the device m plopen 75122 16 FGI and plFGI Report 2002 September 2002 o plSet DLL name plSet dll Syntax plSet handle plSet handle parametername plSet handle parametername value plSet serialnumber plSet serialnumber parametername or plSet serialnumber parametername value Description plSet sets the value of a given parameter When 1 argument is given a list of all possible parameters is given When 2 arguments are given the possible values of the given parameters are given When called with 3 or more arguments the device s parameter given in the second argument will be set to the value s given in the other argument s Input prhs 0 struct handle for the device or int serial number of the device prhs 1 string name of the parameter optional prhs 2 n value of the given parameter optional Output A list of all possible parameters is printed on the screen with 1 input argument NEN The possible values of the parameter are printed on the screen with 2 input arguments Examples plSet m plSet m Timeout plSet m Timeout value plSet 75122 plSet 75122 Timeout plSet 75122 Timeout 1024 plSet m SubWindowSize PCS2112 NO DECIMATION 480 640 17 FGI and plFGI Report 2002 September 2002 6 3 plDevices plDevices is an internal function which is called by the other functions DLL name plDevices dll mexCallMATLA
104. done using two nested for loops Within the for loops the bytes for R G and B are copied to the appropriate locations in the matlab array All above mentioned case and if constructions contain a default case resulting in an appropriate error message when the distinguishing variable is not recognised e Suggestions for improvement o Implementation of the 5 other ways to call plGrab moviematrix plGrab handle imgmatrix imgmatrix moviematrix plGrab handle plGrab handle imgmatrix plGrab handle imgmatrix moviematrix plGrab handle imgmatrix moviematrix scaling factor Addition of RGB48 format for 16 bit captures Testing the plGrab function with a colour camera this should work Loop optimalisations Capture a RAW image directly into the matlab array OO000 25 Description of pllsOpen plisOpen is the MEX function for checking if certain PixeLINK device is open First it is tested whether only 1 argument was given If not the else part of the check is executed resulting in an error message and the termination of plIsOpen by using the Matlab call mexErrMsgTxt The argument is either a serial number or a device handle structure If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given an
105. e PCS2112 NO DECIMATION i 1 100 y plgrab m end t toc gt gt tid for E e 52 7800 gt gt plset m ExposureTime 1 gt gt tic for ee 51 3500 gt gt plget m ans DeviceID BlueGain CurrentFrameRate DataTransferSize Exposure ExposureTime Gamma Gpo GreenGain HardwareVersion ProductID HardwareVersion SerialNumber HardwareVersion FirmwareVersion HardwareVersion FpgaVersion ImagerChipId ImagerClocking ImagerName ImagerType MonoGain PreviewWindowPos Top PreviewWindowPos Left PreviewWindowSize Height i 1 100 y plgrab m end t toc i 1 100 y plgrab m end t toc 512 640 256 640 1024 640 1024 320 256106896 Unsupported Could not get value DATA 8BIT SIZE 1028 1 0400 1 Ore Unsupported PL A630 Series Monochrome EC Module WE Up Tet Vue 805306368 0x01 External 16Mhz Division by 2 Imager0 PCS2112M IMAGER Monochrome Camera 0 Could not get value Could not get value Could not get value 33 plFGI Technical Guide PreviewWindowSize Width RedGain Saturation SerialNumber SoftwareVersion SubWindow Decimation SubWindow StartRow SubWindow StartColumn SubWindow NumberRows SubWindow NumberColumns SubWindowPos StartRow SubWindowPos StartColumn SubWindowSize Decimation SubWindowSize Height SubWindowSize Width Timeout ode GrabColorConversion GrabOutputType Video September 2002 Could
106. e getting DataTransferSize value mexErrMsgTxt Mn if dataTransferSizeValue DATA_8BIT_SIZE m mxCreateString DATA 8BIT SIZE else if dataTransferSizeValue DATA_16BIT_SIZE 67 FGI and plFGI Report 2002 September 2002 m mxCreateString DATA 16BIT SIZE m mxCreateString Unknown value else if strcomp parametername Exposure Exposure nRetValue PimMegaGetExposure deviceld amp exposureValue if plError nRetValue getting Exposure value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 exposureValue else if stromp parametername ExposureTime Exposure Time nRetValue PimMegaGetExposureTime deviceld amp exposureTimeValue if plError nRetValue getting ExposureTime value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 exposureTimeValue else if stromp parametername Gamma Gamma nRetValue PimMegaGetGamma deviceld amp gammaValue if plError nRetValue getting Gamma value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 gammaValue else if strcmp parametername Gpo Gpo nRetValue PimMegaGetGpo deviceld amp gpoValue if plError nRetValue getting BlueGain value mexErrMsgTxt Mn
107. e store the serial number in the array of available serial numbers check if the serial number matches the requested serial number then close it and loop If the serial number matches the requested serial number the variable found is set to true and the loop is exited by using a break statement If found is not true the array containing all available serial numbers is printed to the screen and the function is terminated using mexErrMsgTxt Finally the open device array is updated by calling plDevices e Suggestions for improvement Use plError after the call to PimMegaGetNumberDevices instead of non standard error code 6 4 6 plSet Description plSet sets the value of a given parameter When 1 argument is given a list of all possible parameters is given When 2 arguments are given the possible values of the given parameters are given When called with 3 or more arguments the device s parameter given in the second argument will be set to the value s given in the other argument s plSet is the MEX function used to change the parameter settings of a PixeLINK device First it is checked whether any arguments are given if not an appropriate error message is printed to the screen using mexPrintf and the plSet is terminated using mexErrMsgTxt If one or more arguments were given the first argument should be either a handle structure or a serial number If it is a double it is stored in the serialNumber variable If it 1s a struct
108. e plError h include plTypes h include plPrintPossibleValues h void plSetValue U32 serialNumber char parametername int nvalues mxArray values m mxArray structure to be returned as device handle mxArray lhs 1 rhs 4 double px HANDLE deviceld variable for receiving the error codes the pixelink api functions return PXL RETURN CODE nRetValue int buflen i U32 tmpU32 tmpU322 tmpU323 tmpU324 tmpU325 char tmpstring float tmpfloat BOOL tmpBOOL KOK KR KK kk Ck kk k Ck kc kc Ck k kc k Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k kok ck kokock ck kok ck ck kok k k ke x kx kx fj ed Get the devicelId J KCKCKCKCk KCkCkCk kOk Ck k kc k Ck kk k Ck kc k Ck k kc k Ck k kc Ck kc k Ck k kc k Ck k k Ck kck k Ck k ck k kok ck e ck ck kok ck ck ok kk k ke x kx A x fj rhs 0 mxCreateString get rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices deviceld HANDLE int mxGetScalar lhs 0 KOK KR KK KK KR Eh kCk k Ck k kc k Ck kc k Ck k kc k Ck k k Ck k kc k A ck kok ck ck ok ok k k ke x kx k k al Check whether the correct parameters are given ZA J KCKCKCKCk KOkCkCkCkCk Ck Ck k Eh kCk k Ck k kc Ck k k Ck k kc k Ck kc k Ck k kc k Ck k ck k A e ck ck kok ck ck Ee dk ke x kx kx fj U32 if strcemp parametername BlueGain stromp parametername Exposure strcmp param
109. e eel eds 37 B 2 PIXELINK EG eb a a a A n a a na eiia 37 APPENDIX C UPDATED SOURCE CODE OF FGI 2000 eere enne 38 APPENDIX D SOURCE CODE OF PLFG I eene eee e eee ee eene eene KEE net ee note 42 1D A GO ef e EE ON 42 D 2 PLCREATEDEVICEHANDLE CPP 000 44 D 3 PLCREATEDEVICEHANDLE H Ne 55 D 4 5 PEDEVICES CPP so ad e dee deep eet A e edere amp 56 D 5 3BEERROR CPPZ A sieut tede ge cr d e IE E RID acces 61 DG ERR RE 63 DL PPGETOCDPAG mb De de eo teer derer Pete a endubede beats Pera peru 64 ID S NE RE E A EUM o D 66 D 9 PEGET VALUE Ta ob en a ne dn aaar ea ae aaa Eea 76 IPAE PEGRAB EES TI B11 SPEISOPEN CPR a me a ed de a ed a OENE EEES 83 ERT PPE OPEN E 2 2 0 en RE A a A a ese ee 85 D 13 PLPRINTPOSSIBLEV ALUES CPP Ne 88 D 14 PLPRINTPOSSIBLEV ALUES H va ea a e a a aai 91 DAS PESE CRP en a en a 92 E PESETVALUE GCPP Eee 95 TT PESETVAEUE B irre Ee EE ares tee ro tee eee ee eeh aud 108 DES uP I VPES He to ed a a ce ee 109 APPENDIX E TEST RESULTS ssn 110 FGI and plFGI Report 2002 September 2002 1 Introduction The people at the Center for Machine Perception of the Czech Technical University in Prague wanted to be able to grab pictures with a number of cameras from within the Matlab environment In this environment they can make analyses and computations on the images Therefore they needed an interface between Matlab and the frame g
110. e plGet gets the handle of the camera or the value of a camera or image processing parameter e plGrab grabs an image from a PixeLINK camera e plIsOpen checks if a PixeLINK camera is already open e plOpen opens a PixeLINK camera or returns its handle if it was already open e plSet sets the value of a camera or image processing parameter or shows the possible parameters or values We give a short description of each of the plFGI functions which are callable from Matlab In paragraph 6 3 we describe plDevices which is used as an internal function called by the other functions In paragraph 6 4 a more detailed description of the plFGI functions is given In the descriptions below prhs 0 is used to indicate the first input parameter prhs 1 for the second input parameter prhs 2 for the third etcetera Similarly plhs 0 is used to indicate the first return value of the MEX function e plClose DLL name plClose dll plClose closes a PixeLINK camera device Input prhs 0 struct handle of the device or U32 serial number of the device Output Examples plClose m plClose 75122 e plGet DLL name plGet handle plGet handle parametername plGet serialnumber OrplGet serialnumber parametername Description plGet returns the device s up to date handle if 1 argument is given or returns DU exies egsenpmmeeri2apmemsaegeen o o n Input prhs 0 struct handle for the device or U32 serial number of the devi
111. eateString Unknown value else if strcmp parametername ImagerName Imager Name imagerNameValue char mxCalloc 81 sizeof char nRetValue PimMegaGetImagerName devicelId imagerNameValue if plError nRetValue getting ImagerName value mexErrMsgTxt Nn m mxCreateString imagerNameValue else if stromp parametername ImagerType Imager Type nRetValue PimMegaGetImagerType deviceld amp imagerTypeValue if plError nRetValue getting ImagerType value mexErrMsgTxt Mn if imagerTypeValue PCS2112M_IMAGER m mxCreateString PCS2112M IMAGER Monochrome Camera else if imagerTypeValue PCS2112C_IMAGER m mxCreateString PCS2112C IMAGER Color Camera else m mxCreateString Unknown value else if strcmp parametername MonoGain Mono Gain nRetValue PimMegaGetMonoGain deviceld amp monoGainValue if plError nRetValue getting MonoGain value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 monoGainValue else if stromp parametername PreviewWindowPos Preview Window Pos nRetValue PimMegaGetPreviewWindowPos deviceId amp previewWindowPosLeftValue amp previewWindowPosTopValue if plError nRetValue getting PreviewWindowPos value mexErrMsgTxt Mn tmp mxCreateDoubleMatri
112. ect to external shutters etcetera 1 3 Short description of pIFGI The plFGI is a simple interface for grabbing images directly from the PixeLINK camera into a Matlab mxArray It follows the concept of the existing Data Translation FGI closely Several picture formats are supported Currently the interface features grabbing an image from a videostream and changing most settings of the camera To accomplish this functionality of the PixeLINK API library which is supplied with the camera is used plFGI User Manual September 2002 1 4 Hardware and software requirements To use this interface the following is required newer versions may also work older versions probably won t give good results A Vitana PixeLINK PL A6xx series camera PixeLINK drivers API version 3 0 A PC with at least a Pentium II processor 64MB of RAM and a IEEE 1394 FireWire interface MS Windows 98SE Windows ME Windows 2000 SP1 or Windows XP Mathworks Matlab 6 plFGI User Manual September 2002 2 Introduction to pIFGI In this chapter some background information and a description of the pIFGI functions are given 21 About data types The following Matlab data types are used when working with the pIFGI e string A vector of which the components are ASCII codes Used with the pIFGI for passing names of camera parameters to plGet and plSet e double The default data type used by Matlab to store numbers in the double precision floating p
113. eenGain tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt PCS2112_MAX_GAIN mexPrintf plSetValue Error setting GreenGain value too large n mexPrintf GreenGain value should not exceed lu n PCS2112 MAX GAIN mexErrMsgTxt Mn set the value nRetValue PimMegaSetGreenGain deviceld tmpU32 if plError nRetValue setting GreenGain mexErrMsgTxt Mn ImagerClocking else if stromp parametername ImagerClocking tmpU32 0x00 buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen check whether this is a known value if strcmp tmpstring 0x00 tmpU32 0x00 else if strcomp tmpstring 0x01 tmpU32 0x01 else if stremp tmpstring 0x02 tmpU32 0x02 else if strcemp tmpstring 0x80 tmpU32 0x80 else if strcmp tmpstring 0x81 tmpU32 0x81 else if strcemp tmpstring 0x82 tmpU32 0x82 lse mexPrintf plSetValue Error setting ImagerClocking unknown value n mexPrintf Valid values are 0x00 OxO1 0x02 0x80 0x81 and 0x82 Nn mexErrMsgTxt Mn set the value nRetValue PimMegaSetImagerClocking deviceld tmpU32 100 FGI and plFGI Report 2002 Se
114. endif on 87 September 2002 MxXREAL IAXREAL device already open return structure serialNumber amp amp mxIsDouble prhs 0 Wrong arguments given lDevices warning then proceed to return the returning device handle Anni KI Nn One argument needed serial FGI and plFGI Report 2002 September 2002 D 13 plPrintPossibleValues cpp ORK RK KK kk kk kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc K Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k k kc k k k ck kokok ck kok ck kokok ck k ke xe x A x fj Filename plPrintPossibleValues cpp f Description Source code for plPrintPossibleValues Authors M A E Bakker L I Oei ST maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 09 K7 Updates avd ORK KK KK RR Ck k kc k Ck kc k Ck k kc k Ck k kc K Ck kc k Ck k kc k k kc k Ck k kc K Ck k kc k k kc k kokok ck kok ck kokok ck he d plPrintPossibleValues prints the possible values for parametername called when plSet gets 2 arguments e ROKK RK KK kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc K Ck k kc Kk Ck k Ck Ck k kc k Ck kc kCk k kc k k kc k k e ck kok ck ck kok I ke xe x rd Input parametername string name of the parameter Output D I Syntax plPrintPossibleValues parametername b s ORK kk RR E I A k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k k ck k I ck ck kok ck k ke xe kx kx d include lt windo
115. ending on the number of input channels DT Frame Grabbers are Open Layer devices For the Open Layers family Data Translation provides a Software Development Kit SDK for Microsoft Windows platforms This SDK is composed of commands which are callable from higher level languages such as C For many types of frame grabbers Data Translation also provides additional function libraries with functions that are specific for that type of frame grabber The SDK and function libraries together form the library layer through which the application layer can communicate with the device interface layer The device interface layer handles the interface between the API and the board DT Open Layers architecture Application Layer Application Space i E Layer Device Interface Layer Figure 3 DT Open Layers architecture FGI and pIFGI Report 2002 September 2002 2 4 PixeLINK Cameras The PixeLINK Megapixel FireWire IEEE 1394 Cameras are firewire cameras with a CMOS image sensor and integrated image processing electronics The camera can be used both as a frame grabber and a source of live images A firewire adapter card is needed to connect the camera to the computer Figure 4 Megapixel FireWire Cameras The PixeLINK Camera Application Programming Interface API can be used to develop new software applications for the PixeLINK Cameras It is a dynamic link library PimMegaApi dll which provides
116. erial number of the device mxArray lhs 1 rhs 3 to call fgdevices double px int isOpen 0 HANDLE deviceld the deviceId PimMegaInitialize returns U32 currentVideoMode to get the current video mode if currentVideoMode VIDEO MODE set VideoMode to VIDEO MODE image properties U32 imagerType ImagerType monochrome or color U32 dataTransferSize DataTransferSize DATA 8BIT SIZE or DATA 16BIT SIZE U32 decimation width height U32 grabColorConversion the Bayer conversion to be used int grabOutputType what sort of data should be returned to Matlab int size array used to build the Matlab array with mxCreateNumericArray int dim number of dimensions of the Matlab array U32 rawImgSize rawlImgByteSize RGB24ImgSize void imgOutPtr NULL pointer to the mxArray in which the image should be stored matlab array void imgCapturePtr NULL pointer to the capture array for conversion from Bayer or I to RGB24 void img24BppPtr NULL pointer to capture array for conversion from RGB24 to MatLAB image U32 pixelWidth pixelHeight T FGI and plFGI Report 2002 September 2002 ROKK KK KK Ck Ck kOk Ck Ck kCk Ck kCk k Ck k kc k Ck kc k Ck k kc k Ck kCk CK k kc k k kc k Ck k kc k k k ck k kok ck kokok ck kok ck ke k ke x kx kx d yx Get the serialNumber and deviceId Jak kk kk Ck Ck kOk Ck Ck kCk Ck k kc k Ck kc kc k k
117. ersion and GrabOutputType prhs O tring print e remove plDevices remove serialnumber Input prhs 0 string remove pe prhs 1 U32 serialnumber plDevices remove 75122 e isopen plDevices isopen serialnumber checks whether a device has been opened Input prhs 0 string isopen prhs 1 U32 serialnumber Output plhs 0 double 1 if the device is open 0 if the device is closed plDevices isopen 75122 19 FGI and plFGI Report 2002 September 2002 get deviceld plDevices get serialnumber returns the device ID handle to the device of a camera Input prhs 0 string get prhs 1 U32 serialnumber Output plhs 0 int deviceID if the device is open 1 if the device is closed plDevices remove 75122 plDevices add serialnumber deviceID adds a device to the open device array Input prhs 0 string add prhs 1 2 U32 serialnumber prhs 2 int deviceID Output plDevices add 75122 256085040 e getpar Syntax parameterValue plDevices getpar serialnumber parametername returns the value of the specified parameter Input prhs 0 string getpar prhs 1 2 U32 serialnumber prhs 2 string parametername plhs 0 value of the specified parameter Example parameterValue plDevices getpar 75122 GrabOutputType e setpar S
118. etername GreenGain strcmp Parametername MonoGain strcmp parametername RedGain strcmp parametername Saturation strcmp parametername Timeout if nvalues 1 amp amp mxIsDouble values 0 mexPrintf plSetValue wrong number of parameters given or wrong 95 FGI and plFGI Report 2002 September 2002 parametertype n mexPrintf s expects 1 parameter of type U32 n parametername mexErrMsgTxt Mn string else if strcmp parametername DataTransferSize strcmp parametername ImagerClocking stromp parametername ImagerName stromp parametername PreviewColorConversion strcmp parametername VideoMode strcmp parametername GrabColorConversion strcmp parametername GrabOutputType if nvalues 1 amp amp mxIsChar values 0 mexPrintf plSetValue wrong number of parameters given or wrong parametertype n mexPrintf s expects 1 parameter of type string n parametername mexErrMsgTxt Mn float string else if stromp parametername ExposureTime if nvalues 1 nvalues 2 mexPrintf plSetValue wrong number of parameters given n mexPrintf s expects 1 or 2 parameters n parametername mexErrMsgTxt Mn if mxIsDouble values 0 mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a float as lst
119. etername ImagerChipId Imager Chip ID nRetValue PimMegaGetImagerChipId deviceld amp imagerChipIdValue if plError nRetValue getting ImagerChipId value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 imagerChipIdValue else if stromp parametername ImagerClocking Imager Clocking nRetValue PimMegaGetImagerClocking deviceld amp imagerClockingValue if plError nRetValue getting ImagerClocking value mexErrMsgTxt Mn if imagerClockingValue 0x00 m mxCreateString 0x00 nOscilator type External 16MHz nMax clock rate divided by no division else if imagerClockingValue 0x01 m mxCreateString 0x01 nOscilator type External 16MHz nMax clock rate divided by 2 else if imagerClockingValue 0x02 m mxCreateString 0x02 nOscilator type External 16MHz nMax clock rate divided by 4 else if imagerClockingValue 0x80 m mxCreateString 0x80 nOscilator type Internal 24MHz nMax clock rate divided by no division else if imagerClockingValue 0x81 m mxCreateString 0x81 nOscilator type Internal 24MHz nMax clock rate divided by 2 69 FGI and plFGI Report 2002 September 2002 else if imagerClockingValue 0x82 m mxCreateString 0x82 nOscilator type Internal 24MHz nMax clock rate divided by 4 else m mxCr
120. f 0 false When an error occurred plError prints an appropriate descriptive message on the screen using mexPrintf and returns a non zero value true To make it possible to distinguish between critical and non critical errors a value of 1 is returned on an error that might not be critical A value of 2 is returned on errors that are always considered critical Where appropriate the program can decide on this information to continue or to terminate e Suggestions for improvement The entire building of the string used in The device s API encountered can be moved within the following if result ApiSucces condition 24 plFGI Technical Guide September 2002 2 11 Description of plGetValue plGetValue is a subroutine which is linked to the plGet MEX function When given an mxArray for returning the parameter value the device s serial number and the name of the parameter to be returned it will return the parameter s value or values in the given mxArray plGetValue is very similar to plCreateDeviceHandle The most important difference is that not all possible parameters of the device are obtained but only the parameter or structure of which the name was given This is accomplished by using an if elseif construction together with multiple strcmp statements An obvious difference is that the mxArray m can differ in size according to the parameter that is stored in it When an unknown parameter name is given plGetValue prints a
121. gTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 redGainValue else if stromp parametername Saturation Saturation nRetValue PimMegaGetSaturation deviceld amp saturationValue if plError nRetValue getting Saturation value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 saturationValue else if stromp parametername SerialNumber Serial Number nRetValue PimMegaGetSerialNumber deviceld amp serialNumberValue if plError nRetValue getting SerialNumber value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 serialNumberValue else if strcmp parametername SoftwareVersion Software Version nRetValue PimMegaGetSoftwareVersion deviceld amp softwareVersionValue if plError nRetValue getting SoftwareVersion value 7 FGI and plFGI Report 2002 me m tmppr tmppr else if Sub nRetVa if pl me DE Ce each lse i lse i ise tmp2 tmppr2 tmppr2 tmp3 tmppr3 tmppr3 tmp4 tmppr4 tmppr4 tmp5 tmppr5 tmppr5 fieldn fieldn fieldn fieldn fieldn m mx mxSetF mxSetF mxSetF mxSetF mxSetF else if ZC Sub nRetValue if pl me tmp mxCreateDoubleMatrix 1 tmp tmp t
122. get add getpar setpar prhs 1 U32 serial number of device Only for remove isopen get add getpar setpar prhs 2 int deviceID Only for add prhs 2 string name of parameter Only for getpar pA setpar prhs 3 value of parameter Only for setpar LU Output plhs 0 double 1 if device open 0 if closed Only for CR isopen Ke plhs 0 int deviceID if open 1 if closed Only for fx get Be plhs 0 parameter value 1 if not found Only for getpar Syntax not to be used directly from matlab A Jak kk kk kk kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k ck k kok ck kokok ck kok ck kokok I ke xe x k amp x d Exclude rarely used stuff from Windows headers define WIN32 LEAN AND MEAN include windows h include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib include plTypes h ifdef _ cplusplus extern C endif global variables needed for storing the open device array struct U32 serialNumber int deviceID U32 grabColorConversion int grabOutputType deviceArray 32 int deviceCount 0 void mexFunction int nlhs mx
123. grab m end t toc i 1 100 y plgrab m end t toc 512 640 256 640 1024 640 1024 320 256106896 Unsupported Could not get value DATA 8BIT SIZE 1028 1 0400 1 Ore Unsupported PL A630 Series Monochrome EC Module WE Up Tet Vue 805306368 0x01 External 16Mhz Division by 2 Imager0 PCS2112M IMAGER Monochrome Camera 0 Could not get value Could not get value Could not get value 110 FGI and plFGI Report 2002 PreviewWindowSize Width RedGain Saturation SerialNumber SoftwareVersion SubWindow Decimation SubWindow StartRow SubWindow StartColumn SubWindow NumberRows SubWindow NumberColumns SubWindowPos StartRow SubWindowPos StartColumn SubWindowSize Decimation SubWindowSize Height SubWindowSize Width Timeout ode GrabColorConversion GrabOutputType Video September 2002 Could not get value Unsupported Unsupported 75122 16777984 PCS2112 NO DECIMATION 0 0 1024 320 0 0 PCS2112 NO DECIMATION 1024 320 1000 VIDEO MODE BAYER 3BY3 COLOR RAW 111 pIFGI MatLAB Interface for PixeLINK FireWire Cameras User Manual amp Technical Guide Last updated September 2002 plFGI User Manual amp Technical Guide September 2002 MatLAB Interface for PixeLINK FireWire Cameras User Manual amp Technical Guide M A E Bakker maarten panic et tudelft nl L I Oei L I Oei its tudelft nl September 2002
124. ible values of the parameter with 2 arguments Syntax plSet serialnumber plSet serialnumber parametername or plSet serialnumber parametername value ORK RK KR KK kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kCk Ck k kc k k kc k Ck k kc k k kk k k kc k k kok ck kok ck kokok ck k ke x kx A x f define WIN32 LEAN AND MEAN include windows h include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib include plPrintPossibleValues h include plSetValue h ifdef cplusplus September 2002 Exclude rarely used stuff from Windows headers extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs mxArray serialNumberField U32 serialNumber 1 the serial number of the device mxArray lhs 1 rhs 5 to call fgdevices double px int isOpen 0 int buflen i char parametername prhs 0 should be the device handle struct or serial number int prhs 1 should be the parameter name optional prhs 2 n should be the parameter value optional if nrhs gt 1 get the serialNumber if mxIsStruct prhs 0 serialNumbe
125. idth pixelHeight and is arranged as an mxArray of pixel Width pixelHeight e The matlab array which is returned to Matlab In case of a RAW image this array has the same size and arrangement as the capture array In case of a Matlab IMAGE it is an array of unsigned 8 bit integers three times the size of pixelWidth pixelHeight It is arranged as an mxArray of pixelHeight pixelWidth 3 In memory this means that 3 column major arrays of pixelHeight pixelWidth are stored consecutively like this RRR GGG BBB e The RGB24 array is used as an intermediate array to store the result of PimMegaConvert in case of a non RAW image before it is converted to fit into the matlab array Its size is always 3 pixelWidth pixelHeight and it is arranged as a normal C type row major array like this RGBRGBRGB 3 Vitana 2002 1 81 5 5 S Vitana 2002 1 p 92 PimMegaSetSubWindow d Vitana 2002 1 p 92 PimMegaSetSubWindow 22 FGI and plFGI Report 2002 September 2002 First a distinction between the various GrabOutputType settings is made using a case construction The size and dim variables are set to the required size and dimensions of the matlab array After that the sizes of the capture array and the RGB24 array are defined A case construction is used to allocate memory for the matlab and capture arrays differentiating between 8 and 16 bits data size After this it is checked whether an er
126. if grabOutputType RAW 8 bits transfer just return the image if dataTransferSize DATA 8BIT SIZE memcpy imgOutPtr imgCapturePtr rawImgByteSize else if dataTransferSize DATA 16BIT SIZE 16 bits transfer shift some bits j 0 for i 0 i rawImgSize itt PU16 imgOutPtr i PU8 imgCapturePtr j gt gt 6 U16 PU8 imgCapturePtr j 1 4 jt 2 else mexPrintf plGrab unknown pixel depth n mexErrMsgTxt n return else grabOutputType RAW postprocessing by PimMegaConvert if dataTransferSize DATA 8BIT SIZE amp amp imagerType PCS2112M IMAGER 8 bit monochrome nRetValue PimMegaConvertMono8BppTo24Bpp deviceId PU8 imgCapturePtr pixelWidth pixelHeight PU8 img24BppPtr plError nRetValue converting raw mono 8 to 24 bpp else if dataTransferSize DATA 8BIT SIZE amp amp imagerType PCS2112C_IMAGER 8 bit color nRetValue PimMegaConvertColor8BppTo24Bpp deviceld PU8 imgCapturePtr pixelWidth pixelHeight PU8 img24BppPtr grabColorConversion plError nRetValue converting raw colour 8 to 24 bpp else if dataTransferSize DATA 16BIT SIZE amp amp imagerType PCS2112M IMAGER 16 bit monochrome nRetValue PimMegaConvertMonol6BppTo24Bpp deviceId PU8 imgCapturePtr pixelWidth pixelHeight PU8 img24BppPtr plError nRetValue converting raw mono
127. if vide m else if m 8 else if st else if GrabC rhs 0 rhs 1 px mxG px 0 rhs 2 rrMsgTxt An oModeValue STILL MODE mxCreateString STILL MODE videoModeValue VIDEO MODE mxCreateString VIDEO MODE mxCreateString Unknown value rcmp parametername GrabColorConversion olorConversion is kept in plDevices and used in plGrab mxCreateString getpar mxCreateDoubleMatrix 1 1 mxREAL etPr rhs 1 U32 serialNumber mxCreateString GrabColorConversion mexCallMATLAB 1 lhs 3 rhs plDevices grabColorConversionValue U32 mxGetScalar lhs 0 switch grabColorConversionValue case BAYER_ 2BY2 COLOR m mxCreateString BAYER 2BY2 COLOR break case BAYER 3BY3 COLOR m mxCreateString BAYER 3BY3 COLOR break case BAYER 3BY3GGRAD COLOR m mxCreateString BAYER 3BY3GGRAD COLOR break case BAYER 2PASSGRAD COLOR m mxCreateString BAYER 2PASSGRAD COLOR break case BAYER 2PASSADAPT COLOR m mxCreateString BAYER 2PASSADAPT COLOR break case BAYER VARGRAD COLOR m mxCreateString BAYER VARGRAD COLOR break case BAYER 2BY2 MONO m mxCreateString BAYER 2BY2 MONO break case BAYER 3BY3 MONO m mxCreateString BAYER 3BY3 MONO break case BAYER ADAPT MONO m mxCreateString BAYER ADAPT MONO break case BAYER NO CONVERSION m mxCreateString B
128. in U32 n mexPrintf Value should not exceed lu n PCS2112_ MAX GAIN Saturation else if strcmp parametername Saturation mexPrintf Saturation U32 n mexPrintf Value should not exceed OxFF n SubWindow 89 FGI and plFGI Report 2002 September 2002 else if stromp parametername SubWindow mexPrintf SubWindow string uDecimation n mexPrintf U32 uStartRow n mexPrintf U32 uStartColumn n mexPrintf U32 uNumberRows Nn mexPrintf U32 uNumberColumns Nn mexPrintf uDecimation should be PCS2112 NO DECIMATION n mexPrintf PCS2112 DECIMATE BY 2 or PCS2112 DECIMATE BY 4 VMn SubWindowPos else if strcmp parametername SubWindowPos mexPrintf SubWindowPos U32 uStartRow U32 uStartColumn n SubWindowSize else if strcemp parametername SubWindowSize mexPrintf SubWindowSize string uDecimation n mexPrintf U32 uHeight n mexPrintf U32 uWidth Nn mexPrintf uDecimation should be PCS2112 NO DECIMATION n mexPrintf PCS2112 DECIMATE BY 2 or PCS2112 DECIMATE BY 4 Vn Timeout else if strcmp parametername Timeout mexPrintf Timeout U32 n VideoMode else if strcomp parametername VideoMode mexPrintf VideoMode string n mexPrintf Valid values are STILL MODE and VIDEO_MODE n GrabColorConversion else if strcmp parametername GrabColorConversion
129. ing PimMegaStopVideoStream For postprocessing two possibilities are distinguished using an if else construction e The first possibility occurs in case of a RAW image An 8 bit RAW image is copied into the matlab array using memcpy a 16 bit RAW image is converted to have all 10 1 Vitana 2002 1 81 5 5 Vitana 2002 1 p 92 PimMegaSetSubWindow 3 Vitana 2002 1 p 92 PimMegaSetSubWindow 17 plFGI Technical Guide September 2002 significant bits in the right order according to to the PixeLINK Megapixel FireWire Camera User s Manual The 2 most significant bits of the first byte are shifted to be the 2 least significant bits The second byte is shifted 2 bits to the left multiplied by 4 then the two bytes are added equivalent to a logical and operation e The second possibility occurs in case of an IMAGE or RGB24 output format Depending on 8 versus 16 bits and black white versus colour one of the PimMegaConvert functions is called to convert the captured image to a 24 bits per pixel image For colour images the GrabColorConversion parameter is used to determine the algorithm to be used by the PimMegaConvert function The result of PimMegaConvert is stored into the RGB24 array If the GrabOutputType is set to RGB24 the RGB24 array is directly copied into the matlab array using memcpy In case of an IMAGE type however the RGB24 array must be transposed in order for Matlab to display it properly This is
130. ing may solve the problem n return 2 default mexPrintf Error unknown to the FGI n return 1 62 FGI and plFGI Report 2002 September 2002 D 6 plError h ORK KK KR kOkCk Ck Ck k Ck k kc k Ck kc kc k k kc k Ck k kc k Ck k Ck Ck k kc k Ck kc k Ck k kc k k k ck k k k ck k kok ck kok ck ck okok ck k kx x kx d Filename plError h 5 Description Header file for plError cpp As Authors L I Oei M A E Bakker Date 2002 08 06 Updates ORK ROKK KK kk kk kOk Ck Ck k Ck Ck kCk k Ck kc kc Ck k kc k Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k k k kc k kok ck kokok ck kok ck kokok ck k ke x x d int plError PXL RETURN CODE char 63 FGI and plFGI Report 2002 September 2002 D 7 plGet cpp ORK KK KK hh kOkCk kk k Ck kCk k Ck kc kc k Ck kc KCk k kc k Ck kc k Ck k kc k k kc k Kk k kc k Ck kc k kk k ck k kock ck kok ck ck kok ck k ke xe kx k x Filename plGet cpp Wi Description Source code for the function plGet Ki Authors L I Oei M A E Bakker y Lt maarten panic et tudelft nl l i oei its tudelft nl ty Date 2002 08 01 Updates 7 ROR KKK KR Ck kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc K Ck kc e k kc k Ck kc k Ck k kc k Ck k kc k k kc k kokok ck kok ck kokok eR kx A x d plGet returns the device s handle if 1 argument is given and returns the value of the given parameter if 2 arguments are given ORK KKK KK kk Ck Ck kOkCk Ck kCk Ck k kc k Ck kc k Ck k kc K Ck k kc k
131. inter problem allocating required memory n return 2 case ApiNoDeviceError mexPrintf The camera may be disconnected n return 1 case ApiCOMError mexPrintf Windows COM object error n return 2 case ApiloctlError mexPrintf I O control error API may be incompatible with driver n return 2 case ApiFileOpenError mexPrintf File I O error n return 1 case ApilnvalidParameterError mexPrintf Invalid parameter n return 2 case ApilmagerUnknownError mexPrintf API doesn t recognize imager should be PCS2112M IMAGER or PCS2112C_IMAGER n return 2 case ApiOutOfMemoryError mexPrintf Unable to allocate required memory n return 2 case ApiUnknownError mexPrintf Error unknown to the API n return 2 case ApiNoPreviewRunningError mexPrintf The preview window is not open n return 2 case ApiNotSupportedError mexPrintf The camera does not support the requested functionality Anni return 1 case ApilnvalidFunctionCallError mexPrintf The function was called in an improper sequence n return 2 case ApiHardwareError mexPrintf Hardware error n return 2 61 FGI and plFGI Report 2002 September 2002 case ApiOSVersionError mexPrintf Unsupported operating system version n return 2 case ApiMaximumIterationsError mexPrintf Too many internal iterations n return 2 case ApiTimeoutError mexPrintf Time limit exceeded increasing the Timeout sett
132. itana PixeLINK digital cameras The name plFGI stands for PixeLINK Frame Grabber Interface In this document you will find described the functionality of this interface and information about the working conditions This document can be used as a reference while working with the interface 1 1 Short description of Matlab Matlab is a mathematical program for technical computing It is used by research institutes and universities all over the world mostly to solve problems which involve matrix and vector calculations It can for example be used to make analyses and computations on images which are stored as matrices This is the main purpose of the plFGI software One of the important features of Matlab is the ability to use external compiled programs from within Matlab called MEX files The pIFGI consists of such external programs In a windows environment the native dll format is used for MEX files Variables are passed between Matlab and the MEX files using mxArrays in which all required variables can be stored and returned 1 2 Short description of the PixeLINK camera The PixeLINK PL A6xx camera series consists of megapixel cameras with a CMOS image sensor and integrated image processing electronics The IEEE 1394 FireWire interface is used for communicating with the computer The cameras are available in both in colour and black amp white versions Some of the camera models are equipped with a machine vision connector to conn
133. k plSet Implementation of PimMegaSetPreview Window plSet Implementation of PimMegaAutoExposure plDevices In remove the inner for loop tries to copy one entry more than needed When having 32 camera s open this could result in a segfault The inner loop for condition should be t i t lt deviceCount 1 t plCreateDeviceHandle Convert some of the if constructions to switch constructions for example the one used for SubWindowSize plError The entire building of the string used in The device s API encountered can be moved within the following if result ApiSucces condition Function to check whether the camera is connected to the computer Reset function to set all parameters to their default value Demo M files Additional tests on the performance of pIFGI 32 September 2002 plFGI Technical Guide Appendix E Test results September 2002 Below are the screen printouts of the tests performed on pIFGI gt gt plset m DataTransferSize DATA 8BIT SIZE gt gt tic for E es 65 8000 gt gt plset m SubWindowSize PCS2112 NO DECIMATION i 1 100 y plgrab m end t toc oF LAG for 29 6600 gt gt plset m SubWindowSize PCS2112_NO_DECIMATION i1 1 100 y plgrab m end t toc o gt tic for C 17 3000 gt gt plset m SubWindowSize PCS2112 NO DECIMATION i 1 100 y 2plgrab m end t toc gt gt tcs for Ti 55 8000 gt gt plset m SubWindowSiz
134. k k ke x kx A x f Header file for plCreateDeviceHandle cpp S ORK kk KR kOkCk Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k Ck kc IA k kc k e E kok ck kokok ck k ke kx A d void plCreateDeviceHandle mxArray returnArray U32 serialNumber 55 FGI and plFGI Report 2002 September 2002 D 4 plDevices cpp ORK RK KR KK kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc K Ck k kc Kk Ck kc k Ck k kc k Ck kc k Ck k kc k k k kc k k kc k kokok ck kok ck kokok ck k ke x x A x fj Filename plDevices cpp Wi Description Source code for the function plDevices Ki Authors M A E Bakker L I Oei y Lt maarten panic et tudelft nl l i oeiGits tudelft nl ty Date 2002 08 08 Updates 7 ROR KKK KK kk Ck Ck kOkCk kk k Ck k kc k Ck kc kc k k kc k Ck k kc Ck kc k Ck k kc k Ck kc k Kk k kc k Ck ko k Ck kok ck kokok ck kok ck kokok ck k ke xe kx A x d plDevices keeps the open device array in which the list of open zA devices and some auxilairy parameters that are not stored in the Zi device are stored This is a list of tuples of the form serialnumber deviceId parameter parameter plDevices provides functionality to check and update the list m ORK RK KK KK KR Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc Ck kc k CK k kc k Ck kc k Ck k kc k Ck k k k k kc k kck ck k kok ck kokok ck k ke e x A x fj Input prhs 0 string name of task to be performed print S remove isopen
135. kc k Ck k kc K Ck k Ck CK k kc k Ck kc k Ck k kc k k ko kc k kok ck kokok ck kok ck k k ke x A kx d Tf get the serial number mxIsStruct prhs 0 serialNumberField mxGetField prhs 0 0 SerialNumber serialNumber U32 mxGetScalar serialNumberField else if mxIsDouble prhs 0 serialNumber U32 mxGetScalar prhs 0 else mexPrintf PixeLINK Interface error n mexPrintf plGrab Wrong arguments given First argument should be the device handle or serial number n mexErrMsgTxt Mn get the deviceId rhs 0 mxCreateString get rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices deviceld HANDLE int mxGetScalar lhs 0 ORK KK KK RR Ck k kc k Ck kc kc k Ck k k Ck k kc K Ck kc e k kc k k kc kc k k kc k e kok ck kokok ck eR ke ke x kx kx d Open the video stream and set VideoMode to VIDEO MODE ORK kk Ck kk kk kOkCk Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck k Ck CK k kc k Ck kc k k k kc k k kok k kok ck kokok ck kok ck k k ke x kx kx d open video stream first to do acquisition nRetValue PimMegaStartVideoStream deviceId if plError nRetValue calling PimMegaStartVideoStream mexErrMsgTxt Mn make sure camera is in video mode it will give better results than stil mode without shutter or flashlight
136. ke x kx A x fj Get the devicelId be KOK KR KK KK kOkCk kOk Ck Eh k kc k Ck k kc Ck kc k Ck kc kc k k k k Ck k kc k k k ck k kok ck kokck ck kok ck kokok ck k ke x kx A x fj rhs 0 mxCreateString get rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices deviceld HANDLE int mxGetScalar lhs 0 KOK KR KK KK RR kc k k k kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k Ck k k Ck k kc E A ck kok ck kokok ck k ke x kx k x fF Get all settings and store them in the mxArray Ski kk kOk Ck kOk ck k kk k Ck kc k Ck k kc k Ck k kc Ck k k Ck k kc k Ck k k Ck kokc k k k ck k kok ck kokock ck kok ck ck ok ok X k ke x kx kx m mxCreateStructMatrix rows cols nof const char fieldnames DeviceID tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 int deviceId mxSetField m 0 DeviceID tmp Blue Gain nRetValue PimMegaGetBlueGain deviceld amp blueGainValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 blueGainValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else 45 September 2002 FGI and plFGI Report 2002 September 2002 tmp mxCreateString Could not get value mxSetField m 0 BlueGain tmp Current Frame Rate nRetValue PimMegaGetCurrent
137. kok ck kokok ck HK kx d plGetValue returns the value of a given parameter A ORK KKK KK kk kk kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k k kc k Ck k ck kckock ck kok ck kokok ck ko k x kx A x fj Input returnarray mxArray mxArray for receiving the structure ZS serialNumber U32 serialNumber of the device SCH parametername string name of the parameter Output K Syntax plGetValue returnArray serialNumber parametername ROKK KK KK CkCk kOkCk Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc K Ck kc k Ck k kc k Ck kc AA k ck k kok ck kokok ck kok ck kokok he f include windows h include Y soft95 matlab6 extern include mex h include Y software framegrag pixelink api pimmegaapiuser h include plError h include plTypes h void plGetValue mxArray returnArray U32 serialNumber char parametername m mxArray structure to be returned as device handle lhs rhs used to call plDevices mxArray xm lhs 1 rhs 3 double px HANDLE deviceld variable for receiving the error codes the pixelink api functions return PXL RETURN CODE nRetValue char fieldnames 5 mxArray tmp tmp2 tmp3 tmp4 tmp5 ER double tmppr tmppr2 tmppr3 tmppr4 tmppr5 variables used for receiving the settings U32 blueGainValue 1 float currentFrameRateValue 1 U32 dataTransferSizeValue 1 U32 exposureValue
138. less than PCS2112 MAX WIDTH uStartRow current number of rows must be less than PCS2112 MAX HEIGHT less than should be less than or equal to 25 plFGI Technical Guide September 2002 Vitana 2002 1 p 95 PimMegaSetSubWindowSize Current start column Width must be less than PCS2112 MAX WIDTH Current start row Height must be less than PCS2112 MAX HEIGHT less than should be less than or equal to 2 13 Description of plPrintPossible Values plPrintPossibleValues is a subroutine linked to the plGet and plSet MEX functions When given the name string of a parameter it will use strcmp in an if else if construction to determine what should be printed Then a short description of the given parametername and its possible values is printed to the screen using mexPrintf 2 14 Description of plTypes plTypes h contains all definitions that are used by the pIFGI program Currently the only values that are defined here are those used to store the GrabOutputType variable 2 15 General hints on modifying e When adding or removing a device parameter this should be done in the obvious places in the following files plCreateDeviceHandle cpp plGetValue cpp plPrintPossibleValues cpp plSetValue cpp and plSet cpp Also the nof variable and the fieldnames structure in plCreateDeviceHandle should be updated accordingly Please also don t forget to update the parameter overview in plGetValue
139. ll entries of the open device array to the screen one device per line by using a for loop for i 0 to deviceCount 1 e 2 arguments remove plDevices remove serialnumber Description removes a device from the open device array Input prhs 0 string remove prhs 1 U32 serialnumber Output None plDevices remove 75122 This task removes a device from the open device list Using a for loop for i 0 to deviceCount 1 the given serial number is compared to every serial number in the open device array As soon as a matching entry is found a new for loop is entered for t number of matching entry to deviceCount 1 to overwrite every entry from the matching entry up to the last entry with the entry immediately following it this goes wrong if the last entry is 31 see Suggestions for improvement After the inner for loop finishes deviceCount is decremented 21 plFGI Technical Guide September 2002 isopen plDevices isopen serialnumber checks whether a device has been opened Input prhs 0 string isopen prhs 1 U32 serialnumber Output plhs 0 double 1 if the device is open 0 if the device is closed plDevices isopen 75122 This task returns 0 if the device is not open 1 if it is open First the return value is set to 0 then a for loop for i 0 to deviceCount 1 is entered The given serial number is compared to every serial
140. ll the function from within Matlab just like normal C MEX files The PixeLINK dll is load time linked This means that when the MEX file is loaded into memory the PixeLINK dll is loaded at the same time Therefore to use the MEX files it is necessary that the file PimMegaApi dll is in the Windows path not the Matlab path Otherwise Matlab will give an error message like Unable to load mex file g fgi bin plOpen dll The specified module could not be found 2 Invalid MEX file This can be quite confusing as it doesn t directly point to the actual cause of the error 1 4 Testing During development frequent testing helped to find bugs in pIFGI After the program reached a stable working state a few other tests were run in the limited time that was still available On suggestion of Assistant Professor Smutny it was tested how much time the capturing of multiple frames takes This could possibly be used as an indication of the quality of the code memory leaks and resources that are not released would have become apparent this way Also the performance of the code the PixeLINK API and the PixeLINK camera could be verified First some basic tests were performed showing that capturing the images resulted in a frame rate a bit lower than that of the demo application but that could be contributed to the overhead of calling functions from Matlab and the lack of loop optimalisation in plFGI When testing different resolutions
141. lnumber J ORK RK KR KK RR kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k k kc k e ck ck kok ck kokok ck k ke x x A x d define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows headers include lt windows h gt include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib ifdef _ cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs mxArray serialNumberField U32 serialNumber 1 the serial number of the device mxArray rhs 2 double px prhs 0 should be the device handle struct or serial number int if nrhs 1 get the serial number if mxIsStruct prhs 0 serialNumberField mxGetField prhs 0 0 SerialNumber serialNumber U32 mxGetScalar serialNumberField else if mxIsDouble prhs 0 serialNumber U32 mxGetScalar prhs 0 else mexPrintf PixeLINK Interface error n mexPrintf plIsOpen Wrong arguments given One argument needed device handle or serial number n mexErrMsgTxt Mn check whether the device is open rhs 0 mxCreateString isopen rhs 1
142. locate memory for the RGB24 array if needed if grabOutputType RAW img24BppPtr U8 mxCalloc RGB24ImgSize sizeof U8 80 FGI and plFGI Report 2002 September 2002 ROR KR KK KK kk k Ck kOk Ck Ck kCk Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc e k kc k k kc k k k kc k k k ck k kok ck kokok ck kok ck I ke x kx kx d L Capture the image and close the video stream x ORK KKK KK Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc K Ck kk CK k kc k k kc k Ck k kc k k kck k kok ck kokok ck kok ck ke k ke x kx kx d capture the image nRetValue PimMegaReturnVideoData deviceld rawlImgByteSize imgCapturePtr if plError nRetValue calling PimMegaReturnVideoData PimMegaStopVideoStream deviceId mexErrMsgTxt Mn close the video stream nRetValue PimMegaStopVideoStream deviceId if plError nRetValue calling PimMegaStopVideoStream mexErrMsgTxt Mn ORK KK KK RR k Ck kc kc k k kc k Ck k kc k Ck k Ck CK k kc k RE kc k k ko k k kok ck kokok ck Re d We Postprocess the image if necessary and return the image iA return the image as is specified by the GrabColorConversion and GrabOutputType variables x
143. make sure plDevices containing the open device array stays in memory Then it is checked whether any arguments are given and if the first argument is a 20 plFGI Technical Guide September 2002 text string If not the error message in the else part of the check is displayed and plDevices terminates If it is the first argument is stored in the task variable If there is a second argument it should always be the serial number of a device If it is not a number plDevices is terminated with an error message A case construction is used to make a first selection between the different tasks based on the number of arguments given For every number of arguments from 1 to 4 a different case exists the default case gives an error message Inside a case the different tasks are selected using an if else if construction together with strcmp When the strcmp fails an appropriate error message is given and plDevices terminates Although plDevices is not meant to be called directly from Matlab in the next part the syntaxes and examples are written down as if it were because this way it is easier to denote and understand the usage of the left hand and right hand side arguments e largument print Syntax plDevices print Description prints a list of open devices with SerialNumber DeviceID GrabColorConversion and GrabOutputT ype prhs O tring print This task is mainly intended for testing and debugging purposes It prints a
144. ment Every MEX function has its own subfolder containing the necessary files for building it Double click on the appropriate workspace file dsw to open the project All relevant header and source files see Appendix C for an overview of the dependencies are included in the workspace Before opening the project you may want to check the pathnames used in the various project configuration files or just place all files in the same folders as used during development G NewFGI src plFGI source files and project folders YAsoftware framegrag pixelink api PixeLINK libraries YAsoft95 matlab6 extern lib win32 microsoft msvc60 Matlab libraries At some point you may want to create a new project below is the procedure that was used to create pIFGI e Create a new DLL project File New Projects Win32 Dynamic Link Library gt A DLL that exports some symbols e Throw away StdAfx cpp StdAfx h and Projectname h e Disable precompiled headers Project Settings C C Category Precompiled Headers Not using precompiled headers e Link the necessary libraries Project Settings Link Category General Object library modules Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib Y Asoft95 matlab6 extern lib win32 microsoft msvc60 libmx lib Y A software framegrag pixelink api pimmegaapi lib e Export the mexFunction Project Settings Link Category General Project Options export
145. ments were given plPrintPossibleValues is called 2 parameters or plSetValue is called 3 arguments e Suggestions for improvement o Implementation of PimMegaSetOverlayCallBack o Implementation of PimMegaSetPreviewWindow o Implementation of PimMegaAutoExposure 19 plFGI Technical Guide September 2002 28 Description of plDevices plDevices is a MEX function just like the 6 functions described above However it only contains plFGI internal functionality and should not be called by the user It is used to keep track of open devices This is its functional specification DLL name plDevices dll mexCallMATLAB nlhs plhs nrhs prhs plDevices Description plDevices maintains the open device array in which the device ID s handles to open devices are stored Also some settings which are not stored in the PixeLINK Camera API itself are stored in plDevices Input prhs 0 string name of task to be performed print remove isopen get add getpar setpar prhs 1 U32 serial number of device Only for remove isopen get add getpar setpar prhs 2 int deviceID Only for add string name of the parameter Only for getpar setpar prhs 3 value of the parameter Only for setpar Output plhs 0 double 1 if device open 0 if closed Only for isopen int deviceID if open 1 if closed Only for get parameter value 1 if not found Only for getpar plDevices is implemented as a MEX function because
146. meters GrabColorConversion and GrabOutputType which are not stored in the PixeLINK API but in plDevices They are obtained in a similar way to the device ID by calling plDevices using mexCallMatlab e Suggestions for improvement Convert some of the if constructions to switch constructions for example the one used for SubWindowSize 6 4 9 plError plError is an error checking function which is linked to every MEX function that uses PixeLINK API calls It is called after every call to such an API function Required inputs are the PixeLINK API return code returned by the called API function and a string describing in max 33 characters what the program was doing when the possible error occurred First the string input of the plError function is used to create an error message The device s API encountered a problem while lt string gt When the PixeLINK API return code which is defined in PimMegaApiUser h indicates an error this string is printed on the screen After that a case construction is used to determine the nature of the PixeLINK API return code When everything is okay plError returns a value of 0 false When an error occurred plError prints an appropriate descriptive message on the screen using mexPrintf and returns a non zero value true To make it possible to distinguish between critical and non critical errors a value of 1 is returned on an error that might not be critical A value of 2 is returned on er
147. mexPrintf plSetValue Error setting SubWindow value too small n mexPrintf uNumberColumns must be at least lu n PCS2112 MIN WIDTH mexErrMsgTxt Mn if tmpU325 lt PCS2112_MIN_HEIGHT mexPrintf plSetValue Error setting SubWindow value too small n mexPrintf uNumberRows must be at least lu n PCS2112 MIN HEIGHT mexErrMsgTxt Mn set the values nRetValue PimMegaSetSubWindow devicelId tmpU32 tmpU322 tmpU323 tmpU324 tmpU325 if plError nRetValue setting SubWindow mexErrMsgTxt Mn SubWindowPos else if strcmp parametername SubWindowPos tmpU32 U32 mxGetScalar values 1 uStartColumn tmpU322 U32 mxGetScalar values 0 uStartRow tmpU323 subWindowSizeDecimationValue tmpU324 subWindowSizeWidthValue number of columns 103 FGI and plFGI Report 2002 September 2002 tmpU325 subWindowSizeHeightValue number of rows nRetValue PimMegaGetSubWindowSize deviceld amp tmpU323 amp tmpU324 amp tmpU325 check whether the given values are within the correct range if tmpU32 tmpU324 gt PCS2112 MAX WIDTH mexPrintf plSetValue Error setting SubWindowPos value too large n mexPrintf uStartColumn current number of columns should not exceed lu n PCS2112 MAX WIDTH mexErrMsgTxt Mn if tmpU322 tmpU325 gt PCS2112 MAX HEIGHT mexPrintf plSetValue Error setting S
148. mexPrintf plSetValue wrong parametertype given n mexPrintf s expects a 3 arguments of types string U32 U32 n parametername mexErrMsgTxt Mn KOK KR KKK Eh kCk k Ck k kc k Ck k k Ck k kc k Ck k k Ck kck k k k ck E I I x Set the value of the given parameter KOK KR RK KK kOk Ck Ck k k Ck kk k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k Ck k k Ck k kc k k k ck k kok ck e ck ck kok ck Ee ke x kx A x fj Blue Gain if strcmp parametername BlueGain 97 FGI and plFGI Report 2002 September 2002 tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt PCS2112_MAX_GAIN mexPrintf plSetValue Error setting BlueGain value too large n mexPrintf BlueGain value should not exceed lu n PCS2112 MAX GAIN mexErrMsgTxt Mn set the value nRetValue PimMegaSetBlueGain deviceld tmpU32 if plError nRetValue setting BlueGain mexErrMsgTxt Mn DataTransferSize else if stromp parametername DataTransferSize buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen check whether this is a known value i stremp tmpstring DATA 8BIT SIZE tmpU32 DATA 8BIT SIZE else if stremp tmpstring DATA 16BIT SIZE tmpU32 DATA 16BIT SI
149. mp tmp xErrMsgTxt Nn 1 0 mxGetPr m U32 softwareVersionVa strcmp parametername Window lue amp amp amp amp Error nRetValue getting S xErrMsgTxt Nn bWindowDecimationValue P mxCreateString PCS2112 f subWindowDecimationValue mxCreateString PCS2112 f subWindowDecimationValue mxCreateString PCS2112 mxCreateS tring Unknown atrix l1 ly indowStartCo atrix l1 E indowStartRo atrix l1 s Double r tmp2 2 subW Double r tmp3 2 subW Double r tmp4 2 subWindowNumberC mxCreateDoubleMatrix 1 15 mxGetPr tmp5 U32 subWindowNumberR mxCrea mxGe 0 mxCrea mxGe 0 mxCrea mxGe 0 di Oh Am om o wmn 0 SubWindowDecimat SubWindowStartCo SubWindowStartRo SubWindowNumberC SubWindowNumberR ames ames ames ames ames CreateStructMatrix 1 1 5 ield ield ield ield ield SubWindowDecima SubWindowStartC SubWindowStartR SubWindowNumber SubWindowNumber m O m O m 0 m 0 m 0 strcmp parametername SubW Window Pos Error nRetValue getting S xErrMsgTxt Nn mxCreateDoubleMatrix 1 1 72 PimMegaGet SubWindow deviceld PimMegaGet SubWindowPos deviceld September 2002 mxREAL lue SubWindow amp subWindowDecimationValue subWindowStartColumnValue subWindowStartRowValue
150. nRetValue PimMegaGetVideoMode deviceId amp currentVideoMode if if plError nRetValue calling PimMegaGetVideoMode mexErrMsgTxt Mn currentVideoMode VIDEO MODE nRetValue PimMegaSetVideoMode deviceld VIDEO MODE if plError nRetValue calling PimMegaSetVideoMode mexErrMsgTxt n mexPrintf Setting VideoMode to VIDEO MODE for better results n ORK KKK KK KK RR Ck k kc k Ck kCk Ck Ck kc k Ck k kc k Ck k Ck Ck k kc k Ck kc k Ck k kc k k ko k k kok ck kokok ck E Ee ek d Get some camera settings ORK KK KK kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc k Ck k k Ck k kc K Ck kk CK k kc k k kc k k k kc k k k ck k kok ck kokok ck kok ck ke k ke x kx kx d get image properties monochrome or color nRetValue PimMegaGetImagerType deviceId amp imagerType if plError nRetValue calling PimMegaGetImagerType PimMegaStopVideoStream deviceId mexErrMsgTxt Mn 78 FGI and plFGI Report 2002 September 2002 DATA 8BIT SIZE or DATA 16BIT SIZE nRetValue PimMegaGetDataTransferSize deviceld amp dataTransferSize if plError nRetValue calling PimMegaGetDataTransferSize PimMegaStopVideoStream deviceId mexErrMsgTxt Mn nRetValue PimMegaGetSubWindowSize deviceld amp decimation amp width amp height if plError nRetValue calling PimMegaGet SubWindowSize PimMegaStopVideoStream deviceId mexErrMsgTxt
151. nged the layout of grabfg to improve readability Added more descriptive error messages to grabfg Improved the documentation of grabfg so now all 6 ways of calling grabfg are documented 36 FGI and plFGI Report 2002 September 2002 Appendix B Topics for improvement This is a full list of all topics for improvement on the DataTranslation and PixeLINK Frame Grabber Interfaces B 1 DataTranslation FGI e Polishing show the settings for device specific functions in the device information structure B 2 PixeLINK FGI e plGrab Implementation of the 5 other ways to call plGrab moviematrix plGrab handle imgmatrix imgmatrix moviematrix plGrab handle plGrab handle imgmatrix plGrab handle imgmatrix moviematrix plGrab handle imgmatrix moviematrix scaling factor plGrab Addition of RGB48 format for 16 bit captures plGrab Testing the plGrab function with a colour camera this should work plGrab Loop optimalisations plGrab Capture a RAW image directly into the left hand array plhs of the mexFunction plOpen Use plError after the call to PimMegaGetNumberDevices instead of non standard error code plSet Implementation of PimMegaSetOverlayCallBack plSet Implementation of PimMegaSetPreview Window plSet Implementation of PimMegaAutoExposure plDevices In remove the inner for loop tries to copy one entry more than needed When having 32 camera s open this could result in a segf
152. nput arguments Examples m plGet m value plGet m Timeout m plGet 75122 value plGet 75122 Timeout e plGrab DLL name Syntax imagematrix plGrab handle or imagematrix plGrab serialnumber plGrab grabs a frame from the PixeLINK camera device and places it into an mxArray Input prhs 0 struct handle for the device or U32 serial number of the device Remarks It will be verified whether the input is a valid handle or number plGrab will then try to capture and return an image If there is not enough free memory the device is not open does not exist or returns an error code and error message is printed and plGrab exits plhs 0 2 mxArray grabbed frame Examples im plGrab m im plGrab 75122 plFGI User Manual September 2002 e plisOpen DLL name plIsOpen dll Syntax plIsOpen handle or plIsOpen serialnumber Description plIsOpen checks whether the device has been opened It returns 0 if the device Input prhs 0 struct device handle or U32 serial number of the device Remarks It will be verified whether the input is a valid handle or number If the camera was unplugged from the computer without being closed first this function will still show it as being open Output plhs 0 double 0 if the camera device is not open 1 if the camera device is open Examples boolean plIsOpen m boolean plIsOpen 75122 e plOpen DLL name plOpen dll Syntax han
153. nts task 4 case 3 if serialnumber deviceid getpar has 3 arguments task serialnumber parameter name stremp task add if deviceCount gt 32 mexErrMsgTxt Maximum number of open devices 32 reached Nn deviceArray deviceCount serialNumber serialnumber deviceArray deviceCount deviceID int mxGetScalar prhs 2 deviceArray deviceCoun t grabColorConversion BAYER_3BY3_COLOR deviceArray deviceCount grabOutputType RAW deviceCount else if stromp task getpar allocate memory for parName string and get the 3rd argument buflen mxGetM prhs 2 mxGetN prhs 2 sizeof mxChar 1 parName char mxCalloc buflen sizeof char mxGetString prhs 2 parName buflen initialise return value plhs 0J mxCreateDoubleMatrix 1 1 mxREAL y mxGetPr plhs 0 if strcmp parName GrabColorConversion t 1 for i 0 i lt deviceCount i if deviceArray i serialNumber serialnumber y 0 double deviceArray i grabColorConversion t 0 break found a matching serialnumber end search Tf CE mexPrintf Internal error getpar called with unknown serial number d serialnumber mexErrMsgTxt Mn else if strcmp parName GrabOutputType t 1 for i 0 i lt deviceCount i if deviceArray i serialNumber serialnumber y 0 double deviceArray i grabOutputType
154. number in the open device array As soon as a matching entry is found the return value is set to 1 and the loop is left using a break statement get deviceld plDevices get serialnumber Input prhs 0 string get prhs 1 2 U32 serialnumber Output plhs 0 int devicelD if the device is open if the device is closed plDevices remove 75122 This task returns the device ID for a given serial number It works the same way as isopen except that the return value is set to 1 and as soon as a matching entry is found the return value is set to the appropriate device ID e Jarguments add plDevices add serialnumber deviceID adds a device to the open device array Input prhs 0 string add prhs 1 U32 serialnumber prhs 2 int deviceID Output plDevices add 75122 256085040 This task adds a new device to the open device array First it is checked whether there is still room in the array to store the information of one more open device If the array is full an error message is printed and plDevices is terminated If there still is room the entry after the last entry of the open device array index deviceCount because array indexing starts at deviceCount 1 is filled with the device ID given in the third argument and suitable default values for the parameters After that deviceCount is incremented 22 plFGI Technical Guide September 2002 getpar
155. of the device prhs 1 string name of the parameter optional prhs 2 n value of the given parameter optional It will be verified whether the input is a valid handle or number If it is not an error message will be printed plSet will then try to write the specified parameter If the parameter does not exist the value is out of range under the given circumstances or if the device returns an error code an error message is printed and plSet exits A list of all possible parameters is printed on the screen with 1 input argument The possible values of the parameter are printed on the screen with 2 input arguments plSet m plSet m Timeout plSet m Timeout value plSet 75122 plSet 75122 Timeout plSet 75122 Timeout 1024 plSet m SubWindowSize PCS2112 NO DECIMATION 480 640 M plFGI User Manual September 2002 24 Notes on plGrab The properties of the grabbed image depend on several parameters For most parameter settings a good overview is given in the PixeLINK manuals Two parameters are not covered directly by those manuals GrabColorConversion and GrabOutputType The setting of GrabOutputType default RAW determines what image format should be returned The following settings are possible e RAW returns the image exactly as produced by the camera row major array one position for every pixel Colour images are returned as a Bayer pattern e IMAGE returns an mxArray
156. of two reasons First this makes it possible to use the function mexLock to keep the file in memory even after typing clear all or clear mex This also eliminates the need of having to do the memory management ourselves The other reason is that for testing purposes it is convenient to be able to call plDevices directly from Matlab The users of the pIFGI however should not use this feature The open device array plDevices maintains the open device array This is an array of structures of type struct U32 serialNumber int deviceID U32 grabColorConversion int grabOutputType In this global array of structs the device ID handle to the device and the parameters GrabColorConversion and GrabOutputType are stored for every open device The serial number of the device is used to uniquely identify the device This is the number returned by PimMegaGetSerialNumber which is called by plOpen immediately after initialising the device The workings of plDevices For every open device the following information is stored in the open device array described above The device s serial number the device s ID which is used by the PixeLINK API to identify the device the GrabColorConversion parameter and the GrabOutputType parameter Another global variable deviceCount is incremented every time a device is opened and decremented every time a device is closed thus counting the number of open devices First mexLock is called to
157. oint format Range from 1 7E 308 to 1 7E 308 Used with the pIFGI for passing all variables that are marked U32 int or double The U32 and int designations used below in this document are only used for indicating the allowed range 32 bit unsigned or signed integer of the passed variable e uint8 8 bit unsigned integer Used by the plFGI within an mxArray for returning a grabbed image e uintl6 16 bit unsigned integer Used by the pIFGI within an mxArray for returning a grabbed image e struct An array containing fieldnames string and their values any type Used by plFGI for the device handle structure e mxArray The default way of storing arrays of any data type in Matlab Data is stored in column major format Used by the plFGI for returning a grabbed image and for storing the device s handle structure 22 About the camera s serial number The camera s serial number is used as a unique identifier for opening and using the camera The PixeLINK camera we used for testing the pIFGI had as many as 3 different serial numbers One serial number on a sticker on the board the image sensor was mounted on this number is returned in the HardwarelInfo structure and also used in the PixeLINK application that comes with the camera Another serial number is on the board on which the other electronics of the camera are located The third serial number is returned when you get the serial number using the function PimMegaGetSerialNumbe
158. om in the array to store the information of one more open device If the array is full an error message is printed and plDevices is terminated If there still is room the entry after the last entry of the open device array index deviceCount because array indexing starts at deviceCount 1 is filled with the device ID given in the third argument and suitable default values for the parameters After that deviceCount is incremented This task reads the value of the given device parameter from the open device array First the third argument which should be a string with the name of the requested parameter is loaded into the parName variable then the return value which should be a double is nitialised It is determined which parameter should be returned by using strcmp in an if then else if else construction The procedure is the same for every parameter A temporary boolean variable t is used to indicate whether a matching serial number was not found It is set to 1 then a for i O to deviceCount 1 loop is entered As soon as a matching serial number is found the requested parameter is stored as return value t is set to 0 and the for loop is terminated using a break statement Finally if t still has value 1 an error message is printed stating that the requested serial number could not be found darguments setpar This task writes the given value of the given device parameter in the open device array Its internal structure is
159. on mexLock to keep the file in memory even after typing clear all or clear mex This also eliminates the need of having to do the memory management ourselves The other reason is that for testing other functions it is convenient to be able to call plDevices directly from Matlab The users of pIFGI however should not use this feature 18 FGI and plFGI Report 2002 September 2002 6 3 8 Functions of plDevices The plFGI functions can call plDevices to manipulate the open device array to check whether a device has been opened and to get the settings stored in the open device array For this plDevices provides the following functions e print prints a list of open devices with SerialNumber DeviceID GrabColorConversion and GrabOutputType remove removes a device from the open device array e isopen checks whether a device has been opened e get returns the device ID handle to the device of a camera e add adds a device to the open device array e getpar returns the value of the specified parameter e setpar sets the value of the specified parameter Although plDevices is not meant to be called directly from Matlab in the next part the syntaxes and examples are written down as if it were because this way it is easier to denote and understand the usage of the left hand and right hand side arguments e print Description prints a list of open devices with SerialNumber DeviceID GrabColorConv
160. opened or not It will return a double acting like a Boolean Output The function will return a double indicating the status of frame grabber device If the function returns 1 the frame grabber has been opened otherwise the function returns zero IsopenfgCDT3155 e Gethandlefg Geihandierg d Gethandlefg alias Description This function will return the device information structure of the frame grabber device when you lost the handle to the device The alias of the frame grabber The user is supposed to know this alias Output The function will return the device information structure of the opened Frame grabber device with the given alias m2 gethandlefg DT3 155 FGI and plFGI Report 2002 September 2002 4 Updating FGI 2000 One part of the assignment was to update and bug fix the original FGI system At first this included fixing the clear all bug and to do some polishing Later the proper release of the device driver s resources was added In this chapter these problems will be explained and the solutions will be given 4 1 The clear all bug One of the problems with FGI was the loss of handles to open devices when typing clear all in Matlab The clear all command in Matlab removes all variables functions and MEX files from the Matlab memory leaving the workspace empty When this command is used the variables in which the device structures are stored and the ME
161. or creating pIFGI we used Microsoft Visual C 6 0 for writing the source files as well as for compiling and linking We used the following procedure to create a project with the correct settings e Create a new DLL project File gt New Projects Win32 Dynamic Link Library A DLL that exports some symbols e Throw away StdAfx cpp StdAfx h and Projectname h e Disable precompiled headers Project Settings C C Category Precompiled Headers Not using precompiled headers e Link the necessary libraries Project Settings Link Category General Object library modules YsAsoft95 matlab6 extern lib win32 microsoft msvc60 libmex lib Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib Y A software framegrag pixelink api pimmegaapi lib e Export the mexFunction Project Settings Link Category General Project Options export mexFunction e Implement Projectname cpp starting with the following template define WIN32_ LEAN AND MEAN This excludes rarely used stuff from Windows headers We don t know what that means exactly but it is generated by MS Visual C when you create a project and we just copied it Ag include lt windows h gt include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib 7 Oei Kap 1998 p
162. ould have discovered earlier that our original design would not work out This would have saved us the time of implementing the command and control layer which are unused in the end Working on this project is not the only thing we enjoyed during our stay here We also had a lovely time in a different country during which we learned a lot about the Czech culture and especially the beautiful city of Prague 33 FGI and plFGI Report 2002 September 2002 Table of figures FIGURE 1 GLOBAL ARCHITECTURE 1 eee eene en e nennen se ese e ee te esee se ener een en sees 2 FIGURE 2 DT3152 FRAME RABBER sas nia dn ETEEN EE EA EEEIEE NOE EOS 3 FIGURE 3 DT OPEN LAYERS ARCHITECTURE eene hne hee hes hse eese rris ee eerte nenne 3 FIGURE 4 MEGAPIXEL FIREWIRE CAMERAS cesses hehe hehe hehe hhee enn aree n erre ee earned 4 FIGURE 5 PIXELINK SOFTWARE ARCHITECTURE eee hehe hehe enses eren eres 4 FIGURE 6 OVERVIEW OF THE ORIGINAL FRAME GRABBER INTERFACE RN 5 FIGURE 7 OVERVIEW OF THE ORIGINAL DESIGN OF THE NEW SYSTEM ce 11 FIGURE 8 IMPLEMENTATION OF A DSI 12 FIGURE 9 STRUCTURE OF PLOT 14 34 FGI and plFGI Report 2002 Bibliography Ammeraal 1993 DataTrans 1996 Heil Waut 2000 MathWorks 1998 1 MathWorks 1998 2 Oei Kap 1998 Planz 1989 Vitana 2002 1 Vitana 2002 2 September 2002 AMMERAAL LEEN 1993 Ansi C Academic Service B V Schoonhoven DATA TRANSLATION March 1996 Frame Gra
163. p mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 ImagerChipId tmp Imager Clocking nRetValue PimMegaGetImagerClocking deviceld amp imagerClockingValue if ApiSuccess nRetValue i if imagerClockingValue 0x00 tmp mxCreateString 0x00 External 16MHz No division SE if imagerClockingValue 0x01 tmp mxCreateString 0x01 External 16MHz Division by 2 um if imagerClockingValue 0x02 tmp mxCreateString 0x02 External 16MHz Division by 4 Ears if imagerClockingValue 0x80 i tmp mxCreateString 0x80 Internal 24MHz No division Elus if imagerClockingValue 0x81 tmp mxCreateString 0x81 Internal 24MHz Division by 2 48 FGI and plFGI Report 2002 September 2002 else if imagerClockingValue 0x82 tmp mxCreateString 0x82 Internal 24MHz Division by 4 else tmp mxCreateString Unknown value else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 ImagerClocking tmp Imager Name imagerNameValue char mxCalloc 81 sizeof char nRetValue PimMegaGetImagerName deviceld imagerNameValue if ApiSuccess nRetValue i tmp mxCreateString imagerNameValue else if ApiNotSupportedError nRetValue tmp mxCreateString Un
164. p mxCreateString PCS2112 NO DECIMATION Sch else if subWindowSizeDecimationValue PCS2112 DECIMATE BY 2 tmp mxCreateString PCS2112 DECIMATE BY 2 else if subWindowSizeDecimationValue PCS2112 DECIMATE BY 4 tmp mxCreateString PCS2112 DECIMATE BY 4 eise tmp mxCreateString Unknown value tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 subWindowSizeWidthValue tmp3 mxCreateDoubleMatrix 1 1 mxREAL tmppr3 mxGetPr tmp3 tmppr3 0 032 subWindowSizeHeightValue fieldnames 0 SubWindowSizeDecimation fieldnames 2 SubWindowSizeWidth fieldnames 1 SubWindowSizeHeight m mxCreateStructMatrix 1 1 3 const char fieldnames mxSetField m 0 SubWindowSizeDecimation tmp mxSetField m 0 SubWindowSizeWidth tmp2 mxSetField m 0 SubWindowSizeHeight tmp3 else if stromp parametername Timeout Timeout nRetValue PimMegaGetTimeout deviceld amp timeoutValue if plError nRetValue getting Timeout value mexErrMsgTxt Mn m mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr m tmppr 0 U32 timeoutValue else if stromp parametername VideoMode Video Mode nRetValue PimMegaGetVideoMode deviceId amp videoModeValue 73 FGI and plFGI Report 2002 September 2002 if plError nRetValue getting VideoMode value mexE
165. pdates ORK ROKK KK Ck kOk Ck Ck kCk Ck k kc k Ck kc kc k k kc k Ck k kc K Ck kc k Ck k kc k Ck kc k Ck k kc k k kc k k k kc k kokok ck kok ck ck kok ck k ke x x k x define RAW 0x0 define IMAGE 0x1 define RGB24 0x2 109 FGI and plFGI Report 2002 Appendix E Test results September 2002 Below are the screen printouts of the tests performed on pIFGI gt gt plset m DataTransferSize DATA 8BIT SIZE gt gt tic for E es 65 8000 gt gt plset m SubWindowSize PCS2112 NO DECIMATION i 1 100 y plgrab m end t toc oF LAG for 29 6600 gt gt plset m SubWindowSize PCS2112_NO_DECIMATION i1 1 100 y plgrab m end t toc o gt tic for C 17 3000 gt gt plset m SubWindowSize PCS2112 NO DECIMATION i 1 100 y 2plgrab m end t toc gt gt tcs for Ti 55 8000 gt gt plset m SubWindowSize PCS2112 NO DECIMATION i 1 100 y plgrab m end t toc gt gt tid for E e 52 7800 gt gt plset m ExposureTime 1 gt gt tic for ee 51 3500 gt gt plget m ans DeviceID BlueGain CurrentFrameRate DataTransferSize Exposure ExposureTime Gamma Gpo GreenGain HardwareVersion ProductID HardwareVersion SerialNumber HardwareVersion FirmwareVersion HardwareVersion FpgaVersion ImagerChipId ImagerClocking ImagerName ImagerType MonoGain PreviewWindowPos Top PreviewWindowPos Left PreviewWindowSize Height i 1 100 y pl
166. plSet m SubWindowSize PCS2112 DECIMATE BY 2 200 320 plSet m GrabOutputType IMAGE plSet m GrabColorConversion BAYER VARGRAD COLOR im plGrab m plSet m GrabColorConversion BAYER ADAPT MONO im2 plGrab m piClose m image im waitforbuttonpress image im2 The following example will capture 100 images and display them on the screen one after the other as in a movie It is presumed that the camera is already open with handle h that all parameters are set correctly and that it will be closed later Note the tic and toc Matlab functions can be used to measure the average frame rate To measure the pure grabbing speed without the time Matlab needs to display the image just leave out the line with image i for im 1 100 im plgrab m image im end ll plIFGI Technical Guide September 2002 PARTI TECHNICAL GUIDE 1 Introduction to pIFGI development 1 1 The plFGI distribution package The pIFGI distribution package currently consists of 3 folders bin contains all dll and m executable files doc contains all documentation src contains the source code and project files used for building the plFGI In every folder and subfolder a readme txt file is present in which all files that should be in the folder are listed along with the purpose they are for 1 2 Building pIFGI plFGI was built using the Microsoft Visual C 6 0 Integrated Development Environ
167. ptember 2002 i if plError nRetValue setting ImagerClocking mexErrMsgTxt Mn ImagerName else if strcmp parametername ImagerName buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen if buflen gt 81 mexPrintf plSetValue Error setting ImagerName string too long n mexPrintf ImagerName should not exceed 80 characters Mn mexErrMsgTxt Mn set the value nRetValue PimMegaSetImagerName deviceld tmpstring if plError nRetValue setting ImagerName mexErrMsgTxt Mn MonoGain else if strcmp parametername MonoGain tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt PCS2112_MAX_GAIN mexPrintf plSetValue Error setting MonoGain value too large n mexPrintf MonoGain value should not exceed lu n PCS2112 MAX GAIN mexErrMsgTxt Mn set the value nRetValue PimMegaSetMonoGain deviceld tmpU32 if plError nRetValue setting MonoGain mexErrMsgTxt Mn OverlayCallBack else if stromp parametername OverlayCallBack TODO mexErrMsgTxt PimMegaSetOverlayCallBack not supported yet n PreviewColorConversion else if strcmp parametername PreviewColorConversion
168. r the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGrab is terminated The serial number is now used to obtain a PixeLINK API device ID by calling plDevices Using PimMegaStartVideoStream the video stream is opened Behind every call to a PixeLINK API function plError is used to check for an error If an error occurs while the videostream is supposed to be active PimMegaStopVideoStream is called before terminating Now it is checked whether the camera is in video mode if it is not a warning is printed to the screen and the camera is set to video mode Video mode is used because still mode requires special lighting conditions or a shutter to control the exposure time After this the program gets some camera parameters and settings get imagerType colour or monochrome get dataTransferSize 8 bit or 16 bit format get decimation width and height of the current subwindow calculate pixelWidth pixelHeight according to the rules in the PixeLINK Megapixel FireWire Camera Developer s Manual e get GrabColorConversion and GrabOutputType parameters using plDevices Using the above parameters 3 arrays must set up e The capture array in which the PixeLINK API stores the raw image returned by the camera This array has the same number of elements either 8 or 16 bit unsigned integers as the image has pixels pixelW
169. r This last number is the one we decided to use as official serial number on basis of the PixeLINK documentation suggesting this If you don t know what serial number the camera you want to use has call plOpen with a non existing number to get a listing of the serial numbers of all cameras that are attached to the computer plFGI User Manual September 2002 A23 TheplFGl functions The plFGI supports the following functions in alphabetical order e plClose closes a PixeLINK camera e plGet gets the value of a camera or image processing parameter or the complete handle structure of the camera e plGrab grabs an image from a PixeLINK camera e plIsOpen checks if a PixeLINK camera is already open e plOpen opens a PixeLINK camera and return its handle structure or only returns its handle if the camera was already open e plSet sets the value of a camera or image processing parameter or shows the possible parameters or values Nota bene In Matlab the function names are not case sensitive although it may be easier to read back code if cases are used Below descriptions are given of each of the plFGI functions callable from Matlab For a description of plDevices which is used as an internal function we refer to the technical documentation In the descriptions below prhs 0 is used to indicate the first input parameter prhs 1 for the second input parameter prhs 2 for the third etcetera Similarly plhs 0 is used to
170. rField mxGetField prhs 0 0 SerialNumber serialNumber U32 mxGetScalar serialNumberField else if mxIsDouble prhs 0 serialNumber U32 mxGetScalar prhs 0 else mexPrintf PixeLINK Interface error n mexPrintf plSet Wrong argument given n mexPrintf First argument should be the device handle or the serial 92 FGI and plFGI Report 2002 September 2002 number n mexErrMsgTxt Mn check whether the device has been opened rhs 0 mxCreateString isopen rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber mexCallMATLAB 1 lhs 2 rhs plDevices isOpen int mxGetScalar lhs 0 if isOpen mexPrintf plSet Device with serial number lu has not been opened n serialNumber mexErrMsgTxt Mn 1 argument give list of possible parameters if nrhs 1 mexPrintf Possible parameters if supported n mexPrintf BlueGain DataTransferSize Nn mexPrintf Exposure ExposureTimeNn mexPrintf Gamma Gpo Nn mexPrintf GreenGain ImagerClocking n mexPrintf ImagerName MonoGain n mexPrintf OverlayCallBack PreviewColorConversion n mexPrintf PreviewWindow RedGain n mexPrintf Saturation SubWindow n mexPrintf SubWindowPos SubWindowSizeNn mexPrintf Timeout VideoMode n mexPrintf GrabColorConversion GrabOutputType n else 2 or 3 arguments get
171. rabbers they were using In 1998 two students from Delft University of Technology developed a Frame Grabber Interface FGI to provide a communication layer between Matlab and the Frame Grabber SDK of Data Translation s DT Open Layers family In 2000 two other students from Delft bug fixed and extended FGI Our task was to fix a few other bugs in FGI and to implement a Matlab interface to provide support for cameras from he PixeLINK family This interface should provide the same functionality for the PixeLINK cameras as the existing FGI does for the Data Translation Frame Grabbers If possible without losing any functionality the same commands should be used from within Matlab to communicate with both DT and PixeLINK cameras Chapter 2 starts with a description of the background to this problem An overview of the Matlab environment and the Data Translation Frame Grabber and PixeLINK interfaces is given Chapter 3 describes the original Frame Grabber Interface as it was after the FGI 2000 project The 4th chapter describes the updates and bug fixes we made to the original FGI system Chapter 5 describes the architecture we originally had in mind for the new system In this system the interfaces for the DataTranslation and PixeLINK frame grabbers are integrated into one system Because of several reasons this is not the system we finally implemented In chapter 6 the implementation of the new system which provides support for only the PixeLINK frame
172. re If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGet is terminated After the serial number has been obtained it is checked whether the device is open by calling plDevices The result of the call to plDevices is stored in the return array of plIsOpen 6 4 5 plOpen Description plOpen opens a PixeLINK camera device and returns the device s handle If there is no camera with the given serial number a list of available serial numbers is printed plOpen is the MEX function which takes care of opening a PixeLINK device for use with the other pIFGI functions First it is tested whether the input argument is a number if it is not the function terminates printing an appropriate error message using mexErrMsgTxt Then it is checked whether the device is open by calling plDevices If the device is already open the else part of the if construction is executed printing a warning message then calling plCreateDeviceHandle and returning the handle If the device was not open a call to PimMegaGetNumberDevices is made to get the amount of available devices When no devices are attached plOpen exits with an appropriate error message When one or more devices are attached a for loop is entered to open every devic
173. rent devices in different ways This would not be very nice since then it would be necessary to move device specific code to the control layer which was meant to remain the same even after adding new device types Another possibility is to move fgdevices to the device specific layer This however would also mean that all functionality has to be taken out of the command layer and moved to the device specific layer which would leave the command layer rather useless It would still provide a uniform interface to the Matlab users but it would also mean a lot of unnecessary overhead when calling one of the functions This would not be much of a problem when the user would only have to grab one image but when grabbing 1000 images in a loop for example it would save a lot of time to call the device specific interface immediately This is the reason why in the end we decided not to implement this original design Instead we implemented plFGI in the same way as the old FGI system for the DataTranslation frame grabbers How this system is implemented is described in the next chapter 13 FGI and plFGI Report 2002 September 2002 6 Implementation of the PixeLINK Frame Grabber Interface This chapter describes the implementation of the PixeLINK Frame Grabber Interface pIFGD which is very much similar to the original FGI system for the DataTranslation frame grabbers The system is composed of several MEX functions which are callable from Matlab It
174. rintPossibleValues cpp As Authors L I Oei M A E Bakker Date 2002 08 06 Updates ROKK KKK RK kk CkCk kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k Ck kc k Ck k kc k k k ck k Ck k ck kokock ck kok ck kokok ck k ke x x d void plPrintPossibleValues char parametername 91 FGI and plFGI Report 2002 D 15 plSet cpp ORK ROKK KK kk Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc Kk Ck kc k Ck k kc k k kc k Ck k kc k k k ck k k kc k k k ck ck kok ck kokok ck k kx x kx x d Filename plSet cpp 5 Description Source code for the function plSet xn Authors M A E Bakker L I Oei maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 06 Updates avd ORK kk hh E Ck Ck k kc k Ck kc kc k Ck kc K Ck k A k kc k Ck kc k Ck k kc k Ck k kc k A A KK I d plSet sets the value of a given parameter When 1 argument is given a list of all possible paramters is given When 2 arguments are Ref given the possible values of the given parameters are given SCH Jak kk KR kOk Ck Ck kCk Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k Ck Ck k kc IA e kok ck kokok ck kok ck eR e d Input prhs 0 struct handle for the device or A int serial number of the device prhs 1 string name of the parameter optional PA prhs 2 n value of the given parameter optional K Output A list of all possible paramters with 1 argument The poss
175. rintf mexPrintf 1 mexPrintf 2 mexPrintf 3 mexPrintf E mexPrintf mexPrintf Cplusplus extern C 94 FGI and plFGI Report 2002 September 2002 D 16 plSetValue cpp ORK RK KR KK kk Ck Ck kOkCk Ck kCk Ck kCk k Ck kc k Ck k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k k ck k k k ck k kock ck kok ck kokok ck k k x x A x d Filename plSetValue cpp 5 Description Source code for plSetValue uy Authors M A E Bakker L I Oei maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 09 Updates aed ROR KKK KR E E Ck kc k Ck k kc kCk k kc K Ck kc k Ck k kc k Ck kc k Ck k kc k Ck A A I ck he d plSetValue sets the value of a given parameter E ORK KKK kk Ck kk Ck Ck kOkCk Ck k Ck Ck k kc k Ck k kc k k kc k Ck k kc k Ck kc k Ck k kc k k kc k Ck k kc k k kc k k Ck k ck kckock ck kok ck kokok ck k ke kx A x Input serialNumber U32 serialNumber of the device Tu parametername string name of the parameter va nvalues int number of values be values mxArray mxArray with values Tu Output Syntax plSetValue serialNumber parametername nvalues values ORK KKK KK KK Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k Ck Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k ck kok ck ck kok ck kokok ck k ke x kx A x include lt windows h gt include y soft95 matlab6 extern include mex h include Y software framegrag pixelink api pimmegaapiuser h includ
176. rintf Buffersize is too small n mexErrMsgTxt Unable return to grab an image Nn destroyFrameOnErrorExit OLT IMG DEM ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Pointer supplied is NULL n mexErrMsgTxt Unable return to grab an image Nn destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2002 07 03 mexPrintf Unknown error n mexErrMsgTxt Unable return 41 to grab an image n FGI and plFGI Report 2002 September 2002 Appendix D Source code of pIFGI D 1 plClose cpp ORK RK KR kk Ck kk kk kOkCk kk k Ck k kc k Ck kc k Ck k kc k Ck k kc Ck k Ck Ck k kc k k kc kc k k kc k k ko k k k kc k kokok ck kok ck ck kok He x k amp x d Filename plClose cpp Lue Description Source code for the function plClose rd Authors M A E Bakker L I Oei ZS maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 07 Updates ut ORK KK KR kk Ck Ck kOk Ck Ck kCk Ck k kc k Ck kc kc k k kc k Ck kc kc k Ck kc k Ck k kc k Ck kc k Ck k kc k k k ck k kok ck kokok ck kok ck kokok ck k ke e kx A x d plClose closes a pixelink device x ORK KKK KKK Ck kOk Ck Ck k Ck Ck k kc k Ck kc k Ck k kc K Ck k kc K Ck kc k Ck k kc k k kc k Ck k kc k k kc kc k k k ck kokock ck kok ck ck kok ck k ke x kx rd Input prhs 0 mxArray handle of the device X U32 serial number of the device Output wh Syntax plClose handle or plClose
177. rname Description This function returns an updated structure with the device information or a parameter from the device information structure Output The function returns an updated device information structure or the chosen Input The device information structure devinfo of the opened frame grabber and the chosen parameter parname parameter from the device information structure Getfg m or getfg m frameheight Selfg DLL name Setfg dll Setfe devinfo parname parvalue OR setfg devinfo Description This function sets a parameter in the device information structure Setfg m lists all the possible variables Input The device information structure evinfo of the opened frame grabber the chosen parameter parname and the new value parvalue of the chosen parameter Setfg m frameheight 400 or setfg m FGI and plFGI Report 2002 September 2002 e Resetfg Rescifg di resetfg devinfo This function resets a DT frame grabber device The device information structure devinfo of the opened frame grabber reset zm e Loadfg Ga Loadfg devinfo filename Description This function loads set ngs from an ini file into the device information structure Input The device information structure devinfo of the opened frame grabber and the a filename of the settings file full path Isopenfg Description This function will let the user check whether the frame grabber device has been
178. ror occurred if so the program is terminated If everything went all right the pointer to the matlab array is set When needed memory is allocated for the RGB24 array Now the image is captured by making a call to PimMegaReturnVideoData and the videostream is closed using PimMegaStopVideoStream For postprocessing two possibilities are distinguished using an if else construction e The first possibility occurs in case of a RAW image An 8 bit RAW image is copied into the matlab array using memcpy a 16 bit RAW image is converted to have all 10 significant bits in the right order according to the PixeLINK Megapixel FireWire Camera User s Manuaf The 2 most significant bits of the first byte are shifted to be the 2 least significant bits The second byte is shifted 2 bits to the left multiplied by 4 then the two bytes are added equivalent to a logical and operation e The second possibility occurs in case of an IMAGE or RGB24 output Depending on 8 versus 16 bits and black white versus colour one of the PimMegaConvert functions is called to convert the captured image to a 24 bits per pixel image For colour images the GrabColorConversion parameter is used to determine the algorithm to be used by the PimMegaConvert function The result of PimMegaConvert is stored into the RGB 24 array If the GrabOutputType is set to RGB24 the RGB24 array is directly copied into the matlab array using memcpy In case of an IMAGE type however the
179. rors that are always considered critical Where appropriate the program can decide on this information to continue or to terminate e Suggestions for improvement The entire building of the string used in The device s API encountered can be moved within the following if result ApiSucces condition 6 4 10 plGetValue plGetValue is a subroutine which is linked to the plGet MEX function When given an mxArray for returning the parameter value the device s serial number and the name of the parameter to be returned it will return the parameter s value or values in the given mxArray 27 FGI and plFGI Report 2002 September 2002 plGetValue is very similar to plCreateDeviceHandle The most important difference is that not all possible parameters of the device are obtained but only the parameter or structure of which the name was given This is accomplished by using an if elseif construction together with multiple strcmp statements An obvious difference is that the mxArray m can differ in size according to the parameter that is stored in it When an unknown parameter name is given plGetValue prints a list of known parameter names to the screen 6 4 11 plSetValue plSetValue is a subroutine linked to the plSet MEX function It needs 4 or more input arguments the serial number of the device the name of the parameter to be set the number of values that are passed all values that are needed to set the parameter Firs
180. rred several times A subroutine was added to properly release resources A call to this subroutine is made every time before a call to mexErrMsgTxt in a place problems could occur 44 Other changes to the original FGI system While solving the problems mentioned above we noticed a few other things that could be changed easily to improve grabfg More descriptive error messages in grabfg To make the source more readable we had already changed the layout of the source code After making the changes mentioned above we noticed that the error messages after calling the Open Layers SDK to acquire a frame were very undescriptive so we added several new ones Documentation of grabfg While we were working on the source code and checking the documentation we noticed that not all six different syntaxes for calling grabfg were documented so we fixed that as well Some parts of the source code of grabfg are given in Appendix C to show the changes 10 Matlab user interface 1 EE a ot il ee es sebo cea Rh coe er ite e SUE Ez 1 1 1 V layer de epp eS eer dou d i 1 L FGI and plFGI Report 2002 September 2002 5 Original design of the new system This chapter describes the original design of the new FGI system First an overview is given Then the functions of the three layers command layer control layer and device specific layer are described Finally we explain why we did not implement this system 5 1 Overview
181. rror nRetValue setting PreviewColorConversion mexErrMsgTxt Mn PreviewWindow else if strcomp parametername PreviewWindow TODO mexErrMsgTxt PimMegaSetPreviewWindow not supported yet n RedGain else if strcmp parametername RedGain tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt PCS2112_MAX_GAIN mexPrintf plSetValue Error setting RedGain value too large n mexPrintf RedGain value should not exceed lu n PCS2112 MAX GAIN mexErrMsgTxt Mn set the value nRetValue PimMegaSetRedGain deviceld tmpU32 if plError nRetValue setting RedGain mexErrMsgTxt Mn Saturation else if stromp parametername Saturation tmpU32 U32 mxGetScalar values 0 check whether the given value is within the correct range if tmpU32 gt OxFF mexPrintf plSetValue Error setting Saturation value too large n mexPrintf Saturation value should not exceed OxFF n mexErrMsgTxt Mn set the value nRetValue PimMegaSetSaturation deviceId tmpU32 if plError nRetValue setting Saturation mexErrMsgTxt Mn SubWindow else if strcmp parametername SubWindow tmpU32 PCS2112_NO_DECIMATION 102 FGI and plFGI Report 2002 September 2002 uDecimation buflen mxGetM values 0 mxGetN
182. s fixed and the device driver s resources are released properly More descriptive error messages are added and the documentation of grabfg is improved The polishing problem still remains unsolved though For the PixeLINK cameras plFGI is implemented It supports most basic functionality to open and close a device check whether a device is opened get and set a number of parameters and grab an image from the camera Unlike the original FGI system it only provides 1 way to call plGrab instead of the 6 ways to call grabfg Also it has no eset function because the PixeLINK API does not provide this We made a full list of topics for improvement which is included in Appendix B We both enjoyed working on this project very much For both of us this was the first time to put into practice everything we had learned during our studies and it is nice to see that we were able to finish this project successfully It is a pity that it took us so long to find out how to work with de We might have been able to deliver a program with more functionality if that had not taken us so much time Also it might have been a good idea to start working on the device specific layer first instead of the command and control layer since that part involved most of the things unknown to us Programming the command and control layer was a rather straightforward task the effort of which was easier to estimate If we had started with the device specific layer we w
183. s open with a call to plDevices If it is not open the else part of the if isOpen construction is executed and the function terminates with an error message If it is open again a call to plDevices is made this time to obtain the PixeLINK API s device ID Then the PixeLINK API function pimMegaUninitialize is made to close the device When an error occurs closing the device the standard error handling code in plError returns a non false value and the plClose function exits If all went well the device should now be closed and a call to plDevices is made to update the list of open devices A23 Description of plGet plGet is the MEX function which is used for obtaining the value of a parameter a set of parameters or a complete device handle for a PixeLINK device First it is tested whether 1 or 2 arguments were given If not the else part of the check is executed resulting in an error message and the termination of plGet by using the Matlab call mexErrMsgTxt The first argument is either a serial number or a device handle structure If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGet is terminated After the serial number has been obtained it is checked whether the device is open
184. serialnumber ORK KK KK Ck Ck kOk Ck Ck k Ck Ck k kc k Ck kc kc k k kc k Ck k kc k Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k ck k kok ck kokok ck kok ck kokok I ke xe kx A x d define WIN32 LEAN AND MEAN Exclude rarely used stuff from Windows headers include windows h include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include yY software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib include plError h ifdef _ cplusplus extern C endif void mexFunction int nlhs mxArray plhs int nrhs const mxArray prhs PXL_RETURN_CODE nRetValue the return codes of the pixelink functions mxArray serialNumberField U32 serialNumber 1 the serial number of the device HANDLE deviceld the deviceId PimMegaInitialize returns mxArray lhs 1 rhs 2 to call fgdevices double px int isOpen 0 prhs 0 should be the device handle struct or serial number int if nrhs 1 get the serialNumber if mxIsStruct prhs 0 serialNumberField mxGetField prhs 0 0 SerialNumber serialNumber U32 mxGetScalar serialNumberField else if mxIsDouble prhs 0 serialNumber U32 mxGetScalar prhs 0 else mexPrintf PixeLINK Interface error n
185. software framegrag pixelink api pimmegaapiuser h include plTypes h void plCreateDeviceHandle mxArray U32 serialNumber returnArray l m mxArray structure to be returned as device handle pe LSS mxArray rhs used to call plDevices m lhs 1 rhs 3 double px HANDLE deviceld variable for receiving the error codes the pixelink api functions return PXL RETURN CODE nRetValue int nof int rows int cols char fieldnames 40 number of fields of the device handle structure 1 1 names of the fields of the device handle structure DeviceID BlueGain CurrentFrameRate DataTransferSize Exposure ExposureTime Gamma Gpo GreenGain HardwareVersion ProductID Pre HardwareVersion SerialNumber ImagerChipId ImagerType HardwareVersion FirmwareVersion HardwareVersion FpgaVersion ImagerClocking ImagerName MonoGain PreviewWindowPos Top viewWindowPos Left PreviewWindowSize Height PreviewWindowSize Width RedGain SoftwareVersion SubWindow StartColumn SubWindowPos StartRow SubWindowSize Height VideoMode SubWindow NumberRows SerialNumber SubWindow StartRow SubWindow NumberColumns SubWindowPos StartColumn SubWindowSize Decimation Timeout GrabOutputType Saturation SubWindow Decimation SubWindowSize Width GrabColorConversion DW
186. subWindowNumberColumnsValue subWindowNumberRowsValue N ubWindow value CS2112 NO DECIMATION MO DECIMATION PCS2112 DECIMATE BY 2 DECIMATE BY 2 PCS2112 DECIMATE BY 4 DECIMATE BY 4 value mxREAL lumnValue mxREAL wValue mxREAL olumnsValue mxREAL owsValue iof lumn wills r olumns ows const char fieldnames tion tmp olumn tmp2 ow tmp3 Columns tmp4 Rows tmp5 indowPos amp subWindowPosStartColumnValue amp subWindowPosStartRowValue ubWindowPos value mxREAL FGI and plFGI Report 2002 September 2002 tmppr mxGetPr tmp tmppr 0 U32 subWindowPosStartColumnValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 subWindowPosStartRowValue fieldnames 1 SubWindowPosStartColumn fieldnames 0 SubWindowPosStartRow m mxCreateStructMatrix 1 1 2 const char fieldnames mxSetField m 0 SubWindowPosStartColumn tmp mxSetField m 0 SubWindowPosStartRow tmp2 else if strcmp parametername SubWindowSize Sub Window Size nRetValue PimMegaGetSubWindowSize deviceId amp subWindowSizeDecimationValue amp subWindowSizeWidthValue amp subWindowSizeHeightValue if plError nRetValue getting SubWindowSize value mexErrMsgTxt Mn if subWindowSizeDecimationValue PCS2112 NO DECIMATION tm
187. supported elise tmp mxCreateString Could not get value mxSetField m 0 ImagerName tmp Imager Type nRetValue PimMegaGetImagerType deviceld amp imagerTypeValue if ApiSuccess nRetValue if imagerTypeValue PCS2112M_IMAGER tmp mxCreateString PCS2112M IMAGER Monochrome Camera else if imagerTypeValue PCS2112C_IMAGER tmp mxCreateString PCS2112C IMAGER Color Camera else tmp mxCreateString Unknown value else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 ImagerType tmp Mono Gain nRetValue PimMegaGetMonoGain deviceld amp monoGainValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 monoGainValue 49 FGI and plFGI Report 2002 September 2002 else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 MonoGain tmp Preview Window Pos nRetValue PimMegaGetPreviewWindowPos deviceld amp previewWindowPosLeftValue amp previewWindowPosTopValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 long previewWindowPosLeftValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 m
188. t the serial number is used to obtain the PixeLINK device ID by calling plDevices For every parameter name it is checked using an if stremp construction whether the right number and type of values are given If not a descriptive error message is printed and plSetValue is terminated using a call to mexErrMsgTxt After this another if elseif stremp construction is used to distinguish between the different parameter names For every parameter name the passed values are copied into a variable parsed if necessary and a call is made to the relevant PimMegaSet function For the GrabColorConversion and the GrabOutputType parameters a call is made to plDevices as these are stored there instead of in the PixeLINK API e Errors found in the PixeLINK API documentation Vitana 2002 1 p 92 PimMegaSetSubWindow uStartColumn uNumberColumns must be less than PCS2112 MAX WIDTH uStartRow uNumberRows must be less than PCS2112 MAX HEIGHT less than should be less than or equal to Vitana 2002 1 p 94 PimMegaSetSubWindowPos uStartColumn current number of columns must be less than PCS2112 MAX WIDTH uStartRow current number of rows must be less than PCS2112 MAX HEIGHT less than should be less than or equal to Vitana 2002 1 p 95 PimMegaSetSubWindowSize Current start column Width must be less than PCS2112 MAX WIDTH Current start row Height must be less than PCS2112 MAX HEI
189. t 2002 September 2002 tmp mxCreateString Could not get value mxSetField m 0 RedGain tmp Saturation nRetValue PimMegaGetSaturation deviceld amp saturationValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 032 saturationValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported eise tmp mxCreateString Could not get value mxSetField m 0 Saturation tmp Serial Number nRetValue PimMegaGetSerialNumber deviceld amp serialNumberValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 serialNumberValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 SerialNumber tmp Software Version nRetValue PimMegaGetSoftwareVersion deviceld amp softwareVersionValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 softwareVersionValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 SoftwareVersion tmp Sub Window nRetValue PimMegaGetSubWindow deviceld amp subWindowDecimationValue amp s
190. tember 2002 The serial number is now used to obtain a PixeLINK API device ID by calling plDevices Using PimMegaStartVideoStream the video stream is opened Behind every call to a PixeLINK API function plError is used to check for an error If an error occurs while the videostream is supposed to be active PimMegaStopVideoStream is calle d before terminating Now it is checked whether the camera is in video mode if it is not a warning is printed to the screen and the camera is set to video mode Video mode is used because still mode requires special lighting conditions or a shutter control the exposure time After this the program gets some camera parameters and settings Get imagerType colour or monochrome Get dataTransferSize 8 bit or 16 bit format Get decimation width and height of the current subwindow Calculate pixelWidth pixelHeight according to the rules in the PixeLINK Megapixel FireWire Camera Developer s Manuaf e Get GrabColorConversion and GrabOutputType parameters using plDevices Using the above parameters 3 arrays must set up e The capture array in which the PixeLINK API stores the raw image returned by the camera This array has the same number of elements either 8 or 16 bit unsigned integers as the image has pixels pixelWidth pixelHeight and is arranged as an mxArray of pixel Width pixelHeight e The matlab array which is returned to Matlab In case of a RAW image this array has the same si
191. tf Unknown error n mexPrintf Failed to destroy allocated resources while displayed bel break recovering from the error ow Xn destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Acquisition section of the device still busy n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Unable to communicate with the device n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Timeout waiting for acquisition n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Too much activity on host bus during transfer n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId M Bakker 2 002 07 03 mexPrintf Too much activity waiting on host bus during transfer n mexErrMsgTxt Unable to grab an image n return M Bakker 2 destroyFrameOnErrorExit OLT IMG DEV ID DeviceId FrameId 002 07 03 mexPrintf Invalid Framehandle n mexErrMsgTxt Unable to grab an image n return destroyFrameOnErrorExit OLT IMG
192. the screen and the function is terminated using mexErrMsgTxt Finally the open device array is updated by calling plDevices e Suggestions for improvement Use plError after the call to PimMegaGetNumberDevices instead of non standard error code 2 7 Description of plSet plSet is the MEX function used to change the parameter settings of a PixeLINK device First it is checked whether any arguments are given if not an appropriate error message is printed to the screen using mexPrintf and the plSet is terminated using mexErrMsgTxt If one or more arguments were given the first argument should be either a handle structure or a serial number If it is a double it is stored in the serialNumber variable If it is a struct containing a field with the name SerialNumber the value of this field is stored in the serialNumber variable without further checking If the first argument is another data type an error message is given and plGet is terminated After the serial number has been obtained it is checked whether the device is open by calling plDevices If not an error message is given and plGet is terminated If only one argument was given a list of parameter names is printed on the screen and plSet terminates If a second argument was given it is checked whether this is a string If not plSet is terminated with an appropriate error message If it is a string it is stored in the parametername variable Depending on whether 2 or 3 argu
193. these tests and do some more advanced testing this might be a good subject for future examination In Appendix E the test results are included 32 FGI and plFGI Report 2002 September 2002 Conclusion For eight weeks we have worked on this project In the beginning we both had no experience with Matlab frame grabbers or the C programming language So we first spent a few days reading documentation and studying the existing FGI Very soon we were able to fix the clear all bug The proper release of the device driver s resources which we were asked to do later during our project was not very difficult either Then we made the original design of the new system We implemented most of the command layer and control layer When we started implementing the device specific layer we encountered several problems concerning dll s Neither of us had ever worked with dll s before so we had to figure out how to load them as well as how to build them We spent a lot of time on this but in the end we succeeded When studying the PixeLINK API we discovered that it differs more from the DT Frame Grabber SDK than we thought originally Since we did not see a neat solution to deal with this problem we decided in the end not to implement our original design Instead we implemented plFGI in a way similar to the implementation of the original FGI system So now we have the following results The original FGI system is updated The clear all bug i
194. tputType should be RAW RGB24 or IMAGE n mexErrMsgTxt n return else nrhs 1 amp amp nlhs 1 mexPrintf plGrab Wrong arguments given Calling syntax image plGrab handle or image plGrab serialnumber n mexErrMsgTxt n ifdef cplusplus extern C endif 82 FGI and plFGI Report 2002 September 2002 D 11 plilsOpen cpp ORK KR KR KK hh kOkCk kk k Ck kCk k Ck kc k Ck k kc K Ck k kc Ck kc k Ck k kc k Ck kc k Ck k kc k Ck k kc k Ck k ck kokok ck kok ck ck okok ck k kx x d Filename plIsOpen cpp f Description Source code for the function plIsOpen Authors M A E Bakker L I Oei ST maarten panic et tudelft nl l i oeiGits tudelft nl Date 2002 08 07 Updates avd ORK KK KK RK k Ck k kc k Ck k kc Ck k kc k Ck k kc KCk k CK Ck k kc k Ck kc k Ck k kc k e A kock ck kok ck kokok ck ko k x kx k x f plIsOpen checks whether the device has been opened It returns 0 if the device has not been opened and 1 if it has been opened ORK KKK KK kk Ck Ck kOkCk Ck kCk Ck k kc k Ck kc kc k k kc K Ck kk Ck kc k Ck k kc k Ck kc k Ck k kc k k kc kc k k k ck kokok ck kok ck kokok k k ke xe x A x fj Input prhs 0 struct device handle or fe U32 serial number of the device Ak output plhs 0 double 0 if the device has not beeen opened 1 if the device has been opened Syntax plIsOpen handle or plIsOpen seria
195. ubWindowPos value too large n mexPrintf uStartRow current number of rows should not exceed lu n PCS2112 MAX HEIGHT mexErrMsgTxt Mn set the values nRetValue PimMegaSetSubWindowPos deviceld tmpU32 tmpU322 if plError nRetValue setting SubWindowPos mexErrMsgTxt Mn SubWindowSize else if strcmp parametername SubWindowSize tmpU32 PCS2112_NO_DECIMATION uDecimation buflen mxGetM values 0 mxGetN values 0 sizeof mxChar 1 tmpstring char mxCalloc buflen sizeof char mxGetString values 0 tmpstring buflen if strcmp tmpstring PCS2112_NO_DECIMATION tmpU32 PCS2112_NO_DECIMATION m else if stremp tmpstring PCS2112 DECIMATE BY 2 tmpU32 PCS2112 DECIMATE BY 2 else if strcomp tmpstring PCS2112 DECIMATE BY 4 tmpU32 PCS2112 DECIMATE BY 4 else mexPrintf plSetValue Error setting SubWindowSize unknown value n mexPrintf uDecimation should be PCS2112 NO DECIMATION Mn mexPrintf PCS2112 DECIMATE BY 2 or PCS2112 DECIMATE BY 4 Mn mexErrMsgTxt Mn tmpU322 U32 mxGetScalar values 2 uWidth tmpU323 U32 mxGetScalar values 1 uHeight check whether the given values are within the correct range tmpU324 subWindowPosStartColumnValue tmpU325 subWindowPosStartRowValue nRetValue PimMegaGetSubWindowPos deviceld
196. ubWindowStartColumnValue amp subWindowStartRowValue amp subWindowNumberColumnsValue amp subWindowNumberRowsValue if ApiSuccess nRetValue if subWindowDecimationValue PCS2112 NO DECIMATION i tmp mxCreateString PCS2112 NO DECIMATION Elus if subWindowDecimationValue PCS2112 DECIMATE BY 2 tmp mxCreateString PCS2112 DECIMATE BY 2 51 FGI and plFGI Report 2002 September 2002 else if subWindowDecimationValue PCS2112 DECIMATE BY Ai tmp mxCreateString PCS2112 DECIMATE BY 4 else tmp mxCreateString Unknown value tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 subWindowStartColumnValue tmp3 mxCreateDoubleMatrix 1 1 mxREAL tmppr3 mxGetPr tmp3 tmppr3 0 032 subWindowStartRowValue tmp4 mxCreateDoubleMatrix 1 1 mxREAL tmppr4 mxGetPr tmp4 tmppr4 0 032 subWindowNumberColumnsValue tmp5 mxCreateDoubleMatrix 1 1 mxREAL tmppr5 mxGetPr tmp5 tmppr5 0 032 subWindowNumberRowsValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported tmp3 mxCreateString Unsupported tmp4 mxCreateString Unsupported tmp5 mxCreateString Unsupported F else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value tmp3 mxCreateString Could not get value
197. value is stored as parameter value No other error checking is being done If everything went okay the value of the requested parameter is stored in a temporary variable by the PixeLINK API and immediately after that it is stored into the handle structure using mxSetField The only exception to this are the parameters GrabColorConversion and GrabOutputType which are not stored in the PixeLINK API but in plDevices They are obtained in a similar way to the device ID by calling plDevices using mexCallMatlab e Suggestions for improvement Convert some of the if constructions to switch constructions for example the one used for SubWindowSize 2 10 Description of plError plError is an error checking function which is linked to every MEX function that uses PixeLINK API calls It is called after every call to such an API function Required inputs are the PixeLINK API return code returned by the called API function and a string describing in max 33 characters what the program was doing when the possible error occurred First the string input of the plError function is used to create an error message The device s API encountered a problem while lt string gt When the PixeLINK API return code which is defined in PimMegaApiUser h indicates an error this string is printed on the screen After that a case construction is used to determine the nature of the PixeLINK API return code When everything is okay plError returns a value o
198. videoModeValue if ApiSuccess nRetValue if videoModeValue STILL_MODE tmp mxCreateString STILL MODE else if videoModeValue VIDEO_MODE tmp mxCreateString VIDEO MODE tmp mxCreateString Unknown value 53 FGI and plFGI Report 2002 September 2002 else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else tmp mxCreateString Could not get value mxSetField m 0 VideoMode tmp GrabColorConversion rhs 0 mxCreateString getpar rhs 1 mxCreateDoubleMatrix 1 1 mxREAL px mxGetPr rhs 1 px 0 U32 serialNumber rhs 2 mxCreateString GrabColorConversion mexCallMATLAB 1 lhs 3 rhs plDevices grabColorConversion U32 mxGetScalar lhs 0 switch grabColorConversion case BAYER_2BY2_COLOR case BAYER_3BY3_COLOR case BAYER_3BY3GGRAD_COLOR case BAYER_2PASSGRAD_COLOR case BAYER_2PASSADAPT_COLOR case BAYER_VARGRAD_COLOR case BAYER_2BY2_MONO case BAYER_3BY3_MONO case BAYER_ADAPT_MONO case BAYER_NO_CONVERSION default tmp mxCreateString BAYER 2BY2 COLOR break tmp mxCreateString BAYER 3BY3 COLOR break tmp mxCreateString BAYER 3BY3GGRAD COLOR break tmp mxCreateString BAYER 2PASSGRAD COLOR break tmp mxCreateString BAYER 2PASSADAPT COLOR break tmp mxCreateString BAYER VARGRAD COLOR break tmp mxCreateString BAYER 2B
199. ws h gt include Y soft95 matlab6 extern include mex h with Y soft95 matlab6 extern lib win32 microsoft msvc60 libmex lib and Y soft95 matlab6 extern lib win32 microsoft msvc60 libmx lib include Y software framegrag pixelink api pimmegaapiuser h with Y software framegrag pixelink api pimmegaapi lib void plPrintPossibleValues char parametername BlueGain if strcemp parametername BlueGain mexPrintf BlueGain U32 n mexPrintf Value should not exceed lu n PCS2112 MAX GAIN DataTransferSize else if stromp parametername DataTransferSize mexPrintf DataTransferSize string n mexPrintf Valid values are DATA 8BIT SIZE and DATA 16BIT SIZE in Exposure else if strcmp parametername Exposure mexPrintf Exposure U32 n mexPrintf Value must not exceed lu n PCS2112 MAX EXPOSURE ExposureTime else if stromp parametername ExposureTime mexPrintf ExposureTime float fExposure string bChangeClockSpeed FALSE n mexPrintf fExposure is the exposure time in milliseconds n mexPrintf bChangeClockSpeed should be a string with value TRUE or FALSE Nn mexPrintf if no bChangeClockSpeed argument is given the default FALSE will be used n Gamma else if stromp parametername Gamma mexPrintf Gamma float n mexPrintf To turn of gamma correction specify a value of 0 or 1 n
200. x 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 long previewWindowPosLeftValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 long previewWindowPosTopValue 70 FGI and plFGI Report 2002 September 2002 fieldnames 1 PreviewWindowPosLeft fieldnames 0 PreviewWindowPosTop m mxCreateStructMatrix 1 1 2 const char fieldnames mxSetField m 0 PreviewWindowPosLeft tmp mxSetField m 0 PreviewWindowPosTop tmp2 else if stromp parametername PreviewWindowSize Preview Window Size nRetValue PimMegaGetPreviewWindowSize deviceId amp previewWindowSizeWidthValue amp previewWindowSizeHeightValue if plError nRetValue getting PreviewWindowSize value mexErrMsgTxt Mn tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 previewWindowSizeWidthValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 previewWindowSizeHeightValue fieldnames 1 PreviewWindowSizeWidth fieldnames 0 PreviewWindowSizeHeight m mxCreateStructMatrix 1 1 2 const char fieldnames mxSetField m 0 PreviewWindowSizeWidth tmp mxSetField m 0 PreviewWindowSizeHeight tmp2 else if stromp parametername RedGain Red Gain nRetValue PimMegaGetRedGain deviceld amp redGainValue if plError nRetValue getting RedGain value mexErrMs
201. xGetPr tmp2 tmppr2 0 long previewWindowPosTopValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value mxSetField m 0 PreviewWindowPos Left tmp mxSetField m 0 PreviewWindowPos Top tmp2 Preview Window Size nRetValue PimMegaGetPreviewWindowSize deviceId amp previewWindowSizeWidthValue amp previewWindowSizeHeightValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 previewWindowSizeWidthValue tmp2 mxCreateDoubleMatrix 1 1 mxREAL tmppr2 mxGetPr tmp2 tmppr2 0 U32 previewWindowSizeHeightValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported tmp2 mxCreateString Unsupported else tmp mxCreateString Could not get value tmp2 mxCreateString Could not get value mxSetField m 0 PreviewWindowSize Width tmp mxSetField m 0 PreviewWindowSize Height tmp2 Red Gain nRetValue PimMegaGetRedGain deviceld amp redGainValue if ApiSuccess nRetValue tmp mxCreateDoubleMatrix 1 1 mxREAL tmppr mxGetPr tmp tmppr 0 U32 redGainValue else if ApiNotSupportedError nRetValue tmp mxCreateString Unsupported else 50 FGI and plFGI Repor
202. yntax plDevices setpar serialnumber parametername parametervalue sets the value of the specified parameter Input prhs 0 string setpar prhs 1 2 U32 serialnumber prhs 2 string parametername prhs 3 value of the specified parameter Example plDevices setpar 75122 GrabOutputType RAW in which case RAW is defined as 0x0 20 FGI and plFGI Report 2002 September 2002 6 4 Detailed description of the pIFGI functions In this paragraph we give a detailed description of all pIFGI functions First we describe the main functions and then all internal functions are treated The complete source files for all functions can be found in Appendix D 6 4 1 plClose Description plClose clses a PixeLINK camera device plClose is the MEX function which takes care of closing an opened PixeLINK device First it is tested whether one and only one argument was given using if nrhs 1 If not the else part is executed printing an error message with mexPrintf and exiting with mexErrMsgTxt If the argument is a device handle structure the device s serial number is extracted from it If the argument is a number this is treated as the serial number If the argument is something else again an error message will be shown and the function will exit Now it can be assumed that a serial number is present It is checked whether the device is registered as open with a call to plDevices If it is not open the
203. ze and arrangement as the capture array In case of a Matlab IMAGE it is an array of unsigned 8 bit integers three times the size of pixelWidth pixelHeight It is arranged as an mxArray of pixelHeight pixelWidth 3 In memory this means that 3 column major arrays of pixelHeight pixelWidth are stored consecutively like this RRR GGG BBB In case of an RGB24 image an array of size Height Width 3 1 of uint8 is returned e The RGB24 array is used as an intermediate array to store the result of PimMegaConvert in case of a non RAW image before it is converted to fit into the matlab array Its size is always 3 pixelWidth pixelHeight and it is arranged as a normal C type row major array like this RGBRGBRGB First a distinction between the various GrabOutputType settings is made using a case construction The size and dim variables are set to the required size and dimensions of the matlab array After that the sizes of the capture array and the RGB24 array are defined A case construction is used to allocate memory for the matlab and capture arrays differentiating between 8 and 16 bits data size After this it is checked whether an error occurred if so the program is terminated If everything went all right the pointer to the matlab array is set When needed memory is allocated for the RGB24 array Now the image is captured by making a call to PimMegaReturnVideoData and the videostream is closed us

FGI and plFGI Report 2002 - Center for Machine Perception

Contents

Download Pdf Manuals

Related Search

Related Contents