Author Name Reviewed by

Package Utilities

Author	Name	Reviewed by	Name
Monica Lozano	[e-mail]	Monica Lozano	[e-mail]
Date	03/07/08	Date	03/07/08

Add rows as needed

Author	Mail	Date	Version	Description of modification
Monica Lozano	[e-mail]	09/07/08	V1.0	Compilation description is added to the document

Table of Contents

Table of Contents 1

Introduction 3

Requirements 3

Windows 3

Steps for compilation 4

BBTK Configuration 9

Boxes description 10

BuildBinaryImage 10

Example 11

References 11

Cataxis 11

Example 12

References 12

Catpoints 13

Example 14

References 14

Drawaxis 15

Example 15

References 15

ExtractVOI 16

Example 16

References 16

Histogram 16

Example 17

References 17

ImageAND 17

Example 18

References 18

ImageThreshold 18

Example 18

References 18

Load Histogram 19

Example 19

References 19

20

MetaImageWriter 20

Example 20

References 20

MetzRegionGrowing 21

Example 21

References 22

Point 22

Example 22

References 22

PolyDataRender 23

Example 23

References 23

SaveAxis 23

Example 24

References 24

SegmentationConnectivity 25

Example 26

References 26

Spline 26

Example 27

References 27

UCharToUSHORT 27

Example 27

References 27

LoadAxis 27

Example 28

References 28

Distance 28

Example 28

References 29

Introduction

The main idea of this package was to create a standard set of tools that can be used for many purposes in manipulating images and rendering results in different BBTK viewers. This document explains in detail the boxes that belong to the package utilities. Here you can find their description in conjunction with their inputs and outputs.

Requirements

Windows

1. 
   Visual Studio 7 2003
   
2. 
   CMake 2.4 patch 6
   
3. 
   Sofa_2008a
   
4. 
   Latest version of BBTK
   
5. 
   Environment variables:
   
   1. 
      BBTK_DIR = C:\Creatis\bbtk-1.0
      
   2. 
      WXWIN = C:\Creatis\Sofa_2008a\wxWidgets-2.8.5_sofa_bin
      
   3. 
      VTK_DIR =C:\Creatis\Sofa_2008a\vtk5.0.3_sofa_bin
      
   4. 
      SOFA =C:\Creatis\Sofa_2008a
      

Steps for compilation

1. 
   Copy the utilities package in your computer the distribution of the package contains two folders as shown in the next figure /UtiliitesPackage (In this case my path is C:\CAT08\Desarrollo\UpgradeBBTKJulio9\Utilidades)
   

Compilation Steps 1 Utilities distribution

2. 
   Look for the CMakeLists.txt in the utilities folder and put it the CMake installed. Whe it opens you should define the bin path for the package as /UtiliitesPackage/UtilitiesBin and press configure for choosing the compiler with which are you going to work.
   

Compilation Steps 2 Choosing the compiler

3. 
   The CMake is going to show an error because the METZ_SRC folder is not found, So presses Accept and set up the path where the metz folder is, it comes with the utilities distribution. After defining the METZ_SRC path presses configure.
   

Compilation Steps 3: METZ_SRC_ NOT FOUND



Compilation Steps 4 METZ_ SRC definition

4. 
   Now we need to turn on the BUILD_BBTK_PACKAGE_Utilities variable such that we can create the utilities package (bbUtilities.dll). Presses configure.
   

Compilation Steps 5 activating the BUILD_BBTK_PACKAGE variable

5. 
   Check out if the variables USE_VTK and USE_WXWIDGETS are ON. Presses Configure
   

Compilation Steps 6 Cheking VTK_USE and USE_WXWIDGETS variable

6. 
   If the VTK_DIR environment is not set up in your pc or if CMake can’t find the vtk distribution an error will be shown, as the next figure but don’t worry, just presses Accept and set up the vtk path. Presses Configure.
   

Compilation Steps 7 Vtk path to binary distribution (COMPILED)



Compilation Steps 8 Defining VTK Path to the binary distribution

7. 
   Activate the check box show advanced values and verify the CMake configuration , for example the bbtk distribution path, vtk path, wxwidgets path etch.
   

Compilation Steps 9 Final Configuration

8. 
   Press OK. The visual studio project is ready for compiling in the /UtilitiesBin :
   

Compilation Steps 10 visual studio project

BBTK Configuration

For using the package you should configure the configuration file of BBTK, in which you can define the your bbs paths and your package paths using the next xml tags:

These paths are where you have all your bbs files and your personal packages or other packages that you are using. The next figure shows a BBTK configuration.

BBTK Configuration 1 BBTK Configuration file

For accessing to this file you should execute the bbi.exe and go to Tools > Edit BBTK config

Boxes description

BuildBinaryImage

This box allows managing a set of points for applying image processing filters in volume of interested centered in each point being studied.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
InX	X- coordinate points	std::vector	ImageOut	Image Binarized
InY	Y- coordinate points	std::vector	FirstPoint	The first point of the extracted axis
InZ	Z- coordinate points	std::vector
ImageIn	Image to binarize	vtkImageData*

Example

\bbs\appli\Test\TestBuildBinaryImage.bbs

This example allows building the binary image and visualizing it in a viewer 2D

References

None

Cataxis

This box saves the axis extracted from a vessel of a dataset. This box respect the dataset directory structure defined in the CAT competition. This directory structure has four folders; each one representing a vessel, named as vessel0, vessel1, vessel2 and vessel3. In each of these vessels there are 4 files that represent the start point, end point, point A and point B as defined in the CAT competition. This box is designed such that it can save in files the axe points calculated in execution and the point given by the user for starting maracas algorithm. Besides it save the axis points in ordered such that the first point is the closer point to the aortha.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
DSDirectory	The dataset directory that contains the vessel folders	std::string
Vessel	Vessel that is being treat	int
PointsX	X-points of the Axe extracted	std::vector
PointsY	Y-points of the Axe extracted	std::vector
PointsZ	Z-points of the Axe extracted	std::vector
ManualPoint	The manual point clicked by the use for starting maracas algorithm	std::vector
FileNameAxis	Path where is going to be save the axe extracted	std::string
FileNameManualPoints	Path where is going to be save the points clicked by the user for starting maracas algorithm	std::string
Image	Image that is being treated	vtkImageData*

Example

\bbs\appli\ Test\TestCatAxis.bbs

This example allows saving in disk a set of points in text files.

References

None



Figure 1 Selecting the point in the viewer



Figure 2 Saving the point in the Point box

The figure 3 shows the input vectors defined in the catAxis box of the bbs script. The values defined are in voxel coordinates but inside the box are going to be converted to real coordinate according to the spacing of the original image

Figure 3 Setting the points

The figure 4 shows both the directory defined in the bbs script where the files were saved and the content of the files.

Figure 4 Saved files

Catpoints

This box draw the points defined in each vessel (corresponding to the CAT directory structure explained in the CatAxis box), the start point, end point, point A, point B defined in the CAT competition. These points have a color coding: the start point has blue color, the end point has green color, point B has red color and point A has white color.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
DSDirectory	The dataset directory that contains the vessel folders	std::string
Vessel	Vessel from which we are going to see the points	int
InRenderer	The render where is going to be draw the vessel points	vtkRenderer*

Example

\bbs\appli\ Test\TestCatPoints.bbs

This example shows the points defined in the CAT contest which have a color code: blue one is the start point, the green one is the end point, the red one is the point B and the white one is the point A. (Figure 5 shows the points plotted in a viewer 2D corresponding to the vessel 0 )

References

None



Figure 5 CAT reference points

Drawaxis

This box draws an axis that has being saved in a file respecting the CAT competition format file. The axis is drawn with the points defined in the CAT competition but that had being put together in the same file (it means the four points are in the same file).

Inputs			Outputs
Name	Description	Type	Name	Description	Type
FileNameAxisPoints	Path to the file that contains the axis points	std::string
image	Image that is being treated	int
FileNamePoints	Path to the file that contains the CAT points	std::string
InRenderer	The render where is going to be draw the axis and the points	vtkRenderer*
Color	The axis color defined in a rgb tuple an takes value between 0 and 1 in each coordinate	std:vector

Example

\bbs\appli\ Test\TestDrawAxes.bbs

This example allows seeing the resulted axis from the maracas extraction algorithm. (See figure 6)

References

None



Figure 6 Extracted axes

ExtractVOI

This box extracts a volume of interest given an image, a center point and the radius of the cube that represents the VOI.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
CenterPoint	Center point where is going to be extracted the VOI cube	std:vector	OutVOI	The extracted VOI	vtkImageData*
Radius	Cube Radius	int
Image	The image from which is going to be extracted the cube	vtkImageData*

Example

\bbs\appli\ Test\TestExtractVOI.bbs

References

None

Histogram

This box calculate the histogram of an image and writes it in a file named histo.his and that can be read by the plotter included in maracasvisu. The file format is “x tab y”, where x represents the level of grey and y the number of voxels that have that level of grey.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
InImage	Image to which is going to be calculated the histogram	vtkImageData*

Example

\bbs\appli\ Test\TestHistogram.bbs

This example allows to save the histogram of the image given. (Figure7 shows the interface created for saving the histogram)

References

None



Figure 7 Image loaded

ImageAND

This box makes the AND operation between two images. Specifically it was designed to do The and operation between a binary image and the original, but it use can be any.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
ImageIn	Original image	vtkImageData*	ImageOut	Image that represents the and operation between the inputs	vtkImageData*
ImageInBIn	Binary Image	vtkImageData*

Example

\bbs\appli\ Test\TestImageAND.bbs

This example do the AND operation between the image resulted from a region growing with the threshold defined interactively and the original image (figure 8).

References

\bbs\appli\ Test\TestSeedConnectivity.bbs



Figure 8 Left: original image, Right: image result after AND operation

ImageThreshold

This box makes the image threshold between an upper level of grey and a lower level of grey

Inputs			Outputs
Name	Description	Type	Name	Description	Type
In	The image	vtkImageData*	Out	The image thresholded	vtkImageData*
Upper	Upper level of grey	double
Lower	Lower level of grey	double

Example

\bbs\appli\ Test\TestImageThreshold.bbs

This example allows to threshold an image interactively, it means, you can change the lower value and the upper value of the threshold, besides you can change of axial slice with the slice slider on the bottom of the window. (See figure 9)

References

None



Figure 9 Left: Thresholded image, Right: Original image

Load Histogram

Load the data from the file “histo.his” generated by the box Histogram and plots it in the histogram window.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
			OutX	Output X vector of the values loaded from the file “histo.his”	std::vector< double >
			OutY	Output Y vector of the values loaded from the file “histo.his”	std::vector< double >

Example

\bbs\appli\ Test\TestLoadhistogram.bbs

After the histo.his file is generated by the box histogram, execute the script testLoadHistogram.bbs to visualize the histrogram calculated (See figure 10).

References

None

Figure 10 Histogram

MetaImageWriter

Writes the input image to disk in raw format (*.raw) with header (*.mhd).

Inputs			Outputs
Name	Description	Type	Name	Description	Type
FileName	Filename and path where the data will be saved, the filename must contain the extension (*.mhd)	std::string
InImage	Image data	vtkImageData*

Example

\bbs\appli\ Test\TestMetaImageWriter.bbs

This example allows writing an image that has being threshold. You can change the threshold range and write it in a raw image by pushing the button. (See figure 11)

References

\bbs\appli\ Test\TestImageThreshold.bbs



Figure 11 Image writer

MetzRegionGrowing

Given the input parameters and using the, the box generates an output image containing all the points connected to the initial point (PositionXYZ) that are between the values of the threshold. The algorithm removes all the points that have more than 3000 neighboring voxels, meaning large structures will be removed and tubular ones will remain.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
InImage	Input image	vtkImageData*	OutImage	Resulting image	vtkImageData*
SeedPoint	Vector with the Position [x, y, z], this position will be the seed of the algorithm	std::vector
Upper	Minimum value of the threshold	double
Lower	Maximum value of the threshold	double

Example

\bbs\appli\ Test\TestMetz.bbs

This examples allows writing an image in RAW format after applying the metz algorithm (pushing the run button-see figure 5)

References

\bbs\appli\TestMetaImageWriter.bbs



Figure 12 Metz algorithm

Point

This box was created to separate the events of connecting “boxChange” and “boxExecutes” to the rest of the pipeline in case you have different boxes that take a point as input. In this case you can connect the boxChange from a CommandButton to the viewer and connect the output point of the viewer to this box. The rest of the boxes that take a point as input will read it from this box instead of the viewer, resulting only in executing one branch of the pipeline.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
InPoint	Input point, normally value comes from the viewer that is being used (ViewerNV etc.)	std::vector< int >	OutPoint	Output point	std::vector< int >

Example

Any bbs with axis extraction

References

None

PolyDataRender

Adds 3D vtk object (vtkProp3D) to the given renderer

Inputs			Outputs
Name	Description	Type	Name	Description	Type
InRenderer	Renderer of the viewer where the data is going to be displayed	vtkRenderer*
PolyData	Any kind of poly data, the box creates a vtkActor and adds it to the renderer	vtkPolyData *

Example

None

References

None

SaveAxis

Saves the extracted axis (stored in three vectors, each one to each coordinate) and the initial point from which is executed the extract algorithm.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
PointsX	Input X coordinates	std::vector
PointsY	Input Y coordinates	std::vector
PointsZ	Input Z coordinates	std::vector
ManualPoint	Point clicked when generated the axis or vector that is going to be saved	std::vector
FileNameAxis	Filename and path where the data is going to be saved	std::string
FileNameManualPoints	Filename and path where the data is going to be saved	std::string
Image	Original image where the axis was extracted this is used to get the spacing of the image so the coordinates will be in the original format of the image (not voxels)	vtkImageData*

Example

\bbs\appli\ Test\TestSaveAxis.bbs

This example allows extracting an axis of a vessel and writing its extracted points and the initial point (from which the extract algorithm starts) in test files. You need to choose the initial point with the red axes and then push the extract button, and then check the path that you defined for saving the extracted points file and the initial point file to see their data. Equally you can see the extracted axes in the image viewer (see figures 6, 7, 8)

References

None



Figure 13 Point to star the extraction algorithm



Figure 14 The file is created is created in the path given



Figure 15 Extracted axis

SegmentationConnectivity

Given the input parameters and using the VTK algorithm, the box generates an output image containing all the points connected to the initial (PositionXYZ) that are between the values of the threshold.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
In	Input image	vtkImageData *	Out	Resulting image of the algorithm in black and white	vtkImageData *
PositionXYZ	Vector with the Position [x, y, z], this position will be the seed of the algorithm	Std::vector
ThresholdMin	Minimum value of the threshold	Int
ThresholdMax	Maximum value of the threshold	int

Example

\bbs\appli\ Test\TestSeedConnectivity.bbs

This example allows doing and visualizing the region growing algorithm result from a chosen point on the original image. Here you can define the threshold and the point interactively with the pink slider on the left of the window and the red axes on the left viewer (see figure 9).

References

None



Figure 16 Left: Original image, Right: image resulted from region growing algorithm

Spline

Modifies the input vectors X, Y, Z adding new points between every set (x_i, y_i, z_i) and (x_i+1, y_i+1, z_i+1), the resulting line will be smoother than the initial.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
XControlPoints	Input X coordinates	std::vector	XSplinePoints	Output X coordinates	std::vector
YControlPoints	Input Y coordinates	std::vector	YSplinePoints	Output Y coordinates	std::vector
ZControlPoints	Input Z coordinates	std::vector	ZSplinePoints	Output Z coordinates	std::vector

Example

\bbs\appli\ Test\TestSpline.bbs

This example shows how to define the inputs of the spline and calculate the spline line defined by the given points.

References

none

UCharToUSHORT

This box cast an image from unsigned char to unsigned short. This box was created due to problems rendering in windows that belong to BBTK, originally they take data in USHORT as precondition.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
In	Input image to be casted, this should be in Unsigned Char (8 bits) of information per voxel	vtkImageData*	Out	Resulting image in Unsigned short (16 bits) of information per voxel	vtkImageData*

Example

\bbs\appli\ Test\TestCast.bbs

This examples shows how to convert an Unsigned char image into an Unsigned short image and write it in disk.

References

None

LoadAxis

This box loads an extracted axis that was saved in disk. It loads the points in three vectors: x, y and z coordinates respectively.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
FileNameAxisPoints	Path where the extracted points file is	std::string	OutX	x-coordinates	std::vector
			OutY	y-coordinates	std::vector
			OutZ	z-coordinates	std::vector

Example

\bbs\appli\ Test\TestDistance.bbs

This example shows how to use the load axis when is used the distance box.

References

None

Distance

This box calculates the distance from the two first points of an extracted axis with the start point defined by the CAT Contest to verify the valid radius for which OF value is positive.

Inputs			Outputs
Name	Description	Type	Name	Description	Type
FileNameAxisPoints	Path where the extracted points file is	std::string
DSDirectory	Dataset directory as defined by CAT contest
Vessel	Vessel that is under study
InX	x-coordinates	std::vector
InY	y-coordinates	std::vector
InZ	z-coordinates	std::vector

Example

\bbs\appli\ Test\TestDistance.bbs

This example shows how to use the distance box.

References

None