-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathFAQ.html
311 lines (284 loc) · 9.98 KB
/
FAQ.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >
<title>
Frequently Asked Questions About Woolz
</title>
</head>
<body>
<h1 align=center>
Frequently Asked Questions About Woolz (Version 1.8.4).
</h1>
<h2 id="general-questions">General questions</h2>
<ol>
<li><a href="#general_000000">What is a Woolz object?</a></li>
<li><a href="#general_000001">What is a domain?</a></li>
<li><a href="#general_000002">How can I export a Woolz domain?</a></li>
</ol>
<h2 id="import-questions">Importing and Exporting Woolz Objects</h2>
<ol>
<li><a href="#import_000000">What image format does Woolz use?</a></li>
<li><a href="#import_000001">How can I import/export to/from Woolz objects?</a></li>
<li><a href="#import_000002">I've exported Woolz objects and they've lost their alignment, why is this?</a></li>
<li><a href="#import_000003">How can I create a 3D object from a set of 2D TIFF images?</a></li>
<li><a href="#import_000004">Is Woolz more compact than other file formats?</a></li>
</ol>
<h2 id="usage-questions">Usage examples</h2>
<ol>
<li><a href="#usage_000000">How can I find out what's in a Woolz object?</a></li>
<li><a href="#usage_000001">How can I threshold an object to segment it and then
compute the volume of the segmented parts?</a></li>
<li><a href="#usage_000002">How can I make a memory mapped object?</a></li>
<li><a href="#usage_000003">I've a 200GB 3D object, how can I cut sections from it?</a></li>
</ol>
<h2 id="general-questions">General questions</h2>
<p>
<dt id="general_000000"><font size=+1>Q.</font>
What is a Woolz Object?</dt>
<font size=+1>A.</font>
A Woolz object contains a definition of a region of space.
The object may also contain the values within that region and properties
associated with the object. Much of the power of Woolz comes from the
separation of spatial region and the values within it.
<p>
<dt id="general_000002"><font size=+1>Q.</font>
What is a domain?</dt>
<font size=+1>A.</font>
A woolz domain is usually a region of space, a 2 or 3D
image region, a polygon, boundary list, mesh, transform, ....
For historical reasons histograms are also domains.
<p>
<h2 id="import-questions">Importing and Exporting Woolz Objects</h2>
<p>
<dt id="import_000000"><font size=+1>Q.</font>
What image format does Woolz use?</dt>
<font size=+1>A.</font>
Woolz has it's own image format (which is defined by it's source code)
it can however read and write to a variety of other formats. In doing
this some information may be lost.
<p>
<dt id="import_000001"><font size=+1>Q.</font>
How can I import/export to/from Woolz objects?</dt>
<font size=+1>A.</font>
Woolz has a format conversion filter (small program) WlzExtFFConvert
which will read and write a variety of formats. A number of filters
(particularly those whose name starts with WlzExtFF) can also use
these formats.
<p>
<dt id="import_000002"><font size=+1>Q.</font>
How can I export a Woolz domain?</dt>
<font size=+1>A.</font>
Woolz domains don't have a simple equivalent in many other systems
so often the best way to export them is as images with constant
image values, eg
<pre>
WlzGreySetValue -g 100 domain.wlz | \
WlzExtFFConvert -f wlz -o domain.tif
</pre>
<p>
If you have a compound object with domains these can be exported as
an index object using something like:
<pre>
WlzIndexObjFromCompound compound.wlz | \
WlzExtFFConvert -f wlz -o labels.tif
</pre>
<p>
<dt id="import_000003"><font size=+1>Q.</font>
How can I create a 3D object from a set of 2D TIFF images?</dt>
<font size=+1>A.</font>
You can build a 3D object directly from registered 2D images using
WlzExtFFConstruct3D. This will read/write all the formats supported by
WlzExtFF not just TIFF. For a small number 2D images you can list them on the
command line, eg:
<pre>
WlzExtFFConstruct3D -o recon.tif plane0.tif plane1.tif plane3.tif
</pre>
but when the maximum command line length of your system is to small
you will need to go via a file list, eg:
<pre>
/bin/ls plane*.tif >file.txt
WlzExtFFConstruct3D -o recon.tif -f file.txt
</pre>
<p>
<dt id="import_000004"><font size=+1>Q.</font>
I've exported Woolz objects and they've lost their alignment, why is this?</dt>
<font size=+1>A.</font>
Woolz has a global origin and all Woolz objects have an object offset
with respect to this global origin. Very few image formats support
this an offsets may be lost through exporting from Woolz. Two other
image formats that do support offsets are the Amira Lattice and NIfTI
formats.
<p>
<dt id="import_000005"><font size=+1>Q.</font>
Is Woolz more compact than other file formats?</dt>
<font size=+1>A.</font>
Woolz does not use compression as in JPEG or TIFF but for image objects it
does only store those image values within the domain of the object. Where
image values are not needed, then they are they are not stored. In many
cases the proportion of forground in a a segmented image is as low as a
third of cubiod containing it. If the segmented domain is reasonably
compact then the storing the domain with just the values within it will
require approximately one third of the storage; storing just the domain
(without image values) may result in an order of magnitude reduction.
Woolz objects can also be compressed outside of Woolz by for example
using gzip. The following example is for a very sparse image:
<table border="1">
<tr>
<th>
Image
</th><th>
Size
</th><th>
Comments
</th>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001.nrrd
</td><td>
364kB
</td><td>
Given segmented sparse image.
</td>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001.nii
</td><td>
219MB
</td><td>
Converted to the NIfTI format.
</td>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001.wlz
</td><td>
110MB
</td><td>
16 bit from NIfTI.
</td>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001_ub_thr1.wlz
</td><td>
524kB
</td><td>
Unsigned byte and thresholded to keep values >= 1.
</td>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001_ub_thr1_dom.wlz
</td><td>
336kB
</td><td>
Binary domain from 5HT1bMARCM-F000001_seg001_ub_thr1.wlz
</td>
</tr><tr>
<td>
5HT1bMARCM-F000001_seg001_ub_thr1_dom.wlz.gz
</td><td>
68kB
</td><td>
Compressed (using gzip --best)
</td>
</tr>
</table>
This was achieved using the commands:
<pre>
WlzExtFFConvert -o 5HT1bMARCM-F000001_seg001.wlz 5HT1bMARCM-F000001_seg001.nii
WlzGreyNormalise -u < 5HT1bMARCM-F000001_seg001.wlz >5HT1bMARCM-F000001_seg001_ub.wlz
WlzThreshold -v 1 < 5HT1bMARCM-F000001_seg001_ub_thr1.wlz >5HT1bMARCM-F000001_seg001_ub_thr1.wlz
WlzDomain < 5HT1bMARCM-F000001_seg001_ub_thr1.wlz > 5HT1bMARCM-F000001_seg001_ub_thr1_dom.wlz
</pre>
<h2 id="usage-questions">Usage examples</h2>
<dt id="usage_000000"><font size=+1>Q.</font>
How can I find out what's in a Woolz object?</dt>
<font size=+1>A.</font>
Use WlzFacts to print out basic information about the object, eg:
<pre>
WlzFacts ts14.wlz
Object type: WLZ_3D_DOMAINOBJ.
Linkcount: 0.
Domain type: WLZ_PLANEDOMAIN_DOMAIN.
Linkcount: 1.
Domain plane bounds: 0 305
Domain line bounds: 42 230
Domain column bounds: 50 396
VoxelSize: 4 4 7
Values type: WLZ_VOXELVALUETABLE_GREY.
Linkcount: 1.
Background type: WLZ_GREY_UBYTE.
Background value: 0.
Values plane bounds: 0 305
Property list NULL.
</pre>
<p>
<dt id="usage_000001"><font size=+1>Q.</font>
How can I threshold an object to segment it and then
compute the volume of the segmented parts?</dt>
<font size=+1>A.</font>
<pre>
WlzThreshold -v100 -H image.wlz | \
WlzLabel | \
WlzVolume
</pre>
WlzThreshold keeps only regions of the input image (read from image.wlz)
where the image values are greater than or equal to the given value (100),
splits the segmentation into separate objects using connectivity (using
WlzLabel) and then computes (and prints) the volume of each of these
separate objects where the values are above threshold.
</p>
<p>
<dt id="usage_000002"><font size=+1>Q.</font>
How can I make a memory mapped object?</dt>
<font size=+1>A.</font>
Memory mapped tiled objects allow voxel values to be accessed without
reading all voxel values into memory. This can make operations, such
as cutting a virtual section from a very large 3D image, possible even
on a machine with little memory. If the 3D image fits within the memory
of the machine being used then a tiled object can be made in a single
operation:
<pre>
WlzTiledObjFromDomain -c -o tiled.wlz ts14.wlz
</pre>
If the image is far greater than the memory available then the
tiled object needs to be created in stages. First creating a
tiled object into which the values can be written, this requires
a spatial domain, but a simple cuboid might be sufficient as in
this example:
<pre>
WlzMakeRect -3 -x0,9999 -y0,9999 -z0,9999 -o dom.wlz
WlzVolume dom.wlz
Object 1: number of voxels = 1000000000000
WlzTiledObjFromDomain -b 0 -o tiled.wlz dom.wlz
</pre>
The size of the domain object will typically be around 200kB, while that
of the tiled object will be around 1TB. At this stage the tiled object
will be filled with the given background value (0 in the example).
If the actual values for the tiled object are in separate tiff files then
these might be written to the tiled object using a simple shell loop:
<pre>
N=0
while [ $N -lt 10000 ]
do
WlzExtFFConvert -F wlz -o - sect$N.tif | \
WlzCopyToTiledObj -z $N -t tiled.wlz -
done
</pre>
<dt id="usage_000002"><font size=+1>Q.</font>
I've a 200GB 3D object, how can I cut sections from it?</dt>
<font size=+1>A.</font>
Convert your object to a memory mapped Woolz object, you can then
apply many of the Woolz command line programs or functions to it.
See (<a href="#usage_000002">How can I make a memory mapped object?</a>).
For example, to cut sections orthogonal to the x-y plane use:
<pre>
Wlz3DGetSection -d 10 -a 90,0,0 -o out.wlz tiled.wlz
</pre>
or
<pre>
Wlz3DGetSection -d 10 -a 90,90,0 -o out.wlz tiled.wlz
</pre>
</p>
</ol>
</body>
</html>