Interfacing t MATLAB Overview: Getting Started Basic Tutrial Interfacing with OCX Installatin GUI with MATLAB's GUIDE First Buttn & Image Mre ActiveX Cntrls Exting the GUI Advanced Tutrial MATLAB Cntrls Getting Data Events Getting Started: Interfacing with OCX Yur interfacing cde cmmunicates with DataRay prducts thrugh the DataRay OCX. The OCX has ActiveX cntrls that can be accessed frm a variety f Windws based envirnments. The OCX is autmatically generated and registered with the Windws perating system upn installing the DataRay sftware. Once initialized, the OCX is always running. This means that the camera is still running, even while editing GUI elements in Visual Studi r the GUI in MATLAB s GUIDE. Unfrtunately, while this characteristic f the OCX is useful fr creating interfaces in sme languages, it causes MATLAB t crash, and as a result, ActiveX cmpnents must be added t a GUI interface prgrammatically. Als, fr reasns unknwn, an interface can nly be run nce per MATLAB sessin. Sme imprtant ntes: The OCX is functinal nly as part f a GUI-based prgram. In this tutrial, we use MATLAB s.fig and GUIDE. Since the OCX is 32-bit, yu will need assciated 32-bit MATLAB and libraries The OCX and DataRay prgram cannt be used at the same time Installatin: First we need t install the DataRay Sftware: As Administratr, install the DataRay sftware which came with yur prduct. Attach the prfiler prduct. Allw the drivers t install. Open the DataRay sftware and select yur prfiler in the Device pull-dwn menu. Learn t use yur prduct in the DataRay sftware. Then clse the sftware. Yu can dwnlad the interface develped in this tutrial. It exists as a cllectin f 3 MATLAB files. Cameras: Dwnlad & unzip WinCamD BeamMap2: Dwnlad & unzip BeamMap2 This example shuld build and run with n errrs. Nt wrking? Email supprt@dataray.cm r call 530-472-1717 with: Device name and serial number DataRay and Windws versins which yu are using.
Basic Tutrial: We will shw yu step-by-step hw the example prgram was created in MATLAB. GUI with MATLAB s GUIDE First, we will make a basic GUI with GUIDE. It supprts all the items yu wuld expect frm a GUI library. In a new flder fr the 3 files which will cmpse the interface, under the HOME tab click Graphical User Interface under the New buttn. Fr ur basic interface, we will nly require adding Panels. If yu need mre space, yu can click the bttm crner and drag t increase the size f yur interface. Althugh we are using ActiveX cntrls, d nt attempt t use ActiveX Cntrl. The ther GUI interface cmpnents are fine t use, and we will cver their use in the Advanced Tutrial sectin. T create the mst basic interface, we will add 3 panels fr the start buttn, the 2D image f the beam and the Palette. The Dataray class will create the furth required GetData cntrl. Right-click n panel and then click and drag t establish the panel s size (and thereby establish the ActiveX Cntrl s size). Once the panels which will hld the Active X Cntrls have been placed, yu may left-click them and pen up the Prperty Inspectr t select cnvenient names fr them such as startbuttn which will make it mre straight-frward t prgrammatically set their ActiveX cntrls fr them.
The Prperty Inspectr allws yu t change many aspects f the selected GUI cmpnent including its Tag which can be used by MATLAB t interact with it prgrammatically. In rder fr changes in the Prperty Inspectr t be saved, yu must minimize it and save the GUI; d nt simply exit the Prperty Inspectr. If the new tag value is nt saved, it will cause the GUI t fail. Once yu save the figure, it will create a.fig file and a.m file which will wrk tgether t create the GUI. We will edit the.m file t make it create ActiveX cntrls First Buttn & Image T add ActiveX cmpnents, we use the handles frm the GUI t instantiate them. The syntax required t instantiate ActiveX cntrl bjects is as fllws; yu must use the OCX cntrl name, a series f raw crdinates OR thse derived frm the handle specified by a tag name, and a handle fr the figure itself: getdatactrl = actxcntrl('datarayocx.getdatactrl.1',[0,0,1,1],handles.figure1); CCDctrl =actxcntrl('datarayocx.ccdimagectrl.1',getpixelpsitin(handles.twd),handles.fig ure1); The ActiveX cntrls are vital fr cmmunicatin t and frm the instance f the DataRay prgram created by the interface. Fr example, the GetDataCtrl cntrl must be present fr the OCX t start and its StartDriver methd must be called fr devices t be recgnized. getdatactrl.startdriver(); T make the cntrls accessible by ther methds f ur GUI class, we will add the Dataray class frm Dataray.m t ur GUI bject which will hld all f the ActiveX cntrls. The reasn fr ding this will becme clearer in the Advanced Tutrial. When the Dataray class is created, the getdatactrl bject is created and the StartDriver methd is called frm its member variable referring t the GetData ActiveX cntrls like s: dobj.getdatactrl.startdriver(); The Dataray class has a useful functin fr setting buttns t the GUI and string their respective ActiveX cntrls int an array: % set buttn n tp f existing uipanel functin setbuttnpanel(dobj,panel_handle,buttnid) % create buttn actxcntrl and place n tp f the panel
dobj.btnctrls{+1} = actxcntrl('datarayocx.buttnctrl.1',getpixelpsitin(panel_handle),dobj.currentfi gure); dobj.btnctrls_handles{+1} = panel_handle; % save handle t panel in an array set(dobj.btnctrls{},'buttnid',buttnid); % set the ButtnID member variable The abve methd n the Dataray class des all f the wrk fr adding buttns t the interface. Adding the fllwing t yur GUI s pening functin will create the ActiveX cmpnents fr the interface; make sure t have the handles added after they have been created: functin basic_openingfcn(hobject, eventdata, handles, varargin) % This functin has n utput args, see OutputFcn. % hobject handle t figure % eventdata reserved - t be defined in a future versin f MATLAB % varargin cmmand line arguments t basic (see VARARGIN) % Chse default cmmand line utput fr basic handles.utput = hobject; handles.dataray = Dataray(handles.figure1); % create DATARAY class handles.dataray.setccdpanel(handles.twd) handles.dataray.setbuttnpanel(handles.startbuttn,297); % set start buttn handles.dataray.setbuttnpanel(handles.buttn1,171); handles.dataray.setpalettepanel(handles.palette); % Update handles structure guidata(hobject, handles);
Mre ActiveX Cntrls We will nw add mre buttns and prfiles t the interface. Adding prfiles nt nly helps display infrmatin, but als it prvides the functinality t pull data frm the camera. We need t g back t ur GUI and add mre panels. The initializatin cde t initialize this GUI is as fllws: handles.dataray = Dataray(handles.figure1); % create DATARAY class handles.dataray.setccdpanel(handles.twd) handles.dataray.set3dpanel(handles.threed) handles.dataray.setbuttnpanel(handles.startbuttn,297); % set start buttn handles.dataray.setbuttnpanel(handles.buttn1,171); % set start buttn handles.dataray.setbuttnpanel(handles.buttn2,172); % set start buttn handles.dataray.setbuttnpanel(handles.buttn3,177); % set start buttn handles.dataray.setbuttnpanel(handles.buttn4,179); % set start buttn handles.dataray.setprfilespanel(handles.prfile1,22); % set start buttn handles.dataray.setprfilespanel(handles.prfile2,23); % set start buttn handles.dataray.setpalettepanel(handles.palette);
Exting the GUI Besides the names f the ActiveX cntrls, yu will need t knw the ID s fr specific buttn and prfiles. In rder t find the crrect Buttn ID# t use fr the buttns, yu need t: 1) Clse yur GUI and pen the DataRay sftware 2) Right click n any buttn, t see the dialg n the right 3) Nte the current Name and ID# fr this result at the tp f the dialg 4) Repeat fr all the results f interest. Clse the DataRay Sftware There are cmplete lists f ID s fr prfiles and buttns available in interface sectin f the DataRay website: Prfiles: http://www.dataray.cm/userfiles/file/prfilesenum.pdf Buttns: http://www.dataray.cm/userfiles/file/indexttestparametersenum.pdf Finally, there is dcumentatin describing the methds and prperties f all the ActiveX cntrls: http://www.dataray.cm/assets/pdf/ocxdcumentatin.pdf This cmpletes the basic tutrial! Prblems/Questins? Please cntact us with the infrmatin listed abve
Advanced Tutrial: MATLAB Cntrls MATLAB prvides its wn cntrls and input methds. These can be used t prvide custm functinality t yur GUI. In this case, we will be using them t select data t write t a file. First, we will add ne static text label, ne edit text cntrl (text input), tw radi buttns in a buttn grup, ne pp-up meu (a drpdwn list) and ne buttn t ur GUI with GUIDE: The buttn grup cmpnent is like a panel, but it makes radi buttns perate as a grup; nly ne radi buttn in a buttn grup can be selected. GUI cmpnents can have their prperties set prgrammatically, but in this tutrial, we will use the Prperty Inspectr t set them. String: Fr mst cmpnents, the String prperty will set the text it displays Fr the pp-up menu, we will want t click the list display f the String prperty and enter ne chice per line Value Fr radi buttns, 1 is true and 0 is false Fr pp-up menus, 1 is the first item, 2 is the secnd item, etc
Entire tutrials have been written abut events and binding in MATLAB. We will stick t the basics. The GUIDE will create functins which will be called n interactins with the varius GUI cmpnents. Yu can specify mre actins t take when, fr instance, the cmpnent is created r destryed by right-clicking n the element and selecting view callbacks. In this case, we will be wrking with ne which is created autmatically: functin pushbuttn1_callback(hobject, eventdata, handles) % hobject handle t pushbuttn1 (see GCBO) % eventdata reserved - t be defined in a future versin f MATLAB %cntents = cellstr(get(handles.ppupmenu1,'string')); fprintf( 'Optin %d selected \n', get(handles.ppupmenu1,'value')); fprintf('%s \n', handles.dataray.btnctrls{2}.getparameter()); The abve prints ut tw items when the Write buttn is hit. First, it prints ut the item selected in the pp-up menu by its psitin. The secnd item we are printing is the value f the secnd ActiveX buttn cntrl we added t the interface; the first is the start buttn. In general, the syntax t get the value f a GUI cmpnent is get(handles.[cmpnent s tag], Prperty name ). GUIDE als prints ut useful tips near the callbacks f items. Getting Data Nw that we have an understanding f hw MATLAB GUI cmpnents can be set up, we will rewrite the callback methd t utput data t a cmma separated value file with the csvwrite functin. Whenever yu are writing a file it is crucial t make sure yu have write privileges fr the directry by either selecting a public directry r running the prgram as administratr. With the fllwing cde, we can write.csv files t be analyzed in MATLAB r Excel. functin pushbuttn1_callback(hobject, eventdata, handles) % hobject handle t pushbuttn1 (see GCBO) % eventdata reserved - t be defined in a future versin f MATLAB %cntents = cellstr(get(handles.ppupmenu1,'string')); fname = get(handles.edit1,'string') if get(handles.radibuttn1,'value') %this is fr prfiles axis = get(handles.ppupmenu1,'value'); data = handles.dataray.prfilectrls{axis}.getprfiledataasvariant(); csvwrite(fname, data); else % this is fr image data data = handles.dataray.getdatactrl.getwincamdataasvariant(); denm = 2; if handles.dataray.getdatactrl.captureisfullreslutin(); denm = 1; display(denm) m = handles.dataray.getdatactrl.gethrizntalpixels() /denm; n = handles.dataray.getdatactrl.getverticalpixels() /denm; image_data = reshape(data,m,n) csvwrite(fname, image_data);
Bth methds return a 1-D matrix f data. Therefre, if yu wish t have all the values f the raw pixels in their prper lcatins frm the GetWinCamDataAsVariant methd, it is necessary t reshape the matrix Events Besides cmmunicating thrugh interfaces t the DataRayOCX, there is a system f events which allw the DataRayOCX t cmmunicate back. One f the mst useful events is the GetData cntrl s SMessage event which is used fr internal cmmunicatin in the DataRay prgram; mst users are interested in the message with ID # 21 as its 3 rd argument which is used whenever a new frame is available. The bject which listens fr events is called a sink. We make a functin and pass it t the GetData cntrl as a callback fr the SMessage event in the Dataray bject: handlermessage = @dobj.eventcallback; dobj.getdatactrl.registerevent({'smessage',handlermessage}); functin eventcallback(dobj,varargin) if varargin{3} == 21 dobj.eventcunter = dobj.eventcunter +1; display(sprintf('%d frames seen', dobj.eventcunter)); This will print ut the ttal number f frames seen by incrementing a cunter. Many custmers have fund this useful fr running data analysis rutines n every x number f frames.
BeamMap2 Tutrial: Yu can dwnlad the interface develped in this tutrial as a cllectin f 3 MATLAB files frm the link that is available n the first page f this dcument. Please build and run this example befre yu cntinue. The example shuld be fully functinal and appear like the image displayed belw. This tutrial is brief because it references many f the techniques described in the Basic and Advanced WinCam tutrials; hwever, we will be using Buttn ID#s, Prfile ID#s and functins unique t the BeamMap2. Please make yurself familiar with the ther tutrials befre attempting t recreate this example. Creating DataRay Buttn Cntrls 1) Create a GetData Cntrl and a Status Buttn (ButtnID# = 104) Buttn Cntrl by using the instructins n pages 1-4 f the Basic WinCam Tutrial. 2) Unlike the WinCam tutrials, this example des nt use a ccdimage Cntrl. Instead, this example uses a TwD Cntrl. Fllw the instructins n pages 3-4 f the Basic WinCam tutrial, but create and use the settwdpanel functin (shwn belw) instead f the setccdpanel functin: functin settwdpanel(dobj,panel_handle) % create CCD actxcntrl and place n tp f the panel dobj.twdctrl = actxcntrl('datarayocx.twdctrl.1',getpixelpsitin(panel_handle),dobj.currentfigure); 3) Create the X2c (ButtnID# = 104), Y2c (ButtnID# = 105), and Ellipticity (ButtnID# = 126) Buttn Cntrls by using the same steps yu used t create the Status Buttn, but by substituting in the apprpriate ButtnID#s.
4) Create the Wander Display fr tracking the centrid psitin by creating a Buttn Cntrl and assigning it Buttn ID# 197. Creating DataRay Prfile Cntrls 5) Create fur unique Prfile Cntrls by fllwing the instructins n page 5 f the Basic WinCam Tutrial. Instead f using PrfileID#s 22 and 23, which crrespnd t the prfiles alng the WinCamD crsshairs, yu will need t use PrfileID#s that apply t the BeamMap2. The example prgram uses the fllwing cmmands t set the prfiles upn initializatin: handles.dataray.setprfilespanel(handles.uipanelprfile,14); % set U1 prf. handles.dataray.setprfilespanel(handles.uipanelprfile2,16); % set U2 prf. handles.dataray.setprfilespanel(handles.uipanelprfile3,18); % set U3 prf. handles.dataray.setprfilespanel(handles.uipanelprfile4,20); % set U4 prf. Please nte that these PrfileID#s (14, 16, 18, 20) crrespnd t the u-prfiles at each f the fur z-psitins n the BeamMap2 puck. We will create radi buttns that allw the user t tggle between the u and v-prfiles. The v-prfiles have their wn PrfileID#s (15, 17, 19, 21). 6) Create the Radi Buttns that are used t select the u r v-prfiles by using the methds discussed n the first page f the Advanced WinCam tutrial. Make sure the default radi buttn selected crrespnds t the default prfile setting, which is the u-prfile in this example. We assigned the tag radibuttnprfileu t the u-prfiles radi buttn t check its state in the fllwing functin. This functin executes when the user-selected radi is changed in the buttn grup: functin uibuttngrup1_selectinchangedfcn(hobject, eventdata, handles) % hobject handle t the selected bject in uibuttngrup1 % eventdata reserved - t be defined in a future versin f MATLAB prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile); % get activex cntrl variable t directly access its Parameters (r Functins) if get(handles.radibuttnprfileu,'value') == 1 set(prfile_actxcntrl,'myid',14); % set prfile U else set(prfile_actxcntrl,'myid',15); % set Prfile V prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile2); if get(handles.radibuttnprfileu,'value') == 1 set(prfile_actxcntrl,'myid',16); % set prfile U else set(prfile_actxcntrl,'myid',17); % set Prfile V prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile3); if get(handles.radibuttnprfileu,'value') == 1 set(prfile_actxcntrl,'myid',18); % set prfile U else set(prfile_actxcntrl,'myid',19); % set Prfile V prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile4); if get(handles.radibuttnprfileu,'value') == 1 set(prfile_actxcntrl,'myid',20); % set prfile U else set(prfile_actxcntrl,'myid',21); % set Prfile V Using DataRay s GetData Cntrl 7) Next, we will use the GetData Cntrl t pen the M 2 Dialg and prgrammatically extract data. First, we need t create a way t access the GetData Cntrl s methds frm the MATLAB file that cntains all the GUI methds. Since the GetData Cntrl bject belngs t the DataRay class, we will create a functin in the DataRay class that returns access t the GetData Cntrl bject: % get the activex cntrl f a specified panel r panel number t get access t further functins f this cntrl functin actxctrl = getgetdatactrl(dobj) % get activex cntrl t get access t get data ctrl functins actxctrl = dobj.getdatactrl;
This functin is used in the callback functins that belng t the Open/Clse M2 Dialg Buttn and GetOCXResult(M^2_u) buttns. 8) Create a Push Buttn using MATLAB s GUIDE. In the example, we assigned this buttn the tag m2buttn and the string Open/Clse M2 Dialg. We use ur functin frm step 7 t gain access t the GetData Cntrl. We use the GetData Cntrl t set change the state f its member IsMSquaredOpen, which effectively pens and clses the M2 Dialg. T use a single buttn t clse and pen the M2 Dialg, the buttn s callback functin shuld be as fllws: % --- Executes n buttn press in m2buttn. functin m2buttn_callback(hobject, eventdata, handles) % hobject handle t m2buttn (see GCBO) % eventdata reserved - t be defined in a future versin f MATLAB getdata_actxcntrl = handles.dataray.getgetdatactrl(); % get activex cntrl variable t directly access its Parameters (r Functins) if (getdata_actxcntrl.ismsquaredopen == 0) getdata_actxcntrl.ismsquaredopen = 1; %pens the M2 dialg else getdata_actxcntrl.ismsquaredopen = 0; %clses the M2 dialg 9) Similarly, we will create anther Push Buttn using MATLAB s GUIDE and use the GetData Cntrl in its callback functin t get the result f the M 2 calculatin at the instant the buttn is clicked. In the example we used getocxresultbuttn as the tag and GetOCXResult(M^2_u) fr the string f the buttn. Use MATLAB s GUIDE t create a Static Text element t display the result. We used textocxresult as the tag fr the Static Text element. The GetData Cntrl s GetOcxResult() functin accepts any ButtnID# as its parameter and returns the value that wuld be calculated and displayed n the crrespnding Buttn Cntrl. This callback functin is used t display the result f the M 2 calculatin in the Static Text: % --- Executes n buttn press in getocxresultbuttn. functin getocxresultbuttn_callback(hobject, eventdata, handles) % hobject handle t getocxresultbuttn (see GCBO) % eventdata reserved - t be defined in a future versin f MATLAB getdata_actxcntrl = handles.dataray.getgetdatactrl(); % get activex cntrl variable t directly access its Parameters (r Functins) result = getdata_actxcntrl.getocxresult(156); %156 is the index/id that applies t m^2_u set(handles.textocxresult,'string', result); Exprting Prfile Data t CSV 10) Next, we will use GUIDE t create a grup f fur Radi Buttns. These elements will allw the user t chse any f the fur prfiles that are currently displayed and exprt the prfile s data. In the example prgram, we used the radi buttn tags radi1, radi2, radi3, and radi4. 11) In additin, we will use the GUIDE t create an Edit Cntrl with the tag editcsvpath and string C:\Users\Public\Dcuments\utput.csv. This string f this edit cntrl cntains the path where the file will be generated and saved when we write t CSV. 12) Finally, we create a Push Buttn with tag writetcsvbuttn and string Write t CSV. This buttn s callback functin will write the selected prfile (identified by the state f the fur radi buttns and the u-prfile / v-prfile radi buttns) t a CSV. Here is the callback functin: % --- Executes n buttn press in writetcsvbuttn. functin writetcsvbuttn_callback(hobject, eventdata, handles) % hobject handle t writetcsvbuttn (see GCBO) % eventdata reserved - t be defined in a future versin f MATLAB path = get(handles.editcsvpath,'string'); if get(handles.radi1,'value') == 1 %1 means it is selected prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile); % get activex cntrl variable t directly access its Parameters (r Functins) if get(handles.radi2,'value') == 1 %1 means it is selected prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile2); % get activex cntrl variable t directly access its Parameters (r Functins) if get(handles.radi3,'value') == 1 %1 means it is selected
prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile3); % get activex cntrl variable t directly access its Parameters (r Functins) if get(handles.radi4,'value') == 1 %1 means it is selected prfile_actxcntrl = handles.dataray.getprfilectrl(handles.uipanelprfile4); % get activex cntrl variable t directly access its Parameters (r Functins) data = prfile_actxcntrl.getprfiledataasvariant(); csvwrite(path,data); The Prfile Cntrl s GetPrfileDataAsVariant returns the current prfile data as a variant array. This cmpletes the BeamMap2 tutrial! Prblems/Questins? Please cntact us with the infrmatin listed abve.