Changes between Version 90 and Version 91 of UvmatHelp


Ignore:
Timestamp:
Sep 27, 2013, 3:36:03 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v90 v91  
    156156
    157157=== 3.5  Image documentation files (.xml) ===
    158 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. 
    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 (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''. 
     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''.
    161161
    162162The 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>. 
     165 * '''<Camera>''' contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>.
    166166 * '''<!TranslationMotor>''' and '''<Oscillator>''' contains information on the mechanical devices used to produce the laser sheet and scan volumes.
    167167 * '''<!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.
     
    213213 * '''!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.
    214214
    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. 
     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.
    216216
    217217The 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'''.
    218218
    219 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.
    220 
    221 Once created, this mirror campaign folder can be opened instead of the source.
    222 It can be regularly updated from the source folder by pressing the button 'update_mirror' in '''browse_data.fig'''.
     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 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.
     220
     221Once 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'''.
    223222
    224223----
     
    243242Scalar are represented by matrices with real ('double') values, unlike images which are integers. They can be alternatively defined with unstructured grid (see [#a5.1Gridingofdata section 5.1]): they are then linearly interpolated on a regular grid before visualisation (a fairly slow process).
    244243
    245 Scalars (or image intensity) can be also represented with contour plots, by switching the popup menu '''[Contours] ''' from the setting 'image' to the setting 'contours'. Contours for positive scalar values are in sold line while contours for negative values are dashed. The interval between contours can be set by the edit box '''[num_IncrA]'''.
    246 
    247 === 4.2 Vectors ===
     244=== 4.2 Contour plots ===
     245Scalars (or image intensity) can be also represented with contour plots, by switching the popup menu '''[Contours] ''' from the setting 'image' to the setting 'contours'. Contours for positive scalar values are in sold line while contours for negative values are dashed. The interval between contours can be set by the edit box '''[num_IncrA]'''. The interval is automatically determined if the box content is blank.
     246
     247By default, the  contours are further marked by jumps of color levels. This can be set to grey levels by selecting the check box '''[CheckBW]. '''To suppress these images, set '''[Opacity]''' to 0. ''''''
     248
     249=== 4.3 Vectors ===
    248250The vector fields are represented by arrows. The length of the arrows is automatically set by default, or can be adjusted by the edit box '''[num_VecScale]''' when the check box'''[!CheckFixVectors]''' is selected.  For clarity of visualisation, the number of displayed vectors can be divided by 2 or 4 in each direction by selecting the check box '''[CheckDecimate4]''', or '''[CheckDecimate16]''' respectively.
    249251
     
    254256-'''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''[!CheckHideWarning]'''.
    255257
    256 -'''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''[!CheckHideFalse]'''. 
     258-'''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''[!CheckHideFalse]'''.
    257259
    258260-'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).
    259261
    260262-'''[!ColorCode] ''' sets the kind of color representation:
     263
    261264 * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [!CheckFixVecColor], these thresholds can be set to match the min and max scalar values.
    262265 * 'black' or 'white': set the color for all vectors
     
    264267 * '64 colors': quasi-continuous color representation, ranging from blue (for the scalar value given by '''[num_MinVec]''', to red, for the scalar value given by '''[num_MaxVec]'''.
    265268
    266 -'''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are 
    267  * fist line: the position coordinates ''x'', ''y'', ''z'' for 3D cases). 
    268  * second line: the vector components
     269-'''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are
     270
     271 * fist line: the position coordinates ''x'', ''y'', ''z'' for 3D cases).
     272 * second line: the vector components
    269273 * third line: the vector index in the file, the values of the scalar (C), the warning flag (F) and the error flag (FF). The meaning of the flag values is given in [#a11.3FIX section 11.3].
    270274
    271275-'''Manual editing of vectors''': error flags are automatically produced by the PIV operation, see [#a11.3FIX section 11.3]. It is also possible to introduce them manually by checking '''[edit_vect]''' and selecting a vector with the mouse. The flag can be removed by selecting it again. To record the changes in the input file, press the button '''[record]'''.
    272276
    273 === 4.3 Histograms ===
     277=== 4.4 Histograms ===
    274278Histograms of the input fields are represented on the bottom left. The choice of the variable is done by the menu '''[histo1_menu]'''.
    275279
    276280For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph.
    277281
    278 === 4.4 Comparing two fields ===
    279 A second field series can be opened and compared to the first one, by selecting the check box '''[!SubField]''' on the very left. 
     282=== 4.5 Comparing two fields ===
     283A second field series can be opened and compared to the first one, by selecting the check box '''[!SubField]''' on the very left.
    280284
    281285If the two files are both images or scalar, their difference is introduced as the input field. If one field  is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field.
     
    287291The second field can be removed by unselecting the check box '''[!SubField] '''.
    288292
    289 === 4.5 Field transforms ===
     293=== 4.6 Field transforms ===
    290294A 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].
    291295
     
    347351In summary, the ''field structure'' is specified by the following elements:
    348352
    349  * (optional) '''!!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    350  * (mandatory) '''!!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
    351  * (mandatory) '''!!VarDimName:''' list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of '''ListVarName'''. Each element is the dimension name for a unidimensional variable, or a cell array specifying the list of dimension names for a multidimensional variable.
    352  * (optional) '''!!VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]).
     353 * (optional) '''!!!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     354 * (mandatory) '''!!!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
     355 * (mandatory) '''!!!VarDimName:''' list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of '''ListVarName'''. Each element is the dimension name for a unidimensional variable, or a cell array specifying the list of dimension names for a multidimensional variable.
     356 * (optional) '''!!!VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]).
    353357 * .Att_1, Att_2... : values of the listed global attributes.
    354358 * .Var_1, .Var_2...: variables arrays whose names are listed in !ListVarName.
     
    356360In some cases, it is useful to define the field object independently from its data content. Then the variables .Var1... are replaced by the lists of dimension names and values.
    357361
    358  * '''!!ListDimName:''' list of dimension names (cell array of character strings)
    359  * '''!!DimValue:''' array of dimension values corresponding to !LisDimName.
     362 * '''!!!ListDimName:''' list of dimension names (cell array of character strings)
     363 * '''!!!DimValue:''' array of dimension values corresponding to !LisDimName.
    360364
    361365The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
     
    553557== 8 - Geometric calibration ==
    554558=== 8.1 Generalities ===
    555 Transforming image to physical coordinates is a prerequisit for measuring techniques based on imaging. 
     559Transforming image to physical coordinates is a prerequisit for measuring techniques based on imaging.
    556560
    557561The ''image coordinates'', expressed in pixels, represent the two cartesian axis ''X,Y'' of the image, with origin taken at the lower left corner. The coordinate of the first lower left pixel centre is therefore (1/2,1/2). Note that the ''Y'' axis is directed upward, while the corresponding image index j increases downward. Therefore, denoting ''npy'' the number of pixels along ''Y'', the (''X,Y'') coordinates of a pixel indexed (''i,j'') are ''X''=''i''-1/2, ''Y''=''npy''-''j''+1/2.
     
    568572
    569573The 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'''.
    570 
    571574
    572575=== 8.2 The GUI geometry_calib.fig ===
     
    593596Alternatively 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].
    594597
    595 -'''3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' ((if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr . For calibration performed inside water, the option of introducing the ''z'' position of water upper surface is provided. 
     598-'''3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' ((if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr . For calibration performed inside water, the option of introducing the ''z'' position of water upper surface is provided.
    596599
    597600-'''Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. if the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous <!ImaDoc> file by the menu bar tool '''[!Import/Intrinsic]''' parameters, then applying the calibration with the option '3D_extrinsic' with the reference grid image only.
    598601
    599 -'''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]'''. 
     602-'''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]'''.
    600603
    601604=== 8.3 Structure of the xml file ===
     
    612615 * <!CoordUnit>: coordinate unit in physical space.
    613616
    614  * {{{<Tx_Ty_Tz>}}}: translation, (Tz=1 for the options calib_lin and calib_rescale)
    615 
    616  * {{{<R>}}}: rotation matrix (in 3 lines). For the option <[https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/search?q=wiki%3ACalibrationType CalibrationType]>= 'rescale', [[BR]] R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1], [[BR]]where pxcmx and pxcmy are the scaling factors along ''x'' and ''y''.
     617 * `<Tx_Ty_Tz>`: translation, (Tz=1 for the options calib_lin and calib_rescale)
     618
     619 * `<R>`: rotation matrix (in 3 lines). For the option <[https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/search?q=wiki%3ACalibrationType CalibrationType]>= 'rescale', [[BR]] R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1], [[BR]]where pxcmx and pxcmy are the scaling factors along ''x'' and ''y''.
    617620
    618621 * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordinate transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation)
     
    624627 * <!SourceCalib> set of the point coordinates used for calibration
    625628
    626    * <!PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
     629 * <!PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
    627630
    628631 * <!NbSlice_i> nbre of slices for the first field  index i (multilevel case), =1 by default.