https://github.com/ma-tech/Woolz
Tip revision: 5ab012fff0fb50186d6ea8508f0d8b3063c45dc3 authored by Bill Hill on 15 August 2022, 13:30:41 UTC
README now Readme.md.
README now Readme.md.
Tip revision: 5ab012f
FAQ.html
<!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>
