changeset 1070:55c44a245b09

documenting Nexus support in STL plugin 1.1
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 22 May 2024 17:00:10 +0200
parents a714c5fdc4cf
children 63a3d4e82c2a
files Sphinx/source/plugins/stl.rst Sphinx/source/plugins/stl/nexus.png Sphinx/source/plugins/stl/nexus.py
diffstat 3 files changed, 93 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/plugins/stl.rst	Tue May 21 12:34:32 2024 +0200
+++ b/Sphinx/source/plugins/stl.rst	Wed May 22 17:00:10 2024 +0200
@@ -265,3 +265,73 @@
 
 .. literalinclude:: stl/nifti.py
                     :language: python
+
+
+Support for Nexus
+-----------------
+
+Starting with release 1.1, the STL plugin provides support for the
+DICOM-ization of 3D models encoded using the `Nexus file format (.NXZ)
+<https://vcg.isti.cnr.it/nexus/>`__. Nexus provides a way to publish
+large, **textured 3D models** over Internet, with **adaptive
+rendering** depending on the available network bandwidth. Nexus is
+notably popular for the preservation of **cultural heritage**.
+
+
+The plugin ships the static HTML/CSS/JavaScript assets of the official
+Nexus Web viewer, so that it can easily be opened right from Orthanc
+Explorer, as depicted in the following screenshot:
+
+.. image:: stl/nexus.png
+           :align: center
+           :width: 800
+
+
+Internals
+^^^^^^^^^
+
+Because Nexus is not endorsed by the DICOM specification, the plugin
+encapsulates the Nexus file using the `Raw Data IOD
+<https://dicom.nema.org/medical/dicom/current/output/chtml/part03/sect_A.37.3.html>`__.
+The Nexus file is encoded as the ``(0x4205,0x1001)`` private DICOM
+tag.
+
+
+Configuration
+^^^^^^^^^^^^^
+
+.. highlight:: json
+
+As it is non-standard, support for Nexus must be explicitly enabled in
+the configuration file of Orthanc as follows::
+
+  {
+    "Plugins" : [ "libOrthancSTL.so" ],
+    "STL" : {
+      "EnableNexus" : true
+    }
+  }
+
+
+REST API
+^^^^^^^^
+
+The STL plugin extends the REST API with two routes that are dedicated
+to the handling of Nexus files:
+
+1. ``/stl/create-nexus`` can be used to DICOM-ize a Nexus file. This
+   route is a wrapper around the ``/tools/create-dicom``
+   :ref:`standard route of Orthanc <image-dicomization>`. The Nexus
+   file must be provided as a `Base64 string
+   <https://en.wikipedia.org/wiki/Base64>`__ in the ``Content`` field
+   of the request. Here is a sample Python script::
+
+.. literalinclude:: stl/nexus.py
+                    :language: python
+
+2. ``/instances/{id}/nexus`` provides access to a DICOM-ized Nexus
+   file by decapsulating it from the DICOM instance whose
+   :ref:`Orthanc identifier <orthanc-identifiers>` is
+   ``id``. Importantly, this route supports `HTTP range requests
+   <https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests>`__
+   for adaptive streaming of Nexus models over Internet.
Binary file Sphinx/source/plugins/stl/nexus.png has changed
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/stl/nexus.py	Wed May 22 17:00:10 2024 +0200
@@ -0,0 +1,23 @@
+import base64
+import json
+import requests
+
+with open('/tmp/model.nxz', 'rb') as f:
+    nexus = f.read()
+
+r = requests.post('http://localhost:8042/stl/create-nexus', json.dumps({
+    'Content' : base64.b64encode(nexus).decode('ascii'),
+    'Parent' : '66c8e41e-ac3a9029-0b85e42a-8195ee0a-92c2e62e',
+    'Tags' : {
+        'SeriesDescription' : 'Nexus',
+
+        # Some additional tags to make the DICOM file compliant according to dciodvfy
+        'AcquisitionContextSequence' : [],
+        'InstanceNumber' : '1',
+        'Laterality' : '',
+        'SeriesNumber' : '1',
+    }
+}))
+
+r.raise_for_status()
+instanceId = r.json() ['ID']