1osiv_synth(1) General Commands Manual osiv_synth(1)
2
6 osiv_synth - generate synthetic PIV images
7
9 osiv_synth [...] -f <formula> <file1.tif> <file2.tif>
10
13 osiv_synth generates a pair of images for PIV analysis. The
14 undisplayed image is saved as a TIFF file with the filename
15 file1 and the displaced image is saved as a TIFF file with the
16 filename file2.
17 Parameters can be passed to osiv_synth using two methods. In
19 the first, parameters are passed using options on the command
20 line. In the second, parameters are placed in a text file and
21 the filename is passed using the -p option. These parameters
22 control the methods used to perform the correlation and the
23 nature of the output.
24
28 The parameter file is specified using the -p option. This is a
29 text file which contains parameters in addition to those which
30 are specified on the command line. The format of this file is
31 simple. Each line specifies a single parameter, for example:
32 width = 512
34 height = 512
35 radius = 1.5
36 ...
37 The parameter name used in this file is very similar to that
39 used on the command line (see PARAMETERS). The only difference
40 being that `-' characters in the command line name are replaced
41 with `_' characters in the parameter file. Additional white
42 space is allowed. Blank lines and lines beginning with `#' are
43 ignored.
44 Parameters from a parameter file are "weak" and may be over‐
46 written by parameters that occur on the command line or that
47 occur in later parameter files. Parsing of parameters occurs
48 in the order which the arguments occur in the command line.
49
53 -f --formula FILE
54 This is the name of a program used to generate the par‐
55 ticle displacements. For more detail on the interface
56 and input to this program see Section FORMULAE. The
57 output of the program should usually have three columns
58 with the x displacement in the first, the y displacement
59 in the second, and the z displacement in the third. It
60 must produce accurate values for all particle locations
61 on the image and within the border around the image. As
62 always, coordinate values are in pixels where the origin
63 is located in the upper-right hand corner of the image.
64 -l --list
67 Reasonable default values are automatically chosen for
68 all parameters based on the dimensions of the image and
69 those parameters which are explicitly specified. This
70 option causes osiv_synth to print out the chosen parame‐
71 ters and then exit without performing the correlation.
72 -w --width INTEGER
75 The width of the output images in pixels. Defaults to
76 640.
77 -h --height INTEGER
80 The height of the output images in pixels. Defaults to
81 480.
82 -d --bits INTEGER
85 The number of bits per pixel of the output image. This
86 is limited to values between 1 and 16, inclusive.
87 Defaults to 8.
88 -g --margin INTEGER
91 The area around the actual image must be seeded with
92 particles so that when the particles are displaced there
93 are no edge effects. This is the size of that border in
94 pixels, it should be at least the size of the largest
95 displacement of any of the border points. Optionally,
96 different values for the x and y borders may be set with
97 the options --x-margin and --y-margin. Defaults to 10.
98 --x-margin INTEGER
101 The size of the seeded margin on the left and right of
102 the image. See --margin for more information.
103 Defaults to 10.
104 --y-margin INTEGER
107 The size of the seeded margin on the top and bottom of
108 the image. See --margin for more information.
109 Defaults to 10.
110 --z-margin FLOAT
113 The thickness of the seeded area in the z-dimension of
114 the image. This is similar to --x-margin and --y-mar‐
115 gin, but this is not set affected by --margin. Defaults
116 to 2.
117 -t --thick FLOAT
120 The thickness of the light sheet which illuminates the
121 particles. More specifically, particles are illuminated
122 with an intensity which has a Gaussian profile. The
123 light sheet thickness is twice the standard deviation of
124 this profile. Defaults to 1.0.
125 -n --density FLOAT
128 The average number of particles per cubic voxel.
129 Defaults to 0.025.
130 -s --seed INTEGER
133 An integer used to seed the random number generator.
134 Defaults to 110482.
135 -r --radius FLOAT
138 The mean particle radius in pixels. Each particle has a
139 Gaussian profile, the radius is taken as twice the stan‐
140 dard deviation of this profile. Defaults to 1.5.
141 --radius-dev FLOAT
144 The standard deviation of the particle radii. Defaults
145 to 0.0.
146 --radius-min FLOAT
149 The minimum particle radius. Defaults to 0.0.
150 --radius-max FLOAT
153 The maximum particle radius. Defaults to the radii
154 average plus two times the radii standard deviation.
155 -x --bright FLOAT
158 The mean particle brightness as a value between 0.0 and
159 1.0. Here 0.0 causes particles not to be drawn and 1.0
160 causes particles to have the maximum representable
161 value. Defaults to 0.75.
162 --bright-dev FLOAT
165 The standard deviation of the particle brightness.
166 Defaults to 0.0.
167 --bright-min FLOAT
170 The minimum particle brightness. Defaults to 0.0.
171 --bright-max FLOAT
174 The maximum particle brightness. Defaults to the
175 brightness average plus two times the brightness stan‐
176 dard deviation.
177 -m --spacing FLOAT
180 The particle locations are taken from a uniform distri‐
181 bution, but when a particle location is found to be
182 within some fixed distance of another particle it is
183 rejected and re-sampled. This distance should be speci‐
184 fied in pixels. Defaults to 0.
185
188 For several reasons, it would be very difficult to calcuate
189 particle displacements within the program. It would require
190 parsing of complex expressions, and would ultimately limit the
191 versatility of this program. Instead osiv_synth passes the
192 location of the particles to an external program specified by
193 the user that is expected to read these locations and output
194 displacements in a known format. This is simpler to implement
195 and much more powerful.
196 The interface of the outside program is fixed with the follow‐
198 ing general form:
199 program [...] [input file] [output file]
200 The program should read from the input file if it exists and
202 write to the output file if it exists. Otherwise, the program
203 should read from the standard in and write to the standard out.
204 The input to the program is always a whitespace-delimited text
205 file, where each particle is given a separate line with the
206 particle position represented in three columns. The first col‐
207 umn is the x position, the second is the y position, and the
208 third is the z position.
209 The output of the program should also be a whitespace-delimited
211 text file; however, the user program may or may not include
212 optional columns. The first two columns are mandatory and rep‐
213 resent the x and y displacement of the particle. All following
214 columns are optional. The third column is the z displacement
215 of the particle. The fourth column is the size of the particle
216 relative to the given average size (between 0 and 1). The fifth
217 column is the intensity of the particle before displacement
218 relative to the given average brightness (between 0 and 1).
219 The sixth column is the intensity of the particle after the
220 displacement relative to the given average brightness (between
221 0 and 1). Empty lines and lines beginning with "#" will be
222 skipped. The symbol "*" may be used to skip over an optional
223 column.
224 For example, to set a displacement of 1 pixel to the right, two
226 pixels upward, and give the particle twice the average inten‐
227 sity you should print the following:
228 1.0 -2.0 * * 2
230 By default, the z displacement is be zero. The default rela‐
232 tive particle size is 1.0. The default relative pre-displace‐
233 ment brightness is 1.0. The default relative post-displacement
234 brightness is equal to the pre-displacement brightness.
235
238 Additional documentation can be found online at www.osiv.org.
239
242 osiv_corr(1), osiv_dump(1), osiv_draw(1), osiv_tune(1),
243 readovd(3).
244
247 No known bugs. Please report bugs as www.osiv.org.
248
251 Copyright © 2003-2005 James Strother.
252 OSIV-2.0 osiv_synth(1)