1. 1 Welcome to the Insight Toolkit! ITK Lecture 1 - Getting Started Methods in Image Analysis CMU Robotics Institute 16-725 U. Pitt Bioengineering 2630 Spring Term, 2006 Methods in Image Analysis CMU Robotics Institute 16-725 U. Pitt Bioengineering 2630 Spring Term, 2006

2. 2 Goals for this lecture  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  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

3. 3 Online course access  Distribution of lectures/homeworks/etc. will be handled via our lab web site: http://www.vialab.org/methods_course/index. html  Distribution of lectures/homeworks/etc. will be handled via our lab web site: http://www.vialab.org/methods_course/index. html

4. 4 Getting help  Email the TA - Ken Rockot  kjr21@pitt.edu kjr21@pitt.edu  Email Aaron Cois  cacois@pitt.edu cacois@pitt.edu  Email me - Damion Shelton  beowulf@cs.cmu.edu beowulf@cs.cmu.edu  Join the insight-users mailing list; instructions are at http://www.itk.orghttp://www.itk.org  Email the TA - Ken Rockot  kjr21@pitt.edu kjr21@pitt.edu  Email Aaron Cois  cacois@pitt.edu cacois@pitt.edu  Email me - Damion Shelton  beowulf@cs.cmu.edu beowulf@cs.cmu.edu  Join the insight-users mailing list; instructions are at http://www.itk.orghttp://www.itk.org

5. 5 Getting help, cont.  Get help at Pitt  Stop by BEH 761 for Ken or Aaron  Get help at CMU  Damion’s office is EDSH 214  Email is usually the easiest contact method  Get help at Pitt  Stop by BEH 761 for Ken or Aaron  Get help at CMU  Damion’s office is EDSH 214  Email is usually the easiest contact method

6. 6 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  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

7. 7 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 judgment is passed  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 judgment is passed

8. 8 Assignments, cont.  Please interpret due dates as absolute, unless told otherwise  Really  We’re happy to spend time helping you debug code, but not at 11 pm the day before the assignment is due  Please interpret due dates as absolute, unless told otherwise  Really  We’re happy to spend time helping you debug code, but not at 11 pm the day before the assignment is due

9. 9 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  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

10. 10 We can help you with  Windows & Linux: Everyone  MacOS: Damion and Ken  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  Windows & Linux: Everyone  MacOS: Damion and Ken  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

11. 11 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  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

12. 12 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!)  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!)

13. 13 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  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

14. 14 You might be able to do…  Generic programming  Templates & templated classes  Partial specialization  The typedef & typename keywords  Revision control using CVS/SVN  Collaborative programming  Generic programming  Templates & templated classes  Partial specialization  The typedef & typename keywords  Revision control using CVS/SVN  Collaborative programming

15. 15 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.  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.

16. 16 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 http://www.itk.org/HTML/Documentation.htm  You have a copy of the ITK Software Guide on the CD Ken made for you  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 http://www.itk.org/HTML/Documentation.htm  You have a copy of the ITK Software Guide on the CD Ken made for you

17. 17  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  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

18. 18 Step 1  Get all of the code  Fortunately, we have 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  Get all of the code  Fortunately, we have 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

19. 19 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

20. 20 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?  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?

21. 21 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  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

22. 22 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  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

23. 23 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 compilers  CMakeLists.txt files are easy to perform revision control on  This is not unlike the configure-make process you may be familiar with from various Unix systems  But… it works with many compilers  CMakeLists.txt files are easy to perform revision control on

24. 24 In source vs. out source builds Source Tree ITK Common Algorithms BasicFilter Numerics IO ITKb Common Algorithms BasicFilter Numerics IO Binary Tree Recommended ! Out Source Build In Source Build

25. 25 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  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

26. 26 Configure - Easy Start  Run CMake  Select the SOURCE directory  Select the BINARY directory  Run CMake  Select the SOURCE directory  Select the BINARY directory

27. 27 Configure - Easy Start, cont.

28. 28  Disable BUILD_EXAMPLES  Disable BUILD_TESTING  Disable USE_FLTK  Disable USE_VTK  Disable ITK_WRAP_TCL  Disable BUILD_EXAMPLES  Disable BUILD_TESTING  Disable USE_FLTK  Disable USE_VTK  Disable ITK_WRAP_TCL Configure - Easy Start, cont.

29. 29  Ignore CMAKE_CXX_FLAGS  Ignore DART_ROOT  Ignore ITK_DATA_ROOT  Ignore VW_RAW_DATA_PATH  Ignore CMAKE_CXX_FLAGS  Ignore DART_ROOT  Ignore ITK_DATA_ROOT  Ignore VW_RAW_DATA_PATH Configure - Easy Start, cont.

30. 30 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  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

31. 31 Build ITK

32. 32 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  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

33. 33 Verify the Build Libraries will be found in: ITK_BINARY / bin / { Debug, Release} Libraries will be found in: ITK_BINARY / bin / { Debug, Release}

34. 34 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  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. 35 Building with gcc cont. Start in directory containing Insight mkdir InsightBin cd InsightBin ccmake../Insight Edit CMake, reconfigure if needed make Start in directory containing Insight mkdir InsightBin cd InsightBin ccmake../Insight Edit CMake, reconfigure if needed make

36. 36 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  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. 37 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  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. 38 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  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. 39 How to build HelloWorld, cont.  Once CMake is happy, generate the makefile/project for your compiler  Build HelloWorld  Give it a try  Once CMake is happy, generate the makefile/project for your compiler  Build HelloWorld  Give it a try

40. 40 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-of- source and build them like you did HelloWorld  These examples link into ITK Software Guide; read the chapter, poke the code and see what happens…  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-of- source 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. 41 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 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. 42 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  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. 43 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  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. 44 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.).  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. 45 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  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. 46 CVS setup  The CVS server for this course is:  cvs.vialab.org  You will each have a module, based on your email; Ken 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  The CVS server for this course is:  cvs.vialab.org  You will each have a module, based on your email; Ken 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. 47 CVS setup, cont.  I prefer to use a GUI wrapper for CVS  http://www.wincvs.org http://www.wincvs.org  Versions are available for Windows, Mac, and Linux  Windows users can use Explorer integration via http://www.tortoisecvs.org/ http://www.tortoisecvs.org/  Command line works fine too, but may be more awkward if you’re used to GUI’s  I prefer to use a GUI wrapper for CVS  http://www.wincvs.org http://www.wincvs.org  Versions are available for Windows, Mac, and Linux  Windows users can use Explorer integration via http://www.tortoisecvs.org/ http://www.tortoisecvs.org/  Command line works fine too, but may be more awkward if you’re used to GUI’s

48. 48 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 http://www.itk.org/Doxygen/html/index.html  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 http://www.itk.org/Doxygen/html/index.html