Programming for DaVis A Basic Guide

Transcription

1 Programming for DaVis A Basic Guide Summer 2012 Co op work term report Prepared for Dr. Spinello Under supervision of Dr. Fenech By Frederick Fahim ( )

2 Contents Introduction...1 Support...1 Self Help...1 Macros...2 CL Files...2.set Files...2 Custom Batch Operations...2 Using DLLs...2.Set Files...3 Definition...3 Acquisition Loops Z axis Loop...3 Motivation...3 Implementation...3 Nguyen Batch Processing...4 Motivation...4 Development...5 DLLs...6 Motivation...6 Required Format...6 DaVis/DLL Interface...6 DaVis...6 DLL...6 Language Considerations...7 Interfacing DaVis with Matlab...8 Through the Matlab Engine...8 Through MEX Files...8 MatView...8 Useful DaVis Objects and Functions...11 Buffers...11

3 Dimensions...11 Access...11 Allocation...11 Properties...12 Stage Control...12 Motor Control...12 Moving MiTas Diagonally...13

4 Introduction This guide, the tools developed, the user guides, source code and useful programs are available on LD511 s internal web site under the file name DaVis. The software used is DaVis 7.2, Matlab R2010b and Visual Studio 2010 s compiler. DaVis 7.2 is a program used in PIV and µpiv. Lab D511 makes use of it along with the MiTas stage and a dual pulse YaG laser. Seeing as it is not thoroughly tested commercial software, bugs are not unheard of. If a function s syntax seems to be correct but it does not behave predictably, it may be a good idea to contact LaVision s support team. Support Its producers are German, so any question asked by to its programmers is typically answered overnight if it can at all be answered within 24 hours. For new programming questions it is recommended to call first, as LD511 s support (Richard Prevost) will pinpoint the programmer most intimate with the issue. Phone: service@lavision.com, rprevost@lavisioninc.com Self Help The list of CL attributes, dialogs, subroutines etc. has been provided by LaVision, however please note that it is in no way exhaustive: from within DaVis an immediate window and searchable command list can be accessed by pressing F7 and Ctrl + F7, respectively. If a CL file is being developed, a debugger is available through the Macro menu or through a CL call to SetupDialogDebugger(). 1

5 Macros Macros are files containing a Command Line function defined C style that, when loaded by DaVis, can be called by users if they are public. DaVis makes use of C like syntax in its CL language to provide quite some flexibility and extensibility, as well as an interface between all its working parts. CL Files All macros created can be stored in one or many CL files (e.g. User.CL) to be loaded automatically when DaVis starts. These files are located in the DaVis directory under the folder called cl, and provide most of the undocumented functions mentioned in this guide s introduction..set Files Set files can be loaded by the macro to be used as parameters for various commands involving movies, acquisition, batch operations etc. The CL manual details how these files can be manipulated programmatically. Custom Batch Operations There is an extensive set of predefined batch operations that should provide enough functionality for the typical user but if needed, custom batch operations can be created by following the instructions from the CL manual in Simple mode or using DaVis callback functions (flowchart) in Advanced mode. Using DLLs DLLs can be called by macros to complete various tasks when more functionality or speed is needed. More information can be found in this guide. 2

6 .Set Files Definition Set files are a kind of file used by DaVis to store settings. These files usually have the.set extension. Set files can be used to load custom settings for everything from acquisition to processing, and make use of existing functions (user defined or packaged with DaVis). They may be accessed programmatically to specify how a particular action is to be carried out (e.g. while automating acquisition a set file may be loaded to provide the loop). Acquisition Loops Z axis Loop Motivation Co workers using DaVis and the MiTas stage for µpiv often have to find the stage position at which the camera s focal plane is the channel s mid height, where the flow s velocity is highest. This involves performing PIV at multiple stage heights, which is very tedious to do by hand. Below and linked is the implementation of a simple acquisition loop that will capture a specified number of pictures starting at a certain height, at every step, until a certain height. A user guide can be found linked. Implementation In the acquisition section of the Recording dialog (boxed in red, below), one can see that the procedure is customizable with loops, commands, etc. For any tasks to be performed during acquisition, this is the place operations will be specified. Choosing a MiTas Stage Z Loop from the list of available commands and placing the Image Acquisition command subordinate to it yields the desired results. 3

7 Nguyen Batch Processing Motivation The Nguyen method is used to accelerate batch processing and cross correlation by making averages when PIV is performed by a double pulse camera. The maximum intensity at each pixel across all the first pulse pictures is taken, as is done with the second pulse. One single cross correlation of the two resulting pictures gives averaged velocities while filtering out static particles which may be stuck on the channel, and when applied with a pixel mask (which can be turned on or off in the PIV operation of a batch processing) can cut processing time in half or more. The implementation can be found linked, as well as the user guide and more information on the Nguyen method. 4

8 Development Batch processing operation lists are lists of commonly used processing functions, where the output of each operation is used as input for the next operation. As such, the Nguyen method should be among the first on the list. Because the Nguyen method compiles pictures, the kind of batch operation will be under Statistics. The Nguyen method calls for the maximum intensity of each pixel, so the box to check is Maximum. t should be noted that custom batch operations can be defined but often necessary tools are preexisting. I 5

9 DLLs A Dynamically Linked Library is an executable that cannot run on its own, but rather contains compiled functions callable from running programs. This is a form of modularization that is becoming increasingly popular for plugins and add ons. For communication with other PCs and software (Ex: DaVis, LabView, etc.) DaVis has Remote.DLL, a module which handles network protocols, data transfer and remote commands. There is more information about these operations in the CL manual. A useful tool for the scrutiny and testing of DLLs is called the Dependency Walker, it can be used to see all the functions implemented in the DLL and the style in which they are specified. Motivation As DaVis macros must be interpreted by the software, they may not run as quickly as can be required for certain applications and the user may sometimes require functions not implemented in the software. In these cases, programmers may compile their own DLLs for DaVis to use. Required Format When loading a DLL, DaVis will call an initialization function in the DLL and pass it function handles to many typical DaVis commands, allowing the DLL to control DaVis. To allow this, the DLL must contain the interface file which defines these handles as constants. A call to the function InitDll within the CL_DLL_Interface is made, at the end of which InitDll calls a function MyInitDllExtensions for custom initialization (this call can be commented out, as it is for the programmer s convenience). Note: For functions to be callable by DaVis, the DLL must export them in C style (flat). For the programmer s convenience, CL_DLL_Interface defines a macro extern C <return_type> EXPORT <function_name> which does this independently of the compiler used. DaVis/DLL Interface DaVis Functions in the DLL may be called using the CL commands int CallDll(string DLL_Name, string Function_Name, int/float & Pars) int CallDllEx(string DLL_Name, string Function_Name, int & IntPars, float & FloatPars, string & StringPars) DLL Passing messages is achieved through the standard CL functions 6

10 void InfoText(string Message) void StatusText(string Message) and workarounds for string passing have been detailed by LaVision. Accessing buffer data is achieved with the function Void * GetBufferRowPtr(int buffer, int row); And any CL command can be executed by DaVis with a call to Void ExecuteCommand(char * cmd); Language Considerations While C++ is the first language that should come to mind due to its use in the CL_DLL_Interface, quite some flexibility may be granted through the use of a pre compiled CL_DLL_Interface library and function wrappers. Certain considerations should be made as to which language is used to produce the DLL: If processing speed is an issue (real time or time critical applications), C++ should be used to minimize overhead. If the function is complex, Matlab may be best due to its scientific nature and toolboxes. Also included in this guide is a section for Matlab generated DLLs. It should be mentioned that while Matlab is still quite a fast language, its use during high speed acquisition and such may be questionable. To illustrate, a snapshot of MatView s Dependency Tree is shown below. It can be seen that MatView and its operational core (PLOTTER.DLL), being Matlab generated, depend on Matlab s (MCLMCRRT), Microsoft C s (MSVCR) and Visual C++ s (MSVCP) runtimes. This means that C++ code calling Matlab must first pass through MSVCP, MSVCR and then MCLMCRRT. 7

11 Interfacing DaVis with Matlab The methods detailed below operate at approximately the same speed (details and speed optimizations as well as related considerations may be found on the MathWorks site), which is noticeably slower than C++. Through the Matlab Engine For anything to be done with the Matlab Engine, Matlab must be installed on the computer. DaVis contains a few functions within the MATLAB.CL system file (included for convenience) which allow direct execution of Matlab commands by an Engine instance from within DaVis. Through MEX Files For Matlab generated modules, both Matlab s MCR and Visual C++ s redistributables must be installed on the computer. Matlab can be used to produce executables and libraries which may run on any computer. It should be noted that since the default compiler for Matlab s mbuild command is a C one and the Interface files are C++, Visual C++ s compiler (supported by Matlab) must be used instead. MatView Motivation MatView is an extension of the Z Axis loop developed earlier to permit µpiv users to visualize 3D velocity profiles and export them to Matlab for further analysis. As it shows a 3D profile immediately after batch processing, it allows users to quickly spot the mid channel focal plane. It also serves as a good introduction on interfacing DaVis and Matlab as the Matlab function involved is very basic. Development Matlab Code to C Shared Library The command in Matlab needed to display a 3D surface plot such as the one obtained by combining all of the width velocity profiles obtained through batch processing is the following: Handle = surf(x,y,z) Since this command needs to be compiled into a library it is saved as plot_intensities and now becomes a callable function. To compile it into the library type needed, the proper Matlab command is mcc -B csharedlib:plotter Plotter\plot_intensities.m where Plotter will be the name of the shared library. 8

12 C Shared Library and Matlab in C++ Code Includes Of the files produced by the MCC, one will need to be included in the C++ wrapper: Plotter.h. In the C++ code, the following includes must then be made #include "Plotter.h" #include "CL_DLL_Interface.h" #include "matrix.h" #include <list> Where matrix.h is used to create Matlab matrices. Lists are used to accumulate the data passed to MatView from DaVis during batch processing, so that everything can be processed by MatView afterwards. There seems to be no restrictions regarding whether code is managed or not, using unmanaged code was simply a choice. Matrices Once matrix.h is included, Matlab double precision real matrices may be declared, instanced, mxarray * array_name; array_name = mxcreatedoublematrix(int rows, int cols, mxreal); and initialized using memcpy(mxgetpr(array_name), double * data_ptr, int data_size * sizeof(double)); where data_ptr is a pointer to a pre existing array of doubles, and data_size is the size of this array. It should be noted that Matlab will read a 1D array column wise into a 2D matrix. Compiled Library Application When comes time to invoke the Matlab functions compiled, first a call to initialize a new MCR instance must be made mclinitializeapplication(null, 0); must be made to tell the MCR to initialize a new Matlab application. Then PlotterInitialize(); is called to initialize the Plotter library, after which mlfplot_intensities(mxarray X, mxarray Y, mxarray Z); mclwaitforfigurestodie(null); may be called. Note that the plot_intensities command in Matlab has now become mlfplot_intensities: Matlab commands names are defined in C/C++ such that they begin with mlf and a capital first letter. 9

13 mclwaitforfigurestodie(null) simply tells the Matlab application not to close the figure or terminate until it is closed. When everything that needed doing in Matlab has been done, a call to PlotterTerminate(); mclterminateapplication(); should be made to terminate the Plotter library and the MCR Instance, respectively. Compiling the C++ Wrapper (MatView) To specify which functions in the DLL should be made public,.exports files need to be created for each CPP file involved. Below is CL_DLL_Interface.exports: InitDll and MatView.exports: add_depth add_profile set_verbose process Only the name is stated and the files end with a new line. The wrapper can then be compiled using Matlab s command line: mcc W lib:matview CL_DLL_Interface.cpp MatView.cpp Plotter.lib CL_DLL_Interface.exports MatView.exports CPP files go first, library files next and exports at the end. Matlab will then evoke the compiler and pass on any messages. Finally, a DLL is produced. When migrating it to the target computer, it should be copied with its internal library as well (Plotter.dll in this case) and registered using the command line tool regsvr32. 10

14 Useful DaVis Objects and Functions Buffers Buffers are used by DaVis to hold information about a single instant in time. For pulsed cameras, all the pulses are stored in one buffer with multiple frames: for a double pulse camera taking 100 shots, there will be 100 buffers of two frames each one frame for each pulse and one buffer for each snapshot. Buffers are stored within DaVis global memory, and pointers to them may be passed to commands in CL as integers. Typically buffers 0 and 1 are reserved for the program, and temporary buffers seem to be around 500. More information on buffers and the operations supported can be found in the CL manual. Dimensions They are composed of 5 dimensions, though these dimensions must be accessed through functions. X Y Z Frame Intensity or vector Access Buffers can be designated by the CL statement B[index]; And pixels within the buffer can be designated by Pix[index, x, y]; index being the number of the buffer. When dealing with 3D buffers or vector buffers, voxels will be used instead. Allocation When performing processing on buffers, DaVis will frequently store the results of each operation into the same buffer in an effort to minimize memory usage. This kind of buffer is called a Temporary Buffer, and can be manually allocated with the command int GetTempBuffer(); If, however, a Reserved Buffer which persists until DaVis closes should be allocated, the following command can be used instead int GetReservedBuffer(); Temporary and Reserved buffers can be locked to prevent changes to them and later unlocked : 11

15 void LockBuffer(int buffnum); void UnlockBuffer(int buffnum); Copying Copies of existing buffers can be automatically made and allocated using the command int GetTempBufferCopy(); Deallocation When temporary and reserved buffers are no longer needed, they should be deallocated (to avoid memory leaks) with the following commands, respectively FreeBuffer(int buffer); FreeReservedBuffer(int buffer); Properties Information about buffers can be retrieved through various functions provided by DaVis. A comprehensive list of these attributes may be found linked. Real World Positions It can be useful to know the actual stage position at which a frame was acquired: this can be done through the following command, also available for Y and Z coordinates*. Buffer_GetRealWorldFramePositionX(int thebuffer, int theframe, float& theposition, string& theunit, string& thelabel) *Due to bugs in DaVis 7.2, this command returns nothing useful. LaVision is currently working on a solution. Custom Attributes If a parameter is encoded to the filename during acquisition in the following format ParameterName=ParameterValue, a corresponding attribute with the name ExpPathValue_ParameterName is automatically created. This specific attribute can then be retrieved using: string svalue = GetBufferAttribute(int buffer, char * attribute); Stage Control Motor Control DaVis allows for programmatic control of the MiTas stage through two macros* void RotateSteps(int motor, int steps); void SetStepMotor(int motor, float pos); *for now, RotateSteps() seems to have a bug in it and will not do anything. LaVision is currently working on this. 12

16 For motor control at the software level during the acquisition stage, see the Z Axis Loop example and the manual s acquisition macros section. If it is to happen at the hardware level, consider.acq files. Moving MiTas Diagonally The µpiv machine will be used to track particles (red blood cell aggregations, bubbles etc.) while studying them and the flow surrounding them. To do so the MiTas stage needs to be able to move diagonally sometimes, a function which is not implemented by LaVision in our current software package as motors have to be moved separately. As a remedy, a basic 2D diagonal line function was created using simple loops and integer math. It has been implemented in Matlab to be able to handle any angle and follow a straight line to its destination as closely as possible so that it may be used in combination with a high speed camera. It does occasionally drift away from the true diagonal and could use improvement but if needed, the code can easily be translated to CL and made to handle 3D diagonals. >> GoSteps(10,50) >> GoSteps(-60,31) >> GoSteps(50, -52) >> GoSteps(-50, -29) >> GoSteps(50,0) Yields the following paths and shows more extreme cases of deviation (true paths in red, motor steps in black). 13

17 14