1
%\documentclass{article}
2
\documentclass{InsightArticle}
4
% to be able to use options in graphics
5
\ifx\pdfoutput\undefined
10
colorlinks,linkcolor={blue},citecolor={blue},urlcolor={blue},
12
\usepackage[dvips]{graphicx}
14
\usepackage[bookmarks,
17
colorlinks,linkcolor={blue},citecolor={blue},urlcolor={blue},
19
\usepackage[pdftex]{graphicx}
21
\SweaveOpts{keep.source=TRUE}
25
\usepackage{subfigure}
27
\title{SimpleITK in R}
30
% At minimum, give your name and an email address. You can include a
31
% snail-mail address if you like.
32
\author{Richard Beare}
33
%\authoraddress{Richard.Beare@monash.edu\\Department of Medicine\\Monash University\\and\\Developmental Imaging\\Murdoch Childrens Research Institute\\Melbourne\\Australia}
38
%\chapter*{Front Matter\label{front}}
42
{\em R}, also known as ``Gnu S'' is a widely used, open source,
43
language based environment for statistics and computational
44
modelling. It will be reasonably familiar to users of other
45
interactive, interpreted environments, like Matlab or python. This
46
article provides an introduction to the SimpleITK package that has
47
been built using the Swig generated wrapping of the SimpleITK
48
library. Note that some of the text is written for readers unfamiliar
49
with {\em R} and can be skipped by experienced users.
54
\section{Introduction}
55
{\em R} is an advanced language environment that supports extension
56
via an advanced package mechanism and object-oriented and generic
57
programming mechanisms. The traditional application domain of {\em R}
58
is in interactive statistical analysis, but the language is general
59
purpose and facilities are available to support many forms of
60
computational work. There are already a number of packages for medical
61
imaging and general purpose imaging, but none with the extent of low
62
level operators provided by SimpleITK. {\em R} has quite nice features
63
that makes interfacing to objects like images quite convenient. This
64
package makes extensive use of {\em external references} and language
65
operator overloading facilities.
67
\section{Very basic {\em R} tutorial}
68
{\em R} has extensive online documentation - see the Documentation
69
links on the r-project pages. Here are some basic concepts to start
70
the project. Skip to the next section if you are already familiar with {\em R}.
73
\item Assignment - traditionally the assignment operator is {\tt <-}, but {\tt =} can be used in most places now:
75
a <- 1 # assign a variable
78
\item Creating vectors - everything in {\em R} is at least a vector, and vectors can contain numbers or strings:
80
a <- c(1,2,34, 20, 10)
82
b = c('a', 'k', 'hello')
87
{\em c} is the concatenate operator and can be used with vectors and lists.
88
\item Displaying objects - as seen above, typing a variable name invokes the generic {\em show} method, which typically provides an informative display of an obje. We'll see how this comes in handy later with images.
91
b<-array(1:20, dim=c(5,4))
94
\item Vector and array subsetting - there are a rich set of these operations with capabilities similar to Matlab. Indexing starts from 1.
98
a[-1] # delete first element
99
b[1,] # first row of b
102
\item Lists - can contain different object types
104
L1 = list('a', 1, 'hello')
109
Notice that we are using the double bracket operator to access list elements.
111
\item Naming components - so far we have been illustrating standard, index-based, access. It is possible to name array, vector and list components which provides options for clear accessing.
113
L1 <- list(first=1, second='hello', third=b)
117
colnames(b) <- c("first", "second", "third", "last")
120
These options provide useful ways of keeping consistency in complex analyses with evolving data structures.
121
\item Other data structures. The main structure not discussed here is a special list, called a data frame, that is widely used by the statistical model-fitting procedures. Classes, methods and other language facilities are also available, but used mainly by package developers.
124
\section{Getting started with SimpleITK}
125
Building and installation instructions are later. Lets jump straight into some examples. In order to display images you need to install ImageJ with the nifti plugin, and be in your path. The results in this docment are displayed slightly differently, using internal {\em R} plotting routines, for compatability with the Sweave document processing.
127
\subsection{Image anatomy and access methods}
129
\item Load the SimpleITK library. This may require that the {\tt R\_LIBS} environment variable is set.
134
# override show function
135
setMethod('show', '_p_itk__simple__Image',
139
a <- t(as.array(object))
141
A <- (a-rg[1])/(rg[2]-rg[1])
143
sp <- object$GetSpacing()
153
im <- ReadImage(system.file("data/cthead1.png", package="SimpleITK"))
159
\item Get some information about the image
165
These vector quantities are translated directly to R vectors. The same applies to filters, as we'll see later.
166
\item Get one pixel value
170
\item Extract the first 100 columns
174
\item First 100 columns, then same data flipped
178
\item Remove the first 100 rows
184
im[seq(1,256, by=2), seq(1,256, by=2)]
187
As you can see, we can use array acess techniques to images. The results of each of these operations is an image, not an array. Evidently, we can do some pretty crazy things using this notation, which means that it is very difficult to decide what to do with image metadata, such as spacing and origin. Currently nothing clever is being done with either - spacing is left as per the input, which could easily be wrong. Origin is left as default image constructor.
188
\item Lets explore the image class in a little more detail to find out what access methods are available:
190
getMethod('$', class(im))
192
This provides a list of accessor functions that can be used via the \$ notation illustrated above. Most classes create by the swig processing work this way.
193
\item Finally, lets allocate an image
195
im2 <- Image(10,10, 20, 'sitkUInt16')
199
The important points to note here is that the enumerated type describing the pixel type is represented as a string.
200
\item Translating images to {\em R} arrays:
205
# now we can do something crazy
214
Points to note here - {\em R} only supports integer and double types (logical types are also integers). Therefore conversion of any image will end up as an array of one of these types. Similarly, conversion of arrays to images also ends up as one of these types. By default, any {\em R} matrix will be double precision, but can be coerced to integer using the {\em as.integer} or {\em storage.mode} functions. Image pixel types can be converted using the {\em Cast} filters.
218
\subsection{Image operations with Simple ITK classes}
219
Finally, onto the crux of the matter. Let's look at doing some image filtering. There are two basic approaches with SimpleITK - the procedural and the filter approach
221
\item Gaussian blurring:
223
res <- SmoothingRecursiveGaussian(im, 3)
228
filt <- SmoothingRecursiveGaussianImageFilter()
229
# check the accessors
230
getMethod('$', class(filt))
232
filt$NormalizeAcrossScaleOn()
233
res2 <- filt$Execute(im)
237
Notice that we can explore the accessor functions in the same way as images. Also note that calling the accessor functions without assigning the result to a variable causes the {\em show} method to display a representation of the object.
238
\item Cryptic error messages - unfortunately it isn't easy to figure out what arguments are expected by the procedural interface. For example, if we assumed that the sigma parameter was a vector, we'd get the following unhelpful response:
240
try(res3 <- SmoothingRecursiveGaussian(im, c(3, 3)))
243
Note that the {\em try} and {\em geterrmessage} commands are to allow Sweave to complete. They aren't needed in interactive sessions.
248
\subsection{Still to come}
254
Beware of images from saved workspaces. External references, which is how images are represented, are not preserved when objects are saved to disk. Thus, attempting to use images from a saved workspace will result in ungraceful crashes.
256
\section{Building and Installing}
257
Fetch SimpleITK from the git repository. Visit \url{https://www.itk.org/SimpleITKDoxygen/html/Wrapping.html} for the latest instructions on building and installing.
258
\section{Development}
added
removed
Wrapping/R/Packaging/SimpleITK/vignettes/SimpleITK_tutorial.Rnw
