Commit e69a67f1 authored by Matt Clarkson's avatar Matt Clarkson

Merge branch '5347-document-tool-config'

* 5347-document-tool-config:
  Issue #5347: Update Doxygen, to specify correct image for figure 5.
parents 675b8aa2 df4728cc
......@@ -27,6 +27,7 @@ the design decisions will be explained in detail. It is however assumed that the
\li \subpage HowToErasePluginCache
\li \subpage HowToWritePlugins
\li \subpage HowToDoUltrasoundCalibration
\li \subpage HowToCreateToolTrackingFiles
\li \subpage BuildInstructionsKelvin
\li \subpage SystemSetupUbuntu1604
\li \subpage TestingApplications
......
/**
\page HowToCreateToolTrackingFiles How To - Create Tool Tracking Files (.IGTToolStorage files)
\section HowToCreateToolTrackingFilesContents Table of Contents
\li \ref HowToCreateToolTrackingFilesIntroduction
\li \ref HowToCreateToolTrackingFilesMarkerFiles
\li \ref HowToCreateToolTrackingFilesIGTToolStorage
\section HowToCreateToolTrackingFilesIntroduction Introduction
If you were to write your own tracking code, then for optical trackers like
the NDI Spectra, you would have to manage multiple configuration files (called .rom files)
to store the geometrical configuration of each optical marker set being tracked.
Similarly, most other optical tracker manufacturers would use a configuration file
for each optically tracked object. This leads to the need for each application to load
in the right set of configuration files in order to initialise an optical tracker.
These are typically not needed for electro-magnetic (EM) trackers like the NDI Aurora, as each tool is
physically connected to a port, so the NDI API can detect which tools are being tracked. However,
in this case, the Aurora would not know what tool was attached to each port, so you would probably
end up with each tool having a name correspding to the port number, eg. [0, 1, 2, 3], which
would then over time be confusing, as you would not know which tool was connected to which port.
MITK on the other hand wraps these necessary configuration files into a single .IGTToolStorage
file, which can be considered as a container. This container stores useful information like
a Name. It can also contain extra configuration parameters
like a surface model to use for rendering. These extra configuration parameters will not be covered
here, as we just want to focus on the tracking capability.
So, within MITK and NifTK, the basic principal of getting your tracker working is
<ol>
<li>Locate, or create a set of configuration files that define the geometry for each optically
tracked object. These are only necessary for optical trackers, not for EM trackers.</li>
<li>Create a .IGTToolStorage file, using the MITK IGT Navigation Tool Manager plugin. This
.IGTToolStorage file acts as a container. This container can then be stored for later use,
and does make management of multiple tool configurations a bit easier. For example it allows
you to name the tool with a human readable name, and then the NifTK Data Manager plugin
will save data in a folder of the same name.</li>
</ol>
These steps are now described in some detail.
\section HowToCreateToolTrackingFilesMarkerFiles Creating Optical Marker Files
These instructions pertain to either NDI Spectra (.rom files), or the Atracsys Fusion Track range (.ini files).
<b>NDI .rom files</b>
For standard NDI markers, which are manufactured to known dimensions by NDI, then the necessary .rom
files can be downloaded from the NDI support website. These standard .rom files are also available in
\verbatim
NifTK/Resources/Tracking
\endverbatim
You can also create your own. Launch NDI 6D Architect, locate the Help files, and
follow the instructions on how to create a new .rom file.
You can also manually create one, simply by specifying the coordinates in
the 6D Architect. This is useful if you have designed your own tool and manufactured
it accurately enough.
<b>Atracsys .ini files</b>
You should probably follow the Atracsys documentation to make a new geometry file for
each marker being tracked. The manual comes with each tracker and is not available for download.
This probably gives the most accurate tracking in the long run.
However, if you already have a .rom file available, for example for when you are using Atracsys to
track a standard NDI marker, then you can create a suitable Atracsys .ini file
by extracting the coordinates from the .rom file and following the Atracsys format to
manually write the .ini file. You can look at similar examples in:
\verbatim
NifTK/Resources/Tracking
NifTK/Resources/Tracking/README.txt
\endverbatim
where the README.txt tells you which Atracsys .ini files correspond with which NDI .rom files.
\section HowToCreateToolTrackingFilesIGTToolStorage Creating Tool Storage Files
Once you have your .rom files or .ini files, you can then proceed to create a .IGTToolStorage to group
them together.
\li Locate the IGT Navigation Tool Manager.
\li Click "Create New" which brings up a dialog box to name your Tool Storage (See Figure 1).
You can call it what you like, but its useful to name the tracker and all tools contained as succinctly as possible.
\image html TrackingCreateToolStorage.png "Figure 1. Locate the IGT Navigation Tool Manager plugin and create a new Tool Storage with a name of your choice."
\li Then you add tools to the storage file using the "Add" button (See Figure 2).
\image html TrackingCreateNewTool.png "Figure 2. Click the Add button to create a new tool."
\li You first select the type of tool, e.g. NDI Polaris, or NDI Aurora. For Atracsys, just select NDI Polaris.
\li Then you name the tool, and for optical tracking, load the configuration file created above (See Figure 3). For EM tools you select NDI Aurora, and just name it. You do not need a .rom or .ini file.
\image html TrackingNameToolAndLoadConfig.png "Figure 3. Name the tool and for optical trackers add the config file created above."
\li Then you specify an identifier. For optical tools, this can be a string, and be the same as the Name. For EM tools,
it must be a number corresponding to the port, [0, 1, 2, 3]. For the NDI 7 sensor, EM shape tool, you have to create
7 tools, numbered: [0, 1, 2, 3, 101, 102, 103], as described <a href="https://cmiclab.cs.ucl.ac.uk/CMIC/NifTK/issues/4765">here</a>.
See Figure 4.
\image html TrackingSetIdentifier.png "Figure 4. Set the identifier, which for EM tools must be numeric [0, 1, 2, 3 (ports), 101, 102, 103]."
\li The process is repeated, adding tools to the same tool storage. Finally, you save the tool storage to a
filename of your choice, using the Save button in the "Select toolstorage" section. See Figure 5.
\image html TrackingAddMoreTools.png "Figure 5. Add multiple tools to the same tool storage, then save the tool storage with an appropriate name."
*/
# Mappings between .rom files and Atracsys geometry files
8700302.rom : geometry100.ini = NDI
8700338.rom : geometry101.ini = NDI
8700339.rom : geometry102.ini = NDI
8700340.rom : geometry103.ini = NDI Optical Pointer
8700449.rom : geometry104.ini = NDI
BigBlue.rom : geometry105.ini
SmallBlue.rom : geometry106.ini
Viking.rom : geometry107.ini
TrackedWoodenBlock.rom : geometry108.ini
0 2.777777778 2.986666667 0
1 8.333333333 2.986666667 0
2 13.88888889 2.986666667 0
3 19.44444444 2.986666667 0
4 25 2.986666667 0
5 30.55555556 2.986666667 0
6 36.11111111 2.986666667 0
7 41.66666667 2.986666667 0
8 47.22222222 2.986666667 0
9 52.77777778 2.986666667 0
10 58.33333333 2.986666667 0
11 63.88888889 2.986666667 0
12 69.44444444 2.986666667 0
13 75 2.986666667 0
14 80.55555556 2.986666667 0
15 86.11111111 2.986666667 0
16 91.66666667 2.986666667 0
17 97.22222222 2.986666667 0
18 2.777777778 8.96 0
19 8.333333333 8.96 0
20 13.88888889 8.96 0
21 19.44444444 8.96 0
22 25 8.96 0
23 30.55555556 8.96 0
24 36.11111111 8.96 0
25 41.66666667 8.96 0
26 47.22222222 8.96 0
27 52.77777778 8.96 0
28 58.33333333 8.96 0
29 63.88888889 8.96 0
30 69.44444444 8.96 0
31 75 8.96 0
32 80.55555556 8.96 0
33 86.11111111 8.96 0
34 91.66666667 8.96 0
35 97.22222222 8.96 0
36 2.777777778 14.93333333 0
37 8.333333333 14.93333333 0
38 13.88888889 14.93333333 0
39 19.44444444 14.93333333 0
40 25 14.93333333 0
41 30.55555556 14.93333333 0
42 36.11111111 14.93333333 0
43 41.66666667 14.93333333 0
44 47.22222222 14.93333333 0
45 52.77777778 14.93333333 0
46 58.33333333 14.93333333 0
47 63.88888889 14.93333333 0
48 69.44444444 14.93333333 0
49 75 14.93333333 0
50 80.55555556 14.93333333 0
51 86.11111111 14.93333333 0
52 91.66666667 14.93333333 0
53 97.22222222 14.93333333 0
54 2.777777778 20.90666667 0
55 8.333333333 20.90666667 0
56 13.88888889 20.90666667 0
57 19.44444444 20.90666667 0
58 25 20.90666667 0
59 30.55555556 20.90666667 0
60 36.11111111 20.90666667 0
61 41.66666667 20.90666667 0
62 47.22222222 20.90666667 0
63 52.77777778 20.90666667 0
64 58.33333333 20.90666667 0
65 63.88888889 20.90666667 0
66 69.44444444 20.90666667 0
67 75 20.90666667 0
68 80.55555556 20.90666667 0
69 86.11111111 20.90666667 0
70 91.66666667 20.90666667 0
71 97.22222222 20.90666667 0
72 2.777777778 26.88 0
73 8.333333333 26.88 0
74 13.88888889 26.88 0
75 19.44444444 26.88 0
76 25 26.88 0
77 30.55555556 26.88 0
78 36.11111111 26.88 0
79 41.66666667 26.88 0
80 47.22222222 26.88 0
81 52.77777778 26.88 0
82 58.33333333 26.88 0
83 63.88888889 26.88 0
84 69.44444444 26.88 0
85 75 26.88 0
86 80.55555556 26.88 0
87 86.11111111 26.88 0
88 91.66666667 26.88 0
89 97.22222222 26.88 0
90 2.777777778 32.85333333 0
91 8.333333333 32.85333333 0
92 13.88888889 32.85333333 0
93 19.44444444 32.85333333 0
94 25 32.85333333 0
95 30.55555556 32.85333333 0
96 36.11111111 32.85333333 0
97 41.66666667 32.85333333 0
98 47.22222222 32.85333333 0
99 52.77777778 32.85333333 0
100 58.33333333 32.85333333 0
101 63.88888889 32.85333333 0
102 69.44444444 32.85333333 0
103 75 32.85333333 0
104 80.55555556 32.85333333 0
105 86.11111111 32.85333333 0
106 91.66666667 32.85333333 0
107 97.22222222 32.85333333 0
108 2.777777778 38.82666667 0
109 8.333333333 38.82666667 0
110 13.88888889 38.82666667 0
111 19.44444444 38.82666667 0
112 25 38.82666667 0
113 30.55555556 38.82666667 0
114 36.11111111 38.82666667 0
115 41.66666667 38.82666667 0
116 47.22222222 38.82666667 0
117 52.77777778 38.82666667 0
118 58.33333333 38.82666667 0
119 63.88888889 38.82666667 0
120 69.44444444 38.82666667 0
121 75 38.82666667 0
122 80.55555556 38.82666667 0
123 86.11111111 38.82666667 0
124 91.66666667 38.82666667 0
125 97.22222222 38.82666667 0
126 2.777777778 44.8 0
127 8.333333333 44.8 0
128 13.88888889 44.8 0
129 19.44444444 44.8 0
130 25 44.8 0
131 30.55555556 44.8 0
132 36.11111111 44.8 0
133 41.66666667 44.8 0
134 47.22222222 44.8 0
135 52.77777778 44.8 0
136 58.33333333 44.8 0
137 63.88888889 44.8 0
138 69.44444444 44.8 0
139 75 44.8 0
140 80.55555556 44.8 0
141 86.11111111 44.8 0
142 91.66666667 44.8 0
143 97.22222222 44.8 0
144 2.777777778 50.77333333 0
145 8.333333333 50.77333333 0
146 13.88888889 50.77333333 0
147 19.44444444 50.77333333 0
148 25 50.77333333 0
149 30.55555556 50.77333333 0
150 36.11111111 50.77333333 0
151 41.66666667 50.77333333 0
152 47.22222222 50.77333333 0
153 52.77777778 50.77333333 0
154 58.33333333 50.77333333 0
155 63.88888889 50.77333333 0
156 69.44444444 50.77333333 0
157 75 50.77333333 0
158 80.55555556 50.77333333 0
159 86.11111111 50.77333333 0
160 91.66666667 50.77333333 0
161 97.22222222 50.77333333 0
162 2.777777778 56.74666667 0
163 8.333333333 56.74666667 0
164 13.88888889 56.74666667 0
165 19.44444444 56.74666667 0
166 25 56.74666667 0
167 30.55555556 56.74666667 0
168 36.11111111 56.74666667 0
169 41.66666667 56.74666667 0
170 47.22222222 56.74666667 0
171 52.77777778 56.74666667 0
172 58.33333333 56.74666667 0
173 63.88888889 56.74666667 0
174 69.44444444 56.74666667 0
175 75 56.74666667 0
176 80.55555556 56.74666667 0
177 86.11111111 56.74666667 0
178 91.66666667 56.74666667 0
179 97.22222222 56.74666667 0
180 2.777777778 62.72 0
181 8.333333333 62.72 0
182 13.88888889 62.72 0
183 19.44444444 62.72 0
184 25 62.72 0
185 30.55555556 62.72 0
186 36.11111111 62.72 0
187 41.66666667 62.72 0
188 47.22222222 62.72 0
189 52.77777778 62.72 0
190 58.33333333 62.72 0
191 63.88888889 62.72 0
192 69.44444444 62.72 0
193 75 62.72 0
194 80.55555556 62.72 0
195 86.11111111 62.72 0
196 91.66666667 62.72 0
197 97.22222222 62.72 0
198 2.777777778 68.69333333 0
199 8.333333333 68.69333333 0
200 13.88888889 68.69333333 0
201 19.44444444 68.69333333 0
202 25 68.69333333 0
203 30.55555556 68.69333333 0
204 36.11111111 68.69333333 0
205 41.66666667 68.69333333 0
206 47.22222222 68.69333333 0
207 52.77777778 68.69333333 0
208 58.33333333 68.69333333 0
209 63.88888889 68.69333333 0
210 69.44444444 68.69333333 0
211 75 68.69333333 0
212 80.55555556 68.69333333 0
213 86.11111111 68.69333333 0
214 91.66666667 68.69333333 0
215 97.22222222 68.69333333 0
<?xml version="1.0" encoding="UTF-8" ?>
<point_set_file>
<file_version>0.1</file_version>
<point_set>
<time_series>
<time_series_id>0</time_series_id>
<Geometry3D ImageGeometry="false" FrameOfReferenceID="0">
<IndexToWorld type="Matrix3x3" m_0_0="1" m_0_1="0" m_0_2="0" m_1_0="0" m_1_1="1" m_1_2="0" m_2_0="0" m_2_1="0" m_2_2="1" />
<Offset type="Vector3D" x="0" y="0" z="0" />
<Bounds>
<Min type="Vector3D" x="-10" y="-30" z="0" />
<Max type="Vector3D" x="140" y="-10" z="65.5" />
</Bounds>
</Geometry3D>
<point>
<id>0</id>
<specification>0</specification>
<x>0</x>
<y>-19</y>
<z>10</z>
</point>
<point>
<id>1</id>
<specification>0</specification>
<x>130</x>
<y>-19</y>
<z>10</z>
</point>
<point>
<id>2</id>
<specification>0</specification>
<x>0</x>
<y>-19</y>
<z>80</z>
</point>
<point>
<id>3</id>
<specification>0</specification>
<x>45.5</x>
<y>-19</y>
<z>55.5</z>
</point>
</time_series>
</point_set>
</point_set_file>
0 0 1 -10
1 0 0 0
4.62223e-33 1 -6.16298e-33 10
0 0 0 1
<?xml version="1.0" encoding="UTF-8" ?>
<point_set_file>
<file_version>0.1</file_version>
<point_set>
<time_series>
<time_series_id>0</time_series_id>
<Geometry3D ImageGeometry="false" FrameOfReferenceID="0">
<IndexToWorld type="Matrix3x3" m_0_0="1" m_0_1="0" m_0_2="0" m_1_0="0" m_1_1="1" m_1_2="0" m_2_0="0" m_2_1="0" m_2_2="1" />
<Offset type="Vector3D" x="0" y="0" z="0" />
<Bounds>
<Min type="Vector3D" x="-10" y="-10" z="-20" />
<Max type="Vector3D" x="80" y="140" z="0" />
</Bounds>
</Geometry3D>
<point>
<id>0</id>
<specification>0</specification>
<x>0</x>
<y>0</y>
<z>-9</z>
</point>
<point>
<id>1</id>
<specification>0</specification>
<x>0</x>
<y>130</y>
<z>-9</z>
</point>
<point>
<id>2</id>
<specification>0</specification>
<x>70</x>
<y>0</y>
<z>-9</z>
</point>
<point>
<id>3</id>
<specification>0</specification>
<x>45.5</x>
<y>45.5</y>
<z>-9</z>
</point>
</time_series>
</point_set>
</point_set_file>
<?xml version="1.0" encoding="UTF-8" ?>
<point_set_file>
<file_version>0.1</file_version>
<point_set>
<time_series>
<time_series_id>0</time_series_id>
<Geometry3D ImageGeometry="false" FrameOfReferenceID="0">
<IndexToWorld type="Matrix3x3" m_0_0="1" m_0_1="0" m_0_2="0" m_1_0="0" m_1_1="1" m_1_2="0" m_2_0="0" m_2_1="0" m_2_2="1" />
<Offset type="Vector3D" x="0" y="0" z="0" />
<Bounds>
<Min type="Vector3D" x="-10" y="-10" z="-20" />
<Max type="Vector3D" x="80" y="140" z="0" />
</Bounds>
</Geometry3D>
<point>
<id>0</id>
<specification>0</specification>
<x>130</x>
<y>-19</y>
<z>80</z>
</point>
<point>
<id>1</id>
<specification>0</specification>
<x>0</x>
<y>-19</y>
<z>80</z>
</point>
<point>
<id>2</id>
<specification>0</specification>
<x>130</x>
<y>-19</y>
<z>10</z>
</point>
<point>
<id>3</id>
<specification>0</specification>
<x>84.5</x>
<y>-19</y>
<z>34.5</z>
</point>
</time_series>
</point_set>
</point_set_file>
<?xml version="1.0" encoding="UTF-8" ?>
<point_set_file>
<file_version>0.1</file_version>
<point_set>
<time_series>
<time_series_id>0</time_series_id>
<Geometry3D ImageGeometry="false" FrameOfReferenceID="0">
<IndexToWorld type="Matrix3x3" m_0_0="1" m_0_1="0" m_0_2="0" m_1_0="0" m_1_1="1" m_1_2="0" m_2_0="0" m_2_1="0" m_2_2="1" />
<Offset type="Vector3D" x="0" y="0" z="0" />
<Bounds>
<Min type="Vector3D" x="-10" y="-10" z="-20" />
<Max type="Vector3D" x="80" y="140" z="0" />
</Bounds>
</Geometry3D>
<point>
<id>0</id>
<specification>0</specification>
<x>0</x>
<y>0</y>
<z>-9</z>
</point>
<point>
<id>1</id>
<specification>0</specification>
<x>0</x>
<y>130</y>
<z>-9</z>
</point>
<point>
<id>2</id>
<specification>0</specification>
<x>70</x>
<y>0</y>
<z>-9</z>
</point>
<point>
<id>3</id>
<specification>0</specification>
<x>45.5</x>
<y>45.5</y>
<z>-9</z>
</point>
</time_series>
</point_set>
</point_set_file>
; NDI 8700302
[geometry]
count=4
id=100
[fiducial0]
x=-113.00
y=-65.00
z=7.42
[fiducial1]
x=-113.00
y=43.00
z=7.42
[fiducial2]
x=-13.00
y=65.00
z=7.42
[fiducial3]
x=0.00
y=-65.00
z=7.42
; NDI 8700338
[geometry]
count=4
id=101