-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathgetstarted.html
More file actions
245 lines (233 loc) · 21.3 KB
/
getstarted.html
File metadata and controls
245 lines (233 loc) · 21.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta content="Get started with the Medical Image Registration ToolKit (MIRTK)" name="description" />
<meta content="image processing, image registration, IRTK, MIRTK, intro, quick start" name="keywords" />
<title>Get Started — MIRTK</title>
<link rel="stylesheet" href="_static/bizstyle.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: 'v2.0 (8c2aa10)',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/bizstyle.js"></script>
<link rel="top" title="MIRTK" href="sidebar.html" />
<link rel="next" title="Applications" href="commands.html" />
<link rel="prev" title="Medical Image Registration ToolKit (MIRTK)" href="index.html" />
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<!--[if lt IE 9]>
<script type="text/javascript" src="_static/css3-mediaqueries.js"></script>
<![endif]-->
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="commands.html" title="Applications"
accesskey="N">next</a></li>
<li class="right" >
<a href="index.html" title="Medical Image Registration ToolKit (MIRTK)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="sidebar.html">MIRTK</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3><a href="sidebar.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Overview</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Get Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#install-the-software">Install the software</a></li>
<li class="toctree-l2"><a class="reference internal" href="#enable-bash-completion">Enable Bash completion</a></li>
<li class="toctree-l2"><a class="reference internal" href="#run-the-commands">Run the commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="#write-your-own-application">Write your own application</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="commands.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="apidoc.html">Reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">News</a></li>
<li class="toctree-l1"><a class="reference internal" href="download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="help.html">Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="publications.html">Publications</a></li>
<li class="toctree-l1"><a class="reference internal" href="people.html">People</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="get-started">
<h1>Get Started<a class="headerlink" href="#get-started" title="Permalink to this headline">¶</a></h1>
<div class="section" id="install-the-software">
<h2>Install the software<a class="headerlink" href="#install-the-software" title="Permalink to this headline">¶</a></h2>
<p><strong>Custom build</strong></p>
<p>Before you can start using the MIRTK or develop your own MIRTK applications,
you have to install the desired modules and available applications on your
system including their prerequisites. For a manual installation of the MIRTK,
please follow the <a class="reference internal" href="download.html"><span class="doc">Download</span></a> and <a class="reference internal" href="install.html"><span class="doc">Installation</span></a> instructions which
list the third-party libraries required by each module and describe how to
build the MIRTK from its publicly available source code.</p>
<p><strong>Using Docker</strong></p>
<p>Instead of manually installing the MIRTK locally on your system, you can use
the pre-made <a class="reference external" href="https://hub.docker.com/r/biomedia/mirtk/">biomedia/mirtk</a>
Docker image to run the <a class="reference internal" href="commands.html"><span class="doc">Applications</span></a> inside a <a class="reference external" href="https://www.docker.com/what-docker">Docker container</a>.
For a guide to install and use <a class="reference external" href="http://www.docker.com">Docker</a>, see the <a class="reference external" href="https://docs.docker.com">official docs</a>.</p>
<p><strong>AppImage for Linux</strong></p>
<p>For Linux users, the easiest way to get started with MIRTK without the need for the Docker
runtime environment is the <a class="reference external" href="https://bintray.com/schuhschuh/AppImages/MIRTK/master">MIRTK AppImage</a> available on <a class="reference external" href="https://bintray.com/schuhschuh/AppImages/MIRTK/master">Bintray</a>. An <a class="reference external" href="https://appimage.org/">AppImage</a> contains
all the required shared libraries and pre-built MIRTK commands. It can be executed on any
Linux system with a compatible minimum glibc version (>=2.15). With this AppImage, there is no
actual need for an installation. Simply download the file, make it executable, and copy it to
a directory that is in your PATH, e.g.,:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>wget -O mirtk https://bintray.com/schuhschuh/AppImages/download_file?file_path=MIRTK%2Bview-latest-x86_64-glibc2.15.AppImage
chmod a+x mirtk
sudo mv mirtk /usr/bin
</pre></div>
</div>
<p>This AppImage is updated automatically when a change is committed to the master branch.</p>
</div>
<div class="section" id="enable-bash-completion">
<span id="bashcompletion"></span><h2>Enable Bash completion<a class="headerlink" href="#enable-bash-completion" title="Permalink to this headline">¶</a></h2>
<p><strong>Custom build</strong></p>
<p>For information on how to enable <a class="reference external" href="https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html">auto-completion</a> when running <code class="docutils literal"><span class="pre">mirtk</span></code> commands of
a manual MIRTK installation in the <a class="reference external" href="https://www.gnu.org/software/bash/">Bash</a> shell, see the <a class="reference internal" href="install.html"><span class="doc">Installation</span></a> instructions.</p>
<p><strong>Using Docker</strong></p>
<p>To enable Bash completion for running the MIRTK commands with Docker,
copy the <a class="reference external" href="https://raw.githubusercontent.com/docker/docker/master/contrib/completion/bash/docker">docker</a>
and <a class="reference external" href="https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Docker/Completion/Bash/docker-mirtk">docker-mirtk</a>
completion scripts to <code class="docutils literal"><span class="pre">/etc/bash_completion.d/</span></code> on Linux or,
with the “bash-completion” <a class="reference external" href="http://brew.sh">Homebrew</a> package installed on OS X,
to <code class="docutils literal"><span class="pre">/usr/local/etc/bash_completion.d/</span></code>, respectively.</p>
<p>This can be done on Linux with the following Terminal commands:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">curl</span> <span class="o">-</span><span class="n">L</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">raw</span><span class="o">.</span><span class="n">githubusercontent</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">docker</span><span class="o">/</span><span class="n">docker</span><span class="o">/</span><span class="n">master</span><span class="o">/</span><span class="n">contrib</span><span class="o">/</span><span class="n">completion</span><span class="o">/</span><span class="n">bash</span><span class="o">/</span><span class="n">docker</span> <span class="o">></span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">bash_completion</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">docker</span>
<span class="n">sudo</span> <span class="n">curl</span> <span class="o">-</span><span class="n">L</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">raw</span><span class="o">.</span><span class="n">githubusercontent</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">BioMedIA</span><span class="o">/</span><span class="n">MIRTK</span><span class="o">/</span><span class="n">master</span><span class="o">/</span><span class="n">Docker</span><span class="o">/</span><span class="n">Completion</span><span class="o">/</span><span class="n">Bash</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">mirtk</span> <span class="o">></span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">bash_completion</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">mirtk</span>
</pre></div>
</div>
<p>On OS X with Homebrew, use these commands instead:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>brew install bash-completion
curl -L https://raw.githubusercontent.com/docker/docker/master/contrib/completion/bash/docker > $(brew --prefix)/etc/bash_completion.d/docker
curl -L https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Docker/Completion/Bash/docker-mirtk > $(brew --prefix)/etc/bash_completion.d/docker-mirtk
</pre></div>
</div>
<p>Alternatively, save the files to your home directory at, for example, <code class="docutils literal"><span class="pre">$HOME/bash_completion/</span></code>
and add the following lines to your <code class="docutils literal"><span class="pre">.bashrc</span></code> (Linux) or <code class="docutils literal"><span class="pre">.bash_profile</span></code> (OS X) file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[ ! -f "$HOME/bash_completion/docker" ] || . "$HOME/bash_completion/docker"
[ ! -f "$HOME/bash_completion/docker-mirtk" ] || . "$HOME/bash_completion/docker-mirtk"
</pre></div>
</div>
<p><strong>Using AppImage</strong></p>
<p>To enable Bash completion for running the MIRTK commands in Bash using the AppImage for Linux,
copy <a class="reference external" href="https://raw.githubusercontent.com/BioMedIA/MIRTK/master/Scripts/mirtk_bash_completion.sh">this file</a>
to <code class="docutils literal"><span class="pre">/etc/bash_completion.d/</span></code>.</p>
<p>This can be done with the following Terminal command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">curl</span> <span class="o">-</span><span class="n">L</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">raw</span><span class="o">.</span><span class="n">githubusercontent</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">BioMedIA</span><span class="o">/</span><span class="n">MIRTK</span><span class="o">/</span><span class="n">master</span><span class="o">/</span><span class="n">Scripts</span><span class="o">/</span><span class="n">mirtk_bash_completion</span><span class="o">.</span><span class="n">sh</span> <span class="o">></span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">bash_completion</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">mirtk</span>
</pre></div>
</div>
<p>Alternatively, save the file to your home directory at, for example, <code class="docutils literal"><span class="pre">$HOME/bash_completion/</span></code>,
rename it to <code class="docutils literal"><span class="pre">mirtk</span></code>, and add the following line to your <code class="docutils literal"><span class="pre">.bashrc</span></code> file:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[ ! -f "$HOME/bash_completion/mirtk" ] || . "$HOME/bash_completion/mirtk"
</pre></div>
</div>
</div>
<div class="section" id="run-the-commands">
<h2>Run the commands<a class="headerlink" href="#run-the-commands" title="Permalink to this headline">¶</a></h2>
<p>The MIRTK installs a single executable named <code class="docutils literal"><span class="pre">mirtk</span></code> in the <code class="docutils literal"><span class="pre">bin/</span></code> directory
of the installation root directory. This executable is used to execute the various
MIRTK commands. The name of the command must be specified as first argument of the
<code class="docutils literal"><span class="pre">mirtk</span></code> executable. Help about a command can be printed using the special <code class="docutils literal"><span class="pre">help</span></code>
or <code class="docutils literal"><span class="pre">help-rst</span></code> commands followed by the name of the command for which help is requested:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mirtk</span> <span class="n">help</span> <span class="o"><</span><span class="n">command</span><span class="o">></span>
<span class="n">mirtk</span> <span class="p">[</span><span class="o">-</span><span class="n">v</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">v</span><span class="p">]</span> <span class="o"><</span><span class="n">command</span><span class="o">></span> <span class="p">[</span><span class="n">options</span><span class="p">]</span>
</pre></div>
</div>
<p>When the <code class="docutils literal"><span class="pre">-v</span></code> option is given to <code class="docutils literal"><span class="pre">mirtk</span></code> before the command name, the path and
arguments of the command executable is printed before execution.</p>
<p>To run the commands inside a <a class="reference external" href="http://www.docker.com">Docker</a> container instead which does not require a local
installation of MIRTK, use the following command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">docker</span> <span class="n">run</span> <span class="o">--</span><span class="n">rm</span> <span class="o">--</span><span class="n">volume</span><span class="o">=<</span><span class="n">path</span><span class="o">></span><span class="p">:</span><span class="o">/</span><span class="n">data</span> <span class="n">biomedia</span><span class="o">/</span><span class="n">mirtk</span> <span class="p">[</span><span class="o">-</span><span class="n">v</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">v</span><span class="p">]</span> <span class="o"><</span><span class="n">command</span><span class="o">></span> <span class="p">[</span><span class="o"><</span><span class="n">options</span><span class="o">></span><span class="p">]</span>
</pre></div>
</div>
<p>This will download the <a class="reference external" href="https://hub.docker.com/r/biomedia/mirtk/">MIRTK Docker image</a> upon first execution. This image is
stored locally and will be reused for consecutive executions.
The <code class="docutils literal"><span class="pre">--volume</span></code> option of <code class="docutils literal"><span class="pre">docker</span> <span class="pre">run</span></code> mounts the specified directory path on the
host system to the <code class="docutils literal"><span class="pre">/data</span></code> directory inside the MIRTK Docker container.
The <code class="docutils literal"><span class="pre">/data</span></code> directory is the working directory of the MIRTK command.
The <code class="docutils literal"><span class="pre">--rm</span></code> option automatically deletes the MIRTK Docker container after the
command finished. Note that each <code class="docutils literal"><span class="pre">docker</span> <span class="pre">run</span></code> will create a new Docker container.
As these containers are meant to be used only once for each command execution, they
should be removed again after the command has finished.</p>
<p>For example, to print information about the NIfTI image file <code class="docutils literal"><span class="pre">/path/to/my/images/image1.nii.gz</span></code>
using the <a class="reference internal" href="commands/info.html"><span class="doc">info</span></a> command, execute the Docker command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">docker</span> <span class="n">run</span> <span class="o">--</span><span class="n">rm</span> <span class="o">--</span><span class="n">volume</span><span class="o">=/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">my</span><span class="o">/</span><span class="n">images</span><span class="p">:</span><span class="o">/</span><span class="n">data</span> <span class="n">biomedia</span><span class="o">/</span><span class="n">mirtk</span> <span class="n">info</span> <span class="n">image1</span><span class="o">.</span><span class="n">nii</span><span class="o">.</span><span class="n">gz</span>
</pre></div>
</div>
<p>See the <a class="reference internal" href="commands.html"><span class="doc">Applications</span></a> page for a description of each command and the available options.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When Bash completion of MIRTK commands is enabled (see <a class="reference internal" href="#bashcompletion"><span class="std std-ref">Enable Bash completion</span></a>),
press the <tab> key twice after typing “mirtk ” or “docker run biomedia/mirtk ”
(incl. a space) to see a list of all commands. To only see a list of partial matches,
type “mirtk eval” or “docker run biomedia/mirtk eval”, for example, and press <tab> twice.</p>
</div>
</div>
<div class="section" id="write-your-own-application">
<h2>Write your own application<a class="headerlink" href="#write-your-own-application" title="Permalink to this headline">¶</a></h2>
<p>For writing your own MIRTK command or an application which uses the MIRTK libraries,
we recommend a look at the source code of the applications included in the MIRTK.
The <a class="reference internal" href="apidoc.html"><span class="doc">API Reference</span></a> generated by <a class="reference external" href="http://www.doxygen.org/">Doxygen</a> provides a more detailed
overview of the available MIRTK classes and their interfaces.</p>
<p>If you intend to contribute your applications in the future to the MIRTK distribution,
see the <a class="reference external" href="https://github.com/BioMedIA/MIRTK/blob/master/CONTRIBUTING.md">code contribution</a>
guidelines for more information on how to contribute your code to the MIRTK source tree
or develop your own MIRTK Package.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="commands.html" title="Applications"
>next</a></li>
<li class="right" >
<a href="index.html" title="Medical Image Registration ToolKit (MIRTK)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="sidebar.html">MIRTK</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2013-2018 Imperial College London, Andreas Schuh.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
</div>
</body>
</html>