1osiv_corr(1) General Commands Manual osiv_corr(1)
2
6 osiv_corr - perform particle image velocimetry
7
9 osiv_corr [ -o output ] [ -p file] movie_a [movie_b]
10
13 osiv_corr is a program for performing efficient analysis of
14 particle image velocimetry (PIV) images. It provides a variety
15 of algorithms for pre-processing, interpolation, and cross cor‐
16 relation of images. This description is intended as a quick
17 reference, more information can be found in the online manual
18 at (www.osiv.org).
19 Parameters can be passed to osiv_corr using two methods. In the
21 first, parameters are passed using options on the command line.
22 In the second, parameters are placed in a text file and the
23 filename is passed using the -p option. These parameters con‐
24 trol the methods used to perform the correlation and the nature
25 of the output.
26 The output of osiv_corr is a binary file that contains the dis‐
28 placement vectors of particles. These displacement vectors can
29 be visualized using osiv_draw or printed in text form using
30 osiv_dump.
31
34 The parameter file is specified using the -p option. This is a
35 text file which contains parameters in addition to those which
36 are specified on the command line. The format of this file is
37 simple. Each line specifies a single parameter, for example:
38 xcorr_alg = 5
40 grid_xsize = 32
41 grid_ysize = 32
42 ...
43 The parameter name used in this file is very similar to that
45 used on the command line (see PARAMETERS). The only difference
46 being that `-' characters in the command line name are replaced
47 with `_' characters in the parameter file. Additional white
48 space is allowed. Blank lines and lines beginning with `#' are
49 ignored.
50 Parameters from a parameter file are "weak" and may be over‐
52 written by parameters that occur on the command line or that
53 occur in later parameter files. Parsing of parameters occurs
54 in the order which the arguments occur in the command line.
55
58 The images which are correlated in order to calculated dis‐
59 placement vectors are taken from movies specified on the com‐
60 mand line. If one filename is present, both the first and sec‐
61 ond frames are taken from the same movie. If two filenames are
62 present, then the first frame is taken from the first movie and
63 the second frame is taken from the second movie. The movie type
64 is inferred from the file extension, possible file extensions
65 are .dat, .tif, .tiff. The manual contains additional informa‐
66 tion.
67
70 The output file is specified with the -o option. If this
71 option is omitted, data will be written to the the file
72 "osiv.out". The output file contains the calculated displace‐
73 ment vectors as well as all of the parameters which were passed
74 to osiv_corr. This file has a binary format, but can be inter‐
75 pretted using osiv_dump.
76
79 -l --list
80 Reasonable default values are automatically chosen for
81 all parameters based on the dimensions of the image and
82 those parameters which are explicitly specified. This
83 option causes osiv_corr to print out the chosen parame‐
84 ters and then exit without performing the correlation.
85 --xcorr-alg INTEGER
88 The algorithm used to perform the correlation is
89 selected by specifying one of the following integers:
90 1 - Direct Least Squares
91 2 - Fast Direct Least Squares
92 3 - Direct Correlation
93 4 - Fast Direct Correlation
94 5 - Fourier Correlation
95 6 - Fourier Least Squares
96 7 - Iterative Fourier Correlation
97 --pproc-alg INTEGER
100 The algorithm used to perform pre-processing of the
101 images is selected by specifying one of the following
102 integers:
103 0 - None
104 1 - Subtract to minima
105 2 - Add to maxima
106 3 - Stretch to limits
107 4 - Stretch to variance
108 5 - Stretch to average
109 --interp-alg INTEGER
112 The algorithm used to perfom peak interpolation is
113 selected by specifying one of the following integers:
114 0 - None
115 1 - Gaussian
116 2 - Parabolic
117 3 - Paraboloidal
118 4 - Centroid
119 --image-xsize INTEGER
122 The width of the images must be the same for every
123 frame. As osiv_corr can almost always determine image
124 sizes from the input image files, this option is very
125 rarely required. Upper bounds on the image size are
126 specified during the compilation.
127 --image-ysize INTEGER
130 The height of the image must be the same for every
131 frame. As osiv_corr can almost always determine image
132 sizes from the input image files, this option is very
133 rarely required. Upper bounds on the image size are
134 specified during the compilation.
135 --grid-xstart INTEGER
138 The horizontal position of the first correlation window
139 on the image frame. A value of zero abuts the left edge
140 of the first window against the left edge of the frame.
141 You should note that certain algorithms must be able to
142 access the pixels surrounding the window, so the first
143 window may need to be offset. Please see the manual for
144 more information.
145 --grid-ystart INTEGER
148 The vertical position of the first correlation window
149 on the image frame. A value of zero abuts the top edge
150 of the first window against the top edge of the frame.
151 You should note that certain algorithms must be able to
152 access the pixels surrounding the window, so the first
153 window may need to be offset. Please see the manual for
154 more information.
155 --grid-xspace INTEGER
158 The horizontal spacing between correlation windows on
159 the image frame. A value of one places overlapping win‐
160 dows on every pixel.
161 --grid-yspace INTEGER
164 The vertical spacing between correlation windows on the
165 image frame. A value of one places overlapping windows
166 on every pixel.
167 --grid-xsize INTEGER
170 The number of windows placed in each row of the grid of
171 correlations windows used for each frame. The grid size
172 must not extend the grid beyond the image bounds, see
173 the manual for more information.
174 --grid-ysize INTEGER
177 The number of windows placed in each column of the grid
178 of correlations windows used for each frame. The grid
179 size must not extend the grid beyond the image bounds,
180 see the manual for more information.
181 --disp-xoffset INTEGER
184 A horizontal displacment around which all correlations
185 are calculated. Adding a fixed displacement improves the
186 accuracy of the correlation in flow fields that are pri‐
187 marily uniform. The displacement is added back to the
188 vector before values are output, so no post-processing
189 is required.
190 --disp-yoffset INTEGER
193 A vertical displacment around which all correlations
194 are calculated. Adding a fixed displacement improves the
195 accuracy of the correlation in flow fields that are pri‐
196 marily uniform. The displacement is added back to the
197 vector before values are output, so no post-processing
198 is required.
199 --disp-xmax INTEGER
202 The maximum horizontal displacement to be examined. For
203 direct methods, the correlation is only evaluated up to
204 this limit. For FFT-based methods, the search is limited
205 to this maximum.
206 --disp-ymax INTEGER
209 The maximum vertical displacement to be examined. For
210 direct methods, the correlation is only evaluated up to
211 this limit. For FFT-based methods, the search is limited
212 to this maximum.
213 --disp-xiter INTEGER
216 The maximum horizontal displacement to which the Itera‐
217 tive Fourier Correlation algorithm may displace a win‐
218 dow. It is ignored by all other algorithms. Note that
219 the correlation window will then be limited to a maxmi‐
220 mum displacement of disp_xmax + disp_xiter.
221 --disp-yiter INTEGER
224 The maximum vertical displacement to which the Iterative
225 Fourier Correlation algorithm may displace a window. It
226 is ignored by all other algorithms. Note that the cor‐
227 relation window will then be limited to a maxmimum dis‐
228 placement of disp_ymax + disp_yiter.
229 --wind-xsize INTEGER
232 Horizontal size of the window used to perform the corre‐
233 lation. Larger windows are generally less prone to
234 error, while smaller windows yield finer spatial resolu‐
235 tion. For FFT-based methods, powers of two allow effi‐
236 cient algorithms.
237 --wind-ysize INTEGER
240 Vertical size of the window used to perform the correla‐
241 tion. Larger windows are generally less prone to error,
242 while smaller windows yield finer spatial resolution.
243 For FFT-based methods, powers of two allow efficient
244 algorithms.
245 --wind-size INTEGER
248 Set the horizontal and vertical sizes of the window to
249 the same value, simultaneously. This is identical to
250 calling both --wind-xsize and --wind-ysize with the same
251 value.
252 --wind-xsuper INTEGER
255 Horizontal size of the larger underlying correlation
256 window used in the Fourier Correlation and Fourier Least
257 Squares algorithms. This parameter is ignored by all
258 other algorithms. See the manual for more information.
259 --wind-ysuper INTEGER
262 Vertical size of the larger underlying correlation win‐
263 dow used in the Fourier Correlation and Fourier Least
264 Squares algorithms. This parameter is ignored by all
265 other algorithms. See the manual for more information.
266 --wind-super INTEGER
269 Set the horizontal and vertical size of the super window
270 to the same value, simultaneously. This is identical to
271 calling both --wind-xsuper and --wind-ysuper with the
272 same value.
273 --movie-start INTEGER
276 The first frame of the movie on which cross correlation
277 is performed. This number is used to calculate the file‐
278 name to use with some movie types, the tiff directory to
279 read with tiff movies, and byte offsets for raw movies.
280 See the manual for more information.
281 --movie-finish INTEGER
284 The last frame of the movie on which cross correlation
285 is performed. This number is used to calculate the file‐
286 name to use with some movie types, the tiff directory to
287 read with tiff movies, and byte offsets for raw movies.
288 See the manual for more information.
289 --movie-skip INTEGER
292 The number of frames to skip between sets of frames that
293 are cross correlated. See the manual for more informa‐
294 tion and some helpful examples.
295 --movie-set INTEGER
298 The number of frames that separate a pair of images to
299 be cross correlated. See the manual for more information
300 and some helpful examples.
301 --num-iter INTEGER
304 The number of iterations to perform when using the iter‐
305 ative cross correlation algorithm. All other algorithms
306 ignore this parameter.
307 --fft-wisdom FILE
310 The FFT-based algorithms make use of the FFTW library.
311 This library is self-tuning and can make use of timing
312 information which may be generated by the program
313 osiv_tune.
314 --write-map
317 This option causes correlation maps to be written to be
318 included in the output file. This substantially
319 increases the size of the output file, and so this out‐
320 put should normally be omitted.
321
324 Additional documentation can be found online at www.osiv.org.
325
328 osiv_dump(1), osiv_draw(1), osiv_tune(1), osiv_synth(1),
329 readovd(3).
330
333 No known bugs. Please report bugs as www.osiv.org.
334
337 Copyright © 2003-2005 James Strother.
338 OSIV-2.0 osiv_corr(1)