# HG changeset patch # User Alain Mazy # Date 1733997324 -3600 # Node ID 3bd01294701451a82d7910603c7cce3443e37f87 # Parent 6cc874fba817aec2e3114f5fde198bcb4bcf6d54 moved tools/find section up in the TOC diff -r 6cc874fba817 -r 3bd012947014 Sphinx/source/users/rest.rst --- 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 `. + + +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 `__ 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 `. - - -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 `__ 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