[Insight-users] BiasCorrector

[Jisung Kim]

Hi Jose.

I am not an expert of VTK, so in the following
description of differences between ITK and VTK may be
wrong. If there are mistakes, I hope someone who knows
better about VTK can correct me.

ITK uses heavily templated C++ codes and VTK doesn't.
Therefore, most of ITK functionalities are not in a
precompiled library. Instead, such functionalities
exist in the forms of templated C++ classes or
functions. Most of ITK codes are much like C++
standard template library (STL). To use ITK, knowledge
of C++ template is essential. Unfortunately, this fact
requires more learning efforts from user side.

Another important factor is that almost all ITK
classes and funtions are based on ITK specific data
structures. So you have to import your data (array of
double) to ITK data structure. In this case, you
probably want to use ITK Image class. You will find
explanation about the class in the itkImage.h header
file in the "ITK source directory"/Code/Common
directory. After you import data to ITK image, to do
something interesting on your image data, you usually
run combinations of "filters". A filter is a function
that usually creates an output image from (an) input
image(s) as a result of filter operation. For example,
you can blur your input image using discrete Gaussian
kernels using the DiscreteGaussianImageFilter in the
Code/BasicFilters directory and get a blurred image as
the output of the filter.

The MRI bias correction scheme is currently
encapsulated in a single "filter", named
MRIBiasFieldCorrectionFilter
(itkMRIBiasFieldCorrectionFilter.h and .txx in the
"ITK source directory"/Code/Algoriths directory). You
can learn how to use the filter from
the BiasCorrector.cxx file in the "ITK source
directory"/Examples/MRIBiasCorrection directory. In
the same directory, you will find the "readme" file
that has some explanation about every executables
including the BiasCorrector. The BiasCorrector.cxx is
an example that shows how to use the filter. It is not
a part of any library.

Let's look at what the BiasCorrector does in order:

1. [line 110 - 165] Reads in command line options for
the filter operation. You can find meaning of each
option by seeing the BiasCorrector usage printed out
by running BiasCorrector without any options or
looking at the comments in the
itkMRIBiasFieldCorrectionFilter.h file.

2. [line 168 - 198] Loads input images, the image that
you want to correct (mendatory), the input mask image
(optional), and the outputmask image (optional). Since
you have image data in memory, this step isn't
relevant to your situation. Instead, you have to
import your image data from the array double to ITK
image object. If you have proper image mask data, you
have to create a ITK image for each mask. You can see
the type definitions for the biased image and mask
image in the "mydefs.h" file in the same example
directory. The filter works without masks, but if you
provides proper masks, the filter runs faster, affects
only the region of the image that is specifed by the
output mask, and the resulting bias field would be
more accurate. Only the pixels in the biased image
that have values greater than zero in the input mask
will be included for bias field estimation
computation. Similarily, Only the pixels in the biased
image that have values greater than zero in the output
mask will be corrected using the estimated bias field.


3. [line 204 - 215] Sets up the filter parameters
using the command line options and default values
(using Set"Something"() methods), and Runs the filter
(using the Update() method).

4. [LIne 200 - 202, Line 219 - 229] Saves the
corrected image in a meta image file. If you don't
want the corrected image in a file, you don't need
these codes.

That's about it. Now, let me suggest how to creates a
VC project that uses the MRIBiasFieldCorrectionFilter
class. 

To creates an VC project file (.dsp file) with correct
path information, compile options and etc., it is
highly recommended to use CMake. There is an example
CMake project in the "ITK source
directory"/Examples/SampleProject directory. The
followings are step-by-step instructions 

1) Create an directory for your project where your
applications source code will be (lets say
c:/myproject/).
 
2) Go to the directory "myproject", copy the
CMakeLists.txt file from the SampleProject directory
to the "myproject" directory.

3) Open the copied CMakeLists.txt file using your
favorite text editor. Change the first line that
specifes the name of your project. The unmodified
version is: PROJECT(SampleProject) that means the
project name is SampleProject. If your project name
will be MyProject, you should change the line that
will be: PROJECT(MyProject). Go to the bottom of the
file and change the last line:
ADD_EXECUTABLE(itkSampleProject itkSampleProject) with
your executable name and source file name. The first
argument of ADD_EXECUTABLE() function is the name of
executable and the second one is the name of your
source code file name. For example, you have a
MyProject.cxx file, and you want the executable name
to be myproject. The line should be:
ADD_EXECUTABLE(myproject MyProject). Note that there
is no file extension for the source file name. CMake
has built-in search capability for common file
extensions.

4) Write your MyProject.cxx file

5) Open CMakeSetup program. Fill the "Where is the
source code" text box with "C:\myproject" and the
"Where to build the binaryies" text box with whatever
path that you want your binary to go. Set proper cache
values in the "Cache Values" list. And click the
"configure" button. Repeat configure step to set all
relevant cache values to values that you want. Click
the "OK" button to creats project file.

6) Go to the binary directory and open the dsp file.
Build it!

I explained how to creates your own project for VC.
Now let me summarize possible challenges you are
facing and give some reference points.

1) Creating your own project - I explained this in
this email using the SampleProject in the Examples
directory.

2) Using templated C++ codes - recent C++ reference
books ( I have "The C++ Programming Language - special
edition" by Bjarne Stroustrup that is based on the
second edition with some additional materials.),
"Programming in C++ - Templated classes in C++" <
http://www.cprogramming.com/tutorial/templates.html >,
"The cplusplus.com tutorial - Complete C++ language
tutorial - 5. Advanced concepts - Templates" <
http://www.cplusplus.com/doc/tutorial/tut5-1.html >

3) Importing your image data from your own data
structructure (array of double) to ITK data structure
(ITK Image object) - The simplest way is using the
ImageRegionIteratorWithIndex. The manual page for the
class
<http://www.itk.org/Doxygen/html/classitk_1_1ImageRegionIteratorWithIndex.html
> is the primary information source. I suggest that
you look at the documentation about general "Image
Iterator" concept <
Ihttp://www.itk.org/Doxygen/html/ImageIteratorsPage.html
>. In the MRIBiasCorrection example directory, there
is the "imageutils.h" file. In that file, the
"copyImage" function shows how to use the iterator to
copy image data from an ITK image to another ITK
image. In your case, the source data is your array of
double.

4) Using the MRIBiasFieldCorrectionFilter with ITK
images - See the BiasCorrector example code and my
description in this email. 

After you are able to create your own project and
compile your codes, you may need more specific
information about how the filter works and how to
select good parameters for the filter. I am eager to
work with you at that stage too. I think at this point
we'd better focus on compling source code. If you face
any problem while getting there, post your questions
in the insight users list so I and other people can
help you. 

Thanks,

Jisung.


--- jmanjon <jmanjon@fis.upv.es> wrote:
> Hi  Jisung,
> 
> I compile a itk release as say itk help that`s
> exactly what you told me.
> 
> now I want to use itk and I wonder how to use it.
> 
> I mean in vtk you just have to include the vtk32.lid
> , vtk32.dll and
> header files on a simple way. What lib and header
> file directory must I
> include? no dll has been created!!!
> 
> I have a double array containing an MRI image it
> would be perfect to
> find something in the way :
> 
> BiasCorrection(double * image);
> 
> thanks for your help,
> 
> jose
> 
> 
> Jisung Kim escribi?
> 
> > Hi Jose.
> >
> > The standard way of building the bias correction
> > example in MFC is using CMake.
> >
> > Since you are interested in building the example
> in MS
> > visual c++ evironment, I believe you are using
> > CMakeSetup program that you can download and
> install
> > from cmake's download page
> > < http://www.cmake.org/HTML/Download.html>.
> >
> > 1. you have to double click the CMakeSetup icon on
> > your windows desktop to run CMakeSetup.
> >
> > 2. In the first text box, "Where is the source
> code",
> > type the path where your ITK source is.
> >
> > 3. In the second text box, "Where to build the
> > binaries", type the directory where you want the
> > project files and executables to exist.
> >
> > 4. Make sure the item, "Visual Studio 6", is
> selected
> > in the "Build for" combo box.
> >
> > 5. In the "Cache Values" list, you have to turn on
> the
> > BUILD_AUXILIARY, the BUILD_EXAMPLE, and the
> > BUILD_METAIMAGE. You may not see all the options
> at
> > the first time. Just turn on what you can see in
> the
> > current list AMONG THOSE THREE, and then click the
> > "configure" button at the bottom of the window.
> You
> > probably see the rest options. Turn them on and
> click
> > the "configure" button again. repeat this until
> you
> > turn on the all three options.
> >
> > 6. Click the "configure" button. Now, the "OK"
> button
> > should be enabled. click the button.
> >
> > 7. Go to the ITK binary directory, open itk.dsw
> file
> > using Visual Studio, and build it. It will take
> some
> > time.
> >
> > If everything goes well, you can see
> BiasCorrector.exe
> > in the "ITK binary
> > directory/Examples/MRIBiasCorrection/"Your active
> > configuration name (e.g. Debug, Release, or
> > RelWithDebInfo)"/ .
> >
> > If you have different system settings or face
> > problems, please let me know.
> >
> > Thank you,
> >
> > Jisung.
> >
> > --- jmanjon <jmanjon@fis.upv.es> wrote:
> > > I am new on ITK and I would like to know how to
> use
> > > BiasCorrector.cxx on
> > > my MFC VC++ project.
> > >
> > > what libs and include directories I need??
> > >
> > > A MFC sample would be perfect!!!
> > >
> > > thanks in advance
> > >
> > > jose
> > >
> > >
> > >
> > > _______________________________________________
> > > Insight-users mailing list
> > > Insight-users@public.kitware.com
> > >
> >
>
http://public.kitware.com/mailman/listinfo/insight-users
> >
> > =====
> > Jisung Kim
> > bahrahm@yahoo.com
> > 106 Mason Farm Rd.
> > 129 Radiology Research Lab., CB# 7515
> > Univ. of North Carolina at Chapel Hill
> > Chapel Hill, NC 27599-7515
> >
> > __________________________________________________
> > Do You Yahoo!?
> > Yahoo! Tax Center - online filing with TurboTax
> > http://taxes.yahoo.com/
> 

=====
Jisung Kim
bahrahm@yahoo.com
106 Mason Farm Rd.
129 Radiology Research Lab., CB# 7515
Univ. of North Carolina at Chapel Hill
Chapel Hill, NC 27599-7515

__________________________________________________
Do You Yahoo!?
Yahoo! Tax Center - online filing with TurboTax
http://taxes.yahoo.com/