132 | | -'''Double index series: ''' they are labeled by two integer indices i and j, with names obtained by concatenating the full root, the suffix '_i_j' and the file extension(e.g. {Exp/aa_45_2.png}). This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i). It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. |
133 | | |
134 | | -'''Pair file indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating the output format. More generally, the result from any processing involving a range of primary indices from i1 to i2 is labeled as _i1-i2. If i1=i2, the two indices are merged in a single label i, or a single index j if j1=j2. |
135 | | |
136 | | -'''Nomenclature types:''' These different indexing systems are implemented by a functions {fullfile_uvmat.m}. The inputs are the root name, four indices i1,i2,j1,j2 and a character string representing the nomenclature type. The reverse operation, splitting a name into a root and indices while detecting the nomenclature type, is performed by the function {fileparts_uvmat.m}. Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' of '''uvmat.fig'''. This nomenclature type is defined as the index string for the first file in the series, for instance '_1' for a single indexing and '1_1-2' for a double indexing. For a field series in a single file, like a movie, the nomenclature type is '*'. For a set of indexed movies (or multimage files), the index i labels the files while the index j labels the frames within a file. |
| 131 | -'''Double index series: ''' they are labeled by two integer indices i and j. This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i). It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. For a set of indexed movies (or multimage files), the index i labels the files while the index j labels the frames within a file. |
| 132 | |
| 133 | -'''Pair indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating the output format. More generally, the result from any processing involving a range of primary indices from i1 to i2 is labeled as _i1-i2. If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively. |
| 134 | |
| 135 | -'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index for the first file in the series, for instance '_1' for a single indexing and '_1-2' for a pair indexing, '_1_1' for a double index series. The second index j can be also represented as a letter suffix, for instance '01a'. For a field series in a single file, like a movie, the nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of [wiki:NomType the nomenclature type (for instance distinguishing '_001]' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all file names when the series is scanned. |
162 | | * <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. |
163 | | * <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. |
164 | | * <!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. |
165 | | * <Illumination> describes the illumination system used, including the position of the laser source. |
166 | | * <Tracor> describes the properties of the flow tracor (particle, dye...) |
| 161 | * <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. |
| 162 | * <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. |
| 163 | * <!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. |
| 164 | * <Illumination> describes the illumination system used, including the position of the laser source. |
| 165 | * <Tracor> describes the properties of the flow tracor (particle, dye...) |
171 | | * ''' 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 : |
172 | | * Intensity < 20: ('black mask') the vector in this place will be set to zero |
173 | | * 20 < Intensity < 200:('gray mask') the vector in this place will be absent |
174 | | * Intensity>200 the vector will be computed |
175 | | 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. |
176 | | |
177 | | * ''' 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 |
| 170 | * ''' 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 : |
| 171 | * Intensity < 20: ('black mask') the vector in this place will be set to zero |
| 172 | * 20 < Intensity < 200:('gray mask') the vector in this place will be absent |
| 173 | * 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. |
| 174 | |
| 175 | * ''' 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 |
185 | | * ''''.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''). |
186 | | * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ. |
| 184 | * ''''.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''). |
| 185 | * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ. |
209 | | The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] |
210 | | '''!Project/Campaign/Experiment/DataSeries/data files'''. |
211 | | |
212 | | * 'Project': contains all information from a project. |
213 | | * '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'. |
214 | | * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. |
215 | | * '!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 civ. '' |
| 207 | The 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'''. |
| 208 | |
| 209 | * 'Project': contains all information from a project. |
| 210 | * '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'. |
| 211 | * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. |
| 212 | * '!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 civ. '''' |
251 | | -'''Associated scalar: ''' for PIV velocity fields, the color represents by default the image correlation, 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}). '''[ColorCode] ''' sets the kind of color representation: |
252 | | * '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. |
253 | | * 'black' or 'white': set the color for all vectors |
254 | | * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values. |
| 247 | -'''Associated scalar: ''' for PIV velocity fields, the color represents by default the image correlation, 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}). '''[ColorCode] ''' sets the kind of color representation: |
| 248 | |
| 249 | * '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. |
| 250 | * 'black' or 'white': set the color for all vectors |
| 251 | * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values. |
283 | | The following succession of operations is performed by '''uvmat.fig''': |
284 | | -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images, or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files. |
285 | | -'''Second file reading:''' The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input fields. |
286 | | -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. |
287 | | -'''Projection:''' on the projection object selected in the menu '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}. |
288 | | -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}. |
289 | | -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field. |
290 | | -'''Plotting:''' plot the results of projection. Function used: {plot_field.m} |
| 280 | The following succession of operations is performed by '''uvmat.fig''': -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images, or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files. -'''Second file reading:''' The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input fields. -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. -'''Projection:''' on the projection object selected in the menu '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}. -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}. -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field. -'''Plotting:''' plot the results of projection. Function used: {plot_field.m} |
324 | | In summary, the ''field structure'' is specified by the following elements: |
325 | | * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes Att_1, Att_2... |
326 | | * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings). |
327 | | * (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. |
328 | | * (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]). |
329 | | * .Att_1, Att_2... : values of the listed global attributes. |
| 313 | In summary, the ''field structure'' is specified by the following elements: |
| 314 | |
| 315 | * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes Att_1, Att_2... |
| 316 | * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings). |
| 317 | * (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. |
| 318 | * (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]). |
| 319 | * .Att_1, Att_2... : values of the listed global attributes. |
332 | | In 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. |
333 | | * '''ListDimName:''' list of dimension names (cell array of character strings) |
334 | | * '''DimValue:''' array of dimension values corresponding to !LisDimName. |
335 | | |
336 | | The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: |
337 | | * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation or derivatives by tps is needed to calculate the requested field. |
338 | | * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection. |
| 322 | In 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. |
| 323 | |
| 324 | * '''!ListDimName:''' list of dimension names (cell array of character strings) |
| 325 | * '''!DimValue:''' array of dimension values corresponding to !LisDimName. |
| 326 | |
| 327 | The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: |
| 328 | |
| 329 | * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation or derivatives by tps is needed to calculate the requested field. |
| 330 | * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection. |
347 | | * ='uvmat/civdata': indicate that the variables are named according to [#civdata]. |
348 | | * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. |
349 | | * '!CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (!CoordUnit='pixel') and physical (for instance !CoordUnit='cm'). If '!CoordUnit' is defined, [projection ->#set_object] will be allowed only on objects with the same '!CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis). |
350 | | * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. |
351 | | * 'Time': real number indicating the time of the field, used to obtain time series from data sets. |
| 340 | * ='uvmat/civdata': indicate that the variables are named according to [#civdata #civdata]. |
| 341 | * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. |
| 342 | * '!CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (!CoordUnit='pixel') and physical (for instance !CoordUnit='cm'). If '!CoordUnit' is defined, [projection ->#set_object] will be allowed only on objects with the same '!CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis). |
| 343 | * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. |
| 344 | * 'Time': real number indicating the time of the field, used to obtain time series from data sets. |
354 | | -'''Global attributes , unactive''' those are merely used for information purpose |
355 | | * Project: recalls the project name |
356 | | * Campaign: recalls the campaign name |
357 | | * Experiment: recalls the experiment name(s) of the raw data |
358 | | * DataSeries: recalls the device name (s), if defined, of the raw data |
359 | | * ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line. |
360 | | * ObjectCoord: Coordinates defining a geometric object on which the data have been projected. |
361 | | * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. |
| 347 | -'''Global attributes , unactive''' those are merely used for information purpose |
| 348 | |
| 349 | * Project: recalls the project name |
| 350 | * Campaign: recalls the campaign name |
| 351 | * Experiment: recalls the experiment name(s) of the raw data |
| 352 | * DataSeries: recalls the device name (s), if defined, of the raw data |
| 353 | * ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line. |
| 354 | * ObjectCoord: Coordinates defining a geometric object on which the data have been projected. |
| 355 | * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. |
369 | | -'''The attribute 'Role':''' the following options are used for the attribute 'Role': |
370 | | * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) |
371 | | * 'coord_x', 'coord_y', 'coord_z': represents a sets of unstructured coordinates x, y and z for the field variables sharing the same dimension name. |
372 | | * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. |
373 | | * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. |
374 | | * 'errorflag': provides an error flag marking the field variables as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost. |
375 | | * 'grad_x', 'grad_y', 'grad_z' :represents the x, y or z component of a contravariant vector** (like gradients). |
376 | | * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field |
377 | | * 'tensor': represents a tensor field whose components correspond to the two last dimensions of the array.** |
378 | | * vector: matrix whose last dimension states for the vector components.** |
379 | | * 'vector_x', 'vector_y', 'vector_z' : represents the x, y or z component of a vector (covariant) |
| 364 | -'''The attribute 'Role':''' the following options are used for the attribute 'Role': |
| 365 | |
| 366 | * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) |
| 367 | * 'coord_x', 'coord_y', 'coord_z': represents a sets of unstructured coordinates x, y and z for the field variables sharing the same dimension name. |
| 368 | * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. |
| 369 | * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. |
| 370 | * 'errorflag': provides an error flag marking the field variables as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost. |
| 371 | * 'grad_x', 'grad_y', 'grad_z' :represents the x, y or z component of a contravariant vector** (like gradients). |
| 372 | * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field |
| 373 | * 'tensor': represents a tensor field whose components correspond to the two last dimensions of the array.** |
| 374 | * vector: matrix whose last dimension states for the vector components.** |
| 375 | * 'vector_x', 'vector_y', 'vector_z' : represents the x, y or z component of a vector (covariant) |
385 | | * Dimension variables: these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate. |
386 | | * Field cell with unstructured coordinates: this is a cell of variables sharing the same set of unstructured coordinates, indicated by the attribute Role=coord_x, coord_y, coord_z. |
387 | | * Field cell with structured coordinates: this is a cell of several variable(s) sharing the same set of dimensions associated with variables. (addditional dimension may indicate for instance a vector component, not associated with a coordinate). |
| 381 | * Dimension variables: these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate. |
| 382 | * Field cell with unstructured coordinates: this is a cell of variables sharing the same set of unstructured coordinates, indicated by the attribute Role=coord_x, coord_y, coord_z. |
| 383 | * Field cell with structured coordinates: this is a cell of several variable(s) sharing the same set of dimensions associated with variables. (addditional dimension may indicate for instance a vector component, not associated with a coordinate). |
390 | | The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used: |
391 | | * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) |
392 | | * 'nb_coord': denotes the space dimension for vector components |
393 | | * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components |
394 | | * 'rgb' : denotes the diemension of the color component in a true color image. |
395 | | * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. |
396 | | * 'nb_tps': dimension of the index for the tps centres |
| 386 | The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used: |
| 387 | |
| 388 | * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) |
| 389 | * 'nb_coord': denotes the space dimension for vector components |
| 390 | * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components |
| 391 | * 'rgb' : denotes the diemension of the color component in a true color image. |
| 392 | * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. |
| 393 | * 'nb_tps': dimension of the index for the tps centres |
410 | | * ''' {Name:} ''' any name given to the object |
411 | | * ''' {Type:} ''' classify the object with the following choice: |
412 | | * 'points': set of n points |
413 | | * 'line': simple straight segment, defined by its two end points |
414 | | * 'polyline': open line made of n-1 consecutive segments (defined by n points) |
415 | | * 'rectangle': defined by its center, half width and half height. |
416 | | * 'polygon': closed line made of n consecutive segments (defined by n points) |
417 | | * 'ellipse': defined by its center, half width and half height. |
418 | | * 'plane': plane with associated cartesian coordinates |
| 407 | * ''' {Name:} ''' any name given to the object |
| 408 | * ''' {Type:} ''' classify the object with the following choice: |
| 409 | * 'points': set of n points |
| 410 | * 'line': simple straight segment, defined by its two end points |
| 411 | * 'polyline': open line made of n-1 consecutive segments (defined by n points) |
| 412 | * 'rectangle': defined by its center, half width and half height. |
| 413 | * 'polygon': closed line made of n consecutive segments (defined by n points) |
| 414 | * 'ellipse': defined by its center, half width and half height. |
| 415 | * 'plane': plane with associated cartesian coordinates |
429 | | * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. |
430 | | * 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. |
431 | | * for 'rectangle', 'ellipse': coordinates of the center. |
| 426 | * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. |
| 427 | * 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. |
| 428 | * for 'rectangle', 'ellipse': coordinates of the center. |
439 | | Each variable of the input field yields a corresponding variable in the projected field. Integral quantities (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role', on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes. |
| 436 | Each variable of the input field yields a corresponding variable in the projected field. Integral quantities (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role', on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes. |
454 | | * ''' {Projection on n points:} ''' for each variable U, a set of n values U(i),i=1 to n is obtained, together with the unstructured coordinates (X(i), Y(i)) of the n points, and Z(i) in 3D. |
455 | | * ProjMode= 'projection': the value U(i) is obtained as an average of the (non false) data values in a domain of sizes max(2RangeX, 2RangeY, 2RangeZ) centered at each projection point. An ancillary data U_nbval(i) is also obtained, indicating the number of non-false data around each point. |
456 | | * ProjMode= 'interp_lin': U(i),i=1 is obtained as a linear interpolation on each point. |
457 | | |
458 | | * ''' {Projection on open lines:} ''' This includes the object styles 'line', 'polyline'. For vector fields, the projected x component is along the line and the y component is perpendicular. 3D case still needs to be implemented**. |
459 | | * ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ), data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line. |
| 451 | * ''' {Projection on n points:} ''' for each variable U, a set of n values U(i),i=1 to n is obtained, together with the unstructured coordinates (X(i), Y(i)) of the n points, and Z(i) in 3D. |
| 452 | * ProjMode= 'projection': the value U(i) is obtained as an average of the (non false) data values in a domain of sizes max(2RangeX, 2RangeY, 2RangeZ) centered at each projection point. An ancillary data U_nbval(i) is also obtained, indicating the number of non-false data around each point. |
| 453 | * ProjMode= 'interp_lin': U(i),i=1 is obtained as a linear interpolation on each point. |
| 454 | |
| 455 | * ''' {Projection on open lines:} ''' This includes the object styles 'line', 'polyline'. For vector fields, the projected x component is along the line and the y component is perpendicular. 3D case still needs to be implemented**. |
| 456 | * ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ), data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line. |
466 | | * ''' {Projection on planes:} ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)] and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. |
467 | | * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane. For structured coordinates with meshes DX,DY (DZ), data are interpolated on the line with a mesh =min(DX,DY,DZ). |
| 463 | * ''' {Projection on planes:} ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)] and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. |
| 464 | * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane. For structured coordinates with meshes DX,DY (DZ), data are interpolated on the line with a mesh =min(DX,DY,DZ). |
482 | | * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface. These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields without the mouse. |
483 | | * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection'). |
484 | | * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line. |
485 | | * 'rectangle': defined by its center, half width and half height. |
486 | | * 'polygon': closed line made of n consecutive segments (defined by n points) |
487 | | * 'ellipse': defined by its center, half width and half height. |
488 | | * 'plane': plane with associated cartesian coordinates |
| 479 | * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface. These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields without the mouse. |
| 480 | * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection'). |
| 481 | * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line. |
| 482 | * 'rectangle': defined by its center, half width and half height. |
| 483 | * 'polygon': closed line made of n consecutive segments (defined by n points) |
| 484 | * 'ellipse': defined by its center, half width and half height. |
| 485 | * 'plane': plane with associated cartesian coordinates |
578 | | -<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...') -<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval. -<code><Cx_Cy></code>: position coordinates of the optical axis on the -<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) -<code><CoordUnit></code>: coordinate unit in physical space. -<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale) -<code><R>:</code> rotation matrix (in 3 lines) |
579 | | |
580 | | For the option calib_rescale |
581 | | R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1] |
582 | | |
583 | | where pxcmx and pxcmy are the scaling factors along x and y. -<code><omc></code> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordiante transforms). The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation) -<code><ErrorRms>:</code> rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function UVMAT/px.m) -<code><ErrorMax> </code>: maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function UVMAT/px.m) -<code><SourceCalib> </code>set of the point coordinates used for calibration -<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates. -<code><NbSlice_i> </code>nbre of slices for the first field index i (multilevel case), =1 by default. -<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default. -<code><SliceCoord> </code>[x y z] positions (nb lines) of the nb planes, where nb=NbSlice_i (multilevel case) or nb=NbSlice_j of j indices (volume scan), for parallel volume scan, x=y=0, z= slice height, for angular scan, [x,y,z]=[origin]. -<code><SliceDZ> </code>, step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan. |
584 | | |
585 | | [<doc115|right>->#top] |
| 575 | * <CalibrationType>: type of calibration ('rescale', 'linear', '3D...') |
| 576 | |
| 577 | * <fx_fy>: focal length along each coordinate of the image sensor, expressed in pixel interval. |
| 578 | |
| 579 | * <Cx_Cy>: position coordinates of the optical axis on the |
| 580 | |
| 581 | * <kc>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) |
| 582 | |
| 583 | * <CoordUnit>: coordinate unit in physical space. |
| 584 | |
| 585 | * <Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale) |
| 586 | |
| 587 | * <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], where pxcmx and pxcmy are the scaling factors along x and y. |
| 588 | |
| 589 | * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordiante transforms). The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation) |
| 590 | |
| 591 | * <ErrorRms>: rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function ''px_XYZ.m in uvmat'') |
| 592 | |
| 593 | * <ErrorMax> : maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function UVMAT/px.m) |
| 594 | |
| 595 | * <SourceCalib> set of the point coordinates used for calibration |
| 596 | |
| 597 | * <PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates |
| 598 | |
| 599 | * <NbSlice_i> nbre of slices for the first field index i (multilevel case), =1 by default. |
| 600 | |
| 601 | * <NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default. |
| 602 | |
| 603 | * <SliceCoord> [x y z] positions (nb lines) of the nb planes, where nb=NbSlice_i (multilevel case) or nb=NbSlice_j of j indices (volume scan), for parallel volume scan, x=y=0, z= slice height, for angular scan, [x,y,z]=[origin]. |
| 604 | |
| 605 | * <SliceDZ> step distance between planes, or |
| 606 | |
| 607 | * <SliceDPhi> step angle for angular scan. |
612 | | Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input. |
613 | | |
614 | | The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#a11PIV:ParticleImagingVelocimetry section 11]. Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''. |
615 | | |
616 | | The action function is first activated when it is selected in the menu '''[ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. |
| 633 | Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input. |
| 634 | |
| 635 | The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#a11PIV:ParticleImagingVelocimetry section 11]. Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''. |
| 636 | |
| 637 | The action function is first activated when it is selected in the menu '''[ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. |