Changes between Version 107 and Version 108 of UvmatHelp


Ignore:
Timestamp:
Aug 13, 2014, 7:41:01 PM (10 years ago)
Author:
g7moreau
Comment:

XML ASCII Matlab name clean

Legend:

Unmodified
Added
Removed
Modified

  • UvmatHelp

    v107 v108  
    77=== 1.1 Aim ===
    88
    9 The package UVMAT can be used to visualise, scan and analyse a wide variety of input data: all image and movie formats recognised by Matlab (see [#a3.1Inputdataformats section 3.1]),  NetCDF binary files(see [#a7.1TheNetCDFformat section 7]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a Particle Image Velocimetry  software, as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing documentation files in the format xml. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
     9The package UVMAT can be used to visualise, scan and analyse a wide variety of input data: all image and movie formats recognised by Matlab (see [#a3.1Inputdataformats section 3.1]),  NetCDF binary files(see [#a7.1TheNetCDFformat section 7]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a Particle Image Velocimetry  software, as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing documentation files in the format XML. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
    1010
    1111This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output.
    … …  
    1717
    1818 * '''browse_data.fig:''' scans the data directory of a project
    19  * '''editxml.fig:'''  displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [http://www.artefact.tk/software/matlab/xml/ xmltree], integrated in the package ''UVMAT'' as a subdirectory /@xmltree.
     19 * '''editxml.fig:'''  displays and edits XML files according to an XML schema. XML reading and editing is performed by the toolbox [http://www.artefact.tk/software/matlab/xml/ xmltree], integrated in the package ''UVMAT'' as a subdirectory /@xmltree.
    2020 * '''geometry_calib.fig''': determines geometric calibration parameters for relating image to physical coordinates. The toolbox http://www.vision.caltech.edu/bouguetj/calib_doc/ is used, integrated in the package ''UVMAT'' as a subdirectory /toolbox_calib.
    2121 * '''get_field.fig:''' selects coordinates and field in a general NetCDF file.
    … …  
    8989Once a root name has been introduced, navigation among  the file indices is provided by the red push buttons '''[runplus]''' ( '''[+>]''')  and   '''[runmin] ''' ('''[<-]'''). The central push button '''[run0]''' ('''[!0]''') refreshes the current plot. See [#a3.4Navigationamongfieldindices section 3.4] for more details.
    9090
    91 When available, the time of each frame or field is displayed in the edit box '''[!TimeValue]''', at the very right. In the case of image pairs, the time interval Dt is displayed between the edit boxes '''[i1], [j1]''' and '''[i2], [j2]'''. This timing information can be read directly in the input file, in the case of movies or Netcdf files, or can be defined in a xml documentation file, see [#a3.5Imagedocumentationfiles.xml section 3.5] (in case of conflict, the latter prevails).
     91When available, the time of each frame or field is displayed in the edit box '''[!TimeValue]''', at the very right. In the case of image pairs, the time interval Dt is displayed between the edit boxes '''[i1], [j1]''' and '''[i2], [j2]'''. This timing information can be read directly in the input file, in the case of movies or Netcdf files, or can be defined in a XML documentation file, see [#a3.5Imagedocumentationfiles.xml section 3.5] (in case of conflict, the latter prevails).
    9292
    9393'''Note: ''' the five last input file names, as well as other pieces of personal information, are stored for convenience in a file (''uvmat_perso.mat'') automatically created in the user preference directory of Matlab (indicated by the Matlab command '>>prefdir'. Browsers then  read default input in this file. A corruption of this file ''uvmat_perso.mat'' may lead to problems for opening UVMAT, type '>>reinit' on the Matlab prompt to delete it and reinitialise the configuration of UVMAT.
    … …  
    159159
    160160=== 3.5  Image documentation files (.xml) ===
    161 Image series in UVMAT are documented by a file providing image timing, geometric calibration, camera type and illumination. This file is in the format ''xml'', a hierarchically organised text file. The content is labelled by tags, represented by brackets <.>, whose names and organisation are specified by a schema file (.xsd). A general introduction to the xml language and schemas is provided for instance in http://www.w3schools.com/xml. The schema used for image documentation is ''!ImaDoc.xsd'', available in the UVMAT package in a sub-directory ''/Schemas''. Simple templates of xml files are also provided there.
    162 
    163 When a new file series is opened in UVMAT, the xml documentation file is automatically sought in the folder containing the data series folder: the documentation of the file series !RootPath/SubDir/RootFile_1,... is in the file !RootPath/RootFile.xml. As a second choice (corresponding to an earlier convention), the xml file will be sought inside the data series folder, as !RootPath/SubDir/RootFile.xml (if this file does not exist, a text file with the same root name but extension .civ is sought as an obsolete option). The detection of the image documentation file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat.fig'''. Press this button to see the content through an xml editor '''editxml.fig''' (described in [#a10-Processingfieldseries section 10]). The xml file can be also opened directly by the UVMAT browser, or by any text editor. In UVMAT, it is read by the function ''imadoc2struct.m''.
    164 
    165 The xml file <!ImaDoc> can contain the following sections, as prescribed by the schema file ''!ImaDoc.xsd''.:
     161Image series in UVMAT are documented by a file providing image timing, geometric calibration, camera type and illumination. This file is in the format ''XML'', a hierarchically organised text file. The content is labelled by tags, represented by brackets <.>, whose names and organisation are specified by a schema file (.xsd). A general introduction to the XML language and schemas is provided for instance in http://www.w3schools.com/xml. The schema used for image documentation is ''!ImaDoc.xsd'', available in the UVMAT package in a sub-directory ''/Schemas''. Simple templates of XML files are also provided there.
     162
     163When a new file series is opened in UVMAT, the XML documentation file is automatically sought in the folder containing the data series folder: the documentation of the file series !RootPath/SubDir/RootFile_1,... is in the file !RootPath/RootFile.xml. As a second choice (corresponding to an earlier convention), the XML file will be sought inside the data series folder, as !RootPath/SubDir/RootFile.xml (if this file does not exist, a text file with the same root name but extension .civ is sought as an obsolete option). The detection of the image documentation file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat.fig'''. Press this button to see the content through an XML editor '''editxml.fig''' (described in [#a10-Processingfieldseries section 10]). The XML file can be also opened directly by the UVMAT browser, or by any text editor. In UVMAT, it is read by the function ''imadoc2struct.m''.
     164
     165The XML file <!ImaDoc> can contain the following sections, as prescribed by the schema file ''!ImaDoc.xsd''.:
    166166
    167167 * '''<Heading>''' contains elements <Campaign>, <Experiment>, <!DataSeries>, which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced.
    … …  
    178178   * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
    179179
    180  * ''' Grid:''' List of numbers (in ascii text) specifying the set of points where the PIV processing is performed.  It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows
     180 * ''' Grid:''' List of numbers (in ASCII text) specifying the set of points where the PIV processing is performed.  It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows
    181181{{{
    182182n X1 Y1 X2 Y2  ......  Xn Yn
    … …  
    187187 * '''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the browser of '''uvmat.fig'''.
    188188
    189  * ''''.civ' ''' (obsolete)  ascii text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the xml image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ''. It is automatically sought by '''uvmat.fig''' and '''series.fig''', in the absence of an xml file <!ImaDoc>. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %...
     189 * ''''.civ' ''' (obsolete)  ASCII text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the XML image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ''. It is automatically sought by '''uvmat.fig''' and '''series.fig''', in the absence of an XML file <!ImaDoc>. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %...
    190190
    191191{{{
    … …  
    20420419 450.000824 30 60 30 1           
    205205}}}
    206  * '''.cmx''' ascii text files containing the parameters sent by the GUI '''civ.fig''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of '''uvmat.fig'''. In a later version of civx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
    207 
    208  * '''.log''' ascii text files, containing information about processing in batch mode. Each velocity field named *.nc is associated with a  file *.log. A file *_patch.log is similarly produced by the ’patch’ program.  These files can be opened by the browser of '''uvmat.fig'''.
     206 * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ.fig''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of '''uvmat.fig'''. In a later version of civx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
     207
     208 * '''.log''' ASCII text files, containing information about processing in batch mode. Each velocity field named *.nc is associated with a  file *.log. A file *_patch.log is similarly produced by the ’patch’ program.  These files can be opened by the browser of '''uvmat.fig'''.
    209209
    210210=== 3.7 Data organisation in a  project ===
    … …  
    220220The data organisation can be controlled and managed by the GUI '''browse_data.fig'''. This is called by the menu bar option '''[Open/browse campaign]''' in UVMAT: with this browser select the path of the folder considered as 'Campaign' (instead of the data file itself). Then the GUI '''browse_data.fig''' appears with a list of 'Experiments' and a list of '!DataSeries'. Select your choice to open the corresponding file series in '''uvmat.fig'''. The selected campaign path is then recorded for future opening under '''[Open/browse campaign]''' in the menu bar of '''uvmat.fig'''.
    221221
    222 Instead of directly opening a file series with '''browse_data.fig''', you can create a 'mirror data tree' by pressing 'create_mirror', then selecting the path chosen for the new mirror folder 'Campaign'.  Inside this mirror folder, a set of folders is then created for each experiment. Furthermore, an xml file 'mirror.xml' is created to recall the source directory (under the label <!SourceDir>). Inside each mirror folder 'Experiment', the source is reproduced as symbolic  links. Data processing in the mirror campaign then produces 'real' !DataSeries folders.
     222Instead of directly opening a file series with '''browse_data.fig''', you can create a 'mirror data tree' by pressing 'create_mirror', then selecting the path chosen for the new mirror folder 'Campaign'.  Inside this mirror folder, a set of folders is then created for each experiment. Furthermore, an XML file 'mirror.xml' is created to recall the source directory (under the label <!SourceDir>). Inside each mirror folder 'Experiment', the source is reproduced as symbolic  links. Data processing in the mirror campaign then produces 'real' !DataSeries folders.
    223223
    224224Once created, this mirror campaign folder can be opened instead of the source.  It can be regularly updated from the source folder by pressing the button 'update_mirror' in '''browse_data.fig'''.
    … …  
    297297A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen  by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see the list in  [#transformfunctions the function overview].
    298298
    299 These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is  !DataOut=transform_fct(!DataIn,!XmlData,!DataIn_1,!XmlData_1) where Data is an input field object, as described in [#a5.2FieldrepresentationasMatlabstructure section 5.2], and !XmlData the content of the xml file Imadoc, as stored in the UVMAT GUI. !XmlData contains in particular the element .[wiki:GeometryCalib] containing the calibration parameters, see  [#a8.2TheGUIgeometry_calib.fig section 8.2].
     299These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is  !DataOut=transform_fct(!DataIn,!XmlData,!DataIn_1,!XmlData_1) where Data is an input field object, as described in [#a5.2FieldrepresentationasMatlabstructure section 5.2], and !XmlData the content of the XML file Imadoc, as stored in the UVMAT GUI. !XmlData contains in particular the element .[wiki:GeometryCalib] containing the calibration parameters, see  [#a8.2TheGUIgeometry_calib.fig section 8.2].
    300300
    301301=== 4.6 Succession of operations: ===
    … …  
    440440These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation to field subregions. The projection of fields on objects is performed by the function ''proj_field.m'', which can be used as well in data processing outside the GUI '''UVMAT''', using for instance [#a10-Processingfieldseries series.fig]).
    441441
    442 When a 2D or 3D field is opened by '''uvmat;fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by selecting the menu option '''[browse...]'''. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as xml files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''.
     442When a 2D or 3D field is opened by '''uvmat;fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing XML object file can be opened by selecting the menu option '''[browse...]'''. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as XML files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''.
    443443
    444444The names of the created objects are listed in the menu '''[!ListObject]'''. The properties of the object selected in this menu can be viewed by activating the check box '''[!CheckViewObject]'''. Check '''[!CheckEditObject]''' to allow object editing with '''set_object.fig'''.  The selected object is plotted in magenta, while the inactive ones are in blue. The field plot resulting from projection can be viewed in the GUI view_field.fig by activating '''[!CheckViewField]'''. This option is automatically selected when a new object is created. Then the projection object used for the main plotting window in UVMAT can be selected by the menu '''[!ListObject_1]''' which reproduces the list of available objects. The active objects are plotted in magenta, while the inactive ones are in blue.The object can be deleted by pressing '''[DeleteObject]'''.
    … …  
    574574To deduce the 3D physical coordinates from the 2D image coordinates, the ''z'' position, or a plane of cut, defined generally by a laser sheet, must be given as part of the calibration parameters. In UVMAT, it is possible to introduce a set of planes obtained by volume scanning.
    575575
    576 The transform coefficients for each image series are stored under the tag <!GeometryCalib> in the corresponding xml documentation file <!ImaDoc>, described in [#a3.5Imagedocumentationfiles.xml section 3.5].  Calibration coefficients  can be obtained and displayed with the GUI '''geometry_calib.fig'''.
     576The transform coefficients for each image series are stored under the tag <!GeometryCalib> in the corresponding XML documentation file <!ImaDoc>, described in [#a3.5Imagedocumentationfiles.xml section 3.5].  Calibration coefficients  can be obtained and displayed with the GUI '''geometry_calib.fig'''.
    577577
    578578=== 8.2 The GUI geometry_calib.fig ===
    579 -''' Opening the GUI: ''' it is made visible  from the GUI '''uvmat.fig''' by  the menu bar command '''[!Tools/Geometric calibration] '''.  If calibration data already exist in the current file <!ImaDoc>, the corresponding parameters and the list of reference points are displayed in the table '''[!ListCoord]'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates (in pixels). The physical unit is imposed as centimeter by the menu '''[!CoordUnit]''' to avoid mistakes. Calibration points can be alternatively introduced by opening any  xml file <!ImaDoc> with the menu bar command '''[Import]''' of '''geometry_calib.fig'''. It is possible to import the whole information, option 'All', the calibration point coordiantes only, or the calibration parameters only.
     579-''' Opening the GUI: ''' it is made visible  from the GUI '''uvmat.fig''' by  the menu bar command '''[!Tools/Geometric calibration] '''.  If calibration data already exist in the current file <!ImaDoc>, the corresponding parameters and the list of reference points are displayed in the table '''[!ListCoord]'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates (in pixels). The physical unit is imposed as centimeter by the menu '''[!CoordUnit]''' to avoid mistakes. Calibration points can be alternatively introduced by opening any XML file <!ImaDoc> with the menu bar command '''[Import]''' of '''geometry_calib.fig'''. It is possible to import the whole information, option 'All', the calibration point coordiantes only, or the calibration parameters only.
    580580
    581581-''' Plotting calibration points: ''' press the button '''[PLOT PTS] ''' to visualise the current list of calibration points. The physical or image coordinates will be used in the list '''[!ListCoord]''', depending on the option blank or 'phys' in the menu '''[transform_fct]''' of ''' uvmat.fig''' .
    … …  
    585585-''' Appending  calibration points with the mouse: ''' Calibration points can be manually picked out by the mouse on the current image displayed by '''UVMAT''' (left button click). This requires the activation of the check box '''[enable mouse]'''. The image coordinates (in pixels) are picked by the mouse (the option 'blank' in the popup menu '''[transform_fct]''' is automatically selected when the mouse button is pressed). Zoom can be used to improve the precision, but must be desactivated for mouse selection (then move across the image by the key board directional arrows). Points can be accumulated from several images, using the key board short cuts 'p' and 'm' to move in the image series without the mouse.  A calibration point can be adjusted by selecting it with the mouse and moving it while pressing the left mouse button. The coordinates in pixel of the selected points get listed in the table '''[!ListCoord]''' of '''geometry_calib.fig'''.
    586586
    587 -''' Editing the coordinate table: ''' After mouse selection, the physical coordinates  must be introduced by editing the table. To make this task easier it is possible to export the table content on the Matlab command window by pressing '''[COPY PTS]''', and copy-paste a column on the table '''[!ListCoord]''' (the column below the introduction cell is filled). A single point can be removed by the 'backward' or 'suppr' keyboard command after selecting its line on the table. The whole set of points can be removed by pressing '''[CLEAR PT]'''. They can be also removed by pressing '''[STORE PT]''', then stored in a xml file (whose path and name is listed in '''[!ListCoordFiles]'''). Stored points can be retrieved by the menu bar command '''[Import/calibration points]'''.
     587-''' Editing the coordinate table: ''' After mouse selection, the physical coordinates  must be introduced by editing the table. To make this task easier it is possible to export the table content on the Matlab command window by pressing '''[COPY PTS]''', and copy-paste a column on the table '''[!ListCoord]''' (the column below the introduction cell is filled). A single point can be removed by the 'backward' or 'suppr' keyboard command after selecting its line on the table. The whole set of points can be removed by pressing '''[CLEAR PT]'''. They can be also removed by pressing '''[STORE PT]''', then stored in a XML file (whose path and name is listed in '''[!ListCoordFiles]'''). Stored points can be retrieved by the menu bar command '''[Import/calibration points]'''.
    588588
    589589-''' Creating a physical grid: ''' This tool '''[!Tools/Create grid]''' in the  menu bar command provides the set of physical coordinates of a cartesian grid, ranked line by line from the bottom. First pick the set of image coordinates with the mouse. Then launch  '''[!Tools/Create grid]''' and fill the first and last ''x'' and ''y'' values, as well as the meshes, in physical coordinates. These coordinates then fill the table '''[!ListCoord]'''.
    … …  
    593593-''' Translation and rotation of calibration points: '''In general  A translation or rotation (in physical space) can be introduced by the menu bar commands '''[!Tools/Translate points]''' and '''[!Tools/Rotate points]'''.  In the case of rotation, the origin of the rotation, as well as the angle (in degree) must be introduced. The resulting coordinates appear in the list '''[!ListCoord]'''.
    594594
    595 -''' Recording calibration parameters: ''' Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous [#a8.1Generalities sub-section 8.1]). Note that the 3D options  require a sufficient number of calibration points (typically > 10) spread over the image with different values of z, or a tilted grid, see below. Calibration coefficients are recorded in the xml file <!ImaDoc> associated with the image currently opened by UVMAT. If previous calibration data already exist, the previous xml file is updated, but  the original one is preserved with the extension .xml~.  If no xml file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''.
    596 
    597 To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the xml documentation file with a text editor.
     595-''' Recording calibration parameters: ''' Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous [#a8.1Generalities sub-section 8.1]). Note that the 3D options  require a sufficient number of calibration points (typically > 10) spread over the image with different values of z, or a tilted grid, see below. Calibration coefficients are recorded in the XML file <!ImaDoc> associated with the image currently opened by UVMAT. If previous calibration data already exist, the previous XML file is updated, but  the original one is preserved with the extension .xml~.  If no XML file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''.
     596
     597To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the XML documentation file with a text editor.
    598598
    599599Alternatively the command '''[REPLICATE]''' can be used to calibrate a whole set of experiments in a 'Campaign', using an overview of the data set provided by the GUI '''data_browser.fig''', described in [#a3.7Dataorganisationinaproject section 3.7].
    … …  
    605605-'''Section planes:''' deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane ''z''=0, but UVMAT can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of multiplane scan). The chosen option can be doucumented in the file <ImaDoc> by the menu bar command '''[Tools/set planes]''' of '''geometry_calib.fig'''. A dialog box appears for entering the set of section plane positions ''z'', as lower value, upper value and increment. Similarly an angular scan be be introduced. After introduction of the multi-plane information, the z-index is displayed in the frame '''[FileIndices]''' of '''uvmat.fig'''. The local z position of the mouse pointer, assuemed to lay on the current section plane, is then displayed in '''[text_display]'''.
    606606
    607 === 8.3 Structure of the xml file ===
    608 The coefficients are recorded in the xml element <!ImaDoc/GeometryCalib> as follows:
     607=== 8.3 Structure of the XML file ===
     608The coefficients are recorded in the XML element <!ImaDoc/GeometryCalib> as follows:
    609609
    610610 * <!CalibrationType>: type of calibration ('rescale', 'linear', '3D...')
    … …  
    670670The panel [!IndexRange] specifies the range of input file or field indices to process while the panel Action specifies the processing function. New processing functions can be added by the user. The files resulting from the processing are put in a folder with the same path RootPath as the folder !SubDir containing the input files. The name of this output folder  is defined in [!OuputSubdir]: the default name is the input folder ''!SubDir'', followed by an extension depending on the processing function.
    671671
    672 The same action can be performed eiither on the local Matlab session, either as background process on the same computer, either as jobs sent on a cluster. In all cases the GUI series exports its content in a xml configuration file put in a subfolder /0_XML of the result folder [!OuputSubdir].
     672The same action can be performed eiither on the local Matlab session, either as background process on the same computer, either as jobs sent on a cluster. In all cases the GUI series exports its content in a XML configuration file put in a subfolder /0_XML of the result folder [!OuputSubdir].
    673673
    674674Other panels can specifiy the input fields to process, the use of transform function, projection objects or masks. They are made visible only if necessary.
    … …  
    683683 * '''[Display Config] ''': exports on the Matlab work space all the data stored in the GUI, in the form of a Matlab structure.
    684684
    685  * '''[Inport Config] ''': reads the xml configuration file of a previous computation (plced in a subfolder /0_XML), and fills the GUI with its content, so the calculation can be repeated.
     685 * '''[Inport Config] ''': reads the XML configuration file of a previous computation (plced in a subfolder /0_XML), and fills the GUI with its content, so the calculation can be repeated.
    686686
    687687 * '''[Inport Param] ''': does the same as '''[Inport Config] '''but without refreshing the input file table and indices. This is useful to repeat a previous calculation for a new series, keeping the same parameters (not however that some processing parameters may be inconsistent with the current input files, so it is less reliable than''' [Inport Config].'''
    … …  
    702702A transform function can be introduced by the menu '''[!TransformName]''' in the frame '''[!FieldTransform]"]'''. New transform functions can be introduced by the option 'more....'. Its path is then recorded and displayed in '''[!TransformPath]. Transform '''functions act field by field to modify the input (for instance transforming image to physical coordinates), like in the GUI UVMAT, while the '''Action''' functions act on the whole series.
    703703
    704 A projection object can be introduced by selecting the check box '''[!CheckObject]'''. If a projection object has been already created the  opened interface '''set_object.fig''' will be used. Otherwise a browser appears to open an object file (xml). It is possible to view the current projection object by pressing '''[view]''', edit it by selecting '''[edit]''', or delete it by pressing '''[delete]'''.
     704A projection object can be introduced by selecting the check box '''[!CheckObject]'''. If a projection object has been already created the  opened interface '''set_object.fig''' will be used. Otherwise a browser appears to open an object file (XML). It is possible to view the current projection object by pressing '''[view]''', edit it by selecting '''[edit]''', or delete it by pressing '''[delete]'''.
    705705
    706706Similarly the check box '''[!CheckMask]''' can be used to select a mask option. These different menus only appear if they are needed as input of the currently selected Action function.
    … …  
    731731 * ''turb_stat.m'': produces turbulent statistics (Reynolds stress tensor)
    732732
    733 These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI series (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an xml file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir ). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).
     733These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI series (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir ). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).
    734734
    735735To update (**): LIF_series: do LIF analysis, Stereo_PIV: combine two velicity series to yield the 3 components, part_stat: count particles and provides their density and luminosity histogramm, Peaklocking errors: estimate errors in PIV . By selecting the press button 'peaklocking' on the 'plotgraph' interface, you smooth the current velocity histograms while preserving its integral over each unity (in pixels). This appears in red. Then an estimate of the peaklocking error is obtained by comparing the initial histogram to the smooth one.
    … …  
    743743
    744744 * '''PIV''': makes image comparisons on sliding index pairs, as usual for measuring velocities by particle displacements. A second menu '''[!ListPairMode]''' in the panel '''[!PairIndices]''' then selects one among three possibilities (not always available depending on the file indexing):
    745    * ''pair j1-j2:'' selects a given j index pair (sometimes denoted by letter index) for the whole time series. This is the most common case for PIV. Pair selection is performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' for the second iteration Civ2, see below. If timing from an xml file [#a3.5Imagedocumentationfiles.xml <!ImaDoc>] has been detected, this is indicated in the edit box '''[!ImaDoc]''' and the corresponding time intervals are indicated (in ms). For some applications, this time interval may evolve in time, so that reference indices ref_i and ref_j are chosen for the display.
     745   * ''pair j1-j2:'' selects a given j index pair (sometimes denoted by letter index) for the whole time series. This is the most common case for PIV. Pair selection is performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' for the second iteration Civ2, see below. If timing from an XML file [#a3.5Imagedocumentationfiles.xml <!ImaDoc>] has been detected, this is indicated in the edit box '''[!ImaDoc]''' and the corresponding time intervals are indicated (in ms). For some applications, this time interval may evolve in time, so that reference indices ref_i and ref_j are chosen for the display.
    746746   * series (Di): selects a given  index interval for the i index, around a set of reference i indices. The intervals are denoted Di=0|1, -1|1, -1|2, -2|2 ... , corresponding to the index pairs i|i+1, i-1|i+1, i-1|i+2, i-2|i+2 ...around each reference index i. Pair selection is then performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' like for 'pair j1-j2'.
    747747   * series (Dj): same as series (Di) but with the j index.
    … …  
    769769The time interval of the image pair (selected by '''[ListPairCiv1]''', see above) must be chosen sufficiently small to provide a good image correlation, and sufficiently large to provide good measurement precision: a displacement of 5-10 pixels is generally optimum.
    770770
    771   Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates.
     771  Examples of XML files are provides in /XML_SCHEMAS/ImaDoc_templates.
    772772
    773773('''[num_CorrBoxSize_1,_2,_3], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[num_SearchBoxSize_1,_2,_3]''' set the size of the 'search box' in which image correlation is calculated, see figure.  This search box can be shifted with respect to the correlation box by parameters  ([num_SearchBoxShift_1,_2,_3]). This is useful in the presence of a known mean flow. The default value SearchBoxSize=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41), to optimise the resolution in one direction (for instance in a boundary layer).
    … …  
    949949
    950950----
    951 == 13 - Editing xml files with the GUI editxml ==
    952   This GUI '''editxml.fig''' visualises and edits xml files. It is automatically called by the browser of '''uvmat.fig''' when a file with extension .xml is opened.
    953 
    954   When an input file is opened, editxml detects the title key, e.g. <!ImaDoc>, and looks for the corresponding xml schema (e.g. {ImaDoc.xsd} ). This schema is sought  in the directory defined by <SchemaPath> in the installation file {PARAM.xml} of UVMAT. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the xml file are displayed.
    955 
    956   Simple elements in the xml file are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
     951== 13 - Editing XML files with the GUI editxml ==
     952  This GUI '''editxml.fig''' visualises and edits XML files. It is automatically called by the browser of '''uvmat.fig''' when a file with extension .xml is opened.
     953
     954  When an input file is opened, editxml detects the title key, e.g. <!ImaDoc>, and looks for the corresponding XML schema (e.g. {ImaDoc.xsd} ). This schema is sought  in the directory defined by <SchemaPath> in the installation file {PARAM.xml} of UVMAT. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the XML file are displayed.
     955
     956  Simple elements in the XML file are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
    957957
    958958  Manual editing of element value is possible. Select the element and use the lower edit box. This edit box transforms in a menu when a preselected list of allowed input values has been set by the schema.
    … …  
    968968 * 'create_grid';...% called by the GUI geometry_calib to create a physical grid
    969969 * 'dataview';...% function for scanning directories in a campaign
    970  * 'editxml';...%display and edit xml files using a xls schema
     970 * 'editxml';...%display and edit XML files using a xls schema
    971971 * 'geometry_calib';...%performs geometric calibration from a set of reference points
    972972 * 'get_field';...% choose and plot a field from a Netcdf file
    … …  
    997997 * 'imadoc2struct';...% convert the image documentation file <!ImaDoc> into a Matlab structure
    998998 * 'nomtype2pair';... creates nomenclature for index pairs knowing the image nomenclature, used by series fct
    999  * 'nc2struct';...% transform a netcdf file in a corresponding matlab structure
     999 * 'nc2struct';...% transform a netcdf file in a corresponding Matlab structure
    10001000 * 'num2stra';...% transform number to the corresponding character string depending on the nomenclature.
    10011001 * 'read_field':...% read the fields from files in different formats (netcdf files, images, video)
    … …  
    10051005 * 'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers
    10061006 * 'struct2nc';...% write fields in netcdf files
    1007  * 'struct2xml';... transform a matlab structure to a xml tree.
    1008  * 'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers
     1007 * 'struct2xml';... transform a Matlab structure to a XML tree.
     1008 * 'xml2struct'...% read an XML file as a Matlab structure, converts numeric character strings into numbers
    10091009
    10101010=== ancillary functions: ===
    … …  
    10161016 * 'close_fig';...% function  activated when a figure is closed
    10171017 * 'compile';...% compile a Matlab function, create a binary in a subdirectory /bin
    1018  * 'copyfields';...% copy fields between two matlab structures
     1018 * 'copyfields';...% copy fields between two Matlab structures
    10191019 * 'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle
    10201020 * 'displ_uvmat';...% display a message using  msgbox_uvmat or on the log file in batch mode
    … …  
    10241024 * find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions
    10251025 * 'find_file_series';...%check the content of an input file and find the corresponding file series
    1026  * 'find_imadoc';...% find the <!ImaDoc> xml file associated with a given input file
     1026 * 'find_imadoc';...% find the <!ImaDoc> XML file associated with a given input file
    10271027 * 'fullfile_uvmat';...%creates a file name from a root name and indices.
    10281028 * 'get_file_series';...% determine the list of file names and file indices for functions called by 'series'.
    … …  
    10501050 * 'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case)
    10511051 * 'uigetfile_uvmat';... browser, and display of directories, faster than the Matlab fct uigetfile
    1052  * 'update_imadoc';...  %update the xml file <!ImaDoc>.
     1052 * 'update_imadoc';...  %update the XML file <!ImaDoc>.
    10531053 * 'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series'
    10541054