Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/stl.rst @ 1057:5a3c238575f8
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 |