Mercurial > hg > orthanc-book

changeset 1120:3bd012947014

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
moved tools/find section up in the TOC
author Alain Mazy <am@orthanc.team>
date Thu, 12 Dec 2024 10:55:24 +0100
parents 6cc874fba817
children f45af556efae 292479b06402
files Sphinx/source/users/rest.rst
diffstat 1 files changed, 177 insertions(+), 178 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/users/rest.rst	Thu Dec 12 10:50:18 2024 +0100
+++ b/Sphinx/source/users/rest.rst	Thu Dec 12 10:55:24 2024 +0100
@@ -538,6 +538,181 @@
   $ curl http://localhost:8042/instances/e465dd27-83c96343-96848735-7035a133-1facf1a0/frames/0/raw > sample.mp4
 
 
+
+.. _rest-find:
+
+Finding resources within Orthanc
+--------------------------------
+
+.. highlight:: bash
+
+Performing a find within the local database of Orthanc is very similar
+to using Queries against DICOM modalities and the additional options
+listed above work with find also.  When performing a find, you will
+receive the Orthanc ID's of all the matched items within your
+find. For example if you perform a study level find and 5 Studies
+match you will receive 5 study level Orthanc ID's in JSON format as a
+response::
+
+  $ curl --request POST --url http://localhost:8042/tools/find \
+    --data '{
+              "Level" : "Instance",
+              "Query" : {
+                "Modality" : "CR",
+                "StudyDate" : "20180323-",
+                "PatientID" : "*"
+              }
+            }'
+
+Setting the ``Expand`` field to ``true`` in the POST body of the
+query will automatically report details about each study::
+
+  $ curl https://orthanc.uclouvain.be/demo/tools/find -d '{"Level":"Study","Query":{"PatientName":"KNIX"}}'
+  [
+    "b9c08539-26f93bde-c81ab0d7-bffaf2cb-a4d0bdd0"
+  ]
+  $ curl https://orthanc.uclouvain.be/demo/tools/find -d '{"Level":"Study","Query":{"PatientName":"KNIX"},"Expand":true}'
+  [
+    {
+      "ID" : "b9c08539-26f93bde-c81ab0d7-bffaf2cb-a4d0bdd0",
+      "IsStable" : true,
+      "LastUpdate" : "20180414T091528",
+      "MainDicomTags" : {
+         "InstitutionName" : "0ECJ52puWpVIjTuhnBA0um",
+         "ReferringPhysicianName" : "1",
+         "StudyDate" : "20070101",
+         "StudyDescription" : "Knee (R)",
+         "StudyID" : "1",
+         "StudyInstanceUID" : "1.2.840.113619.2.176.2025.1499492.7391.1171285944.390",
+         "StudyTime" : "120000.000000"
+      },
+      "ParentPatient" : "6816cb19-844d5aee-85245eba-28e841e6-2414fae2",
+      "PatientMainDicomTags" : {
+         "PatientID" : "ozp00SjY2xG",
+         "PatientName" : "KNIX"
+      },
+      "Series" : [
+         "20b9d0c2-97d85e07-f4dbf4d2-f09e7e6a-0c19062e",
+         "edbfa0a9-fa2641d7-29514b1c-45881d0b-46c374bd",
+         "f2635388-f01d497a-15f7c06b-ad7dba06-c4c599fe",
+         "4d04593b-953ced51-87e93f11-ae4cf03c-25defdcd",
+         "5e343c3e-3633c396-03aefde8-ba0e08c7-9c8208d3",
+         "8ea120d7-5057d919-837dfbcc-ccd04e0f-7f3a94aa"
+      ],
+      "Type" : "Study"
+    }
+  ]
+
+Here is a sample REST API call to find the Orthanc identifiers of all
+the DICOM series generated by an imaging modality whose "Device Serial
+Number (0018,1000)" DICOM tag is equal to "123"::
+
+  $ curl -X POST http://localhost:8042/tools/find -d '{"Level":"Series","Query":{"DeviceSerialNumber":"123"},"Expand":true}'
+
+If you are interested by a **list of several items** (in this case, in
+a list of serial numbers), just separate them with backslashes as
+would do with DICOM C-FIND::
+
+  $ curl -X POST http://localhost:8042/tools/find -d '{"Level":"Series","Query":{"DeviceSerialNumber":"123\\abc"},"Expand":true}'
+
+ 
+Additional ``/tools/find`` options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. highlight:: json
+
+You also have the ability to limit the responses by specifying a limit within the body of the POST message. For example::
+
+  "Limit":4
+
+.. highlight:: bash
+
+Since Orthanc 1.11.0, 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"
+   }
+  ]
+
+
+**Important:** Starting with Orthanc 1.12.0, this route in the REST
+API also provide the ``Labels`` and ``LabelsConstraint`` options to
+bring support for :ref:`labels <labels>`.
+
+
+Additional ``/tools/find`` options (new in Orthanc 1.12.5)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. highlight:: bash
+
+Starting with Orthanc 1.12.5 and for DB backends supporting the ``ExtendedFind`` 
+extension (SQLite DB and PostgreSQL 7.0+), you also have the ability to 
+order the results, filter by metadata values and precisely define the content of the
+response.  Check the `API documentation <https://orthanc.uclouvain.be/api/index.html#tag/System/paths/~1tools~1find/post>`__ for full details. A full option call will look like::
+
+  $ curl -X POST http://localhost:8042/tools/find -d ' \
+    {
+      "Level": "Studies",
+      "Query": {
+        "StudyDate": "20200101-"
+      },
+      "MetadataQuery": {
+        "my-metadata": "value*"
+      },
+      "OrderBy": [
+        {
+          "Type": "DicomTag",
+          "Key": "StudyDate",
+          "Direction": "ASC"
+        },
+        {
+          "Type": "Metadata",
+          "Key": "my-metadata",
+          "Direction": "DESC"
+        }
+      ],
+      "Labels": ["Toto", "Tutu"],
+      "LabelsConstraint": "Any",
+      "ParentPatient": "93034833-163e42c3-bc9a428b-194620cf-2c5799e5",
+
+      "ResponseContent": ["MainDicomTags", "Metadata", "Children", "Labels", "Attachments"],
+      "RequestedTags": ["PatientName", "PatientID", "StudyDescription", "StudyDate", "StudyInstanceUID", "ModalitiesInStudy", "NumberOfStudyRelatedSeries"]
+    }'
+
+
 .. _peering:
 
 Sending resources to remote Orthanc over HTTP/HTTPS (through Orthanc peering)
@@ -841,7 +1016,7 @@
 
 
 Performing C-Get (coming in Orthanc 1.12.6)
----------------------------------------
+-------------------------------------------
 
 .. highlight:: bash
 
@@ -1117,182 +1292,6 @@
   }
 
 
-
-.. _rest-find:
-
-Finding resources within Orthanc
---------------------------------
-
-.. highlight:: bash
-
-Performing a find within the local database of Orthanc is very similar
-to using Queries against DICOM modalities and the additional options
-listed above work with find also.  When performing a find, you will
-receive the Orthanc ID's of all the matched items within your
-find. For example if you perform a study level find and 5 Studies
-match you will receive 5 study level Orthanc ID's in JSON format as a
-response::
-
-  $ curl --request POST --url http://localhost:8042/tools/find \
-    --data '{
-              "Level" : "Instance",
-              "Query" : {
-                "Modality" : "CR",
-                "StudyDate" : "20180323-",
-                "PatientID" : "*"
-              }
-            }'
-
-Setting the ``Expand`` field to ``true`` in the POST body of the
-query will automatically report details about each study::
-
-  $ curl https://orthanc.uclouvain.be/demo/tools/find -d '{"Level":"Study","Query":{"PatientName":"KNIX"}}'
-  [
-    "b9c08539-26f93bde-c81ab0d7-bffaf2cb-a4d0bdd0"
-  ]
-  $ curl https://orthanc.uclouvain.be/demo/tools/find -d '{"Level":"Study","Query":{"PatientName":"KNIX"},"Expand":true}'
-  [
-    {
-      "ID" : "b9c08539-26f93bde-c81ab0d7-bffaf2cb-a4d0bdd0",
-      "IsStable" : true,
-      "LastUpdate" : "20180414T091528",
-      "MainDicomTags" : {
-         "InstitutionName" : "0ECJ52puWpVIjTuhnBA0um",
-         "ReferringPhysicianName" : "1",
-         "StudyDate" : "20070101",
-         "StudyDescription" : "Knee (R)",
-         "StudyID" : "1",
-         "StudyInstanceUID" : "1.2.840.113619.2.176.2025.1499492.7391.1171285944.390",
-         "StudyTime" : "120000.000000"
-      },
-      "ParentPatient" : "6816cb19-844d5aee-85245eba-28e841e6-2414fae2",
-      "PatientMainDicomTags" : {
-         "PatientID" : "ozp00SjY2xG",
-         "PatientName" : "KNIX"
-      },
-      "Series" : [
-         "20b9d0c2-97d85e07-f4dbf4d2-f09e7e6a-0c19062e",
-         "edbfa0a9-fa2641d7-29514b1c-45881d0b-46c374bd",
-         "f2635388-f01d497a-15f7c06b-ad7dba06-c4c599fe",
-         "4d04593b-953ced51-87e93f11-ae4cf03c-25defdcd",
-         "5e343c3e-3633c396-03aefde8-ba0e08c7-9c8208d3",
-         "8ea120d7-5057d919-837dfbcc-ccd04e0f-7f3a94aa"
-      ],
-      "Type" : "Study"
-    }
-  ]
-
-Here is a sample REST API call to find the Orthanc identifiers of all
-the DICOM series generated by an imaging modality whose "Device Serial
-Number (0018,1000)" DICOM tag is equal to "123"::
-
-  $ curl -X POST http://localhost:8042/tools/find -d '{"Level":"Series","Query":{"DeviceSerialNumber":"123"},"Expand":true}'
-
-If you are interested by a **list of several items** (in this case, in
-a list of serial numbers), just separate them with backslashes as
-would do with DICOM C-FIND::
-
-  $ curl -X POST http://localhost:8042/tools/find -d '{"Level":"Series","Query":{"DeviceSerialNumber":"123\\abc"},"Expand":true}'
-
- 
-Additional ``/tools/find`` options
-^^^^^^^^^^^^^^^^^^
-.. highlight:: json
-
-You also have the ability to limit the responses by specifying a limit within the body of the POST message. For example::
-
-  "Limit":4
-
-.. highlight:: bash
-
-Since Orthanc 1.11.0, 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"
-   }
-  ]
-
-
-**Important:** Starting with Orthanc 1.12.0, this route in the REST
-API also provide the ``Labels`` and ``LabelsConstraint`` options to
-bring support for :ref:`labels <labels>`.
-
-
-Additional ``/tools/find`` options (new in Orthanc 1.12.5)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. highlight:: bash
-
-Starting with Orthanc 1.12.5 and for DB backends supporting the ``ExtendedFind`` 
-extension (SQLite DB and PostgreSQL 7.0+), you also have the ability to 
-order the results, filter by metadata values and precisely define the content of the
-response.  Check the `API documentation <https://orthanc.uclouvain.be/api/index.html#tag/System/paths/~1tools~1find/post>`__ for full details. A full option call will look like::
-
-  $ curl -X POST http://localhost:8042/tools/find -d ' \
-    {
-      "Level": "Studies",
-      "Query": {
-        "StudyDate": "20200101-"
-      },
-      "MetadataQuery": {
-        "my-metadata": "value*"
-      },
-      "OrderBy": [
-        {
-          "Type": "DicomTag",
-          "Key": "StudyDate",
-          "Direction": "ASC"
-        },
-        {
-          "Type": "Metadata",
-          "Key": "my-metadata",
-          "Direction": "DESC"
-        }
-      ],
-      "Labels": ["Toto", "Tutu"],
-      "LabelsConstraint": "Any",
-      "ParentPatient": "93034833-163e42c3-bc9a428b-194620cf-2c5799e5",
-
-      "ResponseContent": ["MainDicomTags", "Metadata", "Children", "Labels", "Attachments"],
-      "RequestedTags": ["PatientName", "PatientID", "StudyDescription", "StudyDate", "StudyInstanceUID", "ModalitiesInStudy", "NumberOfStudyRelatedSeries"]
-    }'
-
-
-
 .. _changes:
 
 Tracking changes
@@ -1386,7 +1385,7 @@
 shows how to use this Changes API to implement a polling loop.
 
 Additional ``/changes`` options (new in Orthanc 1.12.5)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. highlight:: bash