Skip to content

Find

pyorthanc.find_patients(client, query=None, labels=None, labels_constraint='All')

Finds patients in Orthanc according to queries and labels

Parameters:

Name Type Description Default
client Orthanc

Orthanc client.

 required
query Dict[str, str]

Dictionary that specifies the filters on the Patient related DICOM tags.

 None
labels Union[List[str], str]

List of strings specifying which labels to look for in the resources.

 None
labels_constraint str

Constraint on the labels, can be 'All', 'Any', or 'None'.

 'All'

Returns:

Type Description
List[Patient]

List of patients that fit the provided criteria.

Examples:

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
patients = find_patients(
    client=client,
    query={'PatientID': 'Something*'},
    labels=['my_label']
)
Source code in pyorthanc/_find.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def find_patients(client: Orthanc,
                  query: Dict[str, str] = None,
                  labels: Union[List[str], str] = None,
                  labels_constraint: str = 'All') -> List[Patient]:
    """Finds patients in Orthanc according to queries and labels

    Parameters
    ----------
    client
        Orthanc client.
    query
        Dictionary that specifies the filters on the Patient related DICOM tags.
    labels
        List of strings specifying which labels to look for in the resources.
    labels_constraint
        Constraint on the labels, can be 'All', 'Any', or 'None'.

    Returns
    -------
    List[Patient]
        List of patients that fit the provided criteria.

    Examples
    --------
    ```python
    import pyorthanc

    client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
    patients = find_patients(
        client=client,
        query={'PatientID': 'Something*'},
        labels=['my_label']
    )
    ```
    """
    return query_orthanc(
        client=client,
        level='Patient',
        query=query,
        labels=labels,
        labels_constraint=labels_constraint
    )

pyorthanc.find_studies(client, query=None, labels=None, labels_constraint='All')

Finds studies in Orthanc according to queries and labels

Parameters:

Name Type Description Default
client Orthanc

Orthanc client.

 required
query Dict[str, str]

Dictionary that specifies the filters on the Study related DICOM tags.

 None
labels Union[List[str], str]

List of strings specifying which labels to look for in the resources.

 None
labels_constraint str

Constraint on the labels, can be 'All', 'Any', or 'None'.

 'All'

Returns:

Type Description
List[Study]

List of studies that fit the provided criteria.

Examples:

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
studies = find_studies(
    client=client,
    query={'ReferringPhysicianName': 'Something*'},
    labels=['my_label']
)
Source code in pyorthanc/_find.py 
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def find_studies(client: Orthanc,
                 query: Dict[str, str] = None,
                 labels: Union[List[str], str] = None,
                 labels_constraint: str = 'All') -> List[Study]:
    """Finds studies in Orthanc according to queries and labels

    Parameters
    ----------
    client
        Orthanc client.
    query
        Dictionary that specifies the filters on the Study related DICOM tags.
    labels
        List of strings specifying which labels to look for in the resources.
    labels_constraint
        Constraint on the labels, can be 'All', 'Any', or 'None'.

    Returns
    -------
    List[Study]
        List of studies that fit the provided criteria.

    Examples
    --------
    ```python
    import pyorthanc

    client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
    studies = find_studies(
        client=client,
        query={'ReferringPhysicianName': 'Something*'},
        labels=['my_label']
    )
    ```
    """

    return query_orthanc(
        client=client,
        level='Study',
        query=query,
        labels=labels,
        labels_constraint=labels_constraint
    )

pyorthanc.find_series(client, query=None, labels=None, labels_constraint='All')

Finds series in Orthanc according to queries and labels

Parameters:

Name Type Description Default
client Orthanc

Orthanc client.

 required
query Dict[str, str]

Dictionary that specifies the filters on the Series related DICOM tags.

 None
labels Union[List[str], str]

List of strings specifying which labels to look for in the resources.

 None
labels_constraint str

Constraint on the labels, can be 'All', 'Any', or 'None'.

 'All'

Returns:

Type Description
List[Series]

List of Series that fit the provided criteria.

Examples:

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
series = find_series(
    client=client,
    query={'Modality': 'RTDose'},
    labels=['my_label']
)
Source code in pyorthanc/_find.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def find_series(client: Orthanc,
                query: Dict[str, str] = None,
                labels: Union[List[str], str] = None,
                labels_constraint: str = 'All') -> List[Series]:
    """Finds series in Orthanc according to queries and labels

    Parameters
    ----------
    client
        Orthanc client.
    query
        Dictionary that specifies the filters on the Series related DICOM tags.
    labels
        List of strings specifying which labels to look for in the resources.
    labels_constraint
        Constraint on the labels, can be 'All', 'Any', or 'None'.

    Returns
    -------
    List[Series]
        List of Series that fit the provided criteria.

    Examples
    --------
    ```python
    import pyorthanc

    client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
    series = find_series(
        client=client,
        query={'Modality': 'RTDose'},
        labels=['my_label']
    )
    ```
    """
    return query_orthanc(
        client=client,
        level='Series',
        query=query,
        labels=labels,
        labels_constraint=labels_constraint
    )

pyorthanc.find_instances(client, query=None, labels=None, labels_constraint='All')

Finds instances in Orthanc according to queries and labels

Parameters:

Name Type Description Default
client Orthanc

Orthanc client.

 required
query Dict[str, str]

Dictionary that specifies the filters on the instances related DICOM tags.

 None
labels Union[List[str], str]

List of strings specifying which labels to look for in the resources.

 None
labels_constraint str

Constraint on the labels, can be 'All', 'Any', or 'None'.

 'All'

Returns:

Type Description
List[Instance]

List of Instances that fit the provided criteria.

Examples:

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
instances = find_instances(
    client=client,
    query={'InstanceCreationDate': '20100301'},
    labels=['my_label']
)
Source code in pyorthanc/_find.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def find_instances(client: Orthanc,
                   query: Dict[str, str] = None,
                   labels: Union[List[str], str] = None,
                   labels_constraint: str = 'All') -> List[Instance]:
    """Finds instances in Orthanc according to queries and labels

    Parameters
    ----------
    client
        Orthanc client.
    query
        Dictionary that specifies the filters on the instances related DICOM tags.
    labels
        List of strings specifying which labels to look for in the resources.
    labels_constraint
        Constraint on the labels, can be 'All', 'Any', or 'None'.

    Returns
    -------
    List[Instance]
        List of Instances that fit the provided criteria.

    Examples
    --------
    ```python
    import pyorthanc

    client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
    instances = find_instances(
        client=client,
        query={'InstanceCreationDate': '20100301'},
        labels=['my_label']
    )
    ```
    """
    return query_orthanc(
        client=client,
        level='Instance',
        query=query,
        labels=labels,
        labels_constraint=labels_constraint
    )

pyorthanc.query_orthanc(client, level, query=None, labels=None, labels_constraint='All', limit=DEFAULT_RESOURCES_LIMIT, since=0, retrieve_all_resources=True, lock=False)

Query data in the Orthanc server

Parameters:

Name Type Description Default
client Orthanc

Orthanc client.

 required
level str

Level of the query ['Patient', 'Study', 'Series', 'Instance'].

 required
query Dict[str, str]

Dictionary that specifies the filters on the level related DICOM tags.

 None
labels Union[List[str], str]

List of strings specifying which labels to look for in the resources.

 None
labels_constraint str

Constraint on the labels, can be 'All', 'Any', or 'None'.

 'All'
limit int

Limit the number of reported resources.

 DEFAULT_RESOURCES_LIMIT
since int

Show only the resources since the provided index (in conjunction with "limit").

 0
retrieve_all_resources bool

Retrieve all resources since the index specified in the "since" parameter.

 True
lock bool

if True, lock the resource state at lookup (useful for minimising the number of HTTP calls).

 False

Returns:

Type Description
List[Resource]

List of resources that fit the provided criteria.

Examples:

import pyorthanc

client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
instances = query_orthanc(
    client=client,
    level='Instance',
    query={'InstanceCreationDate': '20100301'},
    labels=['my_label'],
    since=100,
    retrieve_all_resource=False
)
Source code in pyorthanc/_find.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def query_orthanc(client: Orthanc,
                  level: str,
                  query: Dict[str, str] = None,
                  labels: Union[List[str], str] = None,
                  labels_constraint: str = 'All',
                  limit: int = DEFAULT_RESOURCES_LIMIT,
                  since: int = 0,
                  retrieve_all_resources: bool = True,
                  lock: bool = False) -> List[Resource]:
    """Query data in the Orthanc server

    Parameters
    ----------
    client
        Orthanc client.
    level
        Level of the query ['Patient', 'Study', 'Series', 'Instance'].
    query
        Dictionary that specifies the filters on the level related DICOM tags.
    labels
        List of strings specifying which labels to look for in the resources.
    labels_constraint
        Constraint on the labels, can be 'All', 'Any', or 'None'.
    limit
        Limit the number of reported resources.
    since
        Show only the resources since the provided index (in conjunction with "limit").
    retrieve_all_resources
        Retrieve all resources since the index specified in the "since" parameter.
    lock
        if `True`, lock the resource state at lookup (useful for minimising the number of HTTP calls).

    Returns
    -------
    List[Resource]
        List of resources that fit the provided criteria.

    Examples
    --------
    ```python
    import pyorthanc

    client = pyorthanc.Orthanc('http://localhost:8042', 'orthanc', 'orthanc')
    instances = query_orthanc(
        client=client,
        level='Instance',
        query={'InstanceCreationDate': '20100301'},
        labels=['my_label'],
        since=100,
        retrieve_all_resource=False
    )
    ```
    """
    _validate_level(level)
    _validate_labels_constraint(labels_constraint)

    # In this function, client that return raw responses are not supported.
    client = util.ensure_non_raw_response(client)

    data = {
        'Expand': True,
        'Level': level,
        'Limit': limit,
        'Since': since,
        'Query': {}
    }

    if query is not None:
        data['Query'] = query

    if labels is not None:
        data['Labels'] = [labels] if isinstance(labels, str) else labels
        data['LabelsConstraint'] = labels_constraint

    if retrieve_all_resources:
        results = []
        while True:
            result_for_interval = client.post_tools_find(data)
            if len(result_for_interval) == 0:
                break

            results += result_for_interval
            data['Since'] += limit  # Updating the lookup window
    else:
        results = client.post_tools_find(data)

    if level == 'Patient':
        resources = [Patient(i['ID'], client, lock=lock) for i in results]
    elif level == 'Study':
        resources = [Study(i['ID'], client, lock=lock) for i in results]
    elif level == 'Series':
        resources = [Series(i['ID'], client, lock=lock) for i in results]
    elif level == 'Instance':
        resources = [Instance(i['ID'], client, lock=lock) for i in results]
    else:
        raise ValueError(f"Unknown level ['Patient', 'Study', 'Series', 'Instance'], got {level}")

    if lock:
        for resource in resources:
            # This loads the state in memory. Since lock=True,
            # subsequent queries on resource will use the local state
            resource.get_main_information()

    return resources

pyorthanc._find.DEFAULT_RESOURCES_LIMIT = 1000 module-attribute