diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..74ef311c --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/Utilities/.chktexrc diff --git a/Common.cmake b/Common.cmake index 63a369a9..0ba3d299 100644 --- a/Common.cmake +++ b/Common.cmake @@ -16,7 +16,6 @@ endif() #----------------------------------------------------------------------------- # Build option(s) #----------------------------------------------------------------------------- -option(USE_OPTION1 "Build OPTION1" ON) #----------------------------------------------------------------------------- # Update CMake module path diff --git a/ITKSoftwareGuide.cmake b/ITKSoftwareGuide.cmake index 349461e6..2c2504ca 100644 --- a/ITKSoftwareGuide.cmake +++ b/ITKSoftwareGuide.cmake @@ -11,7 +11,8 @@ set(CMAKE_MODULE_PATH ) #----------------------------------------------------------------------------- -find_package(ITK REQUIRED) +set(MINIMUM_ITK_VERSION 5) +find_package(ITK ${MINIMUM_ITK_VERSION} REQUIRED) if(Slicer_BUILD_${PROJECT_NAME}) set(ITK_NO_IO_FACTORY_REGISTER_MANAGER 1) # Incorporate with Slicer nicely endif() diff --git a/SoftwareGuide/Art/CMakeLists.txt b/SoftwareGuide/Art/CMakeLists.txt index 3b7acdcc..448bce85 100644 --- a/SoftwareGuide/Art/CMakeLists.txt +++ b/SoftwareGuide/Art/CMakeLists.txt @@ -9,8 +9,8 @@ file(GLOB PNGandJPG_IMAGES *.jpg *.png) file(GLOB EPS_IMAGES *.eps) -find_package(ImageMagick REQUIRED) -if(NOT IMAGEMAGICK_CONVERT_EXECUTABLE) +find_package(ImageMagick 6 COMPONENTS convert REQUIRED) +if(NOT ImageMagick_convert_EXECUTABLE) message("ImageMagick convert utility was not found. Please pass to advanced mode and provide its full path") endif() # Convert an image from some file format to EPS for inclusion in Latex using @@ -30,7 +30,7 @@ foreach(ImageFile ${PNGandJPG_IMAGES}) set(OutputEPSFile "${OutputEPSFilePath}/${ImageFileNoExt}.eps") add_custom_command( OUTPUT ${OutputEPSFile} - COMMAND ${IMAGEMAGICK_CONVERT_EXECUTABLE} + COMMAND ${ImageMagick_convert_EXECUTABLE} ${EPS_INPUT_CONVERT_FLAGS} ${ImageFile} ${EPS_OUTPUT_CONVERT_FLAGS} diff --git a/SoftwareGuide/Cover/Source/CMakeLists.txt b/SoftwareGuide/Cover/Source/CMakeLists.txt index b341f39e..2e9ae9b2 100644 --- a/SoftwareGuide/Cover/Source/CMakeLists.txt +++ b/SoftwareGuide/Cover/Source/CMakeLists.txt @@ -3,7 +3,7 @@ cmake_policy(VERSION 3.10.2) project( VWSegmentation ) -find_package( ITK REQUIRED ) +find_package( ITK 5 REQUIRED ) include( ${ITK_USE_FILE} ) set( operations diff --git a/SoftwareGuide/Examples/CMakeLists.txt b/SoftwareGuide/Examples/CMakeLists.txt index 7d2ac07b..18792ec2 100644 --- a/SoftwareGuide/Examples/CMakeLists.txt +++ b/SoftwareGuide/Examples/CMakeLists.txt @@ -21,7 +21,7 @@ endforeach() # # First make a directory to store generated images set(ART_GENERATED_FOLDER "${SoftwareGuide_BINARY_DIR}/Art/Generated" ) -make_directory( "${ART_GENERATED_FOLDER}" ) +file(MAKE_DIRECTORY "${ART_GENERATED_FOLDER}" ) # # Rebuild the Software Guide figures @@ -37,8 +37,8 @@ set(RUN_EXAMPLES_SCRIPT "${SoftwareGuide_SOURCE_DIR}/Examples/RunExamples.py" CA # This is used to convert image formats # #include(${CMAKE_ROOT}/Modules/FindImageMagick.cmake) -find_package(ImageMagick REQUIRED) -if(NOT IMAGEMAGICK_CONVERT_EXECUTABLE) +find_package(ImageMagick 6 COMPONENTS convert REQUIRED) +if(NOT ImageMagick_convert_EXECUTABLE) message("ImageMagick convert utility was not found. Please pass to advanced mode and provide its full path") endif() @@ -269,7 +269,7 @@ macro(CONVERT_INPUT_IMG SOME_IMG EPS_IMG IMAGEMAGICK_FLAGS) if( NOT DEFINED \${EPS_IMG}_HAS_CUSTOM_COMMAND) message(STATUS \"Converting \${SOME_IMG}\") execute_process( - COMMAND \"${IMAGEMAGICK_CONVERT_EXECUTABLE}\" \${FLAGS} -quality 100 \${EPS_INPUT_CONVERT_FLAGS} \"\${SOME_IMG}\" \${EPS_OUTPUT_CONVERT_FLAGS} \"\${EPS_IMG}\" + COMMAND \"${ImageMagick_convert_EXECUTABLE}\" \${FLAGS} -quality 100 \${EPS_INPUT_CONVERT_FLAGS} \"\${SOME_IMG}\" \${EPS_OUTPUT_CONVERT_FLAGS} \"\${EPS_IMG}\" OUTPUT_FILE ${CMAKE_CURRENT_BINARY_DIR}/ConvertImagesToEPSOutput.txt ERROR_FILE ${CMAKE_CURRENT_BINARY_DIR}/ConvertImagesToEPSError.txt RESULT_VARIABLE _result diff --git a/SoftwareGuide/LaTeXWrapper.sh.in b/SoftwareGuide/LaTeXWrapper.sh.in index 56dd54c3..030cac4b 100755 --- a/SoftwareGuide/LaTeXWrapper.sh.in +++ b/SoftwareGuide/LaTeXWrapper.sh.in @@ -3,6 +3,9 @@ TEXINPUTS=$TEXINPUTS:${ITK_TEXINPUTS} export TEXINPUTS -# NOTE: Run 3 times just to get all dependencies resolved. -${LATEX_COMPILER} -shell-escape "$@" +# Prevent console and log outputs from latex from wrapping at 80 characters. +export max_print_line=10000 +export error_line=254 +export half_error_line=238 +${LATEX_COMPILER} -shell-escape "$@" \ No newline at end of file diff --git a/SoftwareGuide/Latex/00-Preamble-Common.tex b/SoftwareGuide/Latex/00-Preamble-Common.tex index f2a22cee..3c75412b 100644 --- a/SoftwareGuide/Latex/00-Preamble-Common.tex +++ b/SoftwareGuide/Latex/00-Preamble-Common.tex @@ -1,3 +1,4 @@ +\usepackage[T1]{fontenc} \usepackage[dvips]{graphicx} \usepackage{times} \usepackage[table]{xcolor} @@ -13,6 +14,9 @@ %\usepackage{siunitx} \usepackage[papersize={7.5in,9.25in},margin=1in]{geometry} \usepackage[utf8]{inputenc} +\usepackage{csquotes} + +\newcommand{\shelldblquotes}[1]{\textquotedbl{}#1\textquotedbl{}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % @@ -94,7 +98,7 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \ifitkPrintedVersion -\usepackage[dvips, +\usepackage[ pdfencoding=auto, psdextra, pdfpagemode={UseOutlines}, @@ -104,7 +108,7 @@ colorlinks,linkcolor={black},citecolor={black},urlcolor={black}, ]{hyperref} \else -\usepackage[dvips, +\usepackage[ pdfencoding=auto, psdextra, pdfpagemode={UseOutlines}, diff --git a/SoftwareGuide/Latex/01-PrintedPreamble-Book1.tex b/SoftwareGuide/Latex/01-PrintedPreamble-Book1.tex index c714c416..db908a0d 100644 --- a/SoftwareGuide/Latex/01-PrintedPreamble-Book1.tex +++ b/SoftwareGuide/Latex/01-PrintedPreamble-Book1.tex @@ -1,6 +1,6 @@ \begin{minipage}[t][1.0cm][b]{\textwidth} \begin{center} Printed and produced in the United States of America.\\ -\bf{ISBN 978-1-930934-35-1} +\textbf{ISBN 978-1-930934-35-1} \end{center} \end{minipage} diff --git a/SoftwareGuide/Latex/01-PrintedPreamble-Book2.tex b/SoftwareGuide/Latex/01-PrintedPreamble-Book2.tex index 74c6e31d..7567dca5 100644 --- a/SoftwareGuide/Latex/01-PrintedPreamble-Book2.tex +++ b/SoftwareGuide/Latex/01-PrintedPreamble-Book2.tex @@ -1,6 +1,6 @@ \begin{minipage}[t][1.0cm][b]{\textwidth} \begin{center} Printed and produced in the United States of America.\\ -\bf{ISBN 978-1-930934-36-8} +\textbf{ISBN 978-1-930934-36-8} \end{center} \end{minipage} diff --git a/SoftwareGuide/Latex/02-Cover-Book2.tex b/SoftwareGuide/Latex/02-Cover-Book2.tex index 7343dc87..d9a94ed7 100644 --- a/SoftwareGuide/Latex/02-Cover-Book2.tex +++ b/SoftwareGuide/Latex/02-Cover-Book2.tex @@ -4,7 +4,8 @@ \chapter*{About the Cover} The cover image consists of a photograph of ABS plastic anatomical objects -printed with a MakerBot Replicator 2X 3D printer. Mesh STL files were generated from the images with VTK. +printed with a \verb|MakerBot Replicator 2X 3D| printer. +Mesh STL files were generated from the images with VTK. \begin{description} diff --git a/SoftwareGuide/Latex/03-Abstract-Common.tex b/SoftwareGuide/Latex/03-Abstract-Common.tex index fd146a39..5684d686 100644 --- a/SoftwareGuide/Latex/03-Abstract-Common.tex +++ b/SoftwareGuide/Latex/03-Abstract-Common.tex @@ -2,12 +2,12 @@ \chapter*{Abstract} \noindent The National Library of Medicine Insight Segmentation and Registration Toolkit, shortened as the Insight Toolkit \href{https://itk.org}{(ITK)}, is an -open-source software toolkit for performing registration and -segmentation. \emph{Segmentation} is the process of identifying and +open-source software toolkit for performing registration and segmentation. +\emph{Segmentation} is the process of identifying and classifying data found in a digitally sampled representation. Typically the sampled representation is an image -acquired from such medical instrumentation as CT or MRI -scanners. \emph{Registration} is the task of aligning or developing +acquired from such medical instrumentation as CT or MRI scanners. +\emph{Registration} is the task of aligning or developing correspondences between data. For example, in the medical environment, a CT scan may be aligned with a MRI scan in order to combine the information contained in both. diff --git a/SoftwareGuide/Latex/04-Contributors.tex b/SoftwareGuide/Latex/04-Contributors.tex index 17b89dc8..0e818b33 100644 --- a/SoftwareGuide/Latex/04-Contributors.tex +++ b/SoftwareGuide/Latex/04-Contributors.tex @@ -16,65 +16,64 @@ \chapter*{Contributors} guide and their contributions. -{\bf Luis Ib\'{a}\~{n}ez} is principal author of this text. +\textbf{Luis Ib\'{a}\~{n}ez} is principal author of this text. He assisted in the design and layout of the text, implemented the bulk of the \LaTeX{} and CMake build process, and was responsible for the bulk of the content. He also developed most of the example code found in the \code{Insight/Examples} directory. -{\bf Will Schroeder} helped design and establish the organization +\textbf{Will Schroeder} helped design and establish the organization of this text and the \code{Insight/Examples} directory. He is principal content editor, and has authored several chapters. -{\bf Lydia Ng} authored the description for the registration framework +\textbf{Lydia Ng} authored the description for the registration framework and its components, the section on the multiresolution framework, and the section on deformable registration methods. She also edited the section on the resampling image filter and the sections on various level set segmentation algorithms. -{\bf Joshua Cates} authored the iterators chapter and the text and examples +\textbf{Joshua Cates} authored the iterators chapter and the text and examples describing watershed segmentation. He also co-authored the level-set segmentation material. -{\bf Jisung Kim} authored the chapter on the statistics framework. +\textbf{Jisung Kim} authored the chapter on the statistics framework. -{\bf Julien Jomier} contributed the chapter on spatial objects and examples on +\textbf{Julien Jomier} contributed the chapter on spatial objects and examples on model-based registration using spatial objects. -{\bf Karthik Krishnan} reconfigured the process for automatically generating +\textbf{Karthik Krishnan} reconfigured the process for automatically generating images from all the examples. Added a large number of new examples and updated the Filtering and Segmentation chapters for the second edition. -{\bf Stephen Aylward} contributed material describing spatial objects and +\textbf{Stephen Aylward} contributed material describing spatial objects and their application. -{\bf Tessa Sundaram} contributed the section on deformable registration using +\textbf{Tessa Sundaram} contributed the section on deformable registration using the finite element method. -{\bf Mark Foskey} contributed the examples on the +\textbf{Mark Foskey} contributed the examples on the \doxygen{AutomaticTopologyMeshSource} class. -{\bf Mathieu Malaterre} contributed the entire section on the description and +\textbf{Mathieu Malaterre} contributed the entire section on the description and use of DICOM readers and writers based on the GDCM library. He also contributed an example on the use of the VTKImageIO class. -{\bf Gavin Baker} contributed the section on how to write composite filters. +\textbf{Gavin Baker} contributed the section on how to write composite filters. Also known as minipipeline filters. Since the software guide is generated in part from the ITK source code itself, many ITK developers have been involved in updating and -extending the ITK documentation. These include {\bf David Doria}, -{\bf Bradley Lowekamp}, {\bf Mark Foskey}, {\bf Ga\"{e}tan Lehmann}, -{\bf Andreas Schuh}, {\bf Tom Vercauteren}, {\bf Cory Quammen}, {\bf Daniel Blezek}, -{\bf Paul Hughett}, {\bf Matthew McCormick}, {\bf Josh Cates}, {\bf Arnaud Gelas}, -{\bf Jim Miller}, {\bf Brad King}, {\bf Gabe Hart}, {\bf Hans Johnson}. - -{\bf Hans Johnson}, {\bf Kent Williams}, {\bf Constantine Zakkaroff}, {\bf -Xiaoxiao Liu}, {\bf Ali Ghayoor}, and {\bf Matthew McCormick} updated +extending the ITK documentation. These include \textbf{David Doria}, +\textbf{Bradley Lowekamp}, \textbf{Mark Foskey}, \textbf{Ga\"{e}tan Lehmann}, +\textbf{Andreas Schuh}, \textbf{Tom Vercauteren}, \textbf{Cory Quammen}, \textbf{Daniel Blezek}, +\textbf{Paul Hughett}, \textbf{Matthew McCormick}, \textbf{Josh Cates}, \textbf{Arnaud Gelas}, +\textbf{Jim Miller}, \textbf{Brad King}, \textbf{Gabe Hart}, \textbf{Hans Johnson}. + +\textbf{Hans Johnson}, \textbf{Kent Williams}, \textbf{Constantine Zakkaroff}, \textbf{Xiaoxiao Liu}, \textbf{Ali Ghayoor}, and \textbf{Matthew McCormick} updated the documentation for the initial ITK Version 4 release. -{\bf Luis Ib\'{a}\~{n}ez} and {\bf S\'{e}bastien Barr\'{e}} designed the -original Book 1 cover. {\bf Xiaoxiao Liu}, {\bf Bill Lorensen}, -{\bf Luis Ib\'{a}\~{n}ez}, and {\bf Matthew McCormick} created the 3D printed anatomical -objects that were photographed by {\bf S\'{e}bastien Barr\'{e}} for the Book 2 cover. -{\bf Steve Jordan} designed the layout of the covers. \ No newline at end of file +\textbf{Luis Ib\'{a}\~{n}ez} and \textbf{S\'{e}bastien Barr\'{e}} designed the +original Book 1 cover. \textbf{Xiaoxiao Liu}, \textbf{Bill Lorensen}, +\textbf{Luis Ib\'{a}\~{n}ez}, and \textbf{Matthew McCormick} created the 3D printed anatomical +objects that were photographed by \textbf{S\'{e}bastien Barr\'{e}} for the Book 2 cover. +\textbf{Steve Jordan} designed the layout of the covers. diff --git a/SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex b/SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex index 1f190e1a..6f2342dc 100644 --- a/SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex +++ b/SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex @@ -1,4 +1,4 @@ -\chapter{Coding Style Guide} +\chapter{Coding Style Guide}% \label{ch:CodingStyleGuide} This chapter describes the ITK Coding Style. Developers must follow these @@ -24,7 +24,7 @@ \chapter{Coding Style Guide} accepted until it is consistent with these guidelines. -\section{Purpose} +\section{Purpose}% \label{sec:Purpose} The following document is a description of the accepted coding style for the @@ -33,7 +33,7 @@ \section{Purpose} here. -\section{Overview} +\section{Overview}% \label{sec:Overview} This chapter is organized into the following sections: @@ -91,7 +91,7 @@ \section{Overview} guidelines. -\section{System Overview \& Philosophy} +\section{System Overview \& Philosophy}% \label{sec:SystemOverviewPhilosophy} The following implementation strategies have been adopted by the ITK community. @@ -120,7 +120,7 @@ \section{System Overview \& Philosophy} Note as well that ITK follows American English spelling and norms. -\subsection{Clang Style} +\subsection{Clang Style}% \label{subsec:clangStyle} ITK has adopted a \code{.clang-format} coding style configuration file so @@ -132,14 +132,14 @@ \subsection{Clang Style} to adhere to the style defined in the \code{.clang-format}. -\subsection{Kitware Style} +\subsection{Kitware Style}% \label{subsec:KWStyle} Kitware Style (\href{https://kitware.github.io/KWStyle/} KWStyle) pre-commit hooks enforce a number of policies on any given patch set submitted to ITK. -\subsection{Implementation Language} +\subsection{Implementation Language}% \label{subsec:ImplementationLanguage} The core implementation language is C++. C++ was chosen for its flexibility, @@ -160,7 +160,7 @@ \subsection{Implementation Language} Tcl, and Ruby. -\subsection{Constants} +\subsection{Constants}% \label{subsec:Constants} ITK does not define constants with \code{\#define} in header files, hence do not @@ -202,7 +202,7 @@ \subsection{Constants} \normalsize -\subsection{Generic Programming and the STL} +\subsection{Generic Programming and the STL}% \label{subsec:GenericProgrammingAndSTL} Compile-time binding using methods of generic programming and template @@ -221,7 +221,7 @@ \subsection{Generic Programming and the STL} member something of a boundary between ITK and STL. -\subsection{Portability} +\subsection{Portability}% \label{subsec:Portability} ITK is designed to build and is systematically tested on a set of target @@ -250,7 +250,7 @@ \subsection{Portability} before a version of their compiler is released to the market. -\subsection{Multi-Layer Architecture} +\subsection{Multi-Layer Architecture}% \label{subsec:MultiLayerArchitecture} ITK is designed with a multi-layer architecture in mind. That is, three layers: @@ -263,7 +263,7 @@ \subsection{Multi-Layer Architecture} layer is not directly addressed by ITK other than providing simple examples of applications. -\subsection{CMake Build Environment} +\subsection{CMake Build Environment}% \label{subsec:CMakeBuildEnvironment} The ITK build environment is CMake. CMake is an open-source, advanced @@ -273,14 +273,14 @@ \subsection{CMake Build Environment} CMake web pages at \href{https://www.cmake.org}{https://www.cmake.org} for more information. -See Section~\ref{sec:UsingCMakeForConfiguringAndBuildingITK} on page -\pageref{sec:UsingCMakeForConfiguringAndBuildingITK} for specifics about the use +See Section~\ref{sec:UsingCMakeForConfiguringAndBuildingITK} +on page~\pageref{sec:UsingCMakeForConfiguringAndBuildingITK} for specifics about the use of CMake in ITK. Section~\ref{sec:CMakeStyle} on page~\pageref{sec:CMakeStyle} provides a reference to the recommended style of makefiles in ITK. -\subsection{Doxygen Documentation System} +\subsection{Doxygen Documentation System}% \label{subsec:DoxygenDocumentationSystem} The Doxygen open-source system is used to generate on-line documentation. @@ -294,7 +294,7 @@ \subsection{Doxygen Documentation System} For more information about Doxygen, please visit \href{https://www.doxygen.nl/index.html}{https://www.doxygen.nl/index.html}. -\subsection{vnl Math Library} +\subsection{vnl Math Library}% \label{subsec:vnlMathLibrary} ITK has adopted the vnl -- visual numerics library. Vnl is a portion of the vxl image @@ -302,7 +302,7 @@ \subsection{vnl Math Library} for more information about vxl and vnl. -\subsection{Reference Counting} +\subsection{Reference Counting}% \label{subsec:ReferenceCounting} ITK has adopted reference counting via so-called \doxygen{SmartPointer} to @@ -329,7 +329,7 @@ \subsection{Reference Counting} further details. -\section{Copyright} +\section{Copyright}% \label{sec:Copyright} ITK has adopted a standard copyright. This copyright should be placed at the @@ -358,11 +358,11 @@ \section{Copyright} \end{minted} \normalsize -See Chapter \ref{sec:InsightToolkitLicense} for further details on the ITK +See Chapter~\ref{sec:InsightToolkitLicense} for further details on the ITK license. -\section{Citations} +\section{Citations}% \label{sec:Citations} Give credit to others' work. If when writing some piece of code (whether it is a @@ -453,7 +453,7 @@ \section{Citations} \normalsize -\section{Naming Conventions} +\section{Naming Conventions}% \label{sec:NamingConventions} In general, names are constructed by using case change to indicate separate @@ -470,7 +470,7 @@ \section{Naming Conventions} \code{Dimension}, \code{point}, \code{size}, or \code{vector}, instead of \code{D}, \code{pt}, \code{sz}, or \code{vec}, respectively). Abbreviations are allowable when in common use, and should be in uppercase as in \code{RGB}, -or \code{ID} for ``identifier''.) +or \code{ID} for ``identifier''. \end{itemize} @@ -485,7 +485,7 @@ \section{Naming Conventions} variations on this theme result as explained in the following subsections. -\subsection{ITK} +\subsection{ITK}% \label{subsec:ITK} The acronym for the NLM Insight Segmentation and Registration Toolkit must @@ -493,7 +493,7 @@ \subsection{ITK} class documentation. -\subsection{Naming Namespaces} +\subsection{Naming Namespaces}% \label{subsec:NamingNamespaces} Namespaces must be written in lowercase, e.g. @@ -510,7 +510,7 @@ \subsection{Naming Namespaces} \normalsize -\subsection{Naming Classes} +\subsection{Naming Classes}% \label{subsec:NamingClasses} Classes are: @@ -604,7 +604,7 @@ \subsection{Naming Classes} \end{itemize} -\subsection{Naming Files} +\subsection{Naming Files}% \label{subsec:NamingFiles} Files should have the same name as the class, with an ``itk'' prepended. @@ -627,11 +627,11 @@ \subsection{Naming Files} \end{itemize} -\subsubsection{Naming Tests} +\subsubsection{Naming Tests}% \label{subsubsec:NamingTests} Following the \code{TestDriver} philosophy, see Section~\ref{sec:Tests} on -page \pageref{sec:Tests}, test files must be named with the same name used to +page~\pageref{sec:Tests}, test files must be named with the same name used to name the \code{main} method contained in the test file (\code{.cxx}). This name should generally be indicative of the class tested, e.g. \small @@ -646,8 +646,8 @@ \subsubsection{Naming Tests} Note that all test files should start with the lowercase \code{itk} prefix. Hence, the main method name in a test is the sole exception to the method naming -convention of starting all method names with capitals (see -\ref{subsec:NamingMethodsAndFunctions}). +convention of starting all method names with capitals +(see~\ref{subsec:NamingMethodsAndFunctions}). A test's input argument number should always be named \code{argc}, and the input arguments \code{argv} for the sake of consistency. @@ -723,11 +723,11 @@ \subsubsection{Naming Tests} about the ITK testing framework. -\subsection{Examples} +\subsection{Examples}% \label{subsec:Examples} -\subsection{Naming Methods and Functions} +\subsection{Naming Methods and Functions}% \label{subsec:NamingMethodsAndFunctions} Global functions and class methods, either static or class members, are named @@ -750,7 +750,7 @@ \subsection{Naming Methods and Functions} The definition of the methods should follow this same order. -\subsection{Naming Class Data Members} +\subsection{Naming Class Data Members}% \label{NamingClassDataMembers} Class data members are prepended with \code{m\_} as in \code{m\_Size}. This @@ -769,7 +769,7 @@ \subsection{Naming Class Data Members} lines for the sake of readability. -\subsection{Naming Enumerations} +\subsection{Naming Enumerations}% \label{subsec:NamingEnums} ITK uses strongly-typed enumerations through the \code{enum class} keyword. @@ -884,7 +884,7 @@ \subsection{Naming Enumerations} \normalsize -\subsection{Naming Local Variables} +\subsection{Naming Local Variables}% \label{subsec:NamingLocalVariables} Local variables begin in lowercase. There is more flexibility in the naming of @@ -896,7 +896,7 @@ \subsection{Naming Local Variables} names and comments will go a long way towards helping other community members. -\subsubsection{Temporary Variable Naming} +\subsubsection{Temporary Variable Naming}% \label{subsubsec:TemporaryVariableNaming} Every effort should be made to properly name temporary variables of any type @@ -946,7 +946,7 @@ \subsubsection{Temporary Variable Naming} \normalsize -\subsubsection{Variable Initialization} +\subsubsection{Variable Initialization}% \label{subsubsec:VariableInitialization} A basic type variable declared and not being assigned immediately within a @@ -1023,7 +1023,7 @@ \subsubsection{Variable Initialization} \normalsize -\subsubsection{Control Statement Variable Naming} +\subsubsection{Control Statement Variable Naming}% \label{subsubsec:ControlStatementVariableNaming} Control statement variables names should be clear and concise. For simple @@ -1038,7 +1038,7 @@ \subsubsection{Control Statement Variable Naming} output structures are involved. Otherwise, \code{it} can be used. -\subsubsection{Variable Scope} +\subsubsection{Variable Scope}% \label{subsubsec:VariableScope} Control statement variables should have a local scope. Hence, instead of @@ -1077,7 +1077,7 @@ \subsubsection{Variable Scope} \normalsize -\subsection{Naming Template Parameters} +\subsection{Naming Template Parameters}% \label{subsec:NamingTemplateParameters} Template parameters follow the usual rules with naming except that they should @@ -1103,7 +1103,7 @@ \subsection{Naming Template Parameters} consistently use \code{typename} instead of \code{class}. -\subsection{Naming Typedefs} +\subsection{Naming Typedefs}% \label{subsec:NamingTypedefs} Type aliases are absolutely essential in generic programming. They significantly @@ -1167,7 +1167,7 @@ \subsection{Naming Typedefs} \end{itemize} -\subsection{Naming Constants} +\subsection{Naming Constants}% \label{subsec:NamingConstants} Constants must start with capital letters, e.g. @@ -1179,7 +1179,7 @@ \subsection{Naming Constants} \normalsize -\subsection{Using Operators to Pointers} +\subsection{Using Operators to Pointers}% \label{subsec:UsingOperatorsToPointers} The indirection unary operator (\code{*}) must be placed next to the variable, e.g. @@ -1218,7 +1218,7 @@ \subsection{Using Operators to Pointers} \normalsize -\subsection{Using Operators to Arrays} +\subsection{Using Operators to Arrays}% \label{subsec:UsingOperatorsToArrays} The subscript operator (\code{[]}) must be placed next to the variable, e.g. @@ -1243,7 +1243,7 @@ \subsection{Using Operators to Arrays} \normalsize -\subsection{Using Underscores} +\subsection{Using Underscores}% \label{subsec:UsingUnderscores} Do not use undersocres. The only exception is when defining preprocessor @@ -1251,7 +1251,7 @@ \subsection{Using Underscores} allowed to separate words. -\subsection{Include Guards} +\subsection{Include Guards}% \label{subsec:Include Guards} An include guard's case must mimic the one used for a file, with the file @@ -1284,7 +1284,7 @@ \subsection{Include Guards} Note that include guards in implementation files are to be used only for templated classes. -\subsection{Preprocessor Directives} +\subsection{Preprocessor Directives}% \label{subsec:PreprocessorDirectives} Some of the worst code contains many preprocessor directives and macros such as @@ -1309,7 +1309,7 @@ \subsection{Preprocessor Directives} regardless of the required indentation level of the code they contain. -\subsection{Header Includes} +\subsection{Header Includes}% \label{subsec:HeaderIncludes} Headers in ITK must be included using quotes (`` '') @@ -1328,7 +1328,7 @@ \subsection{Header Includes} are only used to prevent circular dependencies. -\subsection{Const Correctness} +\subsection{Const Correctness}% \label{subsec:ConstCorrectness} As a general rule, the \code{const} type qualifier must be used for: @@ -1376,7 +1376,7 @@ \subsection{Const Correctness} \end{itemize} -\subsection{Integer Type Specifiers} +\subsection{Integer Type Specifiers}% \label{subsec:IntegerTypeSpecifiers} Throughout the code base, the built-in type \code{unsigned int} is spelled exactly like that: @@ -1391,7 +1391,7 @@ \subsection{Integer Type Specifiers} ``itkIntTypes.h'' may need to be \code{\#include}d, to ensure that those types are declared within the \code{itk} namespace. -\section{Namespaces} +\section{Namespaces}% \label{sec:Namespaces} All classes should be placed in the \code{itk::} namespace. Additional @@ -1420,7 +1420,7 @@ \section{Namespaces} When declaring or defining members of the \code{itk::} namespace, for example, the \code{itk::} namespace prefix should not be added. That is, code within -\code{namespace itk \{ ... \}}" should not use \code{itk::}. +\code{namespace itk \{ \ldots \}} should not use \code{itk::}. The \code{::} global namespace should be used when referring to a global function, e.g. @@ -1440,7 +1440,7 @@ \section{Namespaces} Note that \code{itk::} should only be used outside the \code{itk::} namespace. -\section{Aliasing Template Parameter Typenames} +\section{Aliasing Template Parameter Typenames}% \label{sec:AliasingTemplateParameterTypenames} The public class typename's should be limited to the types that are required to @@ -1495,7 +1495,7 @@ \section{Aliasing Template Parameter Typenames} \normalsize -\section{Pipelines} +\section{Pipelines}% \label{sec:Pipelines} The following is a set of useful tips that must be taken into account when @@ -1549,7 +1549,7 @@ \section{Pipelines} \end{itemize} -\section{The auto Keyword} +\section{The auto Keyword}% \label{sec:TheAutoKeyword} Available since C++11, the \code{auto} keyword specifies that a variable's type @@ -1577,10 +1577,10 @@ \section{The auto Keyword} may use \code{auto} more liberally. -\section{Initialization and Assignment} +\section{Initialization and Assignment}% \label{sec:IniitalizationAndAssignment} -\subsection{Initialization of member variables} +\subsection{Initialization of member variables}% \label{subsec:InitializationOfMemberVariables} All member variables must be initialized when they are declared. For such @@ -1657,7 +1657,7 @@ \subsection{Initialization of member variables} example \code{FixedArray::m\_InternalArray} and \code{Index::m\_InternalArray} do not have a default member initializer. -\subsection{Initializing variables of fixed size array types} +\subsection{Initializing variables of fixed size array types}% \label{subsec:InitializingVariablesOfFixedSizeArrayTypes} ITK has various fixed size array types, including template instantiations of @@ -1705,7 +1705,7 @@ \subsection{Initializing variables of fixed size array types} \end{minted} \normalsize -\section{Accessing Members} +\section{Accessing Members}% \label{sec:Accessing Members} The C++ keyword \code{this} must be used when calling a class' own methods: @@ -1771,7 +1771,7 @@ \section{Accessing Members} \normalsize -\section{Code Layout and Indentation} +\section{Code Layout and Indentation}% \label{sec:CodeLayoutAndIndentation} The following are the accepted ITK code layout rules and indentation style. @@ -1779,7 +1779,7 @@ \section{Code Layout and Indentation} in ITK. This will help crystallize the rules described here. -\subsection{General Layout} +\subsection{General Layout}% \label{subsec:GeneralLayout} \begin{itemize} @@ -1824,13 +1824,13 @@ \subsection{General Layout} section. -\subsection{Class Layout} +\subsection{Class Layout}% \label{subsec:ClassLayout} Classes are declared (\code{.h}) using the following guidelines: \begin{itemize} \item Begin with the Copyright notice. -\item Follow with include guards (e.g \code{\#ifndef itkBoxImageFilter\_h})). +\item Follow with include guards (e.g \code{\#ifndef itkBoxImageFilter\_h}). \item Follow with the necessary includes. Include only what is necessary to avoid dependency problems. \item Place the class in the correct namespace. @@ -1918,7 +1918,7 @@ \subsection{Class Layout} \begin{itemize} \item Begin with the Copyright notice. \item Follow with include guards in case of templated classes (e.g -\code{\#ifndef itkBoxImageFilter\_hxx})). +\code{\#ifndef itkBoxImageFilter\_hxx}). \item Follow with the necessary includes. Include only what is necessary to avoid dependency problems. \item Place the class in the correct namespace. @@ -2001,7 +2001,7 @@ \subsection{Class Layout} follow. -\subsection{Method Definition} +\subsection{Method Definition}% \label{subsec:MethodDefinition} Methods are defined across multiple lines. This is to accommodate the extremely @@ -2045,11 +2045,11 @@ \subsection{Method Definition} may be split into a separate line. -\subsection{Use of Braces} +\subsection{Use of Braces}% \label{subsec:UseOfBraces} -\subsubsection{Braces in Control Sequences} +\subsubsection{Braces in Control Sequences}% \label{subsubsec:BracesInControlSequences} Braces must be used to delimit the scope of an \code{if}, \code{for}, @@ -2120,7 +2120,7 @@ \subsubsection{Braces in Control Sequences} \end{minted} \normalsize -\subsubsection{Braces in Arrays} +\subsubsection{Braces in Arrays}% \label{subsubsec:BracesInArrays} When initializing an array, no space shall be left between the first value and @@ -2137,7 +2137,7 @@ \subsubsection{Braces in Arrays} \normalsize -\subsection{Indentation and Tabs} +\subsection{Indentation and Tabs}% \label{subsec:IndentationAndTabs} The ITK style bans the use of tabs. Contributors should configure their editors @@ -2202,7 +2202,7 @@ \subsection{Indentation and Tabs} \normalsize -\subsection{White Spaces} +\subsection{White Spaces}% \label{subsec:WhiteSpaces} As a general rule, a single white space should be used to separate every word. @@ -2302,7 +2302,7 @@ \subsection{White Spaces} Trailing white spaces are not allowed in ITK. -\subsection{Grouping} +\subsection{Grouping}% \label{subsec:Grouping} Unnecessary parentheses for grouping hinder reading the code. @@ -2314,7 +2314,7 @@ \subsection{Grouping} where mathematical, logical or bitwise operations are performed. -\subsubsection{Conditional Expressions} +\subsubsection{Conditional Expressions}% \label{subsubsec:ConditionalExpressions} In conditional expressions contained in control statements (e.g. \code{if}, @@ -2353,7 +2353,7 @@ \subsubsection{Conditional Expressions} \normalsize -\subsubsection{Assignments} +\subsubsection{Assignments}% \label{subsubsec:Assignments} In assignments, the operator precedence and associativity rules apply to help @@ -2380,7 +2380,7 @@ \subsubsection{Assignments} \normalsize -\subsubsection{Return Statements} +\subsubsection{Return Statements}% \label{subsubsec:ReturnStatements} In \code{return} statements, using parentheses should be avoided when they @@ -2456,7 +2456,7 @@ \subsubsection{Return Statements} \normalsize -\subsection{Alignment} +\subsection{Alignment}% \label{subsec:Alignment} In every ITK file, the following code parts always start in column one: @@ -2669,7 +2669,7 @@ \subsection{Alignment} \normalsize -\subsection{Line Splitting Policy} +\subsection{Line Splitting Policy}% \label{subsec:LineSplittingPolicy} Lines exceeding the recommended line length in ITK must be split in the @@ -2720,7 +2720,7 @@ \subsection{Line Splitting Policy} \end{itemize} -\subsection{Empty Lines} +\subsection{Empty Lines}% \label{subsec:EmptyLines} As a general rule, empty lines should be used to separate code blocks that @@ -3023,7 +3023,7 @@ \subsection{Empty Lines} \code{.hxx}). -\subsection{New Line Character} +\subsection{New Line Character}% \label{subsec:NewLineCharacter} Use \code{std::endl} to introduce a new line instead of \code{{\textbackslash}n} in string @@ -3055,7 +3055,7 @@ \subsection{New Line Character} \normalsize -\subsection{End Of File Character} +\subsection{End Of File Character}% \label{subsec:EndOfFileCharacter} The file must be terminated by a (preferably single) blank line. @@ -3063,7 +3063,7 @@ \subsection{End Of File Character} ~\ref{subsec:KWStyle} on page~\pageref{subsec:KWStyle}). -\section{Increment/decrement Operators} +\section{Increment/decrement Operators}% \label{sec:IncrementDecrementOperators} Systematically use the pre-increment(decrement) syntax, instead of the @@ -3093,7 +3093,7 @@ \section{Increment/decrement Operators} \normalsize -\section{Trailing Return Types} +\section{Trailing Return Types}% \label{sec:TrailingReturnTypes} Whenever choosing between a trailing return type (as introduced with C++11) and @@ -3134,7 +3134,7 @@ \section{Trailing Return Types} \normalsize -\section{Empty Arguments in Methods} +\section{Empty Arguments in Methods}% \label{sec:EmptyArgumentInMethods} The use of the \code{void} keyword is discouraged for methods not requiring @@ -3158,7 +3158,7 @@ \section{Empty Arguments in Methods} \normalsize -\section{Ternary Operator} +\section{Ternary Operator}% \label{sec:TernaryOperator} The use of the ternary operator @@ -3258,7 +3258,7 @@ \section{Ternary Operator} And hence, the ternary operator is accepted in such cases. -\section{Using Standard Macros} +\section{Using Standard Macros}% \label{sec:UsingStandardMacros} There are several macros defined in the file \code{itkMacro.h}. These macros @@ -3371,7 +3371,7 @@ \section{Using Standard Macros} \normalsize -\section{Exception Handling} +\section{Exception Handling}% \label{sec:ExceptionHandling} ITK exceptions are defined in \code{itkExceptionObject.h}. Derived exception @@ -3487,7 +3487,7 @@ \section{Exception Handling} details about error handling in ITK. -\subsection{Errors in Pipelines} +\subsection{Errors in Pipelines}% \label{subsec:ErrorsInPipelines} When in a function an element must have a given value, a check must ensure that @@ -3546,11 +3546,11 @@ \subsection{Errors in Pipelines} it would be helpful to also add an error message. -\section{Messages} +\section{Messages}% \label{sec:Messages} -\subsection{Messages in Macros} +\subsection{Messages in Macros}% \label{sec:MessagesInMacros} Messages written for debugging purposes which are deemed to be appropriate to @@ -3574,7 +3574,7 @@ \subsection{Messages in Macros} \normalsize -\subsection{Messages in Tests} +\subsection{Messages in Tests}% \label{subsec:MessagesInTests} ITK tests are run automatically, and hence, results are not read by humans. @@ -3684,11 +3684,11 @@ \subsection{Messages in Tests} \normalsize -\section{Concept Checking} +\section{Concept Checking}% \label{sec:ConceptChecking} -\section{Printing Variables} +\section{Printing Variables}% \label{sec:PrintingVariables} All member variables, regardless of whether they are publicly exposed or not, @@ -3755,7 +3755,7 @@ \section{Printing Variables} \normalsize -\section{Checking for Null} +\section{Checking for Null}% \label{sec:CheckingForNull} ITK's \doxygen{SmartPointer} constructs can be checked against the \code{null} @@ -3777,14 +3777,14 @@ \section{Checking for Null} The latter, being more explicit, is preferred over the former. -\section{Writing Tests} +\section{Writing Tests}% \label{sec:WritingTests} The following section provides additional rules that apply to writing tests in ITK. -\subsection{Code Layout in Tests} +\subsection{Code Layout in Tests}% \label{subsec:CodeLayoutInTests} The following general layout is recommended for ITK unit tests: @@ -3806,7 +3806,7 @@ \subsection{Code Layout in Tests} them, they should be put after the input argument number check section. -\subsection{Regressions in Tests} +\subsection{Regressions in Tests}% \label{subsec:RegressionsInTests} Tests should run as long as possible to report as much failures as possible before returning @@ -3898,11 +3898,11 @@ \subsection{Regressions in Tests} When the magnitude of the error needs to be reported, as in the above examples, the error message should be split into different lines, all starting with the -error output redirection \code{std::cerr << "";}. Care must be taken to +error output redirection \code{std::cerr << \shelldblquotes{};}. Care must be taken to appropriately add white space for a correct formatting of the message. -\subsection{Arguments in Tests} +\subsection{Arguments in Tests}% \label{subsec:ArgumentsInTests} Tests generally require input arguments, whether the filename of an input image, @@ -3966,7 +3966,7 @@ \subsection{Arguments in Tests} \normalsize -\subsection{Testing Enumeration Streaming} +\subsection{Testing Enumeration Streaming}% \label{subsec:TestEnumStreaming} The enumeration class streaming operator overload needs to be tested, e.g. @@ -3989,7 +3989,7 @@ \subsection{Testing Enumeration Streaming} \normalsize -\subsection{Test Return Value} +\subsection{Test Return Value}% \label{subsec:TestReturnValue} Tests must always return a value of type \code{int}, @@ -4025,7 +4025,7 @@ \subsection{Test Return Value} allowed in ITK. -\section{Writing Examples} +\section{Writing Examples}% \label{sec:WritingExamples} Many ITK examples are used in this software guide to demonstrate ITK's @@ -4081,7 +4081,7 @@ \section{Writing Examples} the sake of readability. -\section{Doxygen Documentation System} +\section{Doxygen Documentation System}% \label{sec:DoxygenDocumentationSystem} Doxygen is an open-source, powerful system for automatically generating @@ -4095,7 +4095,7 @@ \section{Doxygen Documentation System} {https://www.stack.nl/~dimitri/doxygen/} -\subsection{General Principles} +\subsection{General Principles}% \label{subsec:GeneralPrinciples} ITK uses a subset of C-style Doxygen markdown. No other markdown style (e.g. Qt, @@ -4131,7 +4131,7 @@ \subsection{General Principles} when documenting. Finish the sentences with a period (.). -\subsection{Documenting Classes} +\subsection{Documenting Classes}% \label{subsec:DocumentingClasses} Classes must be documented using the \code{{\textbackslash}class}, @@ -4173,7 +4173,7 @@ \subsection{Documenting Classes} Every class must be documented. -\subsection{Documenting Methods} +\subsection{Documenting Methods}% \label{subsec:DocumentingMethods} The method Doxygen documentation must be placed in the header file (\code{.h}). @@ -4232,7 +4232,7 @@ \subsection{Documenting Methods} Every method must be documented. -\subsection{Documenting Data Members} +\subsection{Documenting Data Members}% \label{subsec:DocumentingDataMembers} Class member variables should be documented through their corresponding @@ -4290,7 +4290,7 @@ \subsection{Documenting Data Members} \normalsize -\subsection{Documenting Macros} +\subsection{Documenting Macros}% \label{subsec:DocumentingMacros} The documentation block in a macro should start in column one, and should be @@ -4326,7 +4326,7 @@ \subsection{Documenting Macros} \normalsize -\subsection{Documenting Tests} +\subsection{Documenting Tests}% \label{subsec:DocumentingTests} Generally, an ITK test does not need to have a documentation block stating its @@ -4355,14 +4355,14 @@ \subsection{Documenting Tests} style where appropriate. -\section{CMake Style} +\section{CMake Style}% \label{sec:CMakeStyle} For writing CMake scripts, the community member is referred to the standard CMake style. -\section{Documentation Style} +\section{Documentation Style}% \label{sec:DocumentationStyle} The Insight Software Consortium has adopted the following guidelines for diff --git a/SoftwareGuide/Latex/Appendices/GitWorkflow.tex b/SoftwareGuide/Latex/Appendices/GitWorkflow.tex index 7d4ba891..fe709263 100644 --- a/SoftwareGuide/Latex/Appendices/GitWorkflow.tex +++ b/SoftwareGuide/Latex/Appendices/GitWorkflow.tex @@ -1,4 +1,4 @@ -\chapter{ITK Git Workflow} +\chapter{ITK Git Workflow}% \label{ch:ITKGitWorkflow} This chapter describes the workflow adopted by the ITK community to develop @@ -6,14 +6,14 @@ \chapter{ITK Git Workflow} and flexible model to develop modern software. -\section{Git Setup} +\section{Git Setup}% \label{sec:Git Setup} Visit the main \href{https://www.git-scm.com/download}{Git download site}, and depending on your operating system, follow the guidelines. -\subsection{Windows} +\subsection{Windows}% \label{subsec:Windows} Git comes in two flavors on Windows: @@ -28,7 +28,7 @@ \subsection{Windows} work tree is not unless \code{core.filemode} is false). -\subsubsection{Git for Windows} +\subsubsection{Git for Windows}% \label{subsubsec:GitForWindows} Download the ``git for windows'' executable from the @@ -46,7 +46,7 @@ \subsubsection{Git for Windows} get a command line shell with Git. -\subsubsection{Cygwin} +\subsubsection{Cygwin}% \label{subsubsec:Cygwin} Install the following packages: @@ -59,10 +59,10 @@ \subsubsection{Cygwin} Launch a Cygwin command prompt to get a command line shell with Git. -\subsection{macOS} +\subsection{macOS}% \label{subsec:macOS} -\subsubsection{Xcode 4} +\subsubsection{Xcode 4}% \label{subsubsec:Xcode4} If you have Xcode 4 installed, you already have git installed. @@ -79,14 +79,14 @@ \subsubsection{Xcode 4} \end{minted} -\subsubsection{OS X Installer} +\subsubsection{OS X Installer}% \label{subsubsec:OSXInstaller} Download an installer from \href{https://code.google.com/archive/p/git-osx-installer/}{code.google.com}. -\subsubsection{MacPorts} +\subsubsection{MacPorts}% \label{subsubsec:MacPorts} Enter these commands: @@ -97,7 +97,7 @@ \subsubsection{MacPorts} \end{minted} -\subsection{Linux} +\subsection{Linux}% \label{subsec:Linux} Popular Linux distributions already come with packages for Git. Typically the packages are called: @@ -108,10 +108,10 @@ \subsection{Linux} \end{itemize} -\section{Workflow} +\section{Workflow}% \label{sec:Workflow} -\subsection{A Primer} +\subsection{A Primer}% \label{subsec:APrimer} This primer details a possible workflow for using Git and ITK. There are many @@ -165,14 +165,14 @@ \subsection{A Primer} \end{quote} -\subsection{A Topic} +\subsection{A Topic}% \label{subsec:ATopic} This workflow is based on the branchy development workflow documented by \href{https://git-scm.com/docs/gitworkflows}{Git help workflows}. -\subsubsection{Motivation} +\subsubsection{Motivation}% \label{subsubsec:Motivation} The primary goal of this workflow is to make release preparation and maintenance @@ -190,7 +190,7 @@ \subsubsection{Motivation} \end{itemize} -\subsubsection{Design} +\subsubsection{Design}% \label{subsubsec:Design} The design of this workflow is based on the observation that meeting the @@ -217,7 +217,7 @@ \subsubsection{Design} \end{itemize} -\subsubsection{Notation} +\subsubsection{Notation}% \label{subsubsec:Notation} This chapter uses Git Directed Acyclic Graphs (DAG) to depict commit history: @@ -225,36 +225,35 @@ \subsubsection{Notation} \begin{table} \begin{center} -\begin{tabular}{ m{0.3\textwidth} | m{0.6\textwidth} } +\begin{tabular}{ m{0.3\textwidth} m{0.6\textwidth} } \toprule \textbf{Meaning} & \textbf{Symbol} \\ \midrule Branch name & \begin{tikzpicture} \node[DAGref,fill=pink](master){master}; -\end{tikzpicture} \\ +\end{tikzpicture}\\ Current branch & \begin{tikzpicture} \node[DAGref,fill=pink](master){*master}; -\end{tikzpicture} \\ +\end{tikzpicture}\\ Commit with parent in same branch & \begin{tikzpicture} \gitDAG[grow right sep = 2em, branch down = 3em]{ {[nodes=placeholder commits] "..."} -- C1 }; -\end{tikzpicture} \\ +\end{tikzpicture}\\ Commit with two parents (merge) & \begin{tikzpicture} \gitDAG[grow right sep = 1em, branch down = 3em]{ {[nodes=placeholder commits] "..."} -- C1, C2; {C2 -- C1} }; -\end{tikzpicture} \\ +\end{tikzpicture}\\ %\bottomrule \end{tabular} \end{center} -\caption[Git DAG notation]{Git graphs notation. -\label{tab:GitDAGNotation}} +\caption[Git DAG notation]{Git graphs notation\label{tab:GitDAGNotation}}. \end{table} Topic branches generally consist of a linear sequence of commits forked off an @@ -278,7 +277,7 @@ \subsubsection{Notation} {right=of C5} % node placement {C5} % target \end{tikzpicture} -\itkcaption{Topic branch.} +\itkcaption{Topic branch.}% \label{fig:TopicBranch} \end{figure} @@ -297,12 +296,12 @@ \subsubsection{Notation} {right=of C5} % node placement {C5} % target \end{tikzpicture} -\itkcaption{Merge commits into the \code{master} branch.} +\itkcaption{Merge commits into the \code{master} branch.}% \label{fig:MergeCommitsInIntegrationBranch} \end{figure} -\subsubsection{Published Branches} +\subsubsection{Published Branches}% \label{subsubsec:PublishedBranches} We publish an \textit{integration} branch for each stage of development: @@ -317,12 +316,12 @@ \subsubsection{Published Branches} developer's local repositories. -\subsubsection{Development} +\subsubsection{Development}% \label{subsubsec:Development} We cover below the steps to take during each phase of development. -\paragraph{Initial Setup} +\paragraph{Initial Setup}% \label{par:InitialSetup} These instructions generally provide all arguments to \code{git push} commands. @@ -338,7 +337,7 @@ \subsubsection{Development} details. -\paragraph{New Topic} +\paragraph{New Topic}% \label{par:NewTopic} Create a new topic branch for each separate feature or bug fix. Always start the @@ -364,7 +363,7 @@ \subsubsection{Development} {right=of C1} % node placement {C1} % target \end{tikzpicture} -\itkcaption{Locate at \code{master}.} +\itkcaption{Locate at \code{master}.}% \label{fig:CheckoutBranch} \end{figure} @@ -383,7 +382,7 @@ \subsubsection{Development} {right=of C2} % node placement {C2} % target \end{tikzpicture} -\itkcaption{Bring most recent changes to \code{master}.} +\itkcaption{Bring most recent changes to \code{master}.}% \label{fig:PullChanges1} \end{figure} @@ -409,14 +408,14 @@ \subsubsection{Development} {below=of C2} % node placement {C2} % target \end{tikzpicture} -\itkcaption{Create a local \code{topic} branch.} +\itkcaption{Create a local \code{topic} branch.}% \label{fig:CreateLocalBranch} \end{figure} This is where the real work happens. Edit, stage, and commit files repeatedly as needed for your work. -During this step, avoid the \ref{par:UrgeToMerge} from an integration branch. +During this step, avoid the~\ref{par:UrgeToMerge} from an integration branch. Keep your commits focused on the topic at hand. \begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{bash} @@ -443,7 +442,7 @@ \subsubsection{Development} {right=of C3} % node placement {C3} % target \end{tikzpicture} -\itkcaption{Commit changes.} +\itkcaption{Commit changes.}% \label{fig:CommitChanges} \end{figure} @@ -471,7 +470,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Commit last changes.} +\itkcaption{Commit last changes.}% \label{fig:CommitLastChanges} \end{figure} @@ -503,7 +502,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Checkout \textit{master} and pull changes.} +\itkcaption{Checkout \textit{master} and pull changes.}% \label{fig:SwitchToMasterAndPull} \end{figure} @@ -532,7 +531,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Merge \code{topic} branch into \code{master}.} +\itkcaption{Merge \code{topic} branch into \code{master}.}% \label{fig:MergeTopicIntoMaster1} \end{figure} @@ -569,7 +568,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Publish the change.} +\itkcaption{Publish the change.}% \label{fig:PushChanges1} \end{figure} @@ -579,7 +578,7 @@ \subsubsection{Development} resolve any conflict that may arise when publishing the change. -\paragraph{Mature Topic} +\paragraph{Mature Topic}% \label{par:MatureTopic} When a topic is ready for inclusion in the next release, we merge it into @@ -610,7 +609,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Checkout \textit{master}.} +\itkcaption{Checkout \textit{master}.}% \label{fig:SwitchToMaster1} \end{figure} @@ -636,7 +635,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Pull latest changes into \textit{master}.} +\itkcaption{Pull latest changes into \textit{master}.}% \label{fig:PullChanges2} \end{figure} @@ -664,7 +663,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Merge the \code{topic} branch into master.} +\itkcaption{Merge the \code{topic} branch into master.}% \label{fig:MergeTopicIntoMaster2} \end{figure} @@ -692,7 +691,7 @@ \subsubsection{Development} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Delete the local \code{topic} branch.} +\itkcaption{Delete the local \code{topic} branch.}% \label{fig:DeleteLocalBranch1} \end{figure} @@ -720,7 +719,7 @@ \subsubsection{Development} {below=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Publish the change.} +\itkcaption{Publish the change.}% \label{fig:PushChanges2} \end{figure} @@ -730,7 +729,7 @@ \subsubsection{Development} resolve any conflict that may arise when publishing the change. -\paragraph{Old Topic} +\paragraph{Old Topic}% \label{par:OldTopic} Sometimes we need to continue work on an old topic that has already been merged @@ -788,7 +787,7 @@ \subsubsection{Development} {right=of C4} % node placement {C4} % target \end{tikzpicture} -\itkcaption{Local \textit{topic} branch started from a given commit and switch to it.} +\itkcaption{Local \textit{topic} branch started from a given commit and switch to it.}% \label{fig:CreateLocalBranchFromCommitAndSwitchToIt} \end{figure} @@ -817,7 +816,7 @@ \subsubsection{Development} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Commit files to \textit{topic}.} +\itkcaption{Commit files to \textit{topic}.}% \label{fig:CommitFilesToTopic1} \end{figure} @@ -844,7 +843,7 @@ \subsubsection{Development} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Further continue developing and commit files to \textit{topic}.} +\itkcaption{Further continue developing and commit files to \textit{topic}.}% \label{fig:CommitFilesToTopic2} \end{figure} @@ -873,7 +872,7 @@ \subsubsection{Development} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge into \textit{master}.} +\itkcaption{Merge into \textit{master}.}% \label{fig:MergeTopicIntoMaster3} \end{figure} @@ -884,7 +883,7 @@ \subsubsection{Development} \end{minted} -\paragraph{Dependent Topic} +\paragraph{Dependent Topic}% \label{par:DependentTopic} Occasionally you may realize that you need the work from another topic to @@ -929,7 +928,7 @@ \subsubsection{Development} {right=of C10} % node placement {C10} % target \end{tikzpicture} -\itkcaption{Fetch the upstream integration branch \textit{other-topic}.} +\itkcaption{Fetch the upstream integration branch \textit{other-topic}.}% \label{fig:FetchUpstreamBranch} \end{figure} @@ -970,7 +969,7 @@ \subsubsection{Development} {right=of C10} % node placement {C10} % target \end{tikzpicture} -\itkcaption{Create a local branch \textit{other-topic} from commit \textit{0a398e5}.} +\itkcaption{Create a local branch \textit{other-topic} from commit \textit{0a398e5}.}% \label{fig:CreateLocalBranchFromCommit} \end{figure} @@ -1004,7 +1003,7 @@ \subsubsection{Development} {right=of C11} % node placement {C11} % target \end{tikzpicture} -\itkcaption{Merge \textbf{other-branch} into \textit{topic} branch.} +\itkcaption{Merge \textbf{other-branch} into \textit{topic} branch.}% \label{fig:MergeBranch} \end{figure} @@ -1027,19 +1026,20 @@ \subsubsection{Development} {right=of C11} % node placement {C11} % target \end{tikzpicture} -\itkcaption{\textit{topic} branch shape.} +\itkcaption{\textit{topic} branch shape.}% \label{fig:BranchShape} \end{figure} Note that after the merge, the \textit{other-topic} is reachable from your topic but the extra-topic has not been included. By not merging from the integration branch we avoided bringing in an unnecessary dependency on the -\textit{extra-topic}. Furthermore, the message ``Merge branch 'other-topic' into -topic'' is very informative about the purpose of the merge. Merging the whole +\textit{extra-topic}. Furthermore, the message +\enquote{Merge branch \enquote{other-topic} into topic} +is very informative about the purpose of the merge. Merging the whole integration branch would not be so clear. -\paragraph{Merge Integration Branches} +\paragraph{Merge Integration Branches}% \label{par:MergeIntegrationBranches} Each published integration branch (see Section~\ref{subsubsec:PublishedBranches} @@ -1075,7 +1075,7 @@ \subsubsection{Development} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Update \textit{master} and \textit{release}.} +\itkcaption{Update \textit{master} and \textit{release}.}% \label{fig:UpdateBranches} \end{figure} @@ -1104,7 +1104,7 @@ \subsubsection{Development} {right=of C10} % node placement {C10} % target \end{tikzpicture} -\itkcaption{Merge \textit{master} into \textit{release}.} +\itkcaption{Merge \textit{master} into \textit{release}.}% \label{fig:MergeMasterIntoRelease} \end{figure} @@ -1137,7 +1137,7 @@ \subsubsection{Development} {below=of C10} % node placement {C10} % target \end{tikzpicture} -\itkcaption{Publish to \textit{release}.} +\itkcaption{Publish to \textit{release}.}% \label{fig:PushChangesToRelease1} \end{figure} @@ -1146,10 +1146,10 @@ \subsubsection{Development} Section~\ref{subpar:NonFastForward} on page~\pageref{subpar:NonFastForward} to resolve any conflict that may arise when publishing the change. -\subsubsection{Discussion} +\subsubsection{Discussion}% \label{subpar:Discussion} -\paragraph{History Shape} +\paragraph{History Shape}% \label{par:HistoryShape} The history graphs produced by this workflow may look complex compared to the @@ -1179,7 +1179,7 @@ \subsubsection{Discussion} {right=of C16} % node placement {C16} % target \end{tikzpicture} -\itkcaption{Complex history graph in Git.} +\itkcaption{Complex history graph in Git.}% \label{fig:ComplexHistory} \end{figure} @@ -1208,7 +1208,7 @@ \subsubsection{Discussion} {right=of C14} % node placement {C14} % target \end{tikzpicture} -\itkcaption{Parent commit in \textit{topic} branch.} +\itkcaption{Parent commit in \textit{topic} branch.}% \label{fig:ParentCommitInTopicBranch} \end{figure} @@ -1230,7 +1230,7 @@ \subsubsection{Discussion} {right=of C15} % node placement {C15} % target \end{tikzpicture} -\itkcaption{Parent commit in \textit{master} branch.} +\itkcaption{Parent commit in \textit{master} branch.}% \label{fig:ParentCommitInMasterBranch} \end{figure} @@ -1253,7 +1253,7 @@ \subsubsection{Discussion} {right=of C16} % node placement {C16} % target \end{tikzpicture} -\itkcaption{Parent commit in \textit{release} branch.} +\itkcaption{Parent commit in \textit{release} branch.}% \label{fig:ParentCommitInReleaseBranch} \end{figure} @@ -1266,7 +1266,7 @@ \subsubsection{Discussion} the above development procedure and strict adherence to it. -\paragraph{Naming Topics} +\paragraph{Naming Topics}% \label{par:NamingTopics} This section uses the placeholder \textit{topic} in place of a real topic name. @@ -1302,13 +1302,13 @@ \subsubsection{Discussion} \end{minted} -\paragraph{Urge to Merge} +\paragraph{Urge to Merge}% \label{par:UrgeToMerge} Avoid the ``urge to merge'' from an integration branch into your topic. Keep commits on your topic focused on the feature or fix under development. -\paragraph{Habitual Merges} +\paragraph{Habitual Merges}% \label{par:HabitualMerges} Merge your work with others when you are finished with it by merging into an @@ -1336,7 +1336,7 @@ \subsubsection{Discussion} clean tree. -\paragraph{Legitimate Merges} +\paragraph{Legitimate Merges}% \label{par:LegitimateMerges} One reason to merge other work into your topic is when you realize that your @@ -1348,21 +1348,21 @@ \subsubsection{Discussion} first. Never merge \textbf{release} into a topic under any circumstances!!! -\subsubsection{Troubleshooting} +\subsubsection{Troubleshooting}% \label{subsubsec:Troubleshooting} Here we document problems one might encounter while following the workflow instructions above. This is not a general Git troubleshooting page. -\paragraph{Trouble Merging} +\paragraph{Trouble Merging}% \label{par:TroubleMerging} %TODO: Write this sub-section and link sub-sub-sections from git merge commands above. -\paragraph{Trouble Pushing} +\paragraph{Trouble Pushing}% \label{par:TroublePushing} -\subparagraph{Remote End Hung up Unexpectedly} +\subparagraph{Remote End Hung up Unexpectedly}% \label{subpar:RemoteEndHungUpUnexpectedly} Pushing may fail with this error: @@ -1399,7 +1399,7 @@ \subsubsection{Troubleshooting} \href{https://git-scm.com/docs/git-remote}{git remote}. -\subparagraph{Non-Fast-Forward} +\subparagraph{Non-Fast-Forward}% \label{subpar:NonFastForward} When trying to publish new merge commits on an integration branch, perhaps @@ -1450,7 +1450,7 @@ \subsubsection{Troubleshooting} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Unreachable \textit{origin/release} branch.} +\itkcaption{Unreachable \textit{origin/release} branch.}% \label{fig:UnreachableBranch} \end{figure} @@ -1511,7 +1511,7 @@ \subsubsection{Troubleshooting} {below=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Start from latest upstream commit.} +\itkcaption{Start from latest upstream commit.}% \label{fig:StartFromLatestUpstreamCommit} \end{figure} @@ -1546,7 +1546,7 @@ \subsubsection{Troubleshooting} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Merge the \textit{topic} branch into the local \textit{release} branch.} +\itkcaption{Merge the \textit{topic} branch into the local \textit{release} branch.}% \label{fig:MergeTopicIntoRelease} \end{figure} @@ -1588,7 +1588,7 @@ \subsubsection{Troubleshooting} {below=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Publish the \textit{release} branch.} +\itkcaption{Publish the \textit{release} branch.}% \label{fig:PushChangesToRelease} \end{figure} @@ -1596,7 +1596,7 @@ \subsubsection{Troubleshooting} resolving the same conflicts on each merge attempt. -\subparagraph{First-Parent Sequence Not Preserved} +\subparagraph{First-Parent Sequence Not Preserved}% \label{subpar:FirstParentSequenceNotPreserved} One goal of this workflow is to preserve a clean shape of history (see @@ -1619,7 +1619,7 @@ \subsubsection{Troubleshooting} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Traversal of the \textit{master} integration branch.} +\itkcaption{Traversal of the \textit{master} integration branch.}% \label{fig:TraversalOfMasterBranch} \end{figure} @@ -1652,7 +1652,7 @@ \subsubsection{Troubleshooting} {right=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Server's integration branch history shape.} +\itkcaption{Server's integration branch history shape.}% \label{fig:IntegrationBranchHistory} \end{figure} @@ -1672,7 +1672,7 @@ \subsubsection{Troubleshooting} {right=of A} % node placement {A} % target \end{tikzpicture} -\itkcaption{First parent traversal of \textit{master} before update.} +\itkcaption{First parent traversal of \textit{master} before update.}% \label{fig:FirstParentTraversalBeforeUpdate} \end{figure} @@ -1692,7 +1692,7 @@ \subsubsection{Troubleshooting} {right=of M} % node placement {M} % target \end{tikzpicture} -\itkcaption{First parent traversal of \textit{master} after update.} +\itkcaption{First parent traversal of \textit{master} after update.}% \label{fig:FirstParentTraversalAfterUpdate} \end{figure} @@ -1720,7 +1720,7 @@ \subsubsection{Troubleshooting} {below=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Incorrect merge of \code{M} on branch \textit{topic}.} +\itkcaption{Incorrect merge of \code{M} on branch \textit{topic}.}% \label{fig:IncorrectMerge} \end{figure} @@ -1744,7 +1744,7 @@ \subsubsection{Troubleshooting} {below=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{First-parent traversal of \textit{master} branch.} +\itkcaption{First-parent traversal of \textit{master} branch.}% \label{fig:FirstParentTraversal} \end{figure} @@ -1779,7 +1779,7 @@ \subsubsection{Troubleshooting} {below=of B} % node placement {B} % target \end{tikzpicture} -\itkcaption{Checkout \textit{master}.} +\itkcaption{Checkout \textit{master}.}% \label{fig:SwitchToMaster2} \end{figure} @@ -1806,7 +1806,7 @@ \subsubsection{Troubleshooting} {right=of U} % node placement {U} % target \end{tikzpicture} -\itkcaption{Commit on \textit{master} branch.} +\itkcaption{Commit on \textit{master} branch.}% \label{fig:WrongCommitOnMasterBranch} \end{figure} @@ -1833,7 +1833,7 @@ \subsubsection{Troubleshooting} {right=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Additional commit on \textit{master} branch.} +\itkcaption{Additional commit on \textit{master} branch.}% \label{fig:WrongAdditionalCommitOnMasterBranch} \end{figure} @@ -1866,7 +1866,7 @@ \subsubsection{Troubleshooting} {right=of M'} % node placement {M'} % target \end{tikzpicture} -\itkcaption{Pull from upstream.} +\itkcaption{Pull from upstream.}% \label{fig:PullChangesFromUpstream} \end{figure} @@ -1909,7 +1909,7 @@ \subsubsection{Troubleshooting} {below=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Create a \textit{topic} branch starting from the first-parent of the incorrect merge.} +\itkcaption{Create a \textit{topic} branch starting from the first-parent of the incorrect merge.}% \label{fig:CreateLocalBranchFromFirstParent} \end{figure} @@ -1940,7 +1940,7 @@ \subsubsection{Troubleshooting} {right=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Reset the local \textit{master} branch to upstream \textit{master}.} +\itkcaption{Reset the local \textit{master} branch to upstream \textit{master}.}% \label{fig:ResetLocalMasterToUpstreamMaster} \end{figure} @@ -1968,7 +1968,7 @@ \subsubsection{Troubleshooting} {right=of T} % node placement {T} % target \end{tikzpicture} -\itkcaption{Merge the \textit{topic} branch.} +\itkcaption{Merge the \textit{topic} branch.}% \label{fig:MergeTopicIntoMaster4} \end{figure} @@ -1995,12 +1995,12 @@ \subsubsection{Troubleshooting} {below=of M} % node placement {M} % target \end{tikzpicture} -\itkcaption{Delete the local \textit{topic} branch.} +\itkcaption{Delete the local \textit{topic} branch.}% \label{fig:DeleteLocalBranch2} \end{figure} -\subparagraph{Topics Must Be Merged} +\subparagraph{Topics Must Be Merged}% \label{subpar:TopicsMustBeMerged} %TODO @@ -2009,7 +2009,7 @@ \subsubsection{Troubleshooting} %pre-commit hook. The fix was to add "--no-ff" arg when merging the topic. -\subsubsection{Conflicts} +\subsubsection{Conflicts}% \label{subsubsec:Conflicts} This section documents conflict resolution in a topic-based branchy workflow. @@ -2018,7 +2018,7 @@ \subsubsection{Conflicts} content conflicts may occur when merging the branches. -\paragraph{Single Integration Branch} +\paragraph{Single Integration Branch}% \label{par:SingleIntegrationBranch} Consider two conflicting topic branches, topic and other-topic, with the latter @@ -2045,7 +2045,7 @@ \subsubsection{Conflicts} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Conflicting topic branches.} +\itkcaption{Conflicting topic branches.}% \label{fig:ConflictingTopicBranches1} \end{figure} @@ -2057,7 +2057,7 @@ \subsubsection{Conflicts} \end{itemize} -\subparagraph{Topic-to-Single-Branch} +\subparagraph{Topic-to-Single-Branch}% \label{subpar:TopicToSingleBranch} If one performs the merge in a local work tree it is possible to simply resolve @@ -2084,12 +2084,12 @@ \subsubsection{Conflicts} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Topic-to-single branch resolution approach.} +\itkcaption{Topic-to-single branch resolution approach.}% \label{fig:TopicToSingleBranchResolutionApproach} \end{figure} -\subparagraph{Branch-to-Topic} +\subparagraph{Branch-to-Topic}% \label{subpar:BranchToTopic} Since a developer works on a topic branch locally one may simply merge the @@ -2116,7 +2116,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Branch-to-Topic resolution approach.} +\itkcaption{Branch-to-Topic resolution approach.}% \label{fig:BranchToTopicResolutionApproach} \end{figure} @@ -2145,12 +2145,12 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Merge disallowing fast-forward (\code{--no-ff}).} +\itkcaption{Merge disallowing fast-forward (\code{--no-ff}).}% \label{fig:MergeDisallowingFF} \end{figure} -\paragraph{Multiple Integration Branches} +\paragraph{Multiple Integration Branches}% \label{par:MultipleIntegrationBranches} In a workflow using multiple integration branches one must deal differently with @@ -2183,7 +2183,7 @@ \subsubsection{Conflicts} {right=of C7} % node placement {C7} % target \end{tikzpicture} -\itkcaption{Conflicting topic branches.} +\itkcaption{Conflicting topic branches.}% \label{fig:ConflictingTopicBranches2} \end{figure} @@ -2201,7 +2201,7 @@ \subsubsection{Conflicts} a topic. -\subparagraph{Topic-to-Branch} +\subparagraph{Topic-to-Branch}% \label{subpar:TopicToBranch} If one performs the merge in a local work tree it is possible to simply resolve @@ -2233,7 +2233,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Merge locally.} +\itkcaption{Merge locally.}% \label{fig:MergeLocally} \end{figure} @@ -2266,7 +2266,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Merge \textit{topic}.} +\itkcaption{Merge \textit{topic}.}% \label{fig:MergeTopic1} \end{figure} @@ -2299,7 +2299,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Merge conflict when attempting to merge \textit{other-topic} into \textbf{master}.} +\itkcaption{Merge conflict when attempting to merge \textit{other-topic} into \textbf{master}.}% \label{fig:MergeConflict} \end{figure} @@ -2337,7 +2337,7 @@ \subsubsection{Conflicts} {right=of ?} % node placement {?} % target \end{tikzpicture} -\itkcaption{\textbf{master} not merging cleanly into \textbf{release} if conflicts have not been resolved.} +\itkcaption{\textbf{master} not merging cleanly into \textbf{release} if conflicts have not been resolved.}% \label{fig:UncleanMerge} \end{figure} @@ -2346,7 +2346,7 @@ \subsubsection{Conflicts} This approach works with manual merging but requires care. -\subparagraph{Topic-to-Topic} +\subparagraph{Topic-to-Topic}% \label{subpar:TopicToTopic} The design (see Section~\ref{subsubsec:Design} on @@ -2389,7 +2389,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Manually merge \textit{other-topic} into \textit{topic}.} +\itkcaption{Manually merge \textit{other-topic} into \textit{topic}.}% \label{fig:ManualMergeTopicIntoTopic} \end{figure} @@ -2425,7 +2425,7 @@ \subsubsection{Conflicts} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge into \textit{release}.} +\itkcaption{Merge into \textit{release}.}% \label{fig:MergeChangesIntoRelease} \end{figure} @@ -2463,7 +2463,7 @@ \subsubsection{Conflicts} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge into \textit{master}.} +\itkcaption{Merge into \textit{master}.}% \label{fig:MergeIntoMaster} \end{figure} @@ -2498,7 +2498,7 @@ \subsubsection{Conflicts} {right=of C11} % node placement {C11} % target \end{tikzpicture} -\itkcaption{Merge \textit{master} into \textit{release}.} +\itkcaption{Merge \textit{master} into \textit{release}.}% \label{fig:MergeIntoRelease1} \end{figure} @@ -2508,7 +2508,7 @@ \subsubsection{Conflicts} the~\ref{subpar:ResolutionTopic} approach to avoid this problem. -\subparagraph{Resolution Topic} +\subparagraph{Resolution Topic}% \label{subpar:ResolutionTopic} The~\ref{subpar:TopicToTopic} approach introduces an artificial topic @@ -2552,7 +2552,7 @@ \subsubsection{Conflicts} {right=of C8} % node placement {C8} % target \end{tikzpicture} -\itkcaption{Start conflict resolution branch.} +\itkcaption{Start conflict resolution branch.}% \label{fig:StartConflictResolutionBranch} \end{figure} @@ -2594,7 +2594,7 @@ \subsubsection{Conflicts} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge into \textit{release}.} +\itkcaption{Merge into \textit{release}.}% \label{fig:MergeIntoRelease2} \end{figure} @@ -2636,7 +2636,7 @@ \subsubsection{Conflicts} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge \textit{topic} branch.} +\itkcaption{Merge \textit{topic} branch.}% \label{fig:MergeTopic2} \end{figure} @@ -2681,7 +2681,7 @@ \subsubsection{Conflicts} {right=of C9} % node placement {C9} % target \end{tikzpicture} -\itkcaption{Merge conflict resolution branch into \textit{master}.} +\itkcaption{Merge conflict resolution branch into \textit{master}.}% \label{fig:MergeConflictResolutionBranchIntoMaster} \end{figure} @@ -2722,16 +2722,16 @@ \subsubsection{Conflicts} {right=of C12} % node placement {C12} % target \end{tikzpicture} -\itkcaption{Merge into \textit{release}.} +\itkcaption{Merge into \textit{release}.}% \label{fig:MergeConflictResolutionBranchIntoRelease} \end{figure} -\subsection{Publish} +\subsection{Publish}% \label{subsec:Publish} -\subsubsection{Push Access} +\subsubsection{Push Access}% \label{subsubsec:PushAccess} Authorized developers may publish work directly to a \href{public.kitware.com} @@ -2741,7 +2741,7 @@ \subsubsection{Push Access} The distributed nature of Git allows contributors to retain authorship credit even if they do not publish changes directly. -\paragraph{Authentication} +\paragraph{Authentication}% \label{par:Authentication} All publishers share the \code{git@public.kitware.com} account but each uses a @@ -2763,7 +2763,7 @@ \subsubsection{Push Access} Include your SSH public key, \code{id\_rsa.pub}, and a reference to someone our administrators may contact to verify your privileges. -\subparagraph{SSH on Windows} +\subparagraph{SSH on Windows}% \label{subpar:SSHOnWindows} If you are familiar with generating an SSH key on Linux or macOS, you can follow @@ -2805,7 +2805,7 @@ \subsubsection{Push Access} directory is. -\subparagraph{AuthenticationTest} +\subparagraph{AuthenticationTest}% \label{subpar:AuthenticationTest} When your SSH public key has been installed for \code{git@public.kitware.com}, @@ -2827,7 +2827,7 @@ \subsubsection{Push Access} Do not attempt to \code{git push} until the ssh-only test succeeds. -\paragraph{Pushing} +\paragraph{Pushing}% \label{subpar:Pushing} Git automatically configures a new clone to refer to its \textit{origin} through @@ -2854,7 +2854,7 @@ \subsubsection{Push Access} Section~\ref{subsec:Hooks} on page~\pageref{subsec:Hooks}. -\subsubsection{Patches} +\subsubsection{Patches}% \label{subsubsec:Patches} Git allows anyone to be a first-class developer on any published project. One @@ -2869,7 +2869,7 @@ \subsubsection{Patches} \end{itemize} -\paragraph{Creating Patches} +\paragraph{Creating Patches}% \label{par:CreatingPatches} Construct your commits on a local topic branch, typically started from the @@ -2898,7 +2898,7 @@ \subsubsection{Patches} message and author. -\paragraph{Sending Patches} +\paragraph{Sending Patches}% \label{par:SendingPatches} The patch files created in the preceding step will be named with the form @@ -2920,7 +2920,7 @@ \subsubsection{Patches} \end{minted} -\paragraph{Applying Patches} +\paragraph{Applying Patches}% \label{par:ApplyingPatches} One may receive patches as attachments in a bug tracker or as attachments to @@ -2967,10 +2967,10 @@ \subsubsection{Patches} \end{minted} -\subsection{Hooks} +\subsection{Hooks}% \label{subsec:Hooks} -\subsubsection{Setup} +\subsubsection{Setup}% \label{subsubsec:Setup} The \code{git commit} command creates local commits. A separate \code{git push} @@ -3000,7 +3000,7 @@ \subsubsection{Setup} will then run in the outer repository to enforce some rules on commits. -\paragraph{Local Pull} +\paragraph{Local Pull}% \label{par:LocalPull} Many \href{public.kitware.com} repositories provide a \code{hooks} branch. It @@ -3014,7 +3014,7 @@ \subsubsection{Setup} \end{minted} -\paragraph{Direct Pull} +\paragraph{Direct Pull}% \label{par:DirectPull} If you did not clone from a \href{public.kitware.com} repository you may not @@ -3029,7 +3029,7 @@ \subsubsection{Setup} where \code{.git} is the name of your project repository. -\subsubsection{Local} +\subsubsection{Local}% \label{subsubsec:Local} The above sequences maintain the following local \code{hooks} in your @@ -3037,7 +3037,7 @@ \subsubsection{Local} \href{githooks}{https://git-scm.com/docs/githooks} for more details. -\paragraph{pre-commit} +\paragraph{pre-commit}% \label{par:pre-commit} This runs during \code{git commit}. It checks identity and content of changes: @@ -3107,7 +3107,7 @@ \subsubsection{Local} \end{minted} -\paragraph{commit-msg} +\paragraph{commit-msg}% \label{par:commit-msg} This runs during \code{git commit}. It checks the commit message format: @@ -3153,13 +3153,13 @@ \subsubsection{Local} the commit to complete and then fix it with \code{git commit --amend}. -\subsubsection{Server} +\subsubsection{Server}% \label{subsubsec:Server} Many \url{public.kitware.com} repositories have server-side \code{hooks}. -\paragraph{Update} +\paragraph{Update}% \label{par:Update} The update hook runs when someone tries to update a ref on the server by @@ -3179,10 +3179,10 @@ \subsubsection{Server} pushed. \end{itemize} -\subsection{TipsAndTricks} +\subsection{TipsAndTricks}% \label{subsec:TipsAndTricks} -\subsubsection{Editor support} +\subsubsection{Editor support}% \label{subsubsec:EditorSupport} Emacs users: if you put this line in your \code{.emacs} file: @@ -3195,10 +3195,10 @@ \subsubsection{Editor support} etiquette requires. -\subsubsection{Shell Customization} +\subsubsection{Shell Customization}% \label{subsubsec:ShellCustomization} -\paragraph{Bash Completion} +\paragraph{Bash Completion}% \label{par:BashCompletion} Bash users: Git comes with a set of completion options that are very useful. The @@ -3214,7 +3214,7 @@ \subsubsection{Shell Customization} \end{minted} -\paragraph{Bash Prompt} +\paragraph{Bash Prompt}% \label{par:BashPrompt} If you are using the bash shell, you can customize the prompt to show which Git @@ -3232,7 +3232,7 @@ \subsubsection{Shell Customization} For more information on the options, see the comments in the top of the bash completion script. -\paragraph{Renaming} +\paragraph{Renaming}% \label{par:Renaming} Git does not explicitly track renames. The command diff --git a/SoftwareGuide/Latex/Appendices/Licenses.tex b/SoftwareGuide/Latex/Appendices/Licenses.tex index 6b40bfe3..dfcf3cb7 100644 --- a/SoftwareGuide/Latex/Appendices/Licenses.tex +++ b/SoftwareGuide/Latex/Appendices/Licenses.tex @@ -1,6 +1,6 @@ \chapter{Licenses} -\section{Insight Toolkit License} +\section{Insight Toolkit License}% \label{sec:InsightToolkitLicense} \verbatiminput{\ITKSOURCEDIR/LICENSE} diff --git a/SoftwareGuide/Latex/Architecture/DataRepresentation.tex b/SoftwareGuide/Latex/Architecture/DataRepresentation.tex index 8a379dce..c53a3ffb 100644 --- a/SoftwareGuide/Latex/Architecture/DataRepresentation.tex +++ b/SoftwareGuide/Latex/Architecture/DataRepresentation.tex @@ -1,12 +1,12 @@ -\chapter{Data Representation} +\chapter{Data Representation}% \label{sec:DataRepresentation} This chapter introduces the basic classes responsible for representing data in ITK. The most common classes are \doxygen{Image}, \doxygen{Mesh} and \doxygen{PointSet}. -\section{Image} +\section{Image}% \label{sec:ImageSection} The \doxygen{Image} class follows the spirit of @@ -24,19 +24,19 @@ \subsection{Creating an Image}\label{sec:CreatingAnImageSection} a file. -\subsection{Reading an Image from a File} +\subsection{Reading an Image from a File}% \label{sec:ReadingImageFromFile} \input{Image2.tex} -\subsection{Accessing Pixel Data} +\subsection{Accessing Pixel Data}% \label{sec:AccessingImagePixelData} \input{Image3.tex} -\subsection{Defining Origin and Spacing} +\subsection{Defining Origin and Spacing}% \label{sec:DefiningImageOriginAndSpacing} \input{Image4.tex} @@ -69,7 +69,7 @@ \subsection{RGB Images} the human eye. In the context of colorimetry, negative color values are used as an artificial construct for color comparison in the sense that -\begin{equation} +\begin{equation}% \label{eqn:ColorSubtraction} ColorA = ColorB - ColorC \end{equation} @@ -79,7 +79,7 @@ \subsection{RGB Images} possible to \emph{subtract light}. So when we mention Equation~\ref{eqn:ColorSubtraction} we actually mean -\begin{equation} +\begin{equation}% \label{eqn:ColorAddition} ColorB = ColorA + ColorC \end{equation} @@ -120,55 +120,56 @@ \subsection{RGB Images} The following example illustrates how RGB images can be represented in ITK. +\subsection{RGB Images}% \label{sec:DefiningRGBImages} \input{RGBImage.tex} -\subsection{Vector Images} +\subsection{Vector Images}% \label{sec:DefiningVectorImages} \input{VectorImage.tex} -\subsection{Importing Image Data from a Buffer} +\subsection{Importing Image Data from a Buffer}% \label{sec:ImportingImageDataFromABuffer} \input{Image5.tex} -\section{PointSet} +\section{PointSet}% \label{PointSetSection} -\subsection{Creating a PointSet} +\subsection{Creating a PointSet}% \label{sec:CreatingAPointSet} \input{PointSet1.tex} -\subsection{Getting Access to Points} +\subsection{Getting Access to Points}% \label{sec:GettingAccessToPointsInThePointSet} \input{PointSet2.tex} -\subsection{Getting Access to Data in Points} +\subsection{Getting Access to Data in Points}% \label{sec:GettingAccessToDataInThePointSet} \input{PointSet3.tex} -\subsection{RGB as Pixel Type} +\subsection{RGB as Pixel Type}% \label{sec:PointSetWithRGBAsPixelType} \input{RGBPointSet.tex} -\subsection{Vectors as Pixel Type} +\subsection{Vectors as Pixel Type}% \label{sec:PointSetWithVectorsAsPixelType} \input{PointSetWithVectors.tex} -\subsection{Normals as Pixel Type} +\subsection{Normals as Pixel Type}% \label{sec:PointSetWithCovariantVectorsAsPixelType} \input{PointSetWithCovariantVectors.tex} @@ -176,61 +177,61 @@ \subsection{Normals as Pixel Type} \section{Mesh}\label{MeshSection} -\subsection{Creating a Mesh} +\subsection{Creating a Mesh}% \label{sec:CreatingAMesh} \input{Mesh1.tex} -\subsection{Inserting Cells} +\subsection{Inserting Cells}% \label{sec:InsertingCellsInMesh} \input{Mesh2.tex} -\subsection{Managing Data in Cells} +\subsection{Managing Data in Cells}% \label{sec:ManagingCellDataInMesh} \input{Mesh3.tex} -\subsection{Customizing the Mesh} +\subsection{Customizing the Mesh}% \label{sec:CustomizingTheMesh} \input{MeshTraits.tex} -\subsection{Topology and the K-Complex} +\subsection{Topology and the K-Complex}% \label{sec:MeshKComplex} \input{MeshKComplex.tex} -\subsection{Representing a PolyLine} +\subsection{Representing a PolyLine}% \label{sec:MeshPolyLine} \input{MeshPolyLine.tex} -\subsection{Simplifying Mesh Creation} +\subsection{Simplifying Mesh Creation}% \label{sec:AutomaticMesh} \input{AutomaticMesh.tex} -\subsection{Iterating Through Cells} +\subsection{Iterating Through Cells}% \label{sec:MeshCellsIteration} \input{MeshCellsIteration.tex} -\subsection{Visiting Cells} +\subsection{Visiting Cells}% \label{sec:MeshCellVisitor} \input{MeshCellVisitor.tex} -\subsection{More on Visiting Cells} +\subsection{More on Visiting Cells}% \label{sec:MeshCellVisitorMultipleType} \input{MeshCellVisitor2.tex} @@ -238,7 +239,7 @@ \subsection{More on Visiting Cells} \section{Path}\label{PathSection} -\subsection{Creating a PolyLineParametricPath} +\subsection{Creating a PolyLineParametricPath}% \label{sec:CreatingAPolyLineParametricPath} \input{PolyLineParametricPath1.tex} diff --git a/SoftwareGuide/Latex/Architecture/ImageAdaptors.tex b/SoftwareGuide/Latex/Architecture/ImageAdaptors.tex index 6af28f12..792237b1 100644 --- a/SoftwareGuide/Latex/Architecture/ImageAdaptors.tex +++ b/SoftwareGuide/Latex/Architecture/ImageAdaptors.tex @@ -1,7 +1,6 @@ -\chapter{Image Adaptors} -\label{sec:ImageAdaptors} - +\chapter{Image Adaptors}% +\label{sec:ImageAdaptors}% \index{ImageAdaptors} \begin{figure} @@ -13,7 +12,7 @@ \chapter{Image Adaptors} produces an intermediate image. In the example illustrated by this figure, the \emph{Image Y} is not created by the ImageAdaptor; instead, the image is simulated on the fly each time an -iterator from the filter downstream attempts to access the image data.} +iterator from the filter downstream attempts to access the image data.}% \label{fig:ImageAdaptorConcept} \end{figure} @@ -53,22 +52,22 @@ \chapter{Image Adaptors} The following examples illustrate common applications of image adaptors. -\section{Image Casting} +\section{Image Casting}% \label{sec:ImageAdaptorForBasicCasting} \input{ImageAdaptor1.tex} -\section{Adapting RGB Images} +\section{Adapting RGB Images}% \label{sec:ImageAdaptorForRGB} \input{ImageAdaptor2.tex} -\section{Adapting Vector Images} +\section{Adapting Vector Images}% \label{sec:ImageAdaptorForVectors} \input{ImageAdaptor3.tex} -\section{Adaptors for Simple Computation} +\section{Adaptors for Simple Computation}% \label{sec:ImageAdaptorForSimpleComputation} \input{ImageAdaptor4.tex} diff --git a/SoftwareGuide/Latex/Architecture/Iterators.tex b/SoftwareGuide/Latex/Architecture/Iterators.tex index 37f0312e..d347536c 100644 --- a/SoftwareGuide/Latex/Architecture/Iterators.tex +++ b/SoftwareGuide/Latex/Architecture/Iterators.tex @@ -1,6 +1,6 @@ -\chapter{Iterators} -\label{sec:ImageIteratorsChapter} -\index{Iterators!image|(} +\chapter{Iterators}% +\label{sec:ImageIteratorsChapter}% +\index{Iterators!image|(}% \index{Generic Programming} This chapter introduces the \emph{image iterator}, an important generic programming construct for image processing in ITK. An iterator is a @@ -9,16 +9,16 @@ \chapter{Iterators} which are highly specialized to simplify common image processing tasks. The next section is a brief introduction that defines iterators in the context -of ITK. Section \ref{sec:IteratorsInterface} describes the programming +of ITK. Section~\ref{sec:IteratorsInterface} describes the programming interface common to most ITK image iterators. Sections~\ref{sec:ImageIterators}--\ref{sec:NeighborhoodIterators} document specific ITK iterator types and provide examples of how they are used. -\section{Introduction} -\label{sec:IteratorsIntroduction} -% Further define iterators in the context of generic programming. -\index{generic programming} +\section{Introduction}% +\label{sec:IteratorsIntroduction}% +\index{generic programming}% \index{Iterators!definition of} +% Further define iterators in the context of generic programming. Generic programming models define functionally independent components called \emph{containers} and \emph{algorithms}. Container objects store data and algorithms operate on data. To access data in containers, algorithms use a @@ -36,10 +36,10 @@ \section{Introduction} sequentially reference elements of an array. Many iterator implementations have an interface similar to a C pointer. -\index{Iterators!advantages of} In ITK we use iterators to write generic image processing code for images instantiated with different combinations of pixel type, pixel -container type, and dimensionality. Because ITK image iterators are +container type, and dimensionality.\index{Iterators!advantages of} +Because ITK image iterators are specifically designed to work with \emph{image} containers, their interface and implementation is optimized for image processing tasks. Using the ITK iterators instead of accessing data directly through the @@ -49,35 +49,30 @@ \section{Introduction} neighborhood-based image processing. -\section{Programming Interface} -\label{sec:IteratorsInterface} - -\index{Iterators!programming interface|(} +\section{Programming Interface}% +\label{sec:IteratorsInterface}% +\index{Iterators!programming interface} %Creating iterators This section describes the standard ITK image iterator programming interface. Some specialized image iterators may deviate from this standard or provide additional methods. -\subsection{Creating Iterators} -\label{sec:CreatingIterators} - +\subsection{Creating Iterators}% +\label{sec:CreatingIterators}% \index{Iterators!construction of} All image iterators have at least one template parameter that is the image type over which they iterate. There is no restriction on the dimensionality of the image or on the pixel type of the image. -\index{Iterators!and image regions} - An iterator constructor requires at least two arguments, a smart pointer to the -image to iterate across, and an image region. The image region, called the +image to iterate across, and an image region\index{Iterators!and image regions}. The image region, called the \emph{iteration region}, is a rectilinear area in which iteration is constrained. The iteration region must be wholly contained within the image. More specifically, a valid iteration region is any subregion of the image within the current \code{BufferedRegion}. See Section~\ref{sec:ImageSection} for more information on image regions. -\index{Iterators!const} -There is a const and a non-const version of most ITK image iterators. A +There is a const\index{Iterators!const} and a non-const version of most ITK image iterators. A non-const iterator cannot be instantiated on a non-const image pointer. Const versions of iterators may read, but may not write pixel values. @@ -97,7 +92,7 @@ \subsection{Creating Iterators} \end{minted} \normalsize -\subsection{Moving Iterators} +\subsection{Moving Iterators}% \label{sec:MovingIterators} An iterator is described as \emph{walking} its iteration region. At any time, the iterator will reference, or ``point to'', one pixel location in the @@ -106,19 +101,17 @@ \subsection{Moving Iterators} iteration}, goes from just past the end of the region back to the beginning. There are two corresponding starting positions for iterators, the \emph{begin} position and the \emph{end} position. An iterator can be moved -directly to either of these two positions using the following methods. - -\index{forward iteration} -\index{reverse iteration} +directly to either of these two positions using the following methods.% +\index{forward iteration}% +\index{reverse iteration}% \index{iteration region} -\index{Iterators!GoToBegin()} + \begin{itemize} -\item \textbf{\code{GoToBegin()}} Points the iterator to the first valid +\item \textbf{\code{GoToBegin()}}\index{Iterators!GoToBegin()} Points the iterator to the first valid data element in the region. -\index{Iterators!GoToEnd()} -\item \textbf{\code{GoToEnd()}} Points the iterator to \emph{one position past} +\item \textbf{\code{GoToEnd()}}\index{Iterators!GoToEnd()} Points the iterator to \emph{one position past} the last valid element in the region. \end{itemize} @@ -130,14 +123,12 @@ \subsection{Moving Iterators} ITK iterators are moved back and forth across their iterations using the decrement and increment operators. -\index{Iterators!operator++()} \begin{itemize} -\item \textbf{\code{operator++()}} Increments the iterator one position in the +\item \textbf{\code{operator++()}}\index{Iterators!operator++()} Increments the iterator one position in the positive direction. Only the prefix increment operator is defined for ITK image iterators. -\index{Iterators!operator--} -\item \textbf{\code{operator--()}} Decrements the iterator one position in the +\item \textbf{\code{operator--()}}\index{Iterators!operator--} Decrements the iterator one position in the negative direction. Only the prefix decrement operator is defined for ITK image iterators. \end{itemize} @@ -163,17 +154,14 @@ \subsection{Moving Iterators} operators may not be optimized for speed and require some knowledge of the dimensionality of the image and the extent of the iteration region to use properly. -\begin{itemize} -\index{Iterators!operator+=()} -\item \textbf{\code{operator+=( OffsetType )}} Moves the iterator to the pixel +\begin{itemize}% +\item \textbf{\code{operator+=( OffsetType )}}\index{Iterators!operator+=()} Moves the iterator to the pixel position at the current index plus specified \doxygen{Offset}. -\index{Iterators!operator-=()} -\item \textbf{\code{operator-=( OffsetType )}} Moves the iterator to +\item \textbf{\code{operator-=( OffsetType )}}\index{Iterators!operator-=()} Moves the iterator to the pixel position at the current index minus specified Offset. -\index{Iterators!SetPosition()} -\item \textbf{\code{SetPosition( IndexType )}} Moves the iterator to the given +\item \textbf{\code{SetPosition( IndexType )}}\index{Iterators!SetPosition()} Moves the iterator to the given \doxygen{Index} position. \end{itemize} @@ -192,13 +180,11 @@ \subsection{Moving Iterators} An iterator can be queried to determine if it is at the end or the beginning of its iteration region. -\begin{itemize} -\index{Iterators!IsAtEnd()} -\item \textbf{\code{bool IsAtEnd()}} True if the iterator points to \emph{one +\begin{itemize}% +\item \textbf{\code{bool IsAtEnd()}}\index{Iterators!IsAtEnd()} True if the iterator points to \emph{one position past} the end of the iteration region. -\index{Iterators!IsAtBegin()} -\item \textbf{\code{bool IsAtBegin()}} True if the iterator points to the first +\item \textbf{\code{bool IsAtBegin()}}\index{Iterators!IsAtBegin()} True if the iterator points to the first position in the iteration region. The method is typically used to test for the end of reverse iteration. @@ -206,31 +192,27 @@ \subsection{Moving Iterators} An iterator can also report its current image index position. -\begin{itemize} -\index{Iterators!GetIndex()} -\item \textbf{\code{IndexType GetIndex()}} Returns the Index -of the image pixel that the iterator currently points to. +\begin{itemize}% +\item \textbf{\code{IndexType GetIndex()}}\index{Iterators!GetIndex()} +Returns the Index of the image pixel that the iterator currently points to. \end{itemize} % A note on bounds checking -\index{Iterators!and bounds checking} -For efficiency, most ITK image iterators do not perform bounds checking. It is -possible to move an iterator outside of its valid iteration region. +For efficiency, most ITK image iterators do not perform bounds checking\index{Iterators!and bounds checking}. +It is possible to move an iterator outside of its valid iteration region. Dereferencing an out-of-bounds iterator will produce undefined results. -\subsection{Accessing Data} +\subsection{Accessing Data}% \label{sec:AccessingData} ITK image iterators define two basic methods for reading and writing pixel values. -\begin{itemize} -\index{Iterators!Get()} -\item \textbf{\code{PixelType Get()}} Returns the value of the pixel at the -iterator position. +\begin{itemize}% +\item \textbf{\code{PixelType Get()}}\index{Iterators!Get()} +Returns the value of the pixel at the iterator position. -\index{Iterators!Set()} -\item \textbf{\code{void Set( PixelType )}} Sets the value of the pixel at the -iterator position. Not defined for const versions of iterators. +\item \textbf{\code{void Set( PixelType )}}\index{Iterators!Set()} +Sets the value of the pixel at the iterator position. Not defined for const versions of iterators. \end{itemize} % Describe efficiency due to inlining for all cases @@ -250,9 +232,8 @@ \subsection{Accessing Data} As written, this code requires one more memory dereference than is necessary. Some iterators define a third data access method that avoids this penalty. -\begin{itemize} -\index{Iterators!Value()} -\item \textbf{\code{PixelType \& Value()}} Returns a reference to the pixel at +\begin{itemize}% +\item \textbf{\code{PixelType \& Value()}}\index{Iterators!Value()} Returns a reference to the pixel at the iterator position. \end{itemize} @@ -274,7 +255,7 @@ \subsection{Accessing Data} adapters (see Section~\ref{sec:ImageAdaptors} on page~\pageref{sec:ImageAdaptors} for more information about image adaptors). -\subsection{Iteration Loops} +\subsection{Iteration Loops}% \label{sec:IterationExample} % Now give a pseudo code example for putting all of this together. Using the methods described in the previous sections, we can now write a simple @@ -293,17 +274,16 @@ \subsection{Iteration Loops} \end{minted} \normalsize -\index{Iterators!and image regions} Notice that both the input and output iterators are initialized over the same -region, the \code{RequestedRegion} of \code{inputImage}. This is good +region, the \code{RequestedRegion} of \code{inputImage}\index{Iterators!and image regions}. +This is good practice because it ensures that the output iterator walks exactly the same set of pixel indices as the input iterator, but does not require that the output and input be the same size. The only requirement is that the input image must contain a region (a starting index and size) that matches the \code{RequestedRegion} of the output image. -\index{reverse iteration} -Equivalent code can be written by iterating through the image in reverse. +Equivalent code can be written by iterating through the image in reverse\index{reverse iteration}. The syntax is slightly more awkward because the \emph{end} of the iteration region is not a valid position and we can only test whether the iterator is strictly \emph{equal} to its beginning position. It is often more @@ -336,9 +316,9 @@ \subsection{Iteration Loops} % operator <, operator >, etc. +\section{Image Iterators}% +\label{sec:ImageIterators}% \index{Iterators!programming interface|)} -\section{Image Iterators} -\label{sec:ImageIterators} %Introduction and overview This section describes iterators that walk rectilinear image regions and reference a single pixel at a time. The \doxygen{ImageRegionIterator} is the @@ -349,35 +329,35 @@ \section{Image Iterators} % Each of the iterators has a const and non-const version -\subsection{ImageRegionIterator} -\index{itk::ImageRegionIterator|(} +\subsection{ImageRegionIterator}% +\index{itk::ImageRegionIterator|(}% \label{sec:itkImageRegionIterator} -\input{ImageRegionIterator.tex} +\input{ImageRegionIterator.tex}% \index{itk::ImageRegionIterator|)} -\subsection{ImageRegionIteratorWithIndex} -\label{sec:itkImageRegionIteratorWithIndex} +\subsection{ImageRegionIteratorWithIndex}% +\label{sec:itkImageRegionIteratorWithIndex}% \index{itk::ImageRegionIteratorWithIndex|(} -\input{ImageRegionIteratorWithIndex.tex} +\input{ImageRegionIteratorWithIndex.tex}% \index{itk::ImageRegionIteratorWithIndex|)} -\subsection{ImageLinearIteratorWithIndex} -\label{sec:itkImageLinearIteratorWithIndex} +\subsection{ImageLinearIteratorWithIndex}% +\label{sec:itkImageLinearIteratorWithIndex}% \index{itk::ImageLinearIteratorWithIndex|(} \input{ImageLinearIteratorWithIndex.tex} -\input{ImageLinearIteratorWithIndex2.tex} +\input{ImageLinearIteratorWithIndex2.tex}% \index{itk::ImageLinearIteratorWithIndex|)} -\subsection{ImageSliceIteratorWithIndex} -\label{sec:itkImageSliceIteratorWithIndex} +\subsection{ImageSliceIteratorWithIndex}% +\label{sec:itkImageSliceIteratorWithIndex}% \index{itk::ImageSliceIteratorWithIndex|(} -\input{ImageSliceIteratorWithIndex.tex} +\input{ImageSliceIteratorWithIndex.tex}% \index{itk::ImageSliceIteratorWithIndex|)} -\subsection{ImageRandomConstIteratorWithIndex} -\label{sec:itkImageRandomConstIteratorWithIndex} +\subsection{ImageRandomConstIteratorWithIndex}% +\label{sec:itkImageRandomConstIteratorWithIndex}% \index{itk::Image\-Random\-Const\-Iterator\-With\-Index|(} -\input{ImageRandomConstIteratorWithIndex} +\input{ImageRandomConstIteratorWithIndex}% \index{itk::Image\-Random\-Const\-Iterator\-With\-Index|)} %\section{Conditional Iterators} @@ -423,8 +403,8 @@ \subsection{ImageRandomConstIteratorWithIndex} %\index{itk::FloodFilledImageFunctionConditionalIterator|)} %\index{Iterators!conditional|)} -\section{Neighborhood Iterators} -\label{sec:NeighborhoodIterators} +\section{Neighborhood Iterators}% +\label{sec:NeighborhoodIterators}% \index{Iterators!neighborhood|(} In ITK, a pixel neighborhood is loosely defined as a small set of pixels that are locally adjacent to one another in an image. The size and shape @@ -450,7 +430,7 @@ \section{Neighborhood Iterators} Section~\ref{sec:IteratorsInterface} and the same code constructs as normal iterators for looping through an image. Figure~\ref{fig:NeighborhoodIteratorFig1} shows a neighborhood iterator -moving through an iteration region. This iterator defines a $3x3$ neighborhood +moving through an iteration region. This iterator defines a 3$\times$3 neighborhood around each pixel that it visits. The \emph{center} of the neighborhood iterator is always positioned over its current index and all other neighborhood pixel indices are referenced as offsets from the center index. The pixel @@ -460,15 +440,14 @@ \section{Neighborhood Iterators} \begin{figure} \centering \includegraphics[width=0.6\textwidth]{NeighborhoodIteratorFig1.eps} -\itkcaption[Neighborhood iterator]{Path of a $3x3$ neighborhood +\itkcaption[Neighborhood iterator]{Path of a 3$\times$3 neighborhood iterator through a 2D image region. The extent of the neighborhood is indicated by the hashing around the iterator position. Pixels that lie within this extent are accessible through the iterator. An arrow denotes a single iterator step, the result of one \code{++} operation.} \protect\label{fig:NeighborhoodIteratorFig1} -\end{figure} - -\index{Neighborhood iterators!construction of} +\end{figure}% +\index{Neighborhood iterators!construction of}% \index{Neighborhood iterators!radius of} In addition to the standard image pointer and iteration region @@ -481,7 +460,7 @@ \section{Neighborhood Iterators} neighborhood in pixels for dimension $N$. The length of each face of the resulting ND hypercube is $2d + 1$ pixels, a distance of $d$ on either side of the single pixel at the neighbor center. -Figure~{\ref{fig:NeighborhoodIteratorFig2} shows the relationship between the +Figure~\ref{fig:NeighborhoodIteratorFig2} shows the relationship between the radius of the iterator and the size of the neighborhood for a variety of 2D iterator shapes. @@ -500,19 +479,16 @@ \section{Neighborhood Iterators} \protect\label{fig:NeighborhoodIteratorFig2} \end{figure} -\begin{itemize} - +\begin{itemize}% \index{NeighborhoodIterator!GetRadius()} \item \textbf{\code{SizeType GetRadius()}} Returns the ND radius of the neighborhood as an \doxygen{Size}. -\index{NeighborhoodIterator!GetImagePointer()} -\item \textbf{\code{const ImageType *GetImagePointer()}} Returns the pointer to -the image referenced by the iterator. +\item \textbf{\code{const ImageType *GetImagePointer()}}\index{NeighborhoodIterator!GetImagePointer()} + Returns the pointer to the image referenced by the iterator. -\index{NeighborhoodIterator!Size()} -\item \textbf{\code{unsigned long Size()}} Returns the size in number of -pixels of the neighborhood. +\item \textbf{\code{unsigned long Size()}}\index{NeighborhoodIterator!Size()} + Returns the size in number of pixels of the neighborhood. \end{itemize} @@ -526,79 +502,61 @@ \section{Neighborhood Iterators} at the top of each pixel. The center pixel is always at position $n/2$, where $n$ is the size of the array. -\begin{itemize} +\begin{itemize}% +\item \textbf{\code{PixelType GetPixel(const unsigned int i)}}\index{NeighborhoodIterator!GetPixel()} + Returns the value of the pixel at neighborhood position \code{i}. -\index{NeighborhoodIterator!GetPixel()} -\item \textbf{\code{PixelType GetPixel(const unsigned int i)}} Returns the -value of the pixel at neighborhood position \code{i}. - -\index{NeighborhoodIterator!SetPixel()} -\item \textbf{\code{void SetPixel(const unsigned int i, PixelType p)}} +\item \textbf{\code{void SetPixel(const unsigned int i, PixelType p)}}\index{NeighborhoodIterator!SetPixel()} Sets the value of the pixel at position \code{i} to \code{p}. \end{itemize} Another way to think about a pixel location in a neighborhood is as an ND offset from the neighborhood center. The upper-left-forward corner -of a $3x3x3$ neighborhood, for example, can be described by offset +of a 3$\times$3$\times$3 neighborhood, for example, can be described by offset $(-1, -1, -1)$. The bottom-right-back corner of the same neighborhood is at offset $(1, 1, 1)$. In Figure~\ref{fig:NeighborhoodIteratorFig2}, the offset from center is shown at the bottom of each neighborhood pixel. -\begin{itemize} - +\begin{itemize}% \index{NeighborhoodIterator!GetPixel()} \item \textbf{\code{PixelType GetPixel(const OffsetType \&o)}} Get the value of the pixel at the position offset \code{o} from the neighborhood center. -\index{NeighborhoodIterator!SetPixel()} -\item \textbf{\code{void SetPixel(const OffsetType \&o, PixelType p)}} Set -the value at the position offset \code{o} from the neighborhood center to +\item \textbf{\code{void SetPixel(const OffsetType \&o, PixelType p)}}\index{NeighborhoodIterator!SetPixel()} +Set the value at the position offset \code{o} from the neighborhood center to the value \code{p}. \end{itemize} The neighborhood iterators also provide a shorthand for setting and getting the -value at the center of the neighborhood. - -\index{NeighborhoodIterators!} -\begin{itemize} - -\index{NeighborhoodIterator!GetCenterPixel()} -\item \textbf{\code{PixelType GetCenterPixel()}} Gets the value at the center -of the neighborhood. - -\index{NeighborhoodIterator!SetCenterPixel()} -\item \textbf{\code{void SetCenterPixel(PixelType p)}} Sets the value at the -center of the neighborhood to the value \code{p} +value at the center of the neighborhood\index{NeighborhoodIterators!}. +\begin{itemize}% +\item \textbf{\code{PixelType GetCenterPixel()}}\index{NeighborhoodIterator!GetCenterPixel()} +Gets the value at the center of the neighborhood. +\item \textbf{\code{void SetCenterPixel(PixelType p)}}\index{NeighborhoodIterator!SetCenterPixel()} +Sets the value at the center of the neighborhood to the value \code{p} \end{itemize} There is another shorthand for setting and getting values for pixels that lie some integer distance from the neighborhood center along one of the image -axes. - -\index{NeighborhoodIterators!} -\begin{itemize} - -\index{NeighborhoodIterator!GetNext()} -\item \textbf{\code{PixelType GetNext(unsigned int d)}} Get the value -immediately adjacent to the neighborhood center in the positive direction along +axes\index{NeighborhoodIterators!}. +\begin{itemize}% +\item \textbf{\code{PixelType GetNext(unsigned int d)}}\index{NeighborhoodIterator!GetNext()} + Get the value immediately adjacent to the neighborhood center in the positive direction along the \code{d} axis. -\index{NeighborhoodIterator!SetNext()} -\item \textbf{\code{void SetNext(unsigned int d, PixelType p)}} Set the value -immediately adjacent to the neighborhood center in the positive direction along +\item \textbf{\code{void SetNext(unsigned int d, PixelType p)}}\index{NeighborhoodIterator!SetNext()} + Set the value immediately adjacent to the neighborhood center in the positive direction along the \code{d} axis to the value \code{p}. -\index{NeighborhoodIterator!GetPrevious()} -\item \textbf{\code{PixelType GetPrevious(unsigned int d)}} Get the value -immediately adjacent to the neighborhood center in the negative direction along +\item \textbf{\code{PixelType GetPrevious(unsigned int d)}}\index{NeighborhoodIterator!GetPrevious()} + Get the value immediately adjacent to the neighborhood center in the negative direction along the \code{d} axis. -\index{NeighborhoodIterator!SetPrevious()} -\item \textbf{\code{void SetPrevious(unsigned int d, PixelType p)}} +\item \textbf{\code{void SetPrevious(unsigned int d, PixelType p)}}\index{NeighborhoodIterator!SetPrevious()} Set the value immediately adjacent to the neighborhood center in the negative direction along the \code{d} axis to the value \code{p}. @@ -627,9 +585,8 @@ \section{Neighborhood Iterators} number of calculations in the neighborhood and would otherwise require multiple dereferences of the same pixels. -\begin{itemize} - -\index{NeighborhoodIterator!GetNeighborhood()} +\begin{itemize}% +\index{NeighborhoodIterator!GetNeighborhood()}% \index{NeighborhoodIterator!SetNeighborhood()} \item \textbf{\code{NeighborhoodType GetNeighborhood()}} Return a \doxygen{Neighborhood} of the same size and shape as the neighborhood @@ -642,14 +599,10 @@ \section{Neighborhood Iterators} \end{itemize} -Several methods are defined to provide information about the neighborhood. - -\index{NeighborhoodIterators!} -\begin{itemize} - -\index{NeighborhoodIterator!GetIndex()} -\item \textbf{\code{IndexType GetIndex()}} Return the image -index of the center pixel of the neighborhood iterator. +Several methods are defined to provide information about the neighborhood\index{NeighborhoodIterators!}. +\begin{itemize}% +\item \textbf{\code{IndexType GetIndex()}}\index{NeighborhoodIterator!GetIndex()} + Return the image index of the center pixel of the neighborhood iterator. \item \textbf{\code{IndexType GetIndex(OffsetType o)}} Return the image index of the pixel at offset \code{o} from the neighborhood @@ -658,22 +611,18 @@ \section{Neighborhood Iterators} \item \textbf{\code{IndexType GetIndex(unsigned int i)}} Return the image index of the pixel at array position \code{i}. -\index{NeighborhoodIterator!GetOffset()} -\item \textbf{\code{OffsetType GetOffset(unsigned int i)}} Return the offset -from the neighborhood center of the pixel at array position \code{i}. +\item \textbf{\code{OffsetType GetOffset(unsigned int i)}}\index{NeighborhoodIterator!GetOffset()} + Return the offset from the neighborhood center of the pixel at array position \code{i}. -\index{NeighborhoodIterator!GetNeighborhoodIndex()} -\item \textbf{\code{unsigned long GetNeighborhoodIndex(OffsetType o)}} +\item \textbf{\code{unsigned long GetNeighborhoodIndex(OffsetType o)}}\index{NeighborhoodIterator!GetNeighborhoodIndex()} Return the array position of the pixel at offset \code{o} from the neighborhood center. -\index{NeighborhoodIterator!GetSlice()} -\item \textbf{\code{std::slice GetSlice(unsigned int n)}} Return a -\code{std::slice} through the iterator neighborhood along axis \code{n}. - -\end{itemize} +\item \textbf{\code{std::slice GetSlice(unsigned int n)}}\index{NeighborhoodIterator!GetSlice()} + Return a \code{std::slice} through the iterator neighborhood along axis \code{n}. -\index{Neighborhood iterators!boundary conditions} +\end{itemize}% +\index{Neighborhood iterators!boundary conditions}% \index{Neighborhood iterators!bounds checking} A neighborhood-based calculation in a neighborhood close to an image boundary may require data that falls outside the boundary. The @@ -706,8 +655,7 @@ \section{Neighborhood Iterators} through clever definition of iteration regions. These techniques are explored in Section~\ref{sec:NeighborhoodExample3}. -\begin{itemize} - +\begin{itemize}% \index{NeighborhoodIterator!NeedToUseBoundaryConditionOn()} \item \textbf{\code{void NeedToUseBoundaryConditionOn()}} Explicitly turn bounds checking on. This method should be used with caution because @@ -715,27 +663,24 @@ \section{Neighborhood Iterators} decrease. In general you should allow the iterator to automatically determine this setting. -\index{NeighborhoodIterator!NeedToUseBoundaryConditionOff()} -\item \textbf{\code{void NeedToUseBoundaryConditionOff()}} Explicitly disable -bounds checking. This method should be used with caution because disabling +\item \textbf{\code{void NeedToUseBoundaryConditionOff()}}\index{NeighborhoodIterator!NeedToUseBoundaryConditionOff()} +Explicitly disable bounds checking. This method should be used with caution because disabling bounds checking when it is needed will result in out-of-bounds reads and undefined results. -\index{NeighborhoodIterator!OverrideBoundaryCondition()} -\item \textbf{\code{void OverrideBoundaryCondition(BoundaryConditionType *b)}} +\item \textbf{\code{void OverrideBoundaryCondition(BoundaryConditionType *b)}}\index{NeighborhoodIterator!OverrideBoundaryCondition()} Overrides the templated boundary condition, using boundary condition object \code{b} instead. Object \code{b} should not be deleted until it has been released by the iterator. This method can be used to change iterator behavior at run-time. -\index{NeighborhoodIterator!ResetBoundaryCondition()} -\item \textbf{\code{void ResetBoundaryCondition()}} Discontinues the use of any +\item \textbf{\code{void ResetBoundaryCondition()}}\index{NeighborhoodIterator!ResetBoundaryCondition()} + Discontinues the use of any run-time specified boundary condition and returns to using the condition specified in the template argument. -\index{NeighborhoodIterator!SetPixel()} -\item \textbf{\code{void SetPixel(unsigned int i, PixelType p, bool -status)}} Sets the value at neighborhood array position \code{i} to value +\item \textbf{\code{void SetPixel(unsigned int i, PixelType p, bool status)}}\index{NeighborhoodIterator!SetPixel()} + Sets the value at neighborhood array position \code{i} to value \code{p}. If the position \code{i} is out-of-bounds, \code{status} is set to \code{false}, otherwise \code{status} is set to \code{true}. \end{itemize} @@ -746,10 +691,9 @@ \section{Neighborhood Iterators} of the standard NeighborhoodIterator that supports an arbitrarily-shaped (non-rectilinear) neighborhood. -\subsection{NeighborhoodIterator} -\label{sec:itkNeighborhoodIterator} - -\index{NeighborhoodIterator!examples} +\subsection{NeighborhoodIterator}% +\label{sec:itkNeighborhoodIterator}% +\index{NeighborhoodIterator!examples}% \index{Neighborhood iterators!examples} The standard neighborhood iterator class in ITK is the \doxygen{NeighborhoodIterator}. Together with its \code{const} version, @@ -757,32 +701,30 @@ \subsection{NeighborhoodIterator} described above. This section provides several examples to illustrate the use of NeighborhoodIterator. -\index{edge detection} +\subsubsection{Basic neighborhood techniques: edge detection}% +\label{sec:NeighborhoodExample1}% +\index{edge detection}% \index{Sobel operator} -\subsubsection{Basic neighborhood techniques: edge detection} -\label{sec:NeighborhoodExample1} -\input{NeighborhoodIterators1.tex} - -\index{convolution filtering} +\input{NeighborhoodIterators1.tex}% +\index{convolution filtering}% \index{Sobel operator} -\subsubsection{Convolution filtering: Sobel operator} +\subsubsection{Convolution filtering: Sobel operator}% \label{sec:NeighborhoodExample2} \input{NeighborhoodIterators2.tex} -\subsubsection{Optimizing iteration speed} +\subsubsection{Optimizing iteration speed}% \label{sec:NeighborhoodExample3} -\input{NeighborhoodIterators3.tex} - +\input{NeighborhoodIterators3.tex}% \index{Gaussian blurring} -\subsubsection{Separable convolution: Gaussian filtering} +\subsubsection{Separable convolution: Gaussian filtering}% \label{sec:NeighborhoodExample4} \input{NeighborhoodIterators4.tex} -\subsubsection{Slicing the neighborhood} +\subsubsection{Slicing the neighborhood}% \label{sec:NeighborhoodExample5} \input{NeighborhoodIterators5.tex} -\subsubsection{Random access iteration} +\subsubsection{Random access iteration}% \label{sec:NeighborhoodExample6} \input{NeighborhoodIterators6.tex} @@ -796,10 +738,10 @@ \subsubsection{Random access iteration} % Example5: Slicing the neighborhood: gaussian filtering, separable convolution % Example6: Advanced Neighborhood Techniques: local minima, local maxima -\subsection{ShapedNeighborhoodIterator} -\label{sec:itkShapedNeighborhoodIterator} -\index{ShapedNeighborhoodIterator} -\index{Neighborhood iterators!shaped} +\subsection{ShapedNeighborhoodIterator}% +\label{sec:itkShapedNeighborhoodIterator}% +\index{ShapedNeighborhoodIterator}% +\index{Neighborhood iterators!shaped}% \index{Neighborhood iterators!as stencils} This section describes a variation on the neighborhood iterator called a \emph{shaped} neighborhood iterator. A shaped neighborhood is defined like @@ -812,37 +754,32 @@ \subsection{ShapedNeighborhoodIterator} \doxygen{NeighborhoodIterator}. A const version, \doxygen{ConstShapedNeighborhoodIterator}, is also available. -\index{Neighborhood iterators!active neighbors} -\index{Neighborhood iterators!inactive neighbors} + Like a regular neighborhood iterator, a shaped neighborhood iterator must be initialized with an ND radius object, but the radius of the neighborhood of a shaped iterator only defines the set of \emph{possible} neighbors. Any number -of possible neighbors can then be activated or deactivated. The shaped -neighborhood iterator defines an API for activating neighbors. When a neighbor +of possible neighbors can then be +activated\index{Neighborhood iterators!active neighbors} or deactivated\index{Neighborhood iterators!inactive neighbors}. +The shaped neighborhood iterator defines an API for activating neighbors. When a neighbor location, defined relative to the center of the neighborhood, is activated, it is placed on the \emph{active list} and is then part of the stencil. An iterator can be ``reshaped'' at any time by adding or removing offsets from the active list. \begin{itemize} - -\index{ShapedNeighborhoodIterator!ActivateOffset()} -\item \textbf{\code{void ActivateOffset(OffsetType \&o)}} Include the offset -\code{o} in the stencil of active neighborhood positions. Offsets are relative +\item \textbf{\code{void ActivateOffset(OffsetType \&o)}}\index{ShapedNeighborhoodIterator!ActivateOffset()} + Include the offset \code{o} in the stencil of active neighborhood positions. Offsets are relative to the neighborhood center. -\index{ShapedNeighborhoodIterator!DeactivateOffset()} -\item \textbf{\code{void DeactivateOffset(OffsetType \&o)}} Remove the offset -\code{o} from the stencil of active neighborhood positions. Offsets are +\item \textbf{\code{void DeactivateOffset(OffsetType \&o)}}\index{ShapedNeighborhoodIterator!DeactivateOffset()} + Remove the offset \code{o} from the stencil of active neighborhood positions. Offsets are relative to the neighborhood center. -\index{ShapedNeighborhoodIterator!ClearActiveList()} -\item \textbf{\code{void ClearActiveList()}} Deactivate all positions in the -iterator stencil by clearing the active list. +\item \textbf{\code{void ClearActiveList()}}\index{ShapedNeighborhoodIterator!ClearActiveList()} + Deactivate all positions in the iterator stencil by clearing the active list. -\index{ShapedNeighborhoodIterator!GetActiveIndexListSize()} -\item \textbf{\code{unsigned int GetActiveIndexListSize()}} Return the number -of pixel locations that are currently active in the shaped iterator stencil. +\item \textbf{\code{unsigned int GetActiveIndexListSize()}}\index{ShapedNeighborhoodIterator!GetActiveIndexListSize()} + Return the number of pixel locations that are currently active in the shaped iterator stencil. \end{itemize} @@ -857,35 +794,31 @@ \subsection{ShapedNeighborhoodIterator} defines \code{Get()} and \code{Set()} for reading and writing the values in the neighborhood. -\begin{itemize} +\begin{itemize}% \index{ShapedNeighborhoodIterator!Iterator::Begin()} \item \textbf{\code{ShapedNeighborhoodIterator::Iterator Begin()}} Return a const or non-const iterator through the shaped iterator stencil that points to the first valid location in the stencil. -\index{ShapedNeighborhoodIterator!Iterator::End()} -\item \textbf{\code{ShapedNeighborhoodIterator::Iterator End()}} Return a -const or non-const iterator through the shaped iterator stencil that points +\item \textbf{\code{ShapedNeighborhoodIterator::Iterator End()}}\index{ShapedNeighborhoodIterator!Iterator::End()} + Return a const or non-const iterator through the shaped iterator stencil that points \emph{one position past} the last valid location in the stencil. \end{itemize} The functionality and interface of the shaped neighborhood iterator is best described by example. We will use the ShapedNeighborhoodIterator to -implement some binary image morphology algorithms (see \cite{Gonzalez1993}, -\cite{Castleman1996}, et al.). The examples that follow implement erosion and +implement some binary image morphology algorithms (see~\cite{Gonzalez1993},~\cite{Castleman1996}, et al.). +The examples that follow implement erosion and dilation. +\subsubsection{Shaped neighborhoods: morphological operations}% +\label{sec:ShapedNeighborhoodExample}% \index{ShapedNeighborhoodIterator!examples of} -\subsubsection{Shaped neighborhoods: morphological operations} -\label{sec:ShapedNeighborhoodExample} \input{ShapedNeighborhoodIterators1.tex} -\input{ShapedNeighborhoodIterators2.tex} - +\input{ShapedNeighborhoodIterators2.tex}% %./Common/itkConstShapedNeighborhoodIterator.h %./Common/itkShapedNeighborhoodIterator.h - -\index{Iterators!neighborhood|)} - +\index{Iterators!neighborhood|)}% % ADD A SECTION WITH TIPS, SUGGESTIONS ON USING ITERATORS? EXTENDING ITERATORS? % USING ITERATORS FOR MULTITHREADING EXAMPLE? \index{Iterators!image|)} diff --git a/SoftwareGuide/Latex/Architecture/SpatialObjects.tex b/SoftwareGuide/Latex/Architecture/SpatialObjects.tex index 1e668382..61334911 100644 --- a/SoftwareGuide/Latex/Architecture/SpatialObjects.tex +++ b/SoftwareGuide/Latex/Architecture/SpatialObjects.tex @@ -1,11 +1,11 @@ -\chapter{Spatial Objects} +\chapter{Spatial Objects}% \label{sec:SpatialObjects} This chapter introduces the basic classes that describe \doxygen{SpatialObject}s. -\section{Introduction} +\section{Introduction}% \label{Introduction} We promote the philosophy that many of the goals of medical image processing @@ -74,42 +74,43 @@ \section{Hierarchy} The user is responsible for maintaining the tree structure, no checking is done to ensure a cycle-free tree. +\subsection{SpatialObjectHierarchy}% \label{sec:SpatialObjectHierarchy} \input{SpatialObjectHierarchy.tex} -\section{Transformations} +\section{Transformations}% \label{sec:SpatialObjectTransforms} \input{SpatialObjectTransforms.tex} -\section{Types of Spatial Objects} +\section{Types of Spatial Objects}% \label{sec:Principal Objects} This section describes in detail the variety of spatial objects implemented in ITK. -\subsection{ArrowSpatialObject} +\subsection{ArrowSpatialObject}% \label{sec:ArrowSpatialObject} \input{ArrowSpatialObject.tex} -\subsection{BlobSpatialObject} +\subsection{BlobSpatialObject}% \label{sec:BlobSpatialObject} \input{BlobSpatialObject.tex} -\subsection{EllipseSpatialObject} +\subsection{EllipseSpatialObject}% \label{sec:EllipseSpatialObject} \input{EllipseSpatialObject.tex} -\subsection{GaussianSpatialObject} +\subsection{GaussianSpatialObject}% \label{sec:GaussianSpatialObject} \input{GaussianSpatialObject.tex} -\subsection{GroupSpatialObject} +\subsection{GroupSpatialObject}% \label{sec:GroupSpatialObject} \input{GroupSpatialObject.tex} @@ -118,37 +119,38 @@ \subsection{GroupSpatialObject} \input{SceneSpatialObject.tex} -\subsection{ImageSpatialObject} +\subsection{ImageSpatialObject}% \label{sec:ImageSpatialObject} \input{ImageSpatialObject.tex} -\subsection{ImageMaskSpatialObject} +\subsection{ImageMaskSpatialObject}% \label{sec:ImageMaskSpatialObject} \input{ImageMaskSpatialObject.tex} -\subsection{LandmarkSpatialObject} +\subsection{LandmarkSpatialObject}% \label{sec:LandmarkSpatialObject} \input{LandmarkSpatialObject.tex} -\subsection{LineSpatialObject} +\subsection{LineSpatialObject}% \label{sec:LineSpatialObject} \input{LineSpatialObject.tex} -\subsection{MeshSpatialObject} +\subsection{MeshSpatialObject}% \label{sec:MeshSpatialObject} \input{MeshSpatialObject.tex} -\subsection{SurfaceSpatialObject} +\subsection{SurfaceSpatialObject}% \label{sec:SurfaceSpatialObject} \input{SurfaceSpatialObject.tex} -\subsection{TubeSpatialObject} +\subsection{TubeSpatialObject}% +\label{sec:TubeSpatialObject} \doxygen{TubeSpatialObject} is a class for the representation of tubular structures using SpatialObjects. In particular, it is intended @@ -158,20 +160,19 @@ \subsection{TubeSpatialObject} The class \doxygen{DTITubeSpatialObject} is derived from this class and adds constructs for representing fiber tracts from diffusion tensor images. -\label{sec:TubeSpatialObject} \input{TubeSpatialObject.tex} -\subsection{DTITubeSpatialObject} +\subsection{DTITubeSpatialObject}% \label{sec:DTITubeSpatialObject} \input{DTITubeSpatialObject.tex} -\section{Read/Write SpatialObjects} +\section{Read/Write SpatialObjects}% \label{sec:ReadWriteSpatialObjects} \input{ReadWriteSpatialObject.tex} -\section{Statistics Computation via SpatialObjects} +\section{Statistics Computation via SpatialObjects}% \label{sec:SpatialObjectToImageStatisticsCalculator} \input{SpatialObjectToImageStatisticsCalculator.tex} diff --git a/SoftwareGuide/Latex/Architecture/SystemOverview.tex b/SoftwareGuide/Latex/Architecture/SystemOverview.tex index 7e56b0e1..63918541 100644 --- a/SoftwareGuide/Latex/Architecture/SystemOverview.tex +++ b/SoftwareGuide/Latex/Architecture/SystemOverview.tex @@ -1,11 +1,11 @@ -\chapter{System Overview} +\chapter{System Overview}% \label{chapter:SystemOverview} The purpose of this chapter is to provide you with an overview of the \emph{Insight Toolkit} system. We recommend that you read this chapter to gain an appreciation for the breadth and area of application of ITK. -\section{System Organization} +\section{System Organization}% \label{sec:SystemOrganization} The Insight Toolkit consists of several subsystems. A brief @@ -22,7 +22,7 @@ \section{System Organization} \item[Numerics.] ITK uses VXL's VNL numerics libraries. These are easy-to-use C++ wrappers around the Netlib Fortran numerical - analysis routines \footnote{\url{https://www.netlib.org}}. + analysis routines\footnote{\url{https://www.netlib.org}}. \item[Data Representation and Access.] Two principal classes are used to represent data: the \doxygen{Image} and \doxygen{Mesh} @@ -86,27 +86,26 @@ \section{System Organization} \end{description} -\section{Essential System Concepts} +\section{Essential System Concepts}% \label{sec:EssentialSystemConcepts} This section describes some of the core concepts and implementation features found in ITK. -\subsection{Generic Programming} -\label{sec:GenericProgramming} - -\index{generic programming} +\subsection{Generic Programming}% +\label{sec:GenericProgramming}% +\index{generic programming}% \index{template} Generic programming is a method of organizing libraries consisting of -generic---or reusable---software components \cite{Musser1996}. The idea is to +generic---or reusable---software components~\cite{Musser1996}. The idea is to make software that is capable of ``plugging together'' in an efficient, adaptable manner. The essential ideas of generic programming are \emph{containers} to hold data, \emph{iterators} to access the data, and \emph{generic algorithms} that use containers and iterators to create efficient, fundamental algorithms such as sorting. Generic programming is implemented in C++ with the \emph{template} programming mechanism and the -use of the STL Standard Template Library \cite{Austern1999}. +use of the STL Standard Template Library~\cite{Austern1999}. C++ templating is a programming technique allowing users to write software in terms of one or more unknown types \code{T}. To create executable code, the @@ -130,7 +129,7 @@ \subsection{Generic Programming} simplest syntax errors. For those unfamiliar with templated code and generic programming, we recommend the two books cited above. -\subsection{Include Files and Class Definitions} +\subsection{Include Files and Class Definitions}% \label{sec:IncludeFiles} In ITK, classes are defined by a maximum of two files: a header file (\code{.h}) @@ -153,10 +152,9 @@ \subsection{Include Files and Class Definitions} possible values. \end{description} -\subsection{Object Factories} -\label{sec:ObjectFactories} - -\index{object factory} +\subsection{Object Factories}% +\label{sec:ObjectFactories}% +\index{object factory}% \index{factory} Most classes in ITK are instantiated through an \emph{object factory} @@ -198,9 +196,8 @@ \subsection{Object Factories} \code{itkNewMacro()} found in \code{Modules/Core/Common/include/itkMacro.h}. -\subsection{Smart Pointers and Memory Management} -\label{sec:SmartPointers} - +\subsection{Smart Pointers and Memory Management}% +\label{sec:SmartPointers}% \index{smart pointer} By their nature, object-oriented systems represent and operate on data through @@ -217,7 +214,7 @@ \subsection{Smart Pointers and Memory Management} releasing memory is known as memory management. In ITK, memory management is implemented through reference counting. This -compares to another popular approach---garbage collection---used +compares to another popular approach---garbage collection---used% \index{garbage collection} by many systems, including Java. In reference counting, a count of the number of references to each instance is kept. When the reference goes to zero, the @@ -276,10 +273,9 @@ \subsection{Smart Pointers and Memory Management} are preferred for multi-threaded sections of code. -\subsection{Error Handling and Exceptions} -\label{sec:ErrorHandling} - -\index{exceptions} +\subsection{Error Handling and Exceptions}% +\label{sec:ErrorHandling}% +\index{exceptions}% \index{error handling} In general, ITK uses exception handling to manage errors during program @@ -299,8 +295,8 @@ \subsection{Error Handling and Exceptions} \end{minted} \normalsize -A particular class may throw an exception as demonstrated below (this -code snippet is taken from \doxygen{ByteSwapper}: +A particular class may throw an exception as demonstrated below +(this code snippet is taken from \doxygen{ByteSwapper}): \small \begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{cpp} @@ -325,17 +321,16 @@ \subsection{Error Handling and Exceptions} can trap \emph{any} ITK exception by catching ExceptionObject. -\subsection{Event Handling} -\label{sec:EventHandling} - -\index{event handling} -\index{Command/Observer design pattern} -\index{itk::Command} -\index{ProgressEvent()} +\subsection{Event Handling}% +\label{sec:EventHandling}% +\index{event handling}% +\index{Command/Observer design pattern}% +\index{itk::Command}% +\index{ProgressEvent()}% \index{InvokeEvent()} Event handling in ITK is implemented using the Subject/Observer design -pattern \cite{Gamma1995} (sometimes referred to as the Command/Observer +pattern~\cite{Gamma1995} (sometimes referred to as the Command/Observer design pattern). In this approach, objects indicate that they are watching for a particular event---invoked by a particular instance---by registering with the instance that they are watching. For example, filters in ITK @@ -372,7 +367,7 @@ \subsection{Event Handling} \code{Command}. If nothing suitable is found, derivation is another possibility.) -\subsection{Multi-Threading} +\subsection{Multi-Threading}% \label{sec:MultiThreading} Multi-threading is handled in ITK through a high-level design @@ -494,10 +489,9 @@ \subsection{Multi-Threading} Invoking methods on the same instance in different threads is to be avoided. -\section{Numerics} -\label{sec:Numerics} - -\index{VNL} +\section{Numerics}% +\label{sec:Numerics}% +\index{VNL}% \index{numerics} ITK uses the VNL numerics library to provide resources for numerical @@ -535,8 +529,8 @@ \section{Numerics} functions either with or without user-supplied derivatives. \item[Standardized functions and constants.] Class \code{vnl\_math} - defines constants (pi, e, eps...) and simple functions (sqr, abs, - rnd...). Class \code{numeric\_limits} is from the ISO standard + defines constants (pi, e, eps\ldots) and simple functions (sqr, abs, + rnd\ldots). Class \code{numeric\_limits} is from the ISO standard document, and provides a way to access basic limits of a type. For example \code{numeric\_limits::max()} returns the maximum value of a short. @@ -559,9 +553,8 @@ \section{Numerics} primarily to support the deformable registration in ITK. -\section{Data Representation} -\label{sec:DataRepresentationAndAccess} - +\section{Data Representation}% +\label{sec:DataRepresentationAndAccess}% \index{data object} There are two principle types of data represented in ITK: images and @@ -570,9 +563,7 @@ \section{Data Representation} \doxygen{DataObject}. In ITK, data objects are classes that are meant to be passed around the system and may participate in data flow pipelines (see Section~\ref{sec:DataProcessingPipeline} on -page~\pageref{sec:DataProcessingPipeline} for more information). - - +page~\pageref{sec:DataProcessingPipeline} for more information).% \index{itk::Image} \doxygen{Image} represents an \emph{n}-dimensional, regular sampling of @@ -598,8 +589,7 @@ \section{Data Representation} \item \code{BufferedRegion}---the portion of the image retained in memory. \item \code{RequestedRegion}---the portion of the region requested by a filter or other class when operating on the image. -\end{enumerate} - +\end{enumerate}% \index{itk::Mesh} The \doxygen{Mesh} class represents an \emph{n}-dimensional, unstructured grid. The @@ -617,9 +607,9 @@ \section{Data Representation} neighborhood relationships, or to store information on the boundaries of cells. -The mesh is defined in terms of three template parameters: 1) a pixel type -associated with the points, cells, and cell boundaries; 2) the dimension of -the points (which in turn limits the maximum dimension of the cells); and 3) +The mesh is defined in terms of three template parameters: (1) a pixel type +associated with the points, cells, and cell boundaries; (2) the dimension of +the points (which in turn limits the maximum dimension of the cells); and (3) a ``mesh traits'' template parameter that specifies the types of the containers and identifiers used to access the points, cells, and/or boundaries. By using the mesh traits carefully, it is possible to create @@ -632,15 +622,13 @@ \section{Data Representation} landmarks, etc. The PointSet class has no associated topology. -\section{Data Processing Pipeline} -\label{sec:DataProcessingPipeline} - -\index{data processing pipeline} - -\index{process object} -\index{source} -\index{reader} -\index{filter} +\section{Data Processing Pipeline}% +\label{sec:DataProcessingPipeline}% +\index{data processing pipeline}% +\index{process object}% +\index{source}% +\index{reader}% +\index{filter}% \index{mapper} While data objects (e.g., images and meshes) are used to represent data, @@ -650,9 +638,7 @@ \section{Data Processing Pipeline} readers) produce data, filter objects take in data and process it to produce new data, and mappers accept data for output either to a file or some other system. Sometimes the term \emph{filter} is used broadly -to refer to all three types. - -\index{streaming} +to refer to all three types.\index{streaming} The data processing pipeline ties together data objects (e.g., images and meshes) and process objects. The pipeline supports an automatic updating @@ -694,8 +680,8 @@ \section{Data Processing Pipeline} filters to execute in order, culminating in writing the final data to a file on disk. -\section{Spatial Objects} -\label{sec:SpatialObjectsOverview} +\section{Spatial Objects}% +\label{sec:SpatialObjectsOverview}% \index{spatial object} The ITK spatial object framework supports the philosophy that the task of @@ -715,7 +701,7 @@ \section{Spatial Objects} The capabilities provided by the spatial objects framework supports their use in object segmentation, registration, surface/volume rendering, and other display and analysis functions. The spatial object framework extends the -concept of a ``scene graph'' \index{scene graph} that is common to computer +concept of a ``scene graph''\index{scene graph} that is common to computer rendering packages so as to support these new functions. With the spatial objects framework you can: \begin{enumerate} @@ -759,10 +745,9 @@ \section{Spatial Objects} data or to register two segmentations of a liver. -\section{Wrapping} -\label{sec:Wrapping} - -\index{wrapping} +\section{Wrapping}% +\label{sec:Wrapping}% +\index{wrapping}% \index{Python} While the core of ITK is implemented in C++, Python bindings can be @@ -788,7 +773,7 @@ \section{Wrapping} To learn more about the wrapping process, please see the section on module wrapping, Section~\ref{sec:ModuleWrapping}. The wrapping process is orchestrated by a number of CMake macros found in the \code{Wrapping} directory. The result of -the wrapping process is a set of shared libraries (.so in Linux or .dlls on +the wrapping process is a set of shared libraries (\code{.so} in Linux or \code{.dlls} on Windows) that can be used by interpreted languages. There is almost a direct translation from C++, with the differences being the @@ -974,7 +959,7 @@ \subsubsection{Build Python Packages from Source} On Windows, it is also necessary to add the ITK build directory containing the .dll files to your \code{PATH} environmental variable if ITK is built with the CMake option \code{BUILD\_SHARED\_LIBS} enabled. For example, the directory -containing .dll files for an ITK build at +containing \code{.dll} files for an ITK build at \code{C:\textbackslash{}ITK-build} when built with Visual Studio in the \code{Release} configuration is \code{C:\textbackslash{}ITK-build\textbackslash{}bin\textbackslash{}Release}. diff --git a/SoftwareGuide/Latex/CellularAggregates.tex b/SoftwareGuide/Latex/CellularAggregates.tex index 259118f9..a8a9bd27 100644 --- a/SoftwareGuide/Latex/CellularAggregates.tex +++ b/SoftwareGuide/Latex/CellularAggregates.tex @@ -47,10 +47,10 @@ \section{Gene Network Modeling} expression \begin{equation} -\frac{\partial{G}}{\partial t} = \left[ ABCDE + A\over{B} \right] +\frac{\partial{G}}{\partial t} = \left[ ABCDE + A\overline{B} \right] \end{equation} -Where the $\over{B}$ represents the repressors and the normal letters represents +Where the $\overline{B}$ represents the repressors and the normal letters represents the enhancers. It is known from boolean algebra that any boolean polynomial can be expressed as a sum of products composed by the polynomial terms and their negations. diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/AnisotropicDiffusionFiltering.tex b/SoftwareGuide/Latex/DesignAndFunctionality/AnisotropicDiffusionFiltering.tex index f6d7126b..3a78b904 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/AnisotropicDiffusionFiltering.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/AnisotropicDiffusionFiltering.tex @@ -12,10 +12,10 @@ fine structure of the image and thereby changes subtle aspects of the anatomical shapes in question. -Perona and Malik \cite{Perona1990} introduced an alternative to +Perona and Malik~\cite{Perona1990} introduced an alternative to linear-filtering that they called \emph{anisotropic diffusion}. Anisotropic -diffusion is closely related to the earlier work of Grossberg -\cite{Grossberg1984}, who used similar nonlinear diffusion processes to model +diffusion is closely related to the earlier work of Grossberg~\cite{Grossberg1984}, +who used similar nonlinear diffusion processes to model human vision. The motivation for anisotropic diffusion (also called \emph{nonuniform} or \emph{variable conductance} diffusion) is that a Gaussian smoothed image is a single time slice of the solution to the heat equation, @@ -36,13 +36,12 @@ conductance at areas of large $|\nabla g|$, and can be any one of a number of functions. The literature has shown \begin{equation} c(|\nabla g|) = e^{-\frac{|\nabla g|^{2}}{2k^{2}}} \end{equation} to be quite effective. -Notice that conductance term introduces a free parameter $k$, the {\em -conductance parameter}, that controls the sensitivity of the process to edge +Notice that conductance term introduces a free parameter $k$, the \emph{conductance parameter}, that controls the sensitivity of the process to edge contrast. Thus, anisotropic diffusion entails two free parameters: the conductance parameter, $k$, and the time parameter, $t$, that is analogous to $\sigma$, the effective width of the filter when using Gaussian kernels. -Equation \ref{eq:aniso} is a nonlinear partial differential equation that can +Equation~\ref{eq:aniso} is a nonlinear partial differential equation that can be solved on a discrete grid using finite forward differences. Thus, the smoothed image is obtained only by an iterative process, not a convolution or non-stationary, linear filter. Typically, the number of iterations required @@ -51,10 +50,9 @@ purpose, single-processor computers. The technique applies readily and effectively to 3D images, but requires more processing time. -In the early 1990's several research groups \cite{Gerig1991,Whitaker1993d} +In the early 1990's several research groups~\cite{Gerig1991,Whitaker1993d} demonstrated the effectiveness of anisotropic diffusion on medical images. In -a series of papers on the subject -\cite{Whitaker1993,Whitaker1993b,Whitaker1993c,Whitaker1993d,Whitaker-thesis,Whitaker1994}, +a series of papers on the subject~\cite{Whitaker1993,Whitaker1993b,Whitaker1993c,Whitaker1993d,Whitaker-thesis,Whitaker1994}, Whitaker described a detailed analytical and empirical analysis, introduced a smoothing term in the conductance that made the process more robust, invented a numerical scheme that virtually eliminated directional artifacts in the @@ -63,9 +61,8 @@ data (such as the color cryosection data of the Visible Human Project). For a vector-valued input $\vec{F}:U \mapsto \Re^{m}$ the process takes the -form \begin{equation} \vec{F}_{t} = \nabla \cdot c({\cal D}\vec{F}) \vec{F}, -\label{eq:vector_diff} \end{equation} where ${\cal D}\vec{F}$ is a {\em -dissimilarity} measure of $\vec{F}$, a generalization of the gradient magnitude +form \begin{equation} \vec{F}_{t} = \nabla \cdot c(\mathcal{D}\vec{F}) \vec{F}, +\label{eq:vector_diff} \end{equation} where $\mathcal{D}\vec{F}$ is a \emph{dissimilarity} measure of $\vec{F}$, a generalization of the gradient magnitude to vector-valued images, that can incorporate linear and nonlinear coordinate transformations on the range of $\vec{F}$. In this way, the smoothing of the multiple images associated with vector-valued data is coupled through the @@ -80,19 +77,18 @@ separately, but linked through the conductance term. Vector-valued diffusion is also useful for processing registered data from different devices or for denoising higher-order geometric or statistical features from scalar-valued -images \cite{Whitaker1994,Yoo1993}. +images~\cite{Whitaker1994,Yoo1993}. The output of anisotropic diffusion is an image or set of images that demonstrates reduced noise and texture but preserves, and can also enhance, edges. Such images are useful for a variety of processes including statistical classification, visualization, and geometric feature extraction. -Previous work has shown \cite{Whitaker-thesis} that anisotropic diffusion, over +Previous work has shown~\cite{Whitaker-thesis} that anisotropic diffusion, over a wide range of conductance parameters, offers quantifiable advantages over linear filtering for edge detection in medical images. Since the effectiveness of nonlinear diffusion was first demonstrated, numerous -variations of this approach have surfaced in the literature \cite{Romeny1994}. -These include alternatives for constructing dissimilarity measures -\cite{Sapiro1996}, directional (i.e., tensor-valued) conductance terms -\cite{Weickert1996,Alvarez1994} and level set interpretations -\cite{Whitaker2001}. +variations of this approach have surfaced in the literature~\cite{Romeny1994}. +These include alternatives for constructing dissimilarity measures~\cite{Sapiro1996}, +directional (i.e., tensor-valued) conductance terms~\cite{Weickert1996,Alvarez1994} +and level set interpretations~\cite{Whitaker2001}. diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/ConfidenceConnectedOnBrainWeb.tex b/SoftwareGuide/Latex/DesignAndFunctionality/ConfidenceConnectedOnBrainWeb.tex index 7ce88d22..cc20e003 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/ConfidenceConnectedOnBrainWeb.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/ConfidenceConnectedOnBrainWeb.tex @@ -1,23 +1,23 @@ \subsubsection{Application of the Confidence Connected filter on the Brain Web Data} -This section shows some results obtained by applying the Confidence Connected filter on the BrainWeb database. The filter was applied on a 181 $\times$ 217 $\times$ 181 crosssection of the {\it brainweb165a10f17} dataset. The data is a MR T1 acquisition, with an intensity non-uniformity of 20\% and a slice thickness 1mm. The dataset may be obtained from +This section shows some results obtained by applying the Confidence Connected filter on the BrainWeb database. The filter was applied on a 181 $\times$ 217 $\times$ 181 crosssection of the \textit{brainweb165a10f17} dataset. The data is a MR T1 acquisition, with an intensity non-uniformity of 20\% and a slice thickness 1mm. The dataset may be obtained from \code{https://www.bic.mni.mcgill.ca/brainweb/} or \code{https://data.kitware.com/\#folder/5882712d8d777f4f3f3072df} The previous code was used in this example replacing the image dimension by 3. Gradient Anistropic diffusion was applied to smooth the image. The filter used 2 iterations, a time step of 0.05 and a conductance value of 3. The smoothed volume was then segmented using the Confidence Connected approach. Five seed points were used at coordinate locations (118,85,92), (63,87,94), (63,157,90), (111,188,90), (111,50,88). The ConfidenceConnnected filter used the parameters, a neighborhood radius of 2, 5 iterations and an $f$ of 2.5 (the same as in the previous example). The results were then rendered using VolView. -Figure \ref{fig:3DregionGrowingScreenshot1} shows the rendered volume. Figure \ref{fig:SlicesBrainWeb} shows an axial, sagittal and a coronal slice of the volume. +Figure~\ref{fig:3DregionGrowingScreenshot1} shows the rendered volume. Figure~\ref{fig:SlicesBrainWeb} shows an axial, sagittal and a coronal slice of the volume. \begin{figure} \centering \includegraphics[width=0.6\textwidth]{3DregionGrowingScreenshot1.eps} -\itkcaption[Whitematter Confidence Connected segmentation.]{White matter segmented using Confidence Connected region growing.} +\itkcaption[Whitematter Confidence Connected segmentation.]{White matter segmented using Confidence Connected region growing.}% \label{fig:3DregionGrowingScreenshot1} \end{figure} \begin{figure} \centering \includegraphics[width=\textwidth]{SlicesBrainWebConfidenceConnected.eps} -\itkcaption[Axial, sagittal, and coronal slice of Confidence Connected segmentation.]{Axial, sagittal and coronal slice segmented using Confidence Connected region growing.} +\itkcaption[Axial, sagittal, and coronal slice of Confidence Connected segmentation.]{Axial, sagittal and coronal slice segmented using Confidence Connected region growing.}% \label{fig:SlicesBrainWeb} \end{figure} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration.tex b/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration.tex index 99355714..08a7593d 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration.tex @@ -10,7 +10,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{FEM-Based Image Registration} +\subsection{FEM-Based Image Registration}% \label{sec:FEMBasedImageRegistration} \begin{figure} @@ -18,13 +18,13 @@ \subsection{FEM-Based Image Registration} \includegraphics[width=0.44\textwidth]{DeformableRegistration1CheckerboardBefore.eps} \includegraphics[width=0.44\textwidth]{DeformableRegistration1CheckerboardAfter.eps} \itkcaption[FEM-based deformable registration results]{Checkerboard comparisons -before and after FEM-based deformable registration.} +before and after FEM-based deformable registration.}% \label{fig:DeformableRegistration1Output} \end{figure} \input{DeformableRegistration1.tex} -Figure \ref{fig:DeformableRegistration1Output} presents the results of +Figure~\ref{fig:DeformableRegistration1Output} presents the results of the FEM-based deformable registration applied to two time-separated slices of a living rat dataset. Checkerboard comparisons of the two images are shown before registration (left) and after registration @@ -46,31 +46,31 @@ \subsection{FEM-Based Image Registration} \verbatiminput{FiniteElementRegistrationParameters1.txt} \normalsize -\subsection{BSplines Image Registration} +\subsection{BSplines Image Registration}% \label{sec:BSplinesImageRegistration} \input{DeformableRegistration4.tex} -\subsection{Level Set Motion for Deformable Registration} +\subsection{Level Set Motion for Deformable Registration}% \label{sec:LevelSetMotionForDeformableRegistration} \input{DeformableRegistration5.tex} -\subsection{BSplines Multi-Grid Image Registration} +\subsection{BSplines Multi-Grid Image Registration}% \label{sec:BSplinesMultiGridImageRegistration} \input{DeformableRegistration6.tex} -\subsection{BSplines Multi-Grid Image Registration in 3D} +\subsection{BSplines Multi-Grid Image Registration in 3D}% \label{sec:BSplinesMultiGridImageRegistrationIn3D} \input{DeformableRegistration7.tex} -\subsection{Image Warping with Kernel Splines} +\subsection{Image Warping with Kernel Splines}% \label{sec:ImageWarpingWithKernelSplines} \input{LandmarkWarping2.tex} -\subsection{Image Warping with BSplines} +\subsection{Image Warping with BSplines}% \label{sec:ImageWarpingWithBSplines} \input{BSplineWarping1.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration4OnBrain.tex b/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration4OnBrain.tex index 41fa80cd..cfd6e697 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration4OnBrain.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/DeformableRegistration4OnBrain.tex @@ -14,18 +14,19 @@ \code{ImageDimension} by 3. The registration method uses B-splines and an LBFGS optimizer. The trace in -Table. \ref{tab:LBFGStrace} prints the trace of the optimizer through the +Table~\ref{tab:LBFGStrace} prints the trace of the optimizer through the search space. \begin{table} \begin{center} -\begin{tabular}{ | p{3cm} | p{1.8cm} | p{2.5cm} | p{4cm} | } -\hline +\begin{tabular}{p{3cm} p{1.8cm} p{2.5cm} p{4cm}} +\toprule \textbf{Iteration} & \textbf{Function value} & \textbf{$\|G\|$} & \textbf{Step length} \\ -\hline\hline +\midrule +\midrule 1 & 156.981 & 14.911 & 0.202 \\ 2 & 68.956 & 11.774 & 1.500 \\ 3 & 38.146 & 4.802 & 1.500 \\ @@ -34,27 +35,27 @@ 6 & 21.454 & 1.032 & 1.500\\ 7 & 20.322 & 1.557 & 1.500\\ 8 & 19.751 & 0.594 & 1.500\\ -\hline +\bottomrule \end{tabular} \end{center} -\itkcaption[LBFGS Optimizer trace]{LBFGS Optimizer trace. +\itkcaption[LBFGS Optimizer trace]{LBFGS Optimizer trace.% \label{tab:LBFGStrace}} \end{table} Here $\|G\|$ is the norm of the gradient at the current estimate of the -minimum, $x$. ``Function Value" is the current value of the function, f(x). +minimum, $x$. \enquote{Function Value} is the current value of the function, f(x). The resulting deformation field that maps the moving to the fixed image is -shown in \ref{fig:DeformationFieldOutput}. A difference image of two slices -before and after registration is shown in -\ref{fig:DefRegistrationDiffScreenshot}. As can be seen from the figures, the +shown in~\ref{fig:DeformationFieldOutput}. A difference image of two slices +before and after registration is shown in~\ref{fig:DefRegistrationDiffScreenshot}. +As can be seen from the figures, the deformation field is in close agreement to the one generated from the Thin plate spline warping. \begin{figure} \centering \includegraphics[width=0.6\textwidth]{ParaviewScreenshot5.eps} -\itkcaption[Deformation field output]{Resulting deformation field that maps the moving image to the fixed image.} +\itkcaption[Deformation field output]{Resulting deformation field that maps the moving image to the fixed image.}% \label{fig:DeformationFieldOutput} \end{figure} @@ -62,6 +63,6 @@ \centering \includegraphics[width=0.44\textwidth]{DeformableRegistration4DiffBefore.eps} \includegraphics[width=0.44\textwidth]{DeformableRegistration4DiffAfter.eps} -\itkcaption[Difference image]{Difference image from a slice before and after registration.} +\itkcaption[Difference image]{Difference image from a slice before and after registration.}% \label{fig:DefRegistrationDiffScreenshot} \end{figure} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/DemonsRegistration.tex b/SoftwareGuide/Latex/DesignAndFunctionality/DemonsRegistration.tex index 6da66cdd..094ac9e8 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/DemonsRegistration.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/DemonsRegistration.tex @@ -10,29 +10,28 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% For the problem of intra-modality deformable registration, the Insight -Toolkit provides an implementation of Thirion's ``demons'' algorithm -\cite{Thirion1995b,Thirion1998}. +Toolkit provides an implementation of Thirion's ``demons'' algorithm~\cite{Thirion1995b,Thirion1998}. In this implementation, each image is viewed as a set of iso-intensity contours. The main idea is that a regular grid of forces deform an image by pushing the contours in the normal direction. The orientation and magnitude of the displacement is derived from the instantaneous optical flow equation: \begin{equation} -\bf{D}(\bf{X}) \cdot \nabla f(\bf{X}) = - \left(m(\bf{X}) - f(\bf{X}) \right) +\textbf{D}(\textbf{X}) \cdot \nabla f(\textbf{X}) = - \left(m(\textbf{X}) - f(\textbf{X}) \right) \label{eqn:OpticalFlow} \end{equation} -In the above equation, $f(\bf{X})$ is the fixed image, $m(\bf{X})$ -is the moving image to be registered, and $\bf{D}(\bf{X})$ is the displacement +In the above equation, $f(\textbf{X})$ is the fixed image, $m(\textbf{X})$ +is the moving image to be registered, and $\textbf{D}(\textbf{X})$ is the displacement or optical flow between the images. It is well known in optical flow -literature that Equation \ref{eqn:OpticalFlow} is insufficient to specify -$\bf{D}(\bf{X})$ locally and is usually determined using some form of +literature that Equation~\ref{eqn:OpticalFlow} is insufficient to specify +$\textbf{D}(\textbf{X})$ locally and is usually determined using some form of regularization. For registration, the projection of the vector on the direction of the intensity gradient is used: \begin{equation} -\bf{D}(\bf{X}) = - \frac -{\left( m(\bf{X}) - f(\bf{X}) \right) \nabla f(\bf{X})} +\textbf{D}(\textbf{X}) = - \frac +{\left( m(\textbf{X}) - f(\textbf{X}) \right) \nabla f(\textbf{X})} {\left\| \nabla f \right\|^2 } \end{equation} @@ -41,9 +40,9 @@ re-normalizes the equation such that: \begin{equation} -\bf{D}(\bf{X}) = - \frac -{\left( m(\bf{X}) - f(\bf{X}) \right) \nabla f(\bf{X})} -{\left\| \nabla f \right\|^2 + \left( m(\bf{X}) - f(\bf{X}) \right)^2 / K } +\textbf{D}(\textbf{X}) = - \frac +{\left( m(\textbf{X}) - f(\textbf{X}) \right) \nabla f(\textbf{X})} +{\left\| \nabla f \right\|^2 + \left( m(\textbf{X}) - f(\textbf{X}) \right)^2 / K }% \label{eqn:DemonsDisplacement} \end{equation} @@ -52,26 +51,25 @@ value of the pixel spacings. The inclusion of $K$ ensures the force computation is invariant to the pixel scaling of the images. -Starting with an initial deformation field $\bf{D}^{0}(\bf{X})$, the demons -algorithm iteratively updates the field using Equation -\ref{eqn:DemonsDisplacement} such that the field at the $N$-th iteration is -given by: +Starting with an initial deformation field $\textbf{D}^{0}(\textbf{X})$, the demons +algorithm iteratively updates the field using Equation~\ref{eqn:DemonsDisplacement} such +that the field at the $N$-th iteration is given by: \begin{equation} -\bf{D}^{N}(\bf{X}) = \bf{D}^{N-1}(\bf{X}) - \frac -{\left( m(\bf{X}+ \bf{D}^{N-1}(\bf{X})) -- f(\bf{X}) \right) \nabla f(\bf{X})} +\textbf{D}^{N}(\textbf{X}) = \textbf{D}^{N-1}(\textbf{X}) - \frac +{\left( m(\textbf{X}+ \textbf{D}^{N-1}(\textbf{X})) +- f(\textbf{X}) \right) \nabla f(\textbf{X})} {\left\| \nabla f \right\|^2 + \left( -m(\bf{X}+ \bf{D}^{N-1}(\bf{X}) ) - - f(\bf{X}) \right)^2 } +m(\textbf{X}+ \textbf{D}^{N-1}(\textbf{X}) ) + - f(\textbf{X}) \right)^2 }% \label{eqn:DemonsUpdateEquation} \end{equation} Reconstruction of the deformation field is an ill-posed problem where matching the fixed and moving images has many solutions. For example, since each image pixel is free to move independently, it is possible that all -pixels of one particular value in $m(\bf{X})$ could map to a single image -pixel in $f(\bf{X})$ of the same value. The resulting deformation field may +pixels of one particular value in $m(\textbf{X})$ could map to a single image +pixel in $f(\textbf{X})$ of the same value. The resulting deformation field may be unrealistic for real-world applications. An option to solve for the field uniquely is to enforce an elastic-like behavior, smoothing the deformation field with a Gaussian filter between iterations. @@ -79,7 +77,7 @@ In ITK, the demons algorithm is implemented as part of the finite difference solver (FDS) framework and its use is demonstrated in the following example. -\subsection{Asymmetrical Demons Deformable Registration} +\subsection{Asymmetrical Demons Deformable Registration}% \label{sec:AsymmetricalDemonsDeformableRegistration} \input{DeformableRegistration2.tex} @@ -89,15 +87,15 @@ \subsection{Asymmetrical Demons Deformable Registration} used in this case is \begin{equation} -\bf{D}(\bf{X}) = - \frac -{2 \left( m(\bf{X}) - f(\bf{X}) \right) \left( \nabla f(\bf{X}) + \nabla g(\bf{X}) \right) } -{\left\| \nabla f + \nabla g \right\|^2 + \left( m(\bf{X}) - f(\bf{X}) \right)^2 / K } +\textbf{D}(\textbf{X}) = - \frac +{2 \left( m(\textbf{X}) - f(\textbf{X}) \right) \left( \nabla f(\textbf{X}) + \nabla g(\textbf{X}) \right) } +{\left\| \nabla f + \nabla g \right\|^2 + \left( m(\textbf{X}) - f(\textbf{X}) \right)^2 / K }% \label{eqn:DemonsDisplacement2} \end{equation} The following example illustrates the use of this deformable registration method. -\subsection{Symmetrical Demons Deformable Registration} +\subsection{Symmetrical Demons Deformable Registration}% \label{sec:SymmetricalDemonsDeformableRegistration} \input{DeformableRegistration3.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/FeatureExtractionMethods.tex b/SoftwareGuide/Latex/DesignAndFunctionality/FeatureExtractionMethods.tex index 76fc06eb..e6c648ef 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/FeatureExtractionMethods.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/FeatureExtractionMethods.tex @@ -17,7 +17,7 @@ extraction methods available in ITK. -\subsection{Hough Transform} +\subsection{Hough Transform}% \label{sec:HoughtTransform} The Hough transform is a widely used technique for detection of geometrical @@ -26,11 +26,11 @@ \subsection{Hough Transform} present in the image. The transformation is specific for each desired geometrical shape. -\subsubsection{Line Extraction} +\subsubsection{Line Extraction}% \label{sec:HoughtLineExtraction} \input{HoughTransform2DLinesImageFilter.tex} -\subsubsection{Circle Extraction} +\subsubsection{Circle Extraction}% \label{sec:HoughtCircleExtraction} \input{HoughTransform2DCirclesImageFilter.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/Filtering.tex b/SoftwareGuide/Latex/DesignAndFunctionality/Filtering.tex index f5dfc5d2..465e7803 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/Filtering.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/Filtering.tex @@ -8,7 +8,7 @@ \chapter{Filtering} in Book 1 for more information.) -\section{Thresholding} +\section{Thresholding}% \label{sec:ThresholdingFiltering} The thresholding operation is used to change or identify pixel values based @@ -16,12 +16,12 @@ \section{Thresholding} following sections describe how to perform thresholding operations using ITK. -\subsection{Binary Thresholding} +\subsection{Binary Thresholding}% \label{sec:BinaryThresholdingImageFilter} \input{BinaryThresholdImageFilter.tex} -\subsection{General Thresholding} +\subsection{General Thresholding}% \label{sec:ThresholdingImageFilter} \input{ThresholdImageFilter.tex} @@ -32,20 +32,20 @@ \subsection{Canny Edge Detection} \input{CannyEdgeDetectionImageFilter.tex} -\section{Casting and Intensity Mapping} +\section{Casting and Intensity Mapping}% \label{sec:CastingImageFilters} The filters discussed in this section perform pixel-wise intensity mappings. Casting is used to convert one pixel type to another, while intensity mappings also take into account the different intensity ranges of the pixel types. -\subsection{Linear Mappings} +\subsection{Linear Mappings}% \label{sec:IntensityLinearMapping} \input{CastingImageFilters.tex} -\subsection{Non Linear Mappings} +\subsection{Non Linear Mappings}% \label{sec:IntensityNonLinearMapping} The following filter can be seen as a variant of the casting filters. Its main @@ -55,7 +55,7 @@ \subsection{Non Linear Mappings} \input{SigmoidImageFilter.tex} -\section{Gradients} +\section{Gradients}% \label{sec:GradientFiltering} Computation of gradients is a fairly common operation in image processing. The @@ -65,31 +65,31 @@ \section{Gradients} appropriate. ITK provides filters for computing both the image of gradient vectors and the image of magnitudes. -\subsection{Gradient Magnitude} +\subsection{Gradient Magnitude}% \label{sec:GradientMagnitudeImageFilter} \input{GradientMagnitudeImageFilter.tex} -\subsection{Gradient Magnitude With Smoothing} +\subsection{Gradient Magnitude With Smoothing}% \label{sec:GradientMagnitudeRecursiveGaussianImageFilter} \input{GradientMagnitudeRecursiveGaussianImageFilter.tex} -\subsection{Derivative Without Smoothing} +\subsection{Derivative Without Smoothing}% \label{sec:DerivativeImageFilter} \input{DerivativeImageFilter.tex} -\section{Second Order Derivatives} +\section{Second Order Derivatives}% \label{sec:SecondOrderDerivatives} -\subsection{Second Order Recursive Gaussian} +\subsection{Second Order Recursive Gaussian}% \label{sec:SecondDerivativeRecursiveGaussian} \input{SecondDerivativeRecursiveGaussianImageFilter.tex} -\subsection{Laplacian Filters} +\subsection{Laplacian Filters}% \label{sec:LaplacianFilters} \subsubsection{Laplacian Filter Recursive Gaussian} @@ -98,7 +98,7 @@ \subsubsection{Laplacian Filter Recursive Gaussian} \input{LaplacianRecursiveGaussianImageFilter2.tex} -\section{Neighborhood Filters} +\section{Neighborhood Filters}% \label{sec:NeighborhoodFilters} The concept of locality is frequently encountered in image processing in the @@ -118,37 +118,37 @@ \section{Neighborhood Filters} advantage of this construction. (See the Iterators chapter in Book 1 for more information.) -\subsection{Mean Filter} +\subsection{Mean Filter}% \label{sec:MeanFilter} \input{MeanImageFilter.tex} -\subsection{Median Filter} +\subsection{Median Filter}% \label{sec:MedianFilter} \input{MedianImageFilter.tex} -\subsection{Mathematical Morphology} +\subsection{Mathematical Morphology}% \label{sec:MathematicalMorphology} Mathematical morphology has proved to be a powerful resource for image -processing and analysis \cite{Serra1982}. ITK implements mathematical +processing and analysis~\cite{Serra1982}. ITK implements mathematical morphology filters using NeighborhoodIterators and \doxygen{NeighborhoodOperator}s. The toolkit contains two types of image morphology algorithms: filters that operate on binary images and filters that operate on grayscale images. -\subsubsection{Binary Filters} +\subsubsection{Binary Filters}% \label{sec:MathematicalMorphologyBinaryFilters} \input{MathematicalMorphologyBinaryFilters.tex} -\subsubsection{Grayscale Filters} +\subsubsection{Grayscale Filters}% \label{sec:MathematicalMorphologyGrayscaleFilters} \input{MathematicalMorphologyGrayscaleFilters.tex} -\subsection{Voting Filters} +\subsection{Voting Filters}% \label{sec:VotingFilters} Voting filters are quite a generic family of filters. In fact, both the Dilate @@ -174,15 +174,16 @@ \subsubsection{Binary Median Filter} The typical effect of median filtration on a noisy digital image is a dramatic reduction in impulse noise spikes. The filter also tends to preserve brightness differences across signal steps, resulting in reduced blurring of regional boundaries. The filter also tends to preserve the positions of boundaries in an image. -Figure \ref{fig:BinaryMedianImageFilterOutputMultipleIterations} below shows the effect of running the median filter with a 3x3 classical window size +Figure~\ref{fig:BinaryMedianImageFilterOutputMultipleIterations} below shows the effect of running the median filter +with a 3$times$3 classical window size 1, 10 and 50 times. There is a tradeoff in noise reduction and the sharpness of the image when the window size is increased\begin{figure} \center \includegraphics[width=0.44\textwidth]{BinaryMedianImageFilterOutput1.eps} \includegraphics[width=0.44\textwidth]{BinaryMedianImageFilterOutput10.eps} \includegraphics[width=0.44\textwidth]{BinaryMedianImageFilterOutput50.eps} \itkcaption[Effect of many iterations on the BinaryMedian filter.]{Effect of 1, 10 and 50 iterations of the - BinaryMedianImageFilter using a 3x3 window.} - \label{fig:BinaryMedianImageFilterOutputMultipleIterations} + BinaryMedianImageFilter using a 3$\times$3 window.}% +\label{fig:BinaryMedianImageFilterOutputMultipleIterations} \end{figure}. @@ -207,7 +208,7 @@ \subsubsection{Iterative Hole Filling Filter} \input{VotingBinaryIterativeHoleFillingImageFilter.tex} -\section{Smoothing Filters} +\section{Smoothing Filters}% \label{sec:SmoothingFilters} Real image data has a level of uncertainty which is manifested in the @@ -216,7 +217,7 @@ \section{Smoothing Filters} data. This section describes several methods that can be applied to reduce noise on images. -\subsection{Blurring} +\subsection{Blurring}% \label{sec:BlurringFilters} Blurring is the traditional approach for removing noise from images. It is @@ -226,70 +227,69 @@ \subsection{Blurring} of the most commonly used kernels is the Gaussian. Two implementations of Gaussian smoothing are available in the toolkit. The first one is based on a traditional convolution while the other is based on the application of IIR -filters that approximate the convolution with a Gaussian -\cite{Deriche1990,Deriche1993}. +filters that approximate the convolution with a Gaussian~\cite{Deriche1990,Deriche1993}. -\subsubsection{Discrete Gaussian} +\subsubsection{Discrete Gaussian}% \label{sec:DiscreteGaussianImageFilter} \input{DiscreteGaussianImageFilter.tex} -\subsubsection{Binomial Blurring} +\subsubsection{Binomial Blurring}% \label{sec:BinomialBlurImageFilter} \input{BinomialBlurImageFilter.tex} -\subsubsection{Recursive Gaussian IIR} +\subsubsection{Recursive Gaussian IIR}% \label{sec:RecursiveGaussianImageFilter} \input{SmoothingRecursiveGaussianImageFilter.tex} -\subsection{Local Blurring} +\subsection{Local Blurring}% \label{sec:BlurringFunctions} In some cases it is desirable to compute smoothing in restricted regions of the image, or to do it using different parameters that are computed locally. The following sections describe options for applying local smoothing in images. -\subsubsection{Gaussian Blur Image Function} +\subsubsection{Gaussian Blur Image Function}% \label{sec:GaussianBlurImageFunction} \input{GaussianBlurImageFunction.tex} -\subsection{Edge Preserving Smoothing} +\subsection{Edge Preserving Smoothing}% \label{sec:EdgePreservingSmoothingFilters} -\subsubsection{Introduction to Anisotropic Diffusion} +\subsubsection{Introduction to Anisotropic Diffusion}% \label{sec:IntroductionAnisotropicDiffusion} \input{DesignAndFunctionality/AnisotropicDiffusionFiltering.tex} -\subsubsection{Gradient Anisotropic Diffusion} +\subsubsection{Gradient Anisotropic Diffusion}% \label{sec:GradientAnisotropicDiffusionImageFilter} \input{GradientAnisotropicDiffusionImageFilter.tex} -\subsubsection{Curvature Anisotropic Diffusion} +\subsubsection{Curvature Anisotropic Diffusion}% \label{sec:CurvatureAnisotropicDiffusionImageFilter} \input{CurvatureAnisotropicDiffusionImageFilter.tex} -\subsubsection{Curvature Flow} +\subsubsection{Curvature Flow}% \label{sec:CurvatureFlowImageFilter} \input{CurvatureFlowImageFilter.tex} -\subsubsection{MinMaxCurvature Flow} +\subsubsection{MinMaxCurvature Flow}% \label{sec:MinMaxCurvatureFlowImageFilter} \input{MinMaxCurvatureFlowImageFilter.tex} -\subsubsection{Bilateral Filter} +\subsubsection{Bilateral Filter}% \label{sec:BilateralImageFilter} \input{BilateralImageFilter.tex} -\subsection{Edge Preserving Smoothing in Vector Images} +\subsection{Edge Preserving Smoothing in Vector Images}% \label{sec:VectorAnisotropicDiffusion} Anisotropic diffusion can also be applied to images whose pixels are vectors. @@ -297,30 +297,30 @@ \subsection{Edge Preserving Smoothing in Vector Images} component. The following classes implement versions of anisotropic diffusion on vector images. -\subsubsection{Vector Gradient Anisotropic Diffusion} +\subsubsection{Vector Gradient Anisotropic Diffusion}% \label{sec:VectorGradientAnisotropicDiffusionImageFilter} \input{VectorGradientAnisotropicDiffusionImageFilter.tex} -\subsubsection{Vector Curvature Anisotropic Diffusion} +\subsubsection{Vector Curvature Anisotropic Diffusion}% \label{sec:VectorCurvatureAnisotropicDiffusionImageFilter} \input{VectorCurvatureAnisotropicDiffusionImageFilter.tex} -\subsection{Edge Preserving Smoothing in Color Images} +\subsection{Edge Preserving Smoothing in Color Images}% \label{sec:ColorAnisotropicDiffusion} -\subsubsection{Gradient Anisotropic Diffusion} +\subsubsection{Gradient Anisotropic Diffusion}% \label{sec:ColorGradientAnisotropicDiffusion} \input{RGBGradientAnisotropicDiffusionImageFilter.tex} -\subsubsection{Curvature Anisotropic Diffusion} +\subsubsection{Curvature Anisotropic Diffusion}% \label{sec:ColorCurvatureAnisotropicDiffusion} \input{RGBCurvatureAnisotropicDiffusionImageFilter.tex} -\section{Distance Map} +\section{Distance Map}% \label{sec:DistanceMap} \input{DanielssonDistanceMapImageFilter.tex} @@ -328,12 +328,12 @@ \section{Distance Map} \input{SignedDanielssonDistanceMapImageFilter.tex} -\section{Geometric Transformations} +\section{Geometric Transformations}% \label{sec:GeometricalTransformationFilters} -\subsection{Filters You Should be Afraid to Use} - +\subsection{Filters You Should be Afraid to Use}% \label{sec:ScaryImageFilters} + \subsection{Change Information Image Filter} This one is the scariest and most dangerous filter in the entire toolkit. You @@ -350,7 +350,7 @@ \subsection{Flip Image Filter} \input{FlipImageFilter.tex} -\subsection{Resample Image Filter} +\subsection{Resample Image Filter}% \label{sec:ResampleImageFilter} \subsubsection{Introduction} @@ -376,35 +376,35 @@ \subsubsection{Resampling using a deformation field} \input{WarpImageFilter1.tex} -\subsubsection{Subsampling and image in the same space} +\subsubsection{Subsampling and image in the same space}% \label{SubsampleVolume} \input{SubsampleVolume.tex} -\subsubsection{Resampling an Anisotropic image to make it Isotropic} +\subsubsection{Resampling an Anisotropic image to make it Isotropic}% \label{ResampleVolumesToBeIsotropic} \input{ResampleVolumesToBeIsotropic.tex} -\section{Frequency Domain} +\section{Frequency Domain}% \label{sec:FrequencyDomain} -\subsection{Computing a Fast Fourier Transform (FFT)} +\subsection{Computing a Fast Fourier Transform (FFT)}% \label{FFTImageFilter} \input{FFTImageFilter.tex} -\subsection{Filtering on the Frequency Domain} +\subsection{Filtering on the Frequency Domain}% \label{FFTImageFilterFourierDomainFiltering} \input{FFTImageFilterFourierDomainFiltering.tex} -\section{Extracting Surfaces} +\section{Extracting Surfaces}% \label{sec:ExtractingSurfaces} -\subsection{Surface extraction} -\label{sec:SufaceExtraction} +\subsection{Surface extraction}% +\label{sec:SufaceExtraction}% \index{Surface Extraction} \input{SurfaceExtraction.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/HybridSegmentationMethods.tex b/SoftwareGuide/Latex/DesignAndFunctionality/HybridSegmentationMethods.tex index 6c32b3c2..45bcee39 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/HybridSegmentationMethods.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/HybridSegmentationMethods.tex @@ -9,7 +9,7 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Introduction} +\subsection{Introduction}% \label{sec:HybridSegmentationIntroduction} This section introduces the use of hybrid methods for segmentation of image data. Typically we are dealing with radiological patient and the Visible @@ -48,7 +48,7 @@ \subsection{Introduction} %REMOVED PATENTED: \input{FuzzyConnectednessImageFilter.tex} -\subsection{Fuzzy Connectedness and Voronoi Classification} +\subsection{Fuzzy Connectedness and Voronoi Classification}% \label{sec:HybridMethod1} In this section we present a hybrid segmentation method that requires minimal manual initialization by integrating the fuzzy connectedness and @@ -125,7 +125,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \begin{figure} \centering \includegraphics[width=0.8\textwidth]{HybridSegmentationEngine1.eps} -\itkcaption[Hybrid Segmentation Engine]{The hybrid segmentation engine.} +\itkcaption[Hybrid Segmentation Engine]{The hybrid segmentation engine.}% \label{fig:ComponentsofaHybridSegmentationApproach} \end{figure} @@ -133,7 +133,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \begin{figure} \centering \includegraphics[width=0.8\textwidth]{FuzzyConnectednessClassDiagram1.eps} -\itkcaption[FuzzyConectedness Filter Diagram]{Inheritance diagram for the fuzzy connectedness filter.} +\itkcaption[FuzzyConectedness Filter Diagram]{Inheritance diagram for the fuzzy connectedness filter.}% \label{fig:UMLClassDiagramoftherFuzzyConnectednessFilter} \end{figure} @@ -142,7 +142,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \centering \includegraphics[width=0.8\textwidth]{FuzzyConnectednessCollaborationDiagram1.eps} \itkcaption[Fuzzy Connectedness Segmentation Diagram]{Inputs and outputs to -FuzzyConnectednessImageFilter segmentation algorithm.} +FuzzyConnectednessImageFilter segmentation algorithm.}% \label{fig:UMLCollaborationDiagramoftheFuzzyConnectednessFilter} \end{figure} @@ -150,7 +150,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \centering \includegraphics[width=0.8\textwidth]{VoronoiSegmentationClassDiagram1.eps} \itkcaption[Voronoi Filter class diagram]{Inheritance diagram for the Voronoi -segmentation filters.} +segmentation filters.}% \label{fig:UMLVoronoiSegmentationClassFilter} \end{figure} @@ -158,7 +158,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \centering \includegraphics[width=0.8\textwidth]{VoronoiSegmentationCollaborationDiagram1.eps} \itkcaption[Voronoi Diagram Filter classes]{Classes used by the Voronoi -segmentation filters.} +segmentation filters.}% \label{fig:UMLClassesforImplementationofVoronoiDiagramFilter} \end{figure} @@ -167,7 +167,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \centering \includegraphics[width=0.8\textwidth]{VoronoiSegmentationCollaborationDiagram2.eps} \itkcaption[Voronoi Diagram Segmentation]{Input and output to the -VoronoiSegmentationImageFilter.} +VoronoiSegmentationImageFilter.}% \label{fig:UMLCollaborationDiagramoftheVoronoiSegmentationFilter} \end{figure} @@ -176,7 +176,7 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \centering \includegraphics[width=0.8\textwidth]{FuzzyVoronoiCollaborationDiagram1.eps} \itkcaption[Fuzzy Connectedness and Voronoi Diagram Classification]{Integration - of the fuzzy connectedness and Voronoi segmentation filters.} + of the fuzzy connectedness and Voronoi segmentation filters.}% \label{fig:UMLHybridMethodDiagram1} \end{figure} @@ -185,12 +185,12 @@ \subsection{Fuzzy Connectedness and Voronoi Classification} \includegraphics[width=0.8\textwidth]{FuzzyVoronoiDeformableCollaborationDiagram1.eps} \itkcaption[Fuzzy Connectedness, Voronoi diagram, and Deformable Models]{Integration of the fuzzy connectedness, Voronoi, and -deformable model segmentation methods.} +deformable model segmentation methods.}% \label{fig:UMLHybridMethodDiagram2} \end{figure} -\subsubsection{Example of a Hybrid Segmentation Method} +\subsubsection{Example of a Hybrid Segmentation Method}% \label{sec:HybridMethod1:Example} \input{HybridSegmentationFuzzyVoronoi.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/IO.tex b/SoftwareGuide/Latex/DesignAndFunctionality/IO.tex index 653eaef0..24f22d81 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/IO.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/IO.tex @@ -1,6 +1,6 @@ -\chapter{Reading and Writing Images} +\chapter{Reading and Writing Images}% \label{sec:IO} This chapter describes the toolkit architecture supporting reading and @@ -10,26 +10,26 @@ \chapter{Reading and Writing Images} We begin the chapter with some simple examples of file I/O. -\section{Basic Example} +\section{Basic Example}% \label{sec:ImagReadWrite} \input{ImageReadWrite.tex} -To better understand the IO architecture, please refer to Figures -\ref{fig:ImageIOCollaborationDiagram}, -\ref{fig:ImageIOFactoriesUseCases}, and -\ref{fig:ImageIOFactoriesClassDiagram}. +To better understand the IO architecture, please refer to +Figures~\ref{fig:ImageIOCollaborationDiagram},~\ref{fig:ImageIOFactoriesUseCases}, +and~\ref{fig:ImageIOFactoriesClassDiagram}. \begin{figure} \centering \includegraphics[width=\textwidth]{ImageIOCollaborationDiagram.eps} \itkcaption[Collaboration diagram of the ImageIO classes]{Collaboration diagram -of the ImageIO classes.} \label{fig:ImageIOCollaborationDiagram} +of the ImageIO classes.}% +\label{fig:ImageIOCollaborationDiagram} \end{figure} \begin{figure} \centering \includegraphics[width=\textwidth]{ImageIOFactoriesUseCases.eps} -\itkcaption[Use cases of ImageIO factories] {Use cases of ImageIO factories.} +\itkcaption[Use cases of ImageIO factories] {Use cases of ImageIO factories.}% \label{fig:ImageIOFactoriesUseCases} \end{figure} @@ -37,7 +37,7 @@ \section{Basic Example} \centering \includegraphics[width=\textwidth]{ImageIOFactoriesClassDiagram.eps} \itkcaption[Class diagram of ImageIO factories] {Class diagram of the ImageIO -factories.} +factories.}% \label{fig:ImageIOFactoriesClassDiagram} \end{figure} @@ -45,11 +45,11 @@ \section{Basic Example} The following section describes the internals of the IO architecture provided in the toolkit. -\section{Pluggable Factories} +\section{Pluggable Factories}% \label{sec:ImageIOPluggableFactories} The principle behind the input/output mechanism used in ITK is known as -\emph{pluggable-factories} \cite{Gamma1995}. This concept is illustrated in +\emph{pluggable-factories}~\cite{Gamma1995}. This concept is illustrated in the UML diagram in Figure~\ref{fig:ImageIOCollaborationDiagram}. From the user's point of view the objects responsible for reading and writing files are the \doxygen{ImageFileReader} and \doxygen{ImageFileWriter} @@ -100,29 +100,29 @@ \section{Pluggable Factories} possible, however, to explicitly select the type of ImageIO object to use. This is illustrated by the following example. -\section{Using ImageIO Classes Explicitly} +\section{Using ImageIO Classes Explicitly}% \label{sec:ImageReadExportVTK} \input{ImageReadExportVTK.tex} -\section{Reading and Writing RGB Images} +\section{Reading and Writing RGB Images}% \label{sec:RGBImagReadWrite} \input{RGBImageReadWrite.tex} -\section{Reading, Casting and Writing Images} +\section{Reading, Casting and Writing Images}% \label{sec:ImagReadCastWrite} \input{ImageReadCastWrite.tex} -\section{Extracting Regions} +\section{Extracting Regions}% \label{sec:ImagReadRegionOfInterestWrite} \input{ImageReadRegionOfInterestWrite.tex} -\section{Extracting Slices} +\section{Extracting Slices}% \label{sec:ImagReadExtractWrite} \input{ImageReadExtractWrite.tex} -\section{Reading and Writing Vector Images} +\section{Reading and Writing Vector Images}% \label{sec:VectorImagReadWrite} Images whose pixel type is a Vector, a CovariantVector, an Array, or a Complex @@ -130,26 +130,26 @@ \section{Reading and Writing Vector Images} how those images can be saved into files and how they can be read from those files later on. -\subsection{The Minimal Example} +\subsection{The Minimal Example}% \label{VectorImageReadWrite} \input{VectorImageReadWrite.tex} -\subsection{Producing and Writing Covariant Images} +\subsection{Producing and Writing Covariant Images}% \label{CovariantVectorImageWrite} \input{CovariantVectorImageWrite.tex} -\subsection{Reading Covariant Images} +\subsection{Reading Covariant Images}% \label{CovariantVectorImageRead} Let's now take the image that we just created and read it into another program. \input{CovariantVectorImageRead.tex} -\section{Reading and Writing Complex Images} +\section{Reading and Writing Complex Images}% \label{sec:ComplexImagReadWrite} \input{ComplexImageReadWrite.tex} -\section{Extracting Components from Vector Images} +\section{Extracting Components from Vector Images}% \label{sec:VectorImageExtractComponent} \input{CovariantVectorImageExtractComponent.tex} @@ -163,34 +163,33 @@ \section{Reading and Writing Image Series} for managing 4D datasets by using sets of files each one containing a 3D image. This practice is common in the domain of cardiac imaging, perfusion, functional MRI and PET. This section illustrates the functionalities available in ITK for -dealing with reading and writing series of images. - -\index{Series!Reading} -\index{Series!Writing} -\index{Image Series!Reading} +dealing with reading and writing series of images.% +% +\index{Series!Reading}% +\index{Series!Writing}% +\index{Image Series!Reading}% \index{Image Series!Writing} -\subsection{Reading Image Series} +\subsection{Reading Image Series}% \label{sec:ReadingImageSeries} \input{ImageSeriesReadWrite.tex} -\subsection{Writing Image Series} +\subsection{Writing Image Series}% \label{sec:WritingImageSeries} \input{ImageReadImageSeriesWrite.tex} -\subsection{Reading and Writing Series of RGB Images} +\subsection{Reading and Writing Series of RGB Images}% \label{sec:ReadingWritingRGBImageSeries} \input{RGBImageSeriesReadWrite.tex} -\section{Reading and Writing DICOM Images} -\label{sec:ReadingDicomImageSeries2} - +\section{Reading and Writing DICOM Images}% +\label{sec:ReadingDicomImageSeries2}% % Small intro to DICOM file format -\index{DICOM} -\index{DICOM!Standard} -\index{DICOM!Series} -\index{DICOM!Introduction} +\index{DICOM}% +\index{DICOM!Standard}% +\index{DICOM!Series}% +\index{DICOM!Introduction}% \subsection{Foreword} With the introduction of computed tomography (CT) followed by other digital @@ -254,26 +253,26 @@ \subsection{Foreword} The version distributed with ITK gets updated with major releases of the GDCM library. -\subsection{Reading and Writing a 2D Image} +\subsection{Reading and Writing a 2D Image}% \label{DicomImageReadWrite} \input{DicomImageReadWrite.tex} -\subsection{Reading a 2D DICOM Series and Writing a Volume} +\subsection{Reading a 2D DICOM Series and Writing a Volume}% \label{DicomSeriesReadImageWrite2} \input{DicomSeriesReadImageWrite2.tex} -\subsection{Reading a 2D DICOM Series and Writing a 2D DICOM Series} -\label{DicomSeriesReadSeriesWrite} +\subsection{Reading a 2D DICOM Series and Writing a 2D DICOM Series}% +\label{DicomSeriesReadSeriesWrite}% \input{DicomSeriesReadSeriesWrite.tex} -\subsection{Printing DICOM Tags From One Slice} -\label{DicomImageReadPrintTags} +\subsection{Printing DICOM Tags From One Slice}% +\label{DicomImageReadPrintTags}% \input{DicomImageReadPrintTags.tex} -\subsection{Printing DICOM Tags From a Series} -\label{DicomSeriesReadPrintTags} +\subsection{Printing DICOM Tags From a Series}% +\label{DicomSeriesReadPrintTags}% \input{DicomSeriesReadPrintTags.tex} -\subsection{Changing a DICOM Header} -\label{DicomImageReadChangeHeaderWrite} +\subsection{Changing a DICOM Header}% +\label{DicomImageReadChangeHeaderWrite}% \input{DicomImageReadChangeHeaderWrite.tex} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/ImageInterpolators.tex b/SoftwareGuide/Latex/DesignAndFunctionality/ImageInterpolators.tex index 47427b9c..262ef31f 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/ImageInterpolators.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/ImageInterpolators.tex @@ -8,7 +8,7 @@ \itkcaption[Mapping moving image to fixed image in Registration]{ The moving image is mapped into the fixed image space under some spatial transformation. An iterator walks through the fixed image and its coordinates -are mapped onto the moving image.} +are mapped onto the moving image.}% \label{fig:ImageOverlapIterator} \end{figure} @@ -18,7 +18,7 @@ \includegraphics[width=7.5cm]{ImageOverlapInterpolator.eps} \caption[Need for interpolation in Registration]{Grid positions of the fixed image map to non-grid positions of the moving -image. \label{fig:ImageOverlapInterpolator}} +image.\label{fig:ImageOverlapInterpolator}} \end{floatingfigure} In the registration process, the metric typically compares intensity values @@ -27,7 +27,7 @@ will in general be mapped to a non-grid position. Therefore, interpolation is required to evaluate the image intensity at the mapped position. -Figure \ref{fig:ImageOverlapIterator} (left) illustrates the mapping of the +Figure~\ref{fig:ImageOverlapIterator} (left) illustrates the mapping of the fixed image space onto the moving image space. The transform maps points from the fixed image coordinate system onto the moving image coordinate system. The figure highlights the region of overlap between the two images after the @@ -35,16 +35,15 @@ region of the fixed image. Each one of the iterator positions is mapped by the transform onto the moving image space in order to find the homologous pixel. -Figure \ref{fig:ImageOverlapInterpolator} presents a detailed view of the +Figure~\ref{fig:ImageOverlapInterpolator} presents a detailed view of the mapping from the fixed image to the moving image. In general, the grid positions of the fixed image will not be mapped onto grid positions of the moving image. Interpolation is needed for estimating the intensity of the moving image at these non-grid positions. The service is provided in ITK by -interpolator classes that can be plugged into the registration method. - -\index{Nearest\-Neighbor\-Interpolate\-Image\-Function} -\index{Linear\-Interpolate\-Image\-Function} -\index{BSpline\-Interpolate\-Image\-Function} +interpolator classes that can be plugged into the registration method.% +\index{Nearest\-Neighbor\-Interpolate\-Image\-Function}% +\index{Linear\-Interpolate\-Image\-Function}% +\index{BSpline\-Interpolate\-Image\-Function}% \index{Windowed\-Sinc\-Interpolate\-Image\-Function} The following interpolators are available: @@ -60,12 +59,11 @@ of the optimization search space and the overall computation time. On the other hand, interpolations are executed thousands of times in a single optimization cycle. Hence, the user has to balance the simplicity of computation with the -smoothness of the optimization when selecting the interpolation scheme. - -\index{itk::InterpolateImageFunction} -\index{itk::InterpolateImageFunction!SetInputImage()} -\index{itk::InterpolateImageFunction!Evaluate()} -\index{itk::InterpolateImageFunction!EvaluateAtContinuousIndex()} +smoothness of the optimization when selecting the interpolation scheme.% +\index{itk::InterpolateImageFunction}% +\index{itk::InterpolateImageFunction!SetInputImage()}% +\index{itk::InterpolateImageFunction!Evaluate()}% +\index{itk::InterpolateImageFunction!EvaluateAtContinuousIndex()}% \index{itk::InterpolateImageFunction!IsInsideBuffer()} The basic input to an \doxygen{InterpolateImageFunction} is the image to @@ -77,8 +75,8 @@ particular image index or a physical point falls inside the spatial domain for which image pixels exist. -\subsection{Nearest Neighbor Interpolation} -\label{sec:NearestNeighborInterpolation} +\subsection{Nearest Neighbor Interpolation}% +\label{sec:NearestNeighborInterpolation}% \index{itk::Nearest\-Neighbor\-Interpolate\-Image\-Function} The \doxygen{NearestNeighborInterpolateImageFunction} simply uses the intensity of the nearest grid position. That is, it assumes that the image @@ -87,8 +85,8 @@ \subsection{Nearest Neighbor Interpolation} computations. -\subsection{Linear Interpolation} -\label{sec:LinearInterpolation} +\subsection{Linear Interpolation}% +\label{sec:LinearInterpolation}% \index{itk::Linear\-Interpolate\-Image\-Function} The \doxygen{LinearInterpolateImageFunction} assumes that intensity varies @@ -97,8 +95,8 @@ \subsection{Linear Interpolation} gradient will be discontinuous at grid positions. -\subsection{B-Spline Interpolation} -\label{sec:BSplineInterpolation} +\subsection{B-Spline Interpolation}% +\label{sec:BSplineInterpolation}% \index{itk::BSpline\-Interpolate\-Image\-Function} \begin{figure} @@ -108,7 +106,7 @@ \subsection{B-Spline Interpolation} BSpline grid and the deformations that are known on those nodes. The right side illustrates the region where interpolation is possible when the BSpline is of cubic order. The small arrows represent deformation values that were -interpolated from the grid deformations shown on the left side of the diagram.} +interpolated from the grid deformations shown on the left side of the diagram.}% \label{fig:BSplineInterpolation} \end{figure} @@ -137,8 +135,8 @@ \subsection{B-Spline Interpolation} that the interpolated value is negative. -\subsection{Windowed Sinc Interpolation} -\label{sec:WindowedSincInterpolation} +\subsection{Windowed Sinc Interpolation}% +\label{sec:WindowedSincInterpolation}% \index{itk::Windowed\-Sinc\-Interpolate\-Image\-Function} The \doxygen{WindowedSincInterpolateImageFunction} is the best possible @@ -198,13 +196,13 @@ \subsection{Windowed Sinc Interpolation} Cosinus window \begin{equation} -w(x) = cos ( \frac{\pi x}{2 m} ) +w(x) = \cos ( \frac{\pi x}{2 m} ) \end{equation} Hamming window \begin{equation} -w(x) = 0.54 + 0.46 cos ( \frac{\pi x}{m} ) +w(x) = 0.54 + 0.46 \cos ( \frac{\pi x}{m} ) \end{equation} @@ -222,7 +220,7 @@ \subsection{Windowed Sinc Interpolation} Blackman window \begin{equation} -w(x) = 0.42 + 0.5 cos(\frac{\pi x}{m}) + 0.08 cos(\frac{2 \pi x}{m}) +w(x) = 0.42 + 0.5 \cos(\frac{\pi x}{m}) + 0.08 \cos(\frac{2 \pi x}{m}) \end{equation} diff --git a/SoftwareGuide/Latex/DesignAndFunctionality/ImageMetrics.tex b/SoftwareGuide/Latex/DesignAndFunctionality/ImageMetrics.tex index eba03d2b..35a1dd69 100644 --- a/SoftwareGuide/Latex/DesignAndFunctionality/ImageMetrics.tex +++ b/SoftwareGuide/Latex/DesignAndFunctionality/ImageMetrics.tex @@ -4,8 +4,6 @@ % % -\index{itk::Image\-To\-Image\-Metricv4} - \begin{floatingfigure}[rlp]{0.5\textwidth} \centering \includegraphics{ParzenWindowing13.eps} @@ -13,7 +11,8 @@ In Parzen windowing, a continuous density function is constructed by superimposing kernel functions (Gaussian function in this case) centered on the intensity samples obtained from the image.\label{fig:ParzenWindowing}} -\end{floatingfigure} +\end{floatingfigure}% +\index{itk::Image\-To\-Image\-Metricv4} In ITK, \doxygen{ImageToImageMetricv4} objects quantitatively measure how well the transformed moving image fits the fixed image by comparing the gray-scale @@ -28,10 +27,10 @@ position. In addition, some metrics are only suitable for comparing images obtained from the same imaging modality, while others can handle inter-modality comparisons. -Unfortunately, there are no clear-cut rules as to how to choose a metric. - -\index{itk::Image\-To\-Image\-Metricv4!GetValue()} -\index{itk::Image\-To\-Image\-Metricv4!GetDerivatives()} +Unfortunately, there are no clear-cut rules as to how to choose a metric.% +% +\index{itk::Image\-To\-Image\-Metricv4!GetValue()}% +\index{itk::Image\-To\-Image\-Metricv4!GetDerivatives()}% \index{itk::Image\-To\-Image\-Metricv4!GetValueAndDerivatives()} The matching Metric class controls most parts of the registration process @@ -43,8 +42,8 @@ image positions are computed using the fixed initial transform and the moving transform with the specified parameters. Then, the fixed and moving interpolators are used to compute the fixed and moving image's intensities at the mapped -positions. Details on this mapping are illustrated in Figures -\ref{fig:ImageOverlapIterator} and \ref{fig:ImageOverlapInterpolator} assuming +positions. Details on this mapping are illustrated in Figures~\ref{fig:ImageOverlapIterator} +and~\ref{fig:ImageOverlapInterpolator} assuming that virtual lattice is the same as the fixed image lattice, which is usually the case in practice. @@ -88,11 +87,11 @@ In the following sections, we describe the ITKv4 metric types in detail. You can check ITK descriptions in doxygen for details about ITKv3 metric classes. -For ease of notation, we will refer to the fixed image $f(\bf{X})$ -and transformed moving image $(m \circ T(\bf{X}))$ as images $A$ and $B$. +For ease of notation, we will refer to the fixed image $f(\textbf{X})$ +and transformed moving image $(m \circ T(\textbf{X}))$ as images $A$ and $B$. -\subsection{Mean Squares Metric} -\label{sec:MeanSquaresMetricv4} +\subsection{Mean Squares Metric}% +\label{sec:MeanSquaresMetricv4}% \index{itk::Mean\-Squares\-Image\-To\-Image\-Metricv4} The \doxygen{MeanSquaresImageToImageMetricv4} computes the mean squared @@ -117,7 +116,7 @@ \subsection{Mean Squares Metric} to images of the same modality. Additionally, any linear changes in the intensity result in a poor match value. -\subsubsection{Exploring a Metric} +\subsubsection{Exploring a Metric}% \label{sec:ExploringAMetric} Getting familiar with the characteristics of the Metric as a cost function is @@ -131,8 +130,8 @@ \subsubsection{Exploring a Metric} \input{MeanSquaresImageMetric1.tex} -\subsection{Normalized Correlation Metric} -\label{sec:NormalizedCorrelationMetric} +\subsection{Normalized Correlation Metric}% +\label{sec:NormalizedCorrelationMetric}% \index{itk::Correlation\-Image\-To\-Image\-Metricv4} The \doxygen{CorrelationImageToImageMetricv4} computes pixel-wise @@ -158,7 +157,7 @@ \subsection{Normalized Correlation Metric} well-defined minima. On the other hand, it has a relatively small capture radius. -\subsection{Mutual Information Metric} +\subsection{Mutual Information Metric}% \label{sec:MutualInformationMetric} The \doxygen{MattesMutualInformationImageToImageMetricv4} computes the mutual @@ -191,7 +190,7 @@ \subsection{Mutual Information Metric} \begin{equation} H(A,B)