Document sans titre

I-File organisation and nomenclature:

1-File hierarchy:

Image files to be processed must be stored in a hierarchical set of directories as:

Project/Exp/Device/Record/Images.

'Project' is a directory containing all the data about an experimental project.
'Exp' is a directory containing all the data for a particular experiment in the project.
'Device' is a directory containing data from a particular device, here an image acquisition system. Its name should be automatically set by the device and remain the same for all experiments using this device. Different devices can be used in the same experiment, corresponding to different instruments.
'Record': successive records from the same device in a given experiment can be classified in different directories 'Record', named for instance 'TEST', 'R1','R2'.... The 'Record' sub-directory is not mandatory.

Data subdirectories: data obtained by the processing of a series of images, for instance velocity fields, are stored in a subdirectory of the directory containing these images.

Documentation files: each directory can contain a .xml documentation file providing information about the files contained in this directory (as well as in sub-directories). In particular the directory of the images contains a .xml file 'ImaDoc' with all the needed information on image timing and calibration, as well as a summary of data obtained from the images.

2-Labelling series of images and velocity fields:

Series of images, labelled by an index i can be used, and are named in the form 'root_i.ext' (e.g. 'aa_45.png').

Double series of images, labelled by two indices i and j, are more generally used. They are named in the form 'root_i_j.ext' (e.g. 'aa_45_2.png'). The index i is the rank inside a burst or in a 3D scan, while j is the rank of the burst or scan.

In both cases, the corresponding image documentation file, stored in the directory containing the images, is named 'root.xml'.

Velocity fields obtained from an image series are stored in a data subdirectory of the directory containing the images, with the format netcdf (.nc). The file resulting from the correlation of the images 'root_i_j1.ext' and 'root_i_j2.ext' is called 'root_i_j1-j2.nc', while the result from the images 'root_i1_j.ext' and 'root_i2_j.ext' is called 'root_i1-i2_j.nc'.

3-Image documentation file (ImaDoc):

The image documentation is provided by a .xml text file, see http://www.w3schools.com/xml for an introduction to the xml language. In this language, each element of information, or group of elements, is labelled by a tag. The list of tags and their hierarchical organisation is specified by a schema file (.xsd). The schema for image documentation is ImaDoc.xsd.

The root element is labelled <ImaDoc>. It contains elements:

<Heading>: contains elements <Project>, <Exp>, <Device>.. to recall the position of the file in the arborescence, allowing to check that the document file has not been displaced.
<Camera> contains information on the camera, as well as the timing of all the images.
<GeometryCalib> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates. The method of Tsai (ref.???) is used.
<Illumination> describes the illumination system used, including position of laser sheet.
<Tracor> describes the properties of the flow tracor (particle, dye...)
<ResultVelocity> summarizes the PIV processing which has been performed.

Details are available as comments in the schema file ImaDoc.xsd.

II-Image files:

The standard format ping (.png) is advised for images, see http://www.libpng.org/pub/png for information. It provides lossless (reversible) compression of the data, limiting the required disk storage space. It can be read by usual programmes for image visualization and processing.

III-Velocity files (netcdf format):

The velocity fields obtained by PIV, as well as their spatial derivatives, are stored in the machine independent binary format 'netcdf', see http://www.unidata.ucar.edu/packages/netcdf for general information about this format. The file contains constants ('attributes') and fields ('variables') whose values can be directly accessed by their name.

Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' can be stored in the same .nc file.

'civ1' is the first image correlation processing,
'fix1' is a fix operation, removing some false vectors from the result of civ1
'patch1' is the interpolation-smoothing on a regular grid of the previous field, providing spatial derivatives.
'civ2', 'fix2', 'patch2' correspond to a second iteration of the hierarchical image correlation algorithm, see ??? for a description.

When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2.

1-List of constants:

nb_coord: =2 for PIV in a plane, =3 for PIV in a volume.
nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume).
constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise.
pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1).
pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1)
Tsai parameters ???
absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken).
dt: time interval between the two images of the pair.
absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair.
dt2: same as dt for the fields obtained by the second iteration (civ2).
hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise.
civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair)
fix: =1 if a fix1 operation has been performed,
patch: =1 if a patch1 operation has been performed.
civ2: =1 if a civ2 operation has been performed.
fix2:=1 if a fix2 operation has been performed.
patch2: =1 if a Patch2 operation has been performed.
patch_nx: number of grid points in the x direction for the patch field
patch_ny: number of grid points in the y direction for the patch field
ro_patch: smoothing coefficient rho used for patch
patch2_nx: number of grid points in the x direction for the patch2 field
patch2_ny: number of grid points in the y direction for the patch2 field
ro2_patch: smoothing coefficient rho used for patch2

2-List of field arrays:

A set of velocity vectors is defined by a 1D array of position coordinates x, y, z and a corresponding array for each of the velocity components u, v, w. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. The field w is only present in the case of 3D velocity (stereoscopic PIV in a plane or PIV in volume), z is only present in the case with three coordinates (PIV in volume). Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation). It is advised that different fix programmes use different digits, so that each correction is reversible (for instance FixFlag=1 from the first programme, FixFlag=10 from the second one).

Code for vec_F:

vec_F=1: default, everything is fine

vec_F=-2: the maximum of the correlation function is close to the border: the search domain is too small

vec_F=2: (only in civ1) we keep the inaccurate Hart result (resulting from averaging with neighborhing points) and vec_C=0 is chosen by convention.

vec_F=3: the optimization of the correlation function is unstable or local intensity rms of the image =0

vec_F=4:only in civ2: the difference between the estimator and the result is more than 1 pixel

Field names:

Different velocity fields, corresponding to successive estimates of a given velocity field, are stored in the same .nc file. The names of the fields (variables) resulting from each operation are given in the following table. Each column corresponds to an operation. 'filter1' and 'interp1' both result from the patch1 interpolation on the same points, with and without smoothing respectively. The first line is the name of the constant representing the number of vectors (the dimension of the arrays). The next successive lines indicate the variable names for the position and velocity components, the image correlation 'c', the 'flag' about civ quality and 'fix' flag (only available for civ1 and civ2), and the spatial derivatives obtained from the patch operations.

	civ1	interp1	filter1	civ2	interp2	filter2
dim.	nb_vectors	nb_vec_patch	nb_vec_patch	nb_vectors2	nb_vec2_patch	nb_vec2_patch
x	vec_X	vec_patch_X	vec_patch_X	vec2_X	vec2_patch_X	vec2_patch_X
y	vec_Y	vec_patch_Y	vec_patch_Y	vec2_Y	vec2_patch_Y	vec2_patch_Y
z	vec_Z	vec_patch_Z	vec_patch_Z	vec2_Z	vec2_patch_Z	vec2_patch_Z
u	vec_U	vec_patch0_U	vec_patch_U	vec2_U	vec2_patch0_U	vec2_patch_U
v	vec_V	vec_patch0_V	vec_patch_V	vec2_V	vec2_patch0_V	vec2_patch_V
w	vec_W	vec_patch0_W	vec_patch_W	vec2_W	vec2_patch0_W	vec2_patch_W
corr.	vec_C			vec2_C
flag	vec_F			vec2_F
fix	vec_FixFlag			vec2_FixFlag
du/dx		vec_patch0_DUDX	vec_patch_DUDX		vec2_patch0_DUDX	vec2_patch_DUDX
du/dy		vec_patch0_DUDY	vec_patch_DUDY		vec2_patch0_DUDY	vec2_patch_DUDY
dv/dx		vec_patch0_DVDX	vec_patch_DVDX		vec2_patch0_DVDX	vec2_patch_DVDX
dv/dy		vec_patch0_DVDY	vec_patch_DVDY		vec2_patch0_DVDY	vec2_patch_DVDY

IV- Auxiliary files:

1-Grid files:

Text ascii file used to specify a set of points where the PIV processing is performed..It specifies the number of points and a corresponding list of x and y coordinates expressed in image pixels, as follows

nb_of_points
X1 Y1
X2 Y2
......
Xn Yn , with n=nb_of_points

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 betwenn the two images.

2-Mask files:

Mask are used to avoid PIV computations in specified areas. The file is a black and white 8 bit image, with the same size as the image it has to mask.
The greyscale code to use is :
Intensity < 20 the vector in this place will be nul
20 < Intensity < 200 the vector will be undefined
200 < Intensity the vector will be computed

3-.cmx files:

Ascii text files used for the input of the PIV parameters in the civ software. It is produced by the 'RUN' command in the 'civ' interface before the computation starts. Each velocity field *.nc is obtained from the associated command file *.cmx in the same directory. Reading this file can be useful as a record of the PIV parameters.

In a later version, it will be replaced by a .xml 'CivDoc' file.

4-.log files:

Ascii text files used by CIVx to record information on the performed computation. Each velocity field *.nc is associated with a file *.log produced in the same directory by the 'civ' operation. A file *_patch.log is similarly produced by the 'patch' operation.

These .log files are useful to track problems with the computations.

5-.civ files (obsolete)

ascii text file with information on image timing and scales, now replaced by the .xml file ImaDoc. It can still be used to process old data.

Description:

number of bursts
image size nx ny
number of images per burst
joker
frame lenght
ratio between pixel and centimeters in x and y directions
same same
joker again ... something related to the first burst to treat
After there is " number of bursts " lines with the following informations :

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.
Example :

19
1024 1024
4
2
0.016667
5.860000 5.860000
5.860000 5.860000
0
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
Explications :

The example is from an experience with 19 bursts of 4 images, the images are named : aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d.
The images are 1024 by 1024 pixels.
The unit of time is 0.01667 ie 1/60, this mean the camera used a frequency of 60 Hz.
The space conversion 5.86 means each pixel on the image is 5.86 cm width in real space.

The line : 18 424.999847 30 60 30 1 reveals the following informations :
the time interval between the first image acquired in the experience and the first image of this 18th burst is 425 seconds, if you need to know the time elapsed between image aa018b and image aa018d the calculation is :
0.016667*(60+30+1+1)=1.5333 second