1.3 Tutorial 1: How to display a stack of 2D tif files as a 3D image

This is a tutorial for learning how to use Visilog to import a 3D image.

Scripting:
To play this tutorial, first, download the 3D demo package with this link, and uncompress it on your Visilog Directory.
You have on ./images/3D/foam_files/ directory, a stack of 2D images.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module CreateIm6File
You must have the 3D module to use this script

To import this stack as a 3D image, use the multifile2im6 command

To select the stack of images on the input parameter, use left click on the edit area of this parameter to open a Filer. With this filer, select one file of the stack.

For the output image

  * if you use an image name (as image1) Visilog will load all slices on memory and displays this 3D
    images.

  * if you use a filename, Visilog will transform all slices as a Visilog file (with .im6 extension) and     displays this image as a "disk image".

Then you can use all Visilog commands from a memory image or a disk image indifferently. The interest of a disk image is to be able to work with image bigger than the memory available.

  1.4 Tutorial 2: basics - measuring a catalyst

This is a step-by-step tutorial for learning how to use Visilog, through a specific example illustrating some of the most typical manipulations. In this example we compute the distribution of distances from a catalyst to object edges. This particular image analysis process can be easily transposed to other cases.

To follow this tutorial you should be familiar with the basic concepts of Visilog. In particular you should be able to load files, to interact with the 3D viewer, and to link different commands.

Scripting
To play this tutorial, first, download the 3D demo package with this link, and uncompress it on your Visilog Directory.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module Catalyst
You must have the 3D module to use this script

The 3D image used in this example is acquired by microtomography: an almost spherical support contains catalyst and pores. The catalyst appears with dark levels in the image (low intensity voxels). The pores and background appear with luminous levels (high intensity voxels). Intermediary grey levels corespond to the support.

The goal of this example is to get a distribution of distances between the catalyst voxels and the background. The algorithm may be devided in 3 steps :

1. object detection (mask of the object)
2. distance map of the catalyst
3. distribution of the catalyst distances

Loading data
Start by loading Catalyst.im6 from your disk ( ./images/3D/Catalyst.im6)

This image is stored using Visilog .im6 format. However Visilog can be used with any images supported by amira.

When loading Visilog files, datas stay on disk. In this case, the Visilog algorithms will require only some slices to be loaded in memory: this raises most limitation on the size of the 3D images that can be processed. However, if you have enough memory on your system, loading image fully in memory allows much faster processing. For these tutorial examples you can choose to load the data in memory.
To do that, use the copy command to load image on memory.

Use the XoY button to display slice image along Z axis:

You can now start the first step for detection of the object by thresholding then closing. Open the Visilog Processing dialog.

The processing dialog contains:

* a command tree area to select commands type and group
* a pipeline area to select input, command, associated parameters and output
* a choice area to select among options available for the selected item in the pipeline area

In the command tree, select the Thresholding type folder and choose Binarisation group. The choices area shows the set of commands belonging to Binarisation group. Alternatively to using the command tree, you can enter directly the command name (I_threshold) in the command search text area, which supports automatic completion.

Getting more help
Once a command is selected in Visilog Processing panel, pressing F1 key will display the corresponding reference documentation for this command with your pdf viewer. Both user's guide and reference documentation are located in the doc subdirectory in Visilog installation directory.

Thresholding
The main difficulty of this step comes from the very similar intensities between background and pores. Thresholding the image between 0 and 225 gives a binary image where:

* Intensity level = 1 -> support or catalyst (material)
* Intensity level = 0 -> pore or background

Select the threshold parameter in the pipeline area then change the threshold values to the range 0-225 in the choices area. Press the Go button to start the command. You will see this dialog:

Interactive commands
Some Visilog commands support interactive input (name starting by I_). Here you can modify interactively the threshold values, with immediate visual feedback. When you are done, or as you already entered the appropriate values in the processing panel, you can press OK.

The I_threshold command has created a binary image. According to Visilog terminology a binary image can be seen as an image label with only interior and exterior material. For binary images Visilog displays the pixels of intensity 1 with a blue color. The command displays automaticaly the resulting image, an appropriate LUT (lookup table) will be selected by default.

Closing object
In order to detect the object you can now apply morphological operations. The mathematical morphology operators are transforms based on shape and size criteria. The morphological closing operator applied on a binary image gives another binary image where :

* Small holes inside objects are filled
* Objects boundaries are smoothed
* Close objects are connected

Closing the material binary image fills the pores and thus gives a binary mask of the object.

Change on the process panel the input and command in the pipeline area. On input, use the binary image resulting from previous I_threshold command ans select the Closing command (in Morphology type, Open & Close group), then push Go button. Here is the result:

Distance map
The second step is to compute a distance map of the catalyst. Applying the distance algorithm on a binary image gives a grey level image where each voxel intensity represents the minimal distance in voxels from the object boundary. For a given voxel intensity of the object distance map :

* Intensity level = 0 -> background
* Intensity level = 1 -> object envelope
* Others low level intensity -> part of the object close to the object envelope
* Others high level intensity -> part of the object far from the object envelope

You can now apply the distance map command distxxx to the previous result image, leaving the default parameters for the command. Then Visilog displays the object's distance map.

Then thresholding the initial image between 0 and 100 gives a binary image where:

* Intensity level = 1 -> catalyst
* Intensity level = 0 -> support, pore or background

Masking
For computing obtaining the distance map of the catalyst we will used masking. The mask operation :

* takes a grey level image for 1st input,
* takes a binary image for 2nd input (mask image),
* provides a grey level image for output where :

     1. each black voxel of the mask image is set to 0 in the output image,
     2. each blue voxel of the mask image is set to the initial level from the grey image

Masking the distance map image by the catalyst image gives a grey image where:

* ach non null intensity represents a voxel of the catalyst
* the intensity value is equal to the distance in voxels from the object envelope

Apply the mask command to the previous result image. Then Visilog displays the catalyst distance map. .

Measurement
Now we can get the distribution of the distances.

For consistent results, we have to consider the voxel calibration: multiplying the distance image by the voxel size converts the image intensities in the metric system (micrometers). Use the Visilog command multiply with second input set to 5 (assuming a voxel size of 5 micrometers). Then retrieve the maximum value, either with Info port dislpayed in Properties panel when selecting the image icon in the pool, or by using the Visilog extrema command.

Then the histogram command histclas can compute and plot for each grey level i, the number of voxels at intensity i. The number of points per each level is graphed as an histogram. Applying histogram on the catalyst distance map plots a graphic that represents the number of catalyst voxels located at a given distance from the object envelope.

1.5 Tutorial 3: separating, measuring and reconstructing individual objects - pores in foam

The 3D image used in this example was generated using data from several slices of oil. This demonstration illustrates the use of automatic segmentation to extract bubbles. The aim is to isolate and quantify these bubbles.

Scripting
To play this tutorial, first, download the 3D demo package with this link, and uncompress it on your Visilog Directory.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module SeparateFoam
You must have the 3D module to use this script

Loading data
Start by loading foam.im6 from your disk ( ./images/3D/foam.im6)

Automated segmentation with separation Here is the result of an automated segmentation based on the watershed algorithm, which can produce better segmentation than the binseparate command:

You can see the sequence of used commands :

* threshold the image in the range 0-38
* with 3D_6 connectivity way
* separation by maxima distance:

1. create a distance map with distxxx
2. create a maxima markers image with merge_maxima
3. use label command to convert the result to an image suitable for commands operating on     material labels
4. invert distance with logical_not
5. separate objects with watershed algorithm with fastwatershed command using distance map and    markers images as input
6. substract with logical_sub the watershed result image from the image obtained after thresholding    and hole filling.

* convert the result to a label object with label command
* filter out small bubbles from the image in 2 steps:

1. create a filter: command createfilter with expression (Volume3d >= 500)
2. apply the filter with command I_filter_image, using created filter as 2nd input

In addition user can create an image of the bubble boundaries by using erode command and substract, then convert it to a label.

Measurements
Then, you could, for instance, measure the volume for each individual region unsing the I_analyse command.
You will see analysis ont the result viewer.

Measurement results : individual analysis with volume for each region.

Interactive selection
Generating an individual analysis from the result image allows an interaction between the 3D viewer and the Result Viewer in order to locate each object. Selecting a cell in the spreadsheet displayed by Visilog analysis viewer will move a point dragger in the 3D view to the corresponding object location.

Custom measures
Visilog offers powerful ways to define custom measures results. See Visilog user's guide and reference guide for details.

1.6 Tutorial 4: further image analysis - Average diameters distribution of pores in foam This example shows how to compute the distribution of diameters of pores in a foam sample.

Scripting
To play this tutorial, first, download the 3D demo package with this link, and uncompress it on your Visilog Directory.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module DiamDistribution
You must have the 3D module to use this script

Loading data
Start by loading FoamPoro.im6 from your disk ( ./images/3D/FoamPoro.im6)

The image used in this example is also acquired by microtomography. It represents foam that is constituted by material and pores Pores appear with dark levels in the image (low intensity voxels). Material appears with luminous levels (high intensity voxels)

The algorithm may be devided in 3 steps :

1. pores detection
2. pores post-processing
3. distribution of the pores diameters

First step : Pores detection
Thresholding the image between 0 and 50 gives a binary image where :

* Intensity level 1 = porosity
* Intensity level 0 = support (material)

2nd step : Pores post-processing
The morphological opening operator applied on a binary image gives another binary image where :

* Small objects are remove
* Objects boundaries are smoothed
* Some objects may be disconnected

Applying morphological opening on the pores image gives a filtered image where noise and artefacts are reduced.

The binseparate command detects surfaces that separate agglomerated particules. These surfaces are subtracted from the initial image. On a bidimensional image :

binseparate is used with parameter "Depth of valley" = 1

3rd step : distribution of the pores diameters
For a given particle, the equivalent diameter measure computes the diameter of the spherical particle of same volume. So the equivalent diameter is given by the following formula :

Visilog allows to compute a set of measures for each particle of a 3D image Once the individual analysis performed, an histogram of a given measure may be plot in order to get a representation of the measure distribution.

1.7 Tutorial 5: further image analysis - Average thickness of material in foam This example shows how to compute the thickness of material in a foam sample.

Scripting
To play this tutorial, first, download the 3D demo package with this link, and uncompress it on your Visilog Directory.
You have on ./images/3D/foam_files/ directory, a stack of 2D images.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module AverageThickness
You must have the 3D module to use this script

Loading data
Start by loading FoamPoro.im6 from your disk ( ./images/3D/FoamPoro.im6).

The image used in this example is acquired by microtomography. It represents foam that is constituted by material and pores. Pores appear with dark levels in the image (low intensity voxels). Material appears with luminous levels (high intensity voxels).

The algorithm may be devided in 4 steps :

1. porosity detection
2. detection of the separation surfaces
3. distance map of the material
4. calculation of the material average thickness

First step : porosity detection
In a same way as in previous example, let's get the pores binary image, using thresholding and morphological opening operators.

2nd step : detection of the separation surfaces
The goal of this step is to detect surfaces that cross the material at an equidistance from two pores. SKIZ (SKeleton by Influence Zones) operation :

* takes a binary image for input,
* gives a binary image for output where :

1. each blue voxel of the output image is closer to the object situated at the center of the zone in     the input image,
2. each black voxel is equidistant from at least two closer objects

The logical_not operation inverts the levels of a binary image. Applying logical_not on a SKIZ image gives a binary image where :

* each black voxel of the output image is closer to the object situated at the center of the zone in   the input image,
* each blue voxel is equidistant from at least two closer objects

So SKIZ and logical_not combination provides a binary image of surfaces that separate pores through the material.

3rd step : distance map of the material
Applying logical_not on the binary image of porosity gives a binary image where :

* each black voxel of the output image represents a background or porosity voxel,
* each blue voxel represents a material voxel

The distance algorithm applied on a binary image gives a grey level image where each voxel intensity represents the minimal distance in voxels from the object boundary. For a given voxel intensity :

* Intensity level = 0 -> porosity or background
* Intensity level = 1 -> material envelope
* Others low level intensity ? part of material close to the material envelope
* Others high level intensity ? part of material far from the material envelope

The mask operation:

* takes a grey level image for 1st input,
* takes a binary image for 2nd input (mask image),
* provides a grey level image for output where :

1. each black voxel of the mask image is set to 0 in the output image,
2. each blue voxel of the mask image is set to the initial level from the grey image

Masking the distance map image by the separation surfaces image gives a grey image where:

* each non null intensity represents a voxel of a separation surface
* the intensity value is equal to the half distance in voxels between the 2 closest objects

4th step : calculation of the material average thickness

Then the average thickness of the material is given by the following formula :

Where :

* Vsize = voxel dimension in micrometers
* Sigma(i) = Sum of the voxel intensities in the distance map image of the separation surfaces
* NbVoxSep = number of voxels in the binary separation surfaces image

The volume3D command gives the sum of the voxels intensities in a 3D image.

* In a binary image it represents the number of blue voxels
* In a grey level image it represents the sum of all voxels intensities

So :

1. Volume3D of the distance map image of separation surfaces gives Sigma(i)
2. Volume3D of the binary image of separation surfaces gives NbVoxSep

Histogram of thickness

To compute the histogram of thickness you must first multiply the image of distance map of the separation surfaces by 2 * calibration.
To do that, use the multiply command.
Then use histclass command to compute and display the histogram of thickness

1.8 Tutorial 6: further image analysis - Wrapping

This example shows how to set background and pores to different grey level values in order to be able to analyse pores later on.

Scripting
To play this tutorial, first, download the 3D demo package with this href="http://www.noesis.fr/_private/en/logiciels/module3d/Demo3d.zip">link, and uncompress it on your Visilog Directory.
You have on ./images/3D/foam_files/ directory, a stack of 2D images.
Load the VBA project ./VBA/Samples/demo3d/Demo3d.vba.
You can find the script of this tutorial on the module Wrapping
You must have the 3D module to use this script

Loading data
Start by loading Corail.im6 from your disk ( ./images/3D/Corail.im6).

The image used in this example is acquired by medical scanner. It represents coral that is constituted by material and pores. Pores appear with dark levels in the image (low intensity voxels). Material appears with luminous levels (high intensity voxels). In order to analyse inside pores structure, we have to set the background level to another value.

The algorithm may be devided in 4 steps :

1. coral detection
2. numerical filtering to remove small elements
3. "spherical" closing and holes filling to get a full coral mask
4. use of basic operations to change the background level

First step : coral detection
In a same way as in previous example, let's get the material binary image, using threshold.

2nd step : numerical filtering to remove small elements
The goal of this step is to remove binary elements whose volume is lower than the objects' mean volume.

* get the number of binary objects : command number
* get the volume of binary objects : command volume3d
* create a filter: command createfilterwith expression (Volume3d >= Volume3d/Number)
* apply the filter with command I_filter_image, using created filter
* convert the resulting filtered image to binary using convert

3rd step : "spherical" closing and holes filling
The purpose of this step is to get round mask of the coral. If the closing is made using the "classical" closing command then the resulting voxels aspect will be cubic. But if you use the closing operation considering different neighbourhood, the result will have a spherical aspect. This way to proceed works with all morpholigical operations as shown on the following figure considering dialtion.

For this image, a closing using a 6 size structuring element is big enough to connect bordering pores.
Thus this closing is made using the following steps :

* set the neighbourhood to 6 using the neighbourhood3d command
* closing with a structuring element size = 3 using closing
* set the neighbourhood to 18
* closing with a structuring element size = 2
* set the neighbourhood to 26
* closing with a structuring element size = 1

Finally, to get a full mask of the coral, we use the hole_fill command considering 26 neighbours.

4th step : use of basic operations to change the background level

* mask coral image with binary image using mask

1. grey level values under the mask are kept
2. other values are set to 0

* inverse the binary image using logical_not
* create a new image initialized to X level using eraseimg (here X = -1100)
* set the coral's background level to X using mask
* merge the 2 images together using Add

Convex hull can be extracted thanks to the following steps :

* erosion with a strcturing element size = 1 of the mask using erode
* subtraction of the eroded image with the coral mask image using logical_sub

We can now extract coral's pores following these steps :

* threshold of the wrapped coral image using threshold
* subtraction of the thresholded image with the coral convex hull using logical_sub