Changes between Version 67 and Version 68 of UvmatHelp


Ignore:
Timestamp:
Jun 13, 2013, 7:39:05 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v67 v68  
    155155
    156156=== 3.5  Image documentation files (.xml) ===
    157 Information on image series is provided by a documentation file in the format xml. This file can include sections about image timing, geometric calibration, camera type and illumination. An xml file is a text file in which each element of information, or group of elements, is labelled by a tag. The list of tags and their hierarchical organisation is specified by a schema file (.xsd). The schema used for image documentation is ''!ImaDoc.xsd'', available in the uvmat package in a sub-directory ''/Schemas''. A general introduction to the xml language and schemas is provided for instance in http://www.w3schools.com/xml.
     157Information on image series is provided by a documentation file in the format xml. This file can include sections about image timing, geometric calibration, camera type and illumination. An xml file is a text file in which each element of information, or group of elements, is labelled by a tag. The list of tags and their hierarchical organisation is specified by a schema file (.xsd). 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. A general introduction to the xml language and schemas is provided for instance in http://www.w3schools.com/xml.
    158158
    159159When a new file series is opened in uvmat, a documentation file is automatically sought, whose path and name are displayed by ''!RootPath'' and  ''!RootFile'' respectively, with extension {.xml} (''!RootPath'' and ''!RootFile'' are the contents of the edit boxes '''[!RootPath]''' and ''' [!RootFile]''').  The detection of this 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.
     
    167167 * '''<Tracor>''' describes the properties of the flow tracor (particle, dye...)
    168168
    169 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).
     169The 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).
    170170
    171171=== 3.6 Ancillary input files ===
     
    695695== 11 - PIV: Particle Imaging Velocimetry ==
    696696=== 11.1 Overview ===
    697 PIV can be performed by selecting the Matlab function ''civ_series'' as '''[!ActionName]''' in the GUI '''series'''. The same operations can be also performed with the older function ''civ.m'' running with the specific GUI '''civ.fig''', accessible from uvmat by the menu bar command '''[RUN/civ]'''. This older option is still used to run the fortran programs [CIVx].
    698 
    699 -''' Opening the GUI: ''' The GUI '''civ.fig''' for PIV calculation can be directly opened by the command '>>civ' on the Matlab prompt. Then open an image or a documentation file (.xml ) with the file browser. ''' '''The''' ''' GUI '''civ.fig''' can be also directly opened from '''uvmat.fig''', by the menu bar command '''[RUN/civ]'''.  A third way is just to open the Matlab image ({civ.fig} file) stored after each processing in the directory of the velocity fields. Then just edit it and run a new calculation.
     697PIV can be performed by selecting the Matlab function ''civ_series'' as '''[!ActionName]''' in the GUI '''series.fig''': then the '''GUI civ_input''' appears to enter the processing parameters. An image file series must have been entered as input of '''series.fig''', or alternatively a Netcdf file resulting form a previous PIV processing (with conventions 'civdata').
     698
     699An alternative possibility is to use the older Fortran program ''CivX'' from the GUI '''civ.fig'''. This can be called directly on the Matlab prompt, by typing  ''>>civ'', or from uvmat by the menu bar command '''[RUN/PIV (old civ)]'''.
     700 
     701'''-Modes of frame pair indexing'''
     702A first menu '''[ListCompareMode]''' selects one among four modes of operation:
     703 * '''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):
     704   * ''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. 
     705   * 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'.
     706   * series (Dj): same as series (Di) but with the j index.
     707 * '''displacement''': compare the current image to a fixed reference frame, as needed to measure the displacement with respect to this reference. The reference index (i index) is set by an edit box '''[num_OriginIndex]'''.
     708 * '''shift''': compares the corresponding images in two separate series, as need for stereographic views. The opening of a second file series is proposed by a browser when this option is selected.
     709 * '''PIV volume''' performs PIV in volumes for frame sequences with two indices i and j. The second index j is assumed to represent a position in a volume laser scan, while i represents time. Therefore PIV volume requires the selection '''series (Di)''' for '''[ListPairMode]'''.
     710
     711With all the options for pair comparisons, the set of reference frames is given by the master GUI '''series.fig'''.
    700712
    701713<doc78|center>
    702 
    703 -''' Input file name and indexing: ''' The root name of the input file is displayed in the edit box '''[RootName]''', and a set of indices can be defined by the edit boxes '''[first_i] ''' (first index), '''[incr_i]''' (increment), '''[last_i ]'''(last index). The GUI offers a wide variety for the choice of image pairs to correlate. In the case of two file indices i and j, a mode for the choice of image pairs can be selected in the popup menu '''[mode]'''. -*'pairj1-j2': a given pair of j indices (or subscript a, b c...) can be chosen in the CIV1 menu '''[list_pair_civ1]''', while the corresponding indices i are set by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]'''. -*'series(Di)': a sliding set of i index pairs is chosen by a set of {reference} indices i_ref given by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]''' and a pair interval defined in '''[list_pair_civ1]''': the first choice 0|1 corresponds to the sliding pair i_ref|i_ref+1. the second choice -1|1 to the sliding pair i_ref-1|i_ref+1,...This mode is generally used with a single image series or movie, but it can be also used in volume scan, with a second index j chosen by '''[first_j] ''', '''[incr_j]''' , '''[last_j ]'''. -*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs. -*comparing two image series: this is made possible by selecting 'displacement' in the popup menu '''[compare]''', which gives access to a browser for selecting the second image series. This second series can be reduced to a single reference image, if it contains no index. The displacement field with respect to this reference image is then obtained  for successive times.  -*stereo PIV: this option in the menu '''[compare]''' provides the three velocity components  by comparing the stereoscopic views from two cameras, see [section 10.6->#sec10.6].
    704714
    705715-''' Succession of operations: '''
     
    712722 * fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results.
    713723
    714 This series of operations is chosen by selecting the corresponding  check boxes on the left, which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file is opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process.
     724This series of operations is chosen by selecting the corresponding  check boxes on the left of the GUI '''civ_series''', which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file has been initially opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process.
    715725
    716726=== 11.2 CIV1: ===
    717 The image pair is selected in the menu '''[list_pair_civ1]''', see sub-section 10.1. The time interval of the image pair must be chosen sufficiently small to provide a good correlation, and sufficiently large to provide good measurment precision: a displacement of 5-10 pixels is generally optimum.
    718 
    719 The time interval for each image pair is indicated in '''[list_pair_civ1]''' iif the information is made available, either from a movie file, or from a detected xml file (with the name !RootName.xml). The source of the timing information is indicated in the edit box '''[ImaDoc]'''. Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates. In the absence of information, the file index is taken for the time.  The time interval for a given index pair may change with time, so the time interval display is taken for given reference indices, given by '''[i_ref]''' and ''' [j_ref].'''.
    720 
    721 ('''[ibx], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[isx],[ isy]''' 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  ([shift x],[shift_y]). This is useful in the presence of a known mean flow.
    722 
    723 The default value ibx=iby=(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).
    724 
    725 A parameter '''[rho(images)] ''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.
    726 
    727 The search parameters (isx, isy,shift x,y) can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v. The result depends on the time interval of the image pair. Change the selected image pair if the maximum displacement (ibsx-ibx)/2 is too small (lack of precision) or too large (bad image correlations and risks of false vectors).
     727The 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.
     728
     729 Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates.
     730
     731('''[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).
     732
     733A parameter '''[num_CorrSmooth] ''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.
     734
     735The search parameters (SearchBoxSize,earchBoxShift) can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v. The result depends on the time interval of the image pair. Change the selected image pair if the maximum displacement (ibsx-ibx)/2 is too small (lack of precision) or too large (bad image correlations and risks of false vectors).
    728736
    729737<doc72|center>
    730738
    731 The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[dx] ''' and '''[dy]''' (in pixels). Alternatively a custom [grid->#sec3.6_grid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.
     739The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[num_Dx] ''' and '''[num_Dy]''' (in pixels). Alternatively a custom [grid->#sec3.6_grid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.
    732740
    733741A subregion can be alternatively  selected by a mask image, selecting the edit box '''[MASK]'''. If a mask image with an appropriate name is found in the image directory, it wil be detected, and the indication 'xxmask' appears in the edit box. (xx is the number of slices, equal to 1 for a single mask). Otherwise a browser appears to select a (single) mask file.