Changes between Version 80 and Version 81 of UvmatHelp


Ignore:
Timestamp:
Jul 4, 2013, 9:35:38 AM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v80 v81  
    156156
    157157=== 3.5  Image documentation files (.xml) ===
    158 Image series in uvmat are documented by an acillary 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.
    159 
    160 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. 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.
    161 
    162 The xml file <!ImaDoc> can contain the following sections:
     158Image 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.
     159
     160When 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''.
     161
     162The xml file <!ImaDoc> can contain the following sections, as prescribed by the schema file ''!ImaDoc.xsd''.:
    163163
    164164 * '''<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.
    165  * '''<Camera>''' contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>. <!TranslationMotor> and <Oscillator> contains information on the mechanical devices used to produce the laser sheet and scan volumes.
     165 * '''<Camera>''' contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>.
     166 * '''<!TranslationMotor>''' and '''<Oscillator>''' contains information on the mechanical devices used to produce the laser sheet and scan volumes.
    166167 * '''<!GeometryCalib>''' contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
    167168 * '''<Illumination>''' describes the illumination system used, including the position of the laser source.
    168169 * '''<Tracor>''' describes the properties of the flow tracor (particle, dye...)
    169 
    170 The detailed commented structure is provided  in the schema file ''!ImaDoc.xsd''. The xml documentation file is read by the function ''imadoc2struct.m''. If this file does not exist, a file with the same root name but extension .civ is sought (obsolete format).
    171170
    172171=== 3.6 Ancillary input files ===
     
    185184 * '''.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'''.
    186185
    187  * ''''.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'' (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.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 %...
     186 * ''''.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 %...
    188187
    189188{{{
     
    209208The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]]   '''!Project/Campaign/Experiment/DataSeries/data files'''.
    210209
    211  * '''Project''' contains all information from a project.
     210 * '''Project''' contains all information on a project.
    212211 * '''Campaign''' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'.
    213212 * '''Experiment''' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters.
    214213 * '''!DataSeries''' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a !DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for the PIV data.
    215214
    216 '''Mirror data trees''' can be created to process a source data set in read only mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic  links to the !DataSeries directories. Data processing then results in real !DataSeries directories created in the Experiment directory.  An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains  the path and name of the source directory under the label <!SourceDir>. The mirror directory can be regularly updated by pressing the button 'update_mirror'.
     215'''Mirror data trees''' can be created to process a source data set in 'read only' mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference.
     216
     217The 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.
     218
     219Instead 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 indicate 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.
     220
     221Once created, this mirror campaign folder can be opened instead of the source.
     222It can be regularly updated from the source folder by pressing the button 'update_mirror' in '''browse_data.fig'''.
    217223
    218224----
     
    559565To deduce the 3D physical coordinates from the 2D image coordinates, the z position, or more generally a plane of cut, defined generally by a laser sheet, must be given as part of the calibration parameters. It is possible to introduce a set of planes obtained by volume scanning.
    560566
    561 The transform coefficients for each image series are stored in the corresponding xml documentation file <!ImaDoc>, in the section <!GeometryCalib>.  Calibration coefficients  can be obtained with the GUI '''geometry_calib.fig'''.
    562 
    563 <doc68|center>
    564 
    565 === 8.2 The GUI geometry_calib.fig} ===
    566 -''' Opening the GUI: ''' it is made visible  from the GUI '''uvmat.fig''' by  the menu bar command '''[Tools/Geometric calibation] '''.  If calibration data already exist in the current file <code>ImaDoc </code>, the corresponding list of reference points is displayed  in the central window '''[!ListCoord] ''' of '''geometry_calib.fig'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates. Calibration points can be alternatively introduced by opening any <code><!ImaDoc></code> xml file with the menu bar command''' [Open] ''' of '''geometry_calib.fig'''.
     567The transform coefficients for each image series are stored under the tag <!GeometryCalib> in the corresponding xml documentation file <!ImaDoc>, see [#a3.5Imagedocumentationfiles.xml section 3.5].  Calibration coefficients  can be obtained and dispalyed with the GUI '''geometry_calib.fig'''.
     568
     569
     570=== 8.2 The GUI geometry_calib.fig ===
     571-''' 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 <code>ImaDoc </code>, the corresponding list of reference points is displayed  in the central window '''[!ListCoord] ''' of '''geometry_calib.fig'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates. Calibration points can be alternatively introduced by opening any <code><!ImaDoc></code> xml file with the menu bar command''' [Open] ''' of '''geometry_calib.fig'''.
    567572
    568573-''' Plotting calibration points: ''' press the menu bar command button '''[Plot] ''' to visualise the list of calibration points. The physical or image coordinates will be used in the list '''[!ListCoord]''', depending on the option 'phys' or 'px' in the menu '''[transform_fct]''' of ''' uvmat.fig''' .