Mercurial > hg > orthanc-book
changeset 837:66ff2f30afcc
added new features from next upcoming Orthanc release
| author | Alain Mazy <am@osimis.io> |
|---|---|
| date | Tue, 03 May 2022 15:09:54 +0200 |
| parents | a9c35bf108fa |
| children | 6afc236cd60a |
| files | Sphinx/source/faq/features.rst Sphinx/source/faq/main-dicom-tags.rst Sphinx/source/faq/scalability.rst Sphinx/source/plugins.rst Sphinx/source/plugins/housekeeper.rst Sphinx/source/users/rest.rst |
| diffstat | 6 files changed, 319 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/faq/features.rst Tue May 03 14:13:57 2022 +0200 +++ b/Sphinx/source/faq/features.rst Tue May 03 15:09:54 2022 +0200 @@ -310,6 +310,7 @@ * ``Attachment 9998`` is used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store instance information. * ``Attachment 9999`` is used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store annotations. * ``Attachments 10000-13999`` are used by the :ref:`Osimis WebViewer plugin <osimis_webviewer>` to store reduced quality images. +* ``Global property 1025`` is used by default by the Housekeeper plugin. * ``Global property 5467`` is used by the Osimis Cloud plugin. * ``Global property 5468`` is used by the :ref:`DICOMweb plugin <dicomweb>` to store the DICOMweb servers into the Orthanc database. * ``Metadata 4200`` is used by the plugin for :ref:`whole-slide imaging <wsi>` with version <= 0.7.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/faq/main-dicom-tags.rst Tue May 03 15:09:54 2022 +0200 @@ -0,0 +1,144 @@ +.. _main-dicom-tags: + +Main DICOM Tags in DB +--------------------- + +Introduction +============ + +By default, Orthanc is saving a predefined subset of DICOM Tags +in the DB. These are called the ``MainDicomTags``. + +Since they are stored in DB, these tags can be retrieved very +quickly and can conveniently be used for filtering/finding resources +while, to access other DICOM tags, Orthanc needs to re-open the +DICOM file which is much slower. + +As of Orthanc 1.4.2 (and later), the predefined list is: + +* Patients: + * PatientName + * PatentID + * PatientBirthDate + * PatientSex + * OtherPatientIDs + +* Studies: + * StudyDate + * StudyTime + * StudyID + * StudyDescription + * AccessionNumber + * StudyInstanceUID + * RequestedProcedureDescription + * InstitutionName + * RequestingPhysician + * ReferringPhysicianName + +* Series: + * SeriesDate + * SeriesTime + * Modality + * Manufacturer + * StationName + * SeriesDescription + * BodyPartExamined + * SequenceName + * ProtocolName + * SeriesNumber + * CardiacNumberOfImages + * ImagesInAcquisition + * NumberOfTemporalPositions + * NumberOfSlices + * NumberOfTimeSlices + * SeriesInstanceUID + * ImageOrientationPatient + * SeriesType + * OperatorsName + * PerformedProcedureStepDescription + * AcquisitionDeviceProcessingDescription + * ContrastBolusAgent + +* Instances: + * InstanceCreationDate + * InstanceCreationTime + * AcquisitionNumber + * ImageIndex + * InstanceNumber + * NumberOfFrames + * TemporalPositionIdentifier + * SOPInstanceUID + * ImagePositionPatient + * ImageComments + * ImageOrientationPatient + + +Adding more tags in DB +====================== + +.. highlight:: json + +Since version 1.11.0 (not released yet), it is possible to +customize a list of ``ExtraMainDicomTags`` to include in the DB +through a new configuration option. + +Below is a sample configuration that is well suited to +optimize DICOMWeb routes in general, especially when you are using +a DICOMWeb viewer:: + + { + "ExtraMainDicomTags" : { + "Instance" : [ + "Rows", + "Columns", + "ImageType", + "SOPClassUID", + "ContentDate", + "ContentTime", + "FrameOfReferenceUID", + "PixelSpacing", + "SpecificCharacterSet", + "BitsAllocated", + "BitsStored" + ], + "Series" : [ + "TimezoneOffsetFromUTC", + "PerformedProcedureStepStartDate", + "PerformedProcedureStepStartTime" + ], + "Study": [ + "TimezoneOffsetFromUTC" + ], + "Patient": [] + } + } + +This configuration will apply only to newly added resources +in Orthanc. If you want to apply this change to resources +already in Orthanc, you may call the ``/studies/../reconstruct`` +API route or use the :ref:`Housekeeper plugin <housekeeper-plugin>` +to automate this reconstruction process. + + +Warnings +======== + +Since Orthanc 1.11.0, Orthanc issues a warning everytime +it opens a DICOM file to access a DICOM tag that could have +been saved in DB. + +Orthanc will also issue a warning everytime it accesses a resource +that has been saved with a ``ExtraMainDicomTags`` configuration that +is different from the current one inviting you to call the +``/reconstruct`` route to fix this. + +These warnings can be enabled/disabled through this configuration:: + + { + "Warnings" : { + "W001_TagsBeingReadFromStorage": true, + "W002_InconsistentDicomTagsInDb": true + } + } + +
--- a/Sphinx/source/faq/scalability.rst Tue May 03 14:13:57 2022 +0200 +++ b/Sphinx/source/faq/scalability.rst Tue May 03 15:09:54 2022 +0200 @@ -108,7 +108,12 @@ scenario is having one "writer" Orthanc server that handles the ingesting of DICOM instances, and multiple "reader" Orthanc servers with features such as DICOMweb or viewers. - + +* From Orthanc 1.11.0 (not released yet): you have the ability to add + more :ref:`main DICOM tags <main-dicom-tags>` in the Orthanc Index + to speed up C-Find, ``tools/find``, DICOMWeb QIDO-RS, WADO-RS and + especially WADO-RS Retrieve Metadata. + * Make sure to carefully :ref:`read the logs <log>` in ``--verbose`` mode, especially at the startup of Orthanc. The logs may contain very important information regarding performance.
--- a/Sphinx/source/plugins.rst Tue May 03 14:13:57 2022 +0200 +++ b/Sphinx/source/plugins.rst Tue May 03 15:09:54 2022 +0200 @@ -69,6 +69,7 @@ plugins/odbc.rst plugins/osimis-webviewer.rst plugins/authorization.rst + plugins/housekeeper.rst .. _plugins-uclouvain:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/plugins/housekeeper.rst Tue May 03 15:09:54 2022 +0200 @@ -0,0 +1,124 @@ +.. _housekeeper-plugin: + + +Housekeeper plugin (not released yet) +========================= + +This page describes the **official sample plugin** that performs +housekeeping in the Database and Storage. + +When changing some configuration or when upgrading Orthanc, it +might be usefull to perform housekeeping operations to optmize +the DB or clean/compress/uncompress the storage. This can happen e.g: + +* when changing the list of indexed :ref:`MainDicomTags <_main-dicom-tags>` +* when changing the ``StorageCompression`` configuration +* when changing the ``IngestTranscoding`` configuration +* to remove unnecessary attachments like the ``dicom-as-json`` that were + used in Orthanc prior to 1.9.1. + +Note that these housekeeping operations are not mandatory. Orthanc will +continue to work without these cleanups. However, running the plugin +might improve performances and storage usage. + +The plugin detects any configuration changes that can trigger a cleanup +and will start process the studies one by one (in the order they have +been ingested in Orthanc). If Orthanc is stopped and restarted, the plugin +will resume where it stopped. + + +Configuration +------------- + +.. highlight:: json + +Here's a sample configuration section for this plugin with its default values:: + + { + "Housekeeper": { + + // Enables/disables the plugin + "Enable": false, + + // the Global Prooperty ID in which the plugin progress + // is stored. Must be > 1024 and must not be used by + // another plugin + "GlobalPropertyId": 1025, + + // Forces execution even if the plugin did not detect + // any changes in configuration + "Force": false, + + // Delay (in seconds) between reconstruction of 2 studies + // This avoids overloading Orthanc with the housekeeping + // process and leaves room for other operations. + "ThrottleDelay": 5, + + // Runs the plugin only at certain period of time. + // If not specified, the plugin runs all the time + // Examples: + // to run between 0AM and 6AM everyday + every night + // from 8PM to 12PM and 24h a day on the weekend: + // "Schedule": { + // "Monday": ["0-6", "20-24"], + // "Tuesday": ["0-6", "20-24"], + // "Wednesday": ["0-6", "20-24"], + // "Thursday": ["0-6", "20-24"], + // "Friday": ["0-6", "20-24"], + // "Saturday": ["0-24"], + // "Sunday": ["0-24"] + // }, + + // configure events that can trigger a housekeeping processing + "Triggers" : { + "StorageCompressionChange": true, + "MainDicomTagsChange": true, + "UnnecessaryDicomAsJsonFiles": true, + "IngestTranscodingChange": true + } + } + } + +Scheduling/throttling +--------------------- + +Processing a whole database/storage might take a very long time (days, weeks +or even months) and can be I/O & CPU intensive. Therefore, the configuration offers +options to schedule and/or throttle the housekeeping operations. E.g, you can +run only the plugin during the night and week-end and, you can introduce a delay +between each processed study. + +Triggers & internals +-------------------- + +By default, all triggers are enabled. Depending on the detected change, +various operations will happen: + +* if ``MainDicomTagsChange`` or ``UnnecessaryDicomAsJsonFiles`` is triggered, + the plugin will call the ``/studies/.../reconstruct`` route on every study + one by one. Orthanc will read the DICOM tags from the DICOM files again and update + their value in the DB. + +* if any other change is detected, the plugin will again call the ``reconstruct`` route + but, this time, with the ``ReconstructFiles`` option enabled. Orthanc will then, + read the DICOM file from the storage, compress/uncompress/transcode it and it will + save it again to disk. The new file will be stored using the new Storage settings + (``StorageCompression`` and ``IngestTranscoding``). + Note that, Orthanc will create a new ``Attachment`` that will be saved at a different + place as the previous one. + + +Status +------ + +You can get a progress status of the plugin by calling the ``/housekeeper/status`` API route. + + +Compilation +----------- + +This plugin is part of the Orthanc core repository and is included in the Orthanc makefile. +It is compiled with Orthanc itself and is distributed together with Orthanc binaries. + + +
--- a/Sphinx/source/users/rest.rst Tue May 03 14:13:57 2022 +0200 +++ b/Sphinx/source/users/rest.rst Tue May 03 15:09:54 2022 +0200 @@ -1094,6 +1094,49 @@ "Limit":4 +.. highlight:: bash + +Since Orthanc 1.11.0 (not released yet), you may also request a specific list of tags in the response (like in a C-FIND) even if these +tags are not stored in the MainDicomTags or if the tags needs to be computed (like ``ModalitiesInStudy``). This ``RequestedTags`` option is +available only if you specify ``"Expand": true``:: + + $ curl -X POST http://localhost:8042/tools/find -d ' + { + "Level": "Studies", + "Expand": true, + "Query": { + "StudyDate": "20220502" + }, + "RequestedTags": ["PatientName", "PatientID", "StudyDescription", "StudyDate", "StudyInstanceUID", "ModalitiesInStudy", "NumberOfStudyRelatedSeries"] + }' + +.. highlight:: json + +This query will return a response like this one:: + + [ + { + "ID" : "8a8cf898-ca27c490-d0c7058c-929d0581-2bbf104d", + "IsStable" : true, + "LastUpdate" : "20220428T074549", + "MainDicomTags" : { + "...":"..." + }, + "..." : "...", + "RequestedTags" : { + "PatientName" : "Patient", + "PatientID" : "1", + "StudyDescription" : "Description", + "StudyDate" : "20220502", + "StudyInstanceUID" : "1.2.3", + "ModalitiesInStudy" : "CT\\SEG\\SR", + "NumberOfStudyRelatedSeries" : "3" + }, + "Series" : [ "93034833-163e42c3-bc9a428b-194620cf-2c5799e5" ], + "Type" : "Study" + } + ] + .. _changes: