Context Navigation

Changes between Version 133 and Version 134 of UvmatHelp

Timestamp:: Jan 13, 2015, 8:53:34 PM (10 years ago)
Author:: sommeria
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

UvmatHelp

-                      v133
+                      v134
  * '''<Tracor>''' describes the properties of the flow tracor (particle, dye...).
 === 3.6 Ancillary input files ===
+=== 3.6 Ancillary input files === #MaskGrid
  * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is :
    * Intensity < 20: ('black mask') the vector in this place will be set to zero.
 …
  * ''' DX: ''', ''' DY: ''', ''' DZ: '''mesh  along each coordinate defining a grid for interpolation.
  * ''' Coord: ''' matrix with two (for 2D fields) or three columns defining the object position.
+ * ''' Coord: ''' matrix with two (for 2D fields) or three columns defining the object position.
    * for  'points', 'line', 'polyline', 'polygon': matrix with n lines [xi yi zi], corresponding to each of the n defining points. Note that in 3D case, polygons must be included in a plane, which imposes restrictions on these coordinates.
    * for 'rectangle', 'ellipse': coordinates of the center.
 …
 == 9 - Masks and grids ==
 === 9.1 Masks ===
 Mask files are used to restrict the domain of CIV processing, to take into account fluid boundaries or invalid image zones. They must be stored as .png images with 8 bits, as described in [section 3.6->#sec3.6_mask].  Mask files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar Tools/make mask on the GUI UVMAT. The mask is created interactively with the mouse on the current image.
+Mask files are used to restrict the domain of CIV processing, to take into account fluid boundaries or invalid image zones. They must be stored as .png images with 8 bits, as described in [#MaskGrids section 3.6].  Mask files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar '''[!Tools/Make mask]''' on the GUI UVMAT. The mask is created interactively with the mouse on the current image.
 First open an input image file name with the browser, or the edit box and carriage return. From the image name, a corresponding mask name is proposed in the lower edit box. It should be edited if a series of masks is made, in case of mutipositions (number nbslices) of the laser sheet in a series. The names must be [filebase '_xxmask' 'filenumber' '.png'], where xx is the number of masks (nbslices). The mask filenumber used is the image field number modulo nbslices. The filenumber can be incremented by the NEXT press button.
 …
 === 9.2 Grids ===
 Grid files, see [section 3.6->#sec3.6_grid], are used to impose a set of positions for PIV vectors. To create a grid for PIV, activate the menu bar Tools/Make grid on the GUI UVMAT. Introduce a minimum value, mesh, and maximum value for each coordinate x in the edit boxes XMin, DX, XMax respectively. Do the same for the y coordinate.  This must be expressed in physical coordinates.
+Grid files, see [#MaskGrids section 3.6], are used to impose a set of positions for PIV vectors. To create a grid for PIV, activate the menu bar Tools/Make grid on the GUI UVMAT. Introduce a minimum value, mesh, and maximum value for coordinate x in the edit boxes XMin, DX, XMax respectively. Do the same for the y coordinate.  This must be expressed in physical coordinates.
 The grid will be limited to an  image , or to the common region of two images, depending whether one or two image names are indicated in the edit boxes image_1 and image_2. Press save to save the corresponding grid file (s). A dialog box appears to edit the name of the output grid file, and a second one in case of two images.
 …
 Several input file series can be introduced simultaneously with the upper menu bar, or filling manually the successive lines of '''!InputTable'''. To get a new line, press the 'down' keyboard arrow after selecting the last existing line (this copies by default the last line content to the new line). A line can be suppressed by selecting it and pressing the key 'Suppress'. Press the button '''[REFRESH]''' to validate the input (checking the existence of the file series) after any editing.
 The 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.
 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].
+The 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.
+The same action can be performed either 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]'''.
 Other panels can specifiy the input fields to process, the use of transform function, projection objects or masks. They are made visible only if necessary.
 …
 The menu bar at the top of the GUI contains the following buttons:
  * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: '''browse...'''  or '''browse_append...'.'' '''''The latter appends a new input line to the table [!InputTable] while the former refreshes the table.
  * '''[Open campaign] ''':  does the same as '''[Open]  but '''scan the data organised as a project/campaign, see [https://servforge.legi.grenoble-inp.fr/#a3.7Dataorganisationinaproject section 3.7].
  * '''[Display Config] ''': exports on the Matlab work space all the data stored in the GUI, in the form of a Matlab structure.
  * '''[Inport Config] ''': reads the XML configuration file of a previous computation (placed in a subfolder /0_XML), and fills the GUI with its content, so the calculation can be repeated.
  * '''[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].'''
  * '''[Help] ''': displays this help file using the Matlab browser.
+ * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: '''browse...'''  or '''browse_append...''' The latter appends a new input line to the table '''[!InputTable]''' while the former refreshes the table.
+ * '''[Open campaign]''':  does the same as '''[Open]''' but scans the data organised as a project/campaign, see [https://servforge.legi.grenoble-inp.fr/#a3.7Dataorganisationinaproject section 3.7].
+ * '''[Display Config]''': exports on the Matlab work space all the data stored in the GUI, in the form of a Matlab structure.
+ * '''[Inport Config]''': reads the XML configuration file of a previous computation (placed in a subfolder /0_XML), and fills the GUI with its content, so the calculation can be repeated.
+ * '''[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 (note however that some processing parameters may be inconsistent with the current input files, so it is less reliable than''' [Inport Config].'''
+ * '''[Help]''': displays this help file using the Matlab browser.
 === 10.3 The frame [!IndexRange] ===
 The series of file indices is set in the frame '''[!IndexRange]'''. Any action is performed from field index '''[num_first_i]''' to '''[num_last_i] ''' with increment '''[num_incr_i]''' . If this increment is empty (or not an integer number), operation is performed on all available files between ''first_i'' and ''last_i''. In case of double indexing, action is similarly performed from field index''' [num_first_j]''' to '''[num_last_j]''' with increment '''[num_incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The box '''num_NbSlice''' can be introduced to scan the ''i'' index modulo NbSlice.
+The series of file indices is set in the frame '''[!IndexRange]'''. Any action is performed from field index '''[num_first_i]''' to '''[num_last_i] ''' with increment '''[num_incr_i]''' . If this increment is empty (or not an integer number), operation is performed on all available files between ''first_i'' and ''last_i''. In case of double indexing, action is similarly performed from field index''' [num_first_j]''' to '''[num_last_j]''' with increment '''[num_incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The box '''num_NbSlice''' can be introduced to scan the ''i'' index modulo !NbSlice.
 The  min and max indices available in the series are indicated as a guide-line, as well as the corresponding times in '''[!TimeTable]'''. The times for the first and last chosen indices are also indicated, as well as the source of the time information (column 'Name' in the table).
 When input files are indexed by pairs i1-i2 or j1-j2, as resulting for instance from PIV, the pair indexing can be chosen by pressing the button '''[!SetPairs]''' which opens an ancilliary GUI. Depending on the input file names, this can provides the choice between 'bursts', 'Di','Dj'. In mode 'bursts' a single j index pair is selected in the menu '''[!ListPairs]'''. In mode 'Di' and 'Dj' it selects a given index interval in i or j respectively. Then the first_i and last_i refer to the ''reference indices''. With the option '*-*' in '''[!ListPairs]''', available pairs are automatically chosen. In case of multiple input lines, the selection from '''[Set pairs]''' refers to the line number displayed in [!ListView]. It is  transfered to the corresponding line in the table '''[!PairString]'''.
+When input files are indexed by pairs i1-i2 or j1-j2, as resulting for instance from PIV, the pair indexing can be chosen by pressing the button '''[!SetPairs]''' which opens an ancilliary GUI. Depending on the input file names, this can provides the choice between 'bursts', 'Di','Dj'. In mode 'bursts' a single j index pair is selected in the menu '''[!ListPairs]'''. In mode 'Di' and 'Dj' it selects a given index interval in i or j respectively. Then the first_i and last_i refer to the ''reference indices''. With the option '*-*' in '''[!ListPairs]''', available pairs are automatically chosen. In case of multiple input lines, the selection from '''[Set pairs]''' refers to the line number displayed in '''[!ListView]'''. It is  transfered to the corresponding line in the table '''[!PairString]'''.
 === 10.4 The frame [Fields] ===
 …
 === 10.5   Field transform, projection object and mask ===
 A 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.
+A 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.
 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]'''.
 Similarly 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.
+Similarly 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.
 === 10.6 The frame [Action] ===
 …
 The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''!RunMode'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster.
 For the cluster option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''!ActionExt'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file 'RunTime' whose address needs to be specified  in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback''of ''series.m'').
+For the cluster option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''!ActionExt'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file '!RunTime' whose address needs to be specified  in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback''of ''series.m'').
 === 10.7 Action functions of general use ===
 …
  * ''check_data_files:'' gives the series of files selected for processing and checks their existence. The oldest modified file is indicated, which is useful to detect whether any file in a civ processing is missing (then the oldest file is not updated). For NetCDF files, the last operation made (civ1, fix1, patch1, civ2, fix2, patch2) is indicated. The details of each NetCDF file can be dispalyed by selecting it with the mouse in the list.
  * ''aver_stat'': this option provides any average over the processed files. If ['''!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results.   If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode '''interp_lin''' or ''interp_tps''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function.
  * ''time_series:'' this action provides a time series of the input field, possibly projected . Thus projection on 'points' lead to time series of the projected variable(s) for each point, projection by interpolation on a line will (x,time) field, while projection on a plane gives a 3D matrix, whose first index corresponds to time. Note that for a vector field, projections on a tilted line or plane give the vector components longitudinal and normal to the object. To preserve the original x and y components, introduce them as ''scalar'', not ''vectors''. In the case of two input files series, the field difference will be perfomed like with the interface '''uvmat.fig'''. It is not possible to use more than two input series for this funtion.
+ * ''aver_stat'': this option provides any average over the processed files. If '''[!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results.   If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode '''interp_lin''' or '''interp_tps'''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function.
+ * ''time_series:'' this action provides a time series of the input field, possibly projected . Thus projection on 'points' lead to time series of the projected variable(s) for each point, projection by interpolation on a line will (x,time) field, while projection on a plane gives a 3D matrix, whose first index corresponds to time. Note that for a vector field, projection on a tilted line or plane yields the vector components longitudinal and normal to the object. To preserve the original ''x'' and ''y'' components, introduce them as ''scalar'', not ''vectors''. In the case of two input files series, the field difference will be perfomed like with the interface '''uvmat.fig'''. It is not possible to use more than two input series for this funtion.
  * ''merge_proj'': this option allows to merge several field series in a single one. This is useful to merge fields obtained with different cameras. Select the different series, using the input option ''append''. In this case, it is generally useful to interpolate the fields on a single grid. For that purpose select a projection object of type 'plane' with projection mode 'interp_lin', or 'interp_tps' to get spatial derivative. Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates.
  * ''civ_series'': does PIV processing, see section [#Civ: section 11].