| 160 | | The xml file <code><ImaDoc> </code> can contain the following sections: |
| 161 | | |
| 162 | | -<code><Heading></code>: contains elements <code><Campaign>, <Experiment>, <Device></code>, 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. -<code><Camera></code> contains information on the camera settings, as well as the timing of all the images in a subsection <code><BurstTiming></code>. -<code><TranslationMotor></code> and <code><Oscillator></code> contains information on the mechanical devices used to produce the laser sheet and scan volumes. -<code><GeometryCalib></code> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [section 7->#geometry_calib]). In the case of volume scanning, it also describes the set of laser plane positions and angles. -<code><Illumination></code> describes the illumination system used, including the position of the laser source. -<code><Tracor></code> describes the properties of the flow tracor (particle, dye...) -<code><ImageTransform></code> describes the image processing which may have been performed. |
| 163 | | |
| 164 | | The detailed commented structure is provided in the schema file {ImaDoc.xsd}. The xml documentation file is read by the function {imadoc2struct.m}. If this file does not exist, a file with the same root name but extension .civ is sought (see [section 3.6->#sec3.6_civ]). |
| | 160 | The xml file <!ImaDoc> can contain the following sections: |
| | 161 | |
| | 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 [wiki:#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...) |
| | 167 | |
| | 168 | The detailed commented structure is provided in the schema file ''ImaDoc.xsd''. The xml documentation file is read by the function ''imadoc2struct.m''. If this file does not exist, a file with the same root name but extension .civ is sought (obsolete format). |
| 167 | | [sec3.6_mask<-] -''' 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 -* 20 < Intensity < 200:('gray mask') the vector in this place will be absent -* Intensity>200 the vector will be computed _ .png imageswith appropriate name in the image directory can be automatically recognised by '''uvmat.fig''' and '''civ.fig''', see [section 8.1->#sec8.1]. The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]''' on the upper right. |
| 168 | | |
| 169 | | [sec3.6_grid<-] -''' 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 <cadre> n X1 Y1 X2 Y2 ...... Xn Yn </cadre> The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [section->#sec8.2]. |
| 170 | | |
| 171 | | -'''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (Callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the briowser of '''uvmat.fig'''. |
| 172 | | |
| 173 | | -''''.civ' ''' 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}). -*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 ;cvi file is named aa.civ. <cadre> 19 % number of bursts 1024 1024 % image size npx npy 4 % number of images per burst 2 % not used 0.016667 % time of exposure (in seconds) 5.860000 5.860000 % scaling pixel/cm x and y directions 5.860000 5.860000 % same 0 % not used 1 0.000000 30 60 30 1 2 25.001003 30 60 30 1 ......................... 18 424.999847 30 60 30 1 19 450.000824 30 60 30 1 % for each line: burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames. </cadre> |
| | 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 [wiki:#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 |
| | 178 | {{{ |
| | 179 | n X1 Y1 X2 Y2 ...... Xn Yn |
| | 180 | }}} |
| | 181 | The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [wiki:#a9-Masksandgrids: section 9.2]. |
| | 182 | |
| | 183 | * '''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the browser of '''uvmat.fig'''. |
| | 184 | |
| | 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. |
| | 187 | {{{ |
| | 188 | 19 % number of bursts 1024 1024 % image size npx npy 4 % number of images per burst 2 % not used 0.016667 % time of exposure (in seconds) 5.860000 5.860000 % scaling pixel/cm x and y directions 5.860000 5.860000 % same 0 % not used 1 0.000000 30 60 30 1 2 25.001003 30 60 30 1 ......................... 18 424.999847 30 60 30 1 19 450.000824 30 60 30 1 % for each line: burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames. |
| | 189 | }}} |
| 182 | | -'Project': contains all information from a project. -'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'. -'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. -'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. '' |
| 183 | | |
| 184 | | '''Mirror data trees''' can be created to process a source data set in read only mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic links to the DataSeries directories. Data processing then results in real DataSeriies directories created in the Experiment directory. An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains the path and name of the source directory under the label <SourceDir>. The mirror directory can be regularly updated by pressing the button 'update_mirror'. |
| | 198 | * 'Project': contains all information from a project. |
| | 199 | * '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'. |
| | 200 | * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. |
| | 201 | * '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. '' |
| | 202 | |
| | 203 | '''Mirror data trees''' can be created to process a source data set in read only mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic links to the DataSeries directories. Data processing then results in real DataSeries directories created in the Experiment directory. An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains the path and name of the source directory under the label <SourceDir>. The mirror directory can be regularly updated by pressing the button 'update_mirror'. |
| 191 | | Images are matrices of integers, visualised by the Matlab function {imagesc.m}. |
| 192 | | |
| 193 | | True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images. |
| | 210 | Images are matrices of integers, visualised by the Matlab function ''imagesc.m''. |
| | 211 | |
| | 212 | True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images. |
| 197 | | The black and white (B/W) images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[MinA]''' and '''[MaxA]''' on the right of the interface: the luminosity level set by '''[MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[MaxA]''' (or levels above) as white. When the check box '''[AutoScal]''' is selected, '''AMin''' and '''AMax''' are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set for '''AMax'''. B/W images can be displayed with false colors, from blue to red, by unselecting the check box '''[BW]'''. |
| 198 | | |
| 199 | | Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion. |
| 200 | | |
| 201 | | Scalar fields are represented like B/W images, by default with a false color map ranging from blue (minimum values) to red (maximum), or as gray scale images by selecting the check box '''[BW]'''. Other color maps can be used by extracting the figure with the menu bar button '''[Export/extract figure]''', then using the standard Matlab button '''[Edit/Colormap]''' in the figure menu bar. |
| | 216 | The greyscale images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[num_MinA]''' and '''[num_MaxA]''' on the right of the interface: the luminosity level set by '''[num_MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[num_MaxA]''' (or levels above) as white. When the check box '''[CheckFixScalar]''' is not selected, these bounds are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set by '''[num_MaxA]'''. Greyscale images can be displayed with false colors, from blue to red, by unselecting the check box '''[CheckBW]'''. |
| | 217 | |
| | 218 | Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion. |
| | 219 | |
| | 220 | Scalar fields are represented like B/W images, by default with a false color map ranging from blue (minimum values) to red (maximum), or as gray scale images by selecting the check box '''[BW]'''. Other color maps can be used by extracting the figure with the menu bar button '''[Export/extract figure]''', then using the standard Matlab button '''[Edit/Colormap]''' in the figure menu bar. |
| 227 | | For 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. |
| | 246 | For 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. |
| 230 | | A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''. Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). |
| 231 | | |
| 232 | | If 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. |
| 233 | | |
| 234 | | If two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. |
| | 249 | A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''. Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). |
| | 250 | |
| | 251 | If 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. |
| | 252 | |
| | 253 | If two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. |
