Welcome to the Insight Toolkit!
ITK Lecture 2 - Getting Started
Methods in Image Analysis
CMU Robotics Institute 16-725
U. Pitt Bioengineering 2630
Spring Term, 2004
1
Methods in Image Analysis 2004, Damion Shelton
Goals for this week
• Compile, compile, compile
– Learn how to use CMake
– Build ITK
– Compile several programs that use ITK
• Find documentation online
• Learn the quirks (if any) of the system you
choose to use
2
Methods in Image Analysis 2004, Damion Shelton
Online course access
• Distribution of lectures/homeworks/etc. will be
handled via our lab web site:
http://www.vialab.org/methods_course/index.html
3
Methods in Image Analysis 2004, Damion Shelton
Getting help
• Email the TA - Aaron Cois
– cacst11@pitt.edu
• Email me - Damion Shelton
– beowulf+teaching@cs.cmu.edu
– PLEASE remember the +teaching!!
• Join the insight-users mailing list;
instructions are at http://www.itk.org
4
Methods in Image Analysis 2004, Damion Shelton
Getting help, cont.
• Get help at Pitt
– Aaron’s office is BEH 761
– Office phone 412-624-9931
• Get help at CMU
– Damion’s office is NSH, A408-o (in the cube
farm)
– Office phone 412-268-3866
• Email is usually the easiest contact method
5
Methods in Image Analysis 2004, Damion Shelton
Assignments
• Collaboration is encouraged; unless told
otherwise, feel free to discuss assignments
with other students
• But… please submit your own code - don’t
copy and paste stuff from friends
• More so than other classes, you will be
learning techniques that translate directly to
the real world - don’t cheat yourself
6
Methods in Image Analysis 2004, Damion Shelton
Grading of assignments
• Grading criteria:
– Does it accomplish the specified task?
– Is it well commented? Follow the “6 month
rule” - if you leave for 6 months, you should be
able to pick up where you left off.
– Many/most assignments will be pass-fail, with
an opportunity to fix problems before final
judgement is passed
7
Methods in Image Analysis 2004, Damion Shelton
Assignments, cont.
• Please interpret due dates as absolute,
unless told otherwise
• Really
• Aaron and I are happy to spend time
helping you debug code, but not at 11 pm
the day before the assignment is due
8
Methods in Image Analysis 2004, Damion Shelton
Computer requirements
• Windows, Linux, and Mac OS 10.2+ work
great, other platforms will work too
– Your own computer is preferable, but cluster
machines will work
– Please be aware that ITK can consume a lot of
disk space during the build process
• There is no reason to use one of the
platforms over another, pick your favorite
9
Methods in Image Analysis 2004, Damion Shelton
We can help you with
•
•
•
•
Windows & Linux: Aaron or Damion
MacOS: Damion
Sun, SGI, Cygwin: You’re on your own
If you’re going to have compiler problems,
they’ll show up early in the course, so don’t
procrastinate the first assignment
10
Methods in Image Analysis 2004, Damion Shelton
What is ITK?
• To clarify, ITK is a toolkit
– It doesn’t “do” anything
– You can’t “run” it
– There isn’t an itk.exe file
• Typically, you use ITK in conjunction with
other toolkits to handle visualization and
GUI interaction
11
Methods in Image Analysis 2004, Damion Shelton
So, what’s it good for?
• ITK code is easy to add to existing C++
code
• It provides a variety of flexible data
containers, and ways of processing /
analyzing them
• You can do a lot in only a few lines of code
• Once you get used to it, it’s easy to use
(gasp!)
12
Methods in Image Analysis 2004, Damion Shelton
What we assume you can do
• Understand C++ syntax
– Classes
– Basic inheritance
– Standard flow control such as for, do, calling
functions, etc.
– Pointers, dereferencing, passing by reference
• Work comfortably in the operating system
of your choice, using the compiler of your
choice
13
Methods in Image Analysis 2004, Damion Shelton
What you might be able to do
• Generic programming
– Templates & templated classes
– Partial specialization
• The typedef & typename keywords
• Revision control using CVS
• Collaborative programming
14
Methods in Image Analysis 2004, Damion Shelton
You probably have not…
• Used cross-platform make software (Jam,
for example)
• Written C++ code that builds on multiple
platforms
• Designed software using a data-flow
architecture, worried about smart pointers,
etc.
15
Methods in Image Analysis 2004, Damion Shelton
QuickTime™ and a
TIFF (Uncompressed) decompressor
are needed to see this picture.
Step 0 - Don’t panic!
• There is substantial documentation on
everything I’m going to present here, and
vastly more about things that we will never
cover in this course
• http://www.itk.org/HTML/Documentation.htm
• You have a copy of the ITK Software Guide on
the CD Aaron made for you
16
Methods in Image Analysis 2004, Damion Shelton
QuickTime™ and a
TIFF (Uncompressed) decompressor
are needed to see this picture.
• Please DON’T wear yourself trying to write
down all of the content of the following slides;
they’ll be on the course web page
• DO interrupt me and ask questions if
something isn’t clear
17
Methods in Image Analysis 2004, Damion Shelton
Step 1
• Get all of the code
• Fortunately, Aaron made CD’s for you
• If you’re working on some particularly
esoteric platform, it’s possible that you’re
missing a binary version of CMake for your
machine
18
Methods in Image Analysis 2004, Damion Shelton
What do I need ?
C++ Compiler
gcc 2.95 – 3.2
Visual C++ 6.0
Visual .NET
Intel 5.0
IRIX CC
Borland 5.0
Mac OSX - gcc
CMake
www.cmake.org
19
Methods in Image Analysis 2004, Damion Shelton
Cross platform development
• ITK builds on a large combination of
operating systems and platforms
• Each compiler has it’s own input format;
makefiles, workspaces, etc.
• Q: How can you possibly coordinate builds
on different platforms?
20
Methods in Image Analysis 2004, Damion Shelton
The answer: CMake
• Cross platform tool to manage the
build process
• Simplifies the build process
• Auto-configuration
• Easy access to external libraries
• Used by several other open source
projects
www.cmake.org
Methods in Image Analysis 2004, Damion Shelton
21
How CMake runs
• Write a CMakeLists.txt file describing your
project in CMake’s language
• Run CMake to generate an appropriate
makefile/project/workspace for your
compiler
• Compile as you normally would
22
Methods in Image Analysis 2004, Damion Shelton
How CMake runs, cont.
• This is not unlike the configure-make
process you may be familiar with from
various Unix systems
• But… it works with many disparate
compilers
• CMakeLists.txt files are easy to perform
revision control on
23
Methods in Image Analysis 2004, Damion Shelton
In source vs. out source builds
Source Tree
Out
Source Build
ITK
Binary Tree
ITKb
Common
Common
Algorithms
Algorithms
BasicFilter
BasicFilter
Numerics
IO
In
Source
Build
Methods in Image Analysis 2004, Damion Shelton
Numerics
IO
24
Why use two trees?
• Keeps your source and binary code separate
• Minimizes the amount of damage you can
do to your CVS tree
• ITK is found in the /Insight folder
• We suggest that you build it in the
/InsightBin folder
25
Methods in Image Analysis 2004, Damion Shelton
Configure - Easy Start
• Run CMake
• Select the SOURCE directory
• Select the BINARY directory
26
Methods in Image Analysis 2004, Damion Shelton
Configure - Easy Start, cont.
27
Methods in Image Analysis 2004, Damion Shelton
Configure - Easy Start, cont.
• Disable BUILD_EXAMPLES
• Disable BUILD_TESTING
• Disable USE_FLTK
• Disable USE_VTK
• Disable ITK_WRAP_TCL
28
Methods in Image Analysis 2004, Damion Shelton
Configure - Easy Start, cont.
• Ignore CMAKE_CXX_FLAGS
• Ignore DART_ROOT
• Ignore ITK_DATA_ROOT
• Ignore VW_RAW_DATA_PATH
29
Methods in Image Analysis 2004, Damion Shelton
Configuring and Generating
• Each time you change an option or options
you may need to “configure” CMake again
• If the generate option (“OK” under
Windows) is not presented, you definitely
need to hit configure again
• If any of the options are highlighted in red,
you need to reconfigure
30
Methods in Image Analysis 2004, Damion Shelton
Build ITK
31
Methods in Image Analysis 2004, Damion Shelton
Build ITK
• Open ITK.dsw in the Binary Directory
• Select ALL_BUILD project
• Build it - it takes about 15 minutes on a
P3-1000, but your mileage may vary
32
Methods in Image Analysis 2004, Damion Shelton
Verify the Build
Libraries will be found in:
ITK_BINARY / bin / { Debug, Release}
33
Methods in Image Analysis 2004, Damion Shelton
Verify the Build
The following libraries should be there (possibly an out of date list)
ITKCommon
ITKStatistics
ITKBasicFilters
VXLNumerics
ITKAlgorithms
itkpng
ITKNumerics
itkzlib
ITKFEM
ITKMetaIO
ITKIO
34
Methods in Image Analysis 2004, Damion Shelton
Building with gcc
• Order of operations is the same
• Differences
– Run the ccmake executable, which uses a
curses TUI, the options are identical
– Run make instead of Visual Studio
– Think of CMake as replacing the “./configure”
step you may be used to
35
Methods in Image Analysis 2004, Damion Shelton
Building with gcc cont.
Start in directory containing Insight
mkdir InsightBin
cd InsightBin
ccmake ../Insight
Edit CMake, reconfigure if needed
make
36
Methods in Image Analysis 2004, Damion Shelton
Now what?
• At this point, you should have two things:
– A directory containing a bunch of source code
(e.g. ~/Insight)
– A directory containing the built ITK libraries
(e.g. ~/InsightBin)
• As mentioned earlier, you don’t have
anything executable
37
Methods in Image Analysis 2004, Damion Shelton
Building an application
• ITK comes with a simple application you
can build in order to test the ITK libraries
“out of source” (I.e. not built inside ITK)
• It can be found in:
/Insight/Examples/Installation
38
Methods in Image Analysis 2004, Damion Shelton
How to build HelloWorld
• Copy & rename the Installation directory
somewhere outside of the Insight directory
• Run CMake on HelloWorld
– Remember the source/binary distinction and
use HelloWorldBin as your build location
• CMake should automatically find ITK
– if not, edit the ITK_DIR option
39
Methods in Image Analysis 2004, Damion Shelton
How to build HelloWorld, cont.
• Once CMake is happy, generate the
makefile/project for your compiler
• Build HelloWorld
• Give it a try
40
Methods in Image Analysis 2004, Damion Shelton
More examples
• You can turn on the Examples option in
CMake, which will build all of the
examples for you
• Or… you can copy the examples out-ofsource and build them like you did
HelloWorld
• These examples link into ITK Software
Guide; read the chapter, poke the code and
see what happens…
41
Methods in Image Analysis 2004, Damion Shelton
Workflow thoughts
You should get used to the idea of:
1. Writing some code
2. Writing a CMakeLists.txt file
3. Running CMake
4. Building your code
5. Rinse, repeat
42
Methods in Image Analysis 2004, Damion Shelton
An aside: how to use ITK with
existing applications
• Your app probably does not use CMake
• In this case, you need to link to the ITK
libraries explicitly and include the
appropriate source directories
• This isn’t hard, but it may take some trial
and error to discover everything you need
• You don’t need to worry about this in the
context of this class
43
Methods in Image Analysis 2004, Damion Shelton
Revision control with CVS
• Revision control software allows you to
store incremental changes to software
• You will be expected to use CVS to manage
your homework assignments
• I encourage you to use revision control on
your code outside of this class as well - it’s
a good habit to develop
44
Methods in Image Analysis 2004, Damion Shelton
CVS terms
• Server - what it sounds like
• Module - a group of files that can be
accessed on the server
• User - each module has associated users,
with varying levels of access (read only,
read/write, etc.).
45
Methods in Image Analysis 2004, Damion Shelton
CVS terms, cont.
• Checkout - Download a fresh copy of a
module from the server to your computer
• Update - Sync your copy of a module with
the server copy; much faster than a
checkout
• Commit - Merge changes made to your
local copy with the server
46
Methods in Image Analysis 2004, Damion Shelton
CVS setup
• The CVS server for this course is:
– cvs.vialab.org
• You will each have a module, based on your
email; Aaron will tell you about this
• Only you and the instructors will have
access to this module
• Later, there may be group modules for the
final project
47
Methods in Image Analysis 2004, Damion Shelton
CVS setup, cont.
• I prefer to use a GUI wrapper for CVS
– http://www.wincvs.org
– Versions are available for Windows, Mac, and
Linux
– Windows users can also try
http://www.tortoisecvs.org/
• Command line works fine too, but may be
more awkward if you’re used to GUI’s
48
Methods in Image Analysis 2004, Damion Shelton
ITK Documentation
• Most of the ITK documentation is generated
automatically from source comments using
Doxygen
• Please familiarize yourself with the various
means of navigating the Doxygen
documentation online
• http://www.itk.org/Doxygen/html/index.html
49
Methods in Image Analysis 2004, Damion Shelton