Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/stl.rst @ 1057:5a3c238575f8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation of stl
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 09 Apr 2024 16:29:42 +0200
parents 89bb195dfbc0
children 30c90ac3e3d6
comparison
equal deleted inserted replaced
1056:89bb195dfbc0 1057:5a3c238575f8
11 -------- 11 --------
12 12
13 This **official** plugin by the `ICTEAM institute of UCLouvain 13 This **official** plugin by the `ICTEAM institute of UCLouvain
14 <https://orthanc.uclouvain.be/>`__ extends Orthanc with support for 14 <https://orthanc.uclouvain.be/>`__ extends Orthanc with support for
15 `Encapsulated 3D Manufacturing Model IODs 15 `Encapsulated 3D Manufacturing Model IODs
16 <https://dicom.nema.org/medical/dicom/current/output/chtml/part03/sect_A.85.html>`_, 16 <https://dicom.nema.org/medical/dicom/current/output/chtml/part03/sect_A.85.html>`_.
17 for the moment limited to `STL files 17 As of release 1.0 of the plugin, this support is limited to `STL files
18 <https://en.wikipedia.org/wiki/STL_(file_format)>`__. 18 <https://en.wikipedia.org/wiki/STL_(file_format)>`__.
19 19
20 The plugin allows to attach STL files to existing DICOM studies and to 20 The plugin allows to attach STL files to existing DICOM studies and to
21 generate a STL mesh from structure sets (i.e., DICOM RT-STRUCT) or 21 generate a STL mesh from structure sets (i.e., DICOM RT-STRUCT) or
22 from `NIfTI binary volumes 22 from `NIfTI binary volumes
23 <https://en.wikipedia.org/wiki/Neuroimaging_Informatics_Technology_Initiative>`__. 23 <https://en.wikipedia.org/wiki/Neuroimaging_Informatics_Technology_Initiative>`__.
24 The description of these features is `available as a paper 24 A high-level description of these features is `available as a paper
25 <https://doi.org/10.1145/3632047.3632051>`__. 25 <https://doi.org/10.1145/3632047.3632051>`__.
26
27 Importantly, any creation of a STL file requires the version of
28 Orthanc to be above or equal to 1.12.1.
26 29
27 **For researchers**: `Please cite this paper 30 **For researchers**: `Please cite this paper
28 <https://doi.org/10.1145/3632047.3632051>`__. 31 <https://doi.org/10.1145/3632047.3632051>`__.
29 32
30 33
31 Usage 34 Compilation
32 ----- 35 -----------
33 36
34 WIP. 37 .. highlight:: bash
38
39 Official releases can be `downloaded from the Orthanc homepage
40 <https://orthanc.uclouvain.be/downloads/sources/orthanc-stl/index.html>`__. As
41 an alternative, the `repository containing the source code
42 <https://orthanc.uclouvain.be/hg/orthanc-stl/>`__ can be accessed
43 using Mercurial.
44
45 The procedure to compile this plugin is similar of that for the
46 :ref:`core of Orthanc <binaries>`. The following commands should work
47 on most GNU/Linux distributions, provided Docker is installed::
48
49 $ mkdir Build
50 $ cd Build
51 $ ../Resources/CreateJavaScriptLibraries.sh
52 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
53 $ make
54
55 The compilation will produce a shared library ``libOrthancSTL.so``
56 that contains the STL plugin for Orthanc.
57
58 Pre-compiled Linux Standard Base (LSB) binaries `are available for
59 download <https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc-stl/index.html>`__.
60
61 Pre-compiled binaries for `Microsoft Windows <https://orthanc.uclouvain.be/downloads/windows-32/orthanc-stl/index.html>`__
62 and `macOS <https://orthanc.uclouvain.be/downloads/macos/orthanc-stl/index.html>`__ are available as well.
63
64 Furthermore, the :ref:`Docker images <docker>`
65 ``jodogne/orthanc-plugins`` and ``orthancteam/orthanc`` also contain the
66 plugin. Debian and Ubuntu packages can be found in the
67 :ref:`standalone repository <binaries>`
68 ``https://debian.orthanc-labs.com/``.
69
70
71 .. _stl_orthanc_explorer:
72
73 Usage using Orthanc Explorer
74 ----------------------------
75
76 The plugin extends the default :ref:`Orthanc Explorer
77 <orthanc-explorer>` Web interface with some new features.
78
79
80 .. _stl_attach:
81
82 Attach STL file
83 ^^^^^^^^^^^^^^^
84
85 An existing STL file can be attached to an existing DICOM study by
86 clicking on the "*Attach STL model*" yellow button:
87
88 .. image:: stl/attach.png
89 :align: center
90 :width: 480
91
92 After selecting the STL file, entering a series description, and
93 clicking on the "*Import*" button, Orthanc creates a new DICOM
94 instance that embeds the STL file. Orthanc Explorer then automatically
95 opens the parent DICOM series containing the newly created DICOM STL
96 instance. A button entitled "*STL viewer*" can then be used to render
97 the STL:
98
99 .. image:: stl/viewers.png
100 :align: center
101 :width: 480
102
103 Note how the STL plugin provides two viewers:
104
105 * One `very basic custom viewer
106 <https://orthanc.uclouvain.be/hg/orthanc-stl/file/OrthancSTL-1.0/WebApplications/three.js>`__
107 with a small footprint that is directly built using the well-known
108 `Three.js library <https://en.wikipedia.org/wiki/Three.js>`__.
109
110 * One slightly more advanced Web viewer that corresponds to
111 `Online3DViewer <https://3dviewer.net/>`__ running in `engine mode
112 <https://kovacsv.github.io/Online3DViewer/Page_Usage.html>`__.
113
114 Here is a screenshot of a rendering using the Online3DViewer embedded
115 viewer:
116
117 .. image:: stl/o3dv.png
118 :align: center
119 :width: 480
120
121
122 .. _stl_rt_struct:
123
124 Create STL from RT-STRUCT
125 ^^^^^^^^^^^^^^^^^^^^^^^^^
126
127 The plugin can also be used to create a STL model from DICOM structure
128 sets (RT-STRUCT) that are routinely used in the context of
129 radiotherapy and nuclear medicine. To this end, open a DICOM RT-STRUCT
130 series using Orthanc Explorer:
131
132 .. image:: stl/rt-struct.png
133 :align: center
134 :width: 480
135
136 As can be seen in this screenshot, an interface opens to choose the
137 structure set of interest, as well as the resolution of the
138 intermediate 3D bitmap that will be used to create the STL mesh. After
139 clicking on the "*Generate*" button, just like if :ref:`attaching an
140 existing STL file <stl_attach>`, Orthanc Explorer will open the newly
141 created DICOM series and will propose to open a STL viewer.
142
143 Internally, the 3D model is generated using the well-known `marching
144 cubes algorithm <https://en.wikipedia.org/wiki/Marching_cubes>`__, as
145 implemented by the `VTK library <https://en.wikipedia.org/wiki/VTK>`__
146 by Kitware. Additional technical details can be found in the
147 `reference paper <https://doi.org/10.1145/3632047.3632051>`__.
148
149
150 Create STL from binary NIfTI
151 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
152
153 .. highlight:: json
154
155 Besides converting :ref:`RT-STRUCT to STL <stl_rt_struct>`, it is also
156 possible to convert a `NIfTI
157 <https://en.wikipedia.org/wiki/Neuroimaging_Informatics_Technology_Initiative>`__
158 3D binary bitmap into a STL mesh. As this use case is very specific,
159 it must be explicitly enabled in the :ref:`configuration file of
160 Orthanc <configuration>` as follows::
161
162 {
163 "Plugins" : [ "libOrthancSTL.so" ],
164 "STL" : {
165 "EnableNIfTI" : true
166 }
167 }
168
169 If the ``EnableNIfTI`` option is present, a new button entitled
170 "*Attach NIfTI 3D model*" appears if opening an existing DICOM study:
171
172 .. image:: stl/nifti.png
173 :align: center
174 :width: 480
175
176 This dialog box can be used to upload a NIfTI volume, and to generate
177 a 3D mesh with a specific resolution through the marching cubes
178 algorithm.
179
180
181 REST API
182 --------
183
184 Besides :ref:`extending the Orthanc Explorer user interface
185 <stl_orthanc_explorer>`, the STL plugin adds dedicated routes to the
186 REST API of Orthanc.
187
188
189 DICOM-ization of STL files
190 ^^^^^^^^^^^^^^^^^^^^^^^^^^
191
192 The creation of a DICOM instance that embeds an existing STL file can
193 be done using the ``/tools/create-dicom`` `route
194 <https://orthanc.uclouvain.be/api/#tag/System/paths/~1tools~1create-dicom/post>`__
195 in the built-in REST API of Orthanc (starting with version
196 1.12.1). This route can be used similarly to the :ref:`DICOM-ization
197 of PDF files <pdf>`, with the `data URI scheme
198 <https://en.wikipedia.org/wiki/Data_URI_scheme>`__ using ``model/stl``
199 instead of ``application/pdf``. Here is a working example in Python 3:
200
201 .. literalinclude:: stl/dicomize.py
202 :language: python
203
204 Note that if the ``Parent`` field is not provided, a new DICOM study
205 will be created.
206
207
208 Extraction of STL from DICOM
209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
210
211 .. highlight:: txt
212
213 The route ``/instances/{id}/stl`` can be used to extract a STL from a
214 DICOM instance embedding a STL file, where ``id`` is the :ref:`Orthanc
215 identifier <orthanc-ids>` of the DICOM instance. For instance::
216
217 $ curl http://localhost:8042/instances/a88c4c3f-8f2bd6fd-02080bed-92ab6817-2cb3c26e/stl > /tmp/liver.stl
218 $ meshlab /tmp/liver.stl
219
220 Evidently, an error is generated for DICOM instances that do not embed
221 a STL file. Note that ``meshlab`` is a well-known desktop application
222 to display STL file.
223
224
225 Listing structures of a DICOM RT-STRUCT
226 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
227
228 .. highlight:: txt
229
230 The STL plugin provides the list of the names of the structures that
231 are part of a DICOM RT-STRUCT instance with :ref:`Orthanc identifier
232 <orthanc-ids>` ``id`` at route ``/stl/rt-struct/{id}``. For instance::
233
234 $ curl http://localhost:8042/stl/rt-struct/f0dc2345-8f627774-f66083ae-a14d781e-1187b513
235 [
236 "Esophagus",
237 "Heart",
238 "Lung_L",
239 "Lung_R",
240 "SpinalCord"
241 ]
242
243
244 Generating a STL mesh from RT-STRUCT
245 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
246
247 A DICOM RT-STRUCT instance can be converted into a DICOM STL instance
248 using the ``/stl/encode-rtstruct`` route provided by the STL plugin.
249 Here is a sample Python script:
250
251 .. literalinclude:: stl/rt-struct.py
252 :language: python
253
254 Note that contrarily to :ref:`the default user interface
255 <stl_rt_struct>`, this route can be used to encode multiple structure
256 sets as a single STL model.
257
258
259 Generating a STL mesh from NIfTI
260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
261
262 Here is a sample Python 3 script to convert a NIfTI file as a DICOM
263 STL instance:
264
265 .. literalinclude:: stl/nifti.py
266 :language: python