### Install Project Dependencies

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/contributing.md

Install the project's dependencies using Poetry. This command ensures all required packages are set up for development.

```shell
peotry install
```

--------------------------------

### Start Orthanc Servers with Docker Compose

Source: https://github.com/gacou54/pyorthanc/blob/main/examples/modalities.ipynb

Start the Orthanc servers using Docker Compose. This command initiates the necessary containers for the demonstration.

```shell
docker compose up orthanc1 orthanc2
```

--------------------------------

### Install PyOrthanc

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/index.md

Install PyOrthanc using pip. Use '[all]' to include optional dependencies.

```bash
pip install pyorthanc        # Basic installation
pip install pyorthanc[all]   # Install all optional dependencies (progr)
```

--------------------------------

### GET /plugins

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all available plugins in Orthanc.

```APIDOC
## GET /plugins

### Description
List plugins.

### Method
GET

### Endpoint
/plugins
```

--------------------------------

### GET /jobs

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all jobs.

```APIDOC
## GET /jobs

### Description
List jobs.

### Method
GET

### Endpoint
/jobs
```

--------------------------------

### GET /instances/{id}/preview

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a preview image of the instance.

```APIDOC
## GET /instances/{id}/preview

### Description
Retrieves a preview image of the instance.

### Method
GET

### Endpoint
`/instances/{id}/preview}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **image_data** (string) - The image data, typically base64 encoded.

#### Response Example
```json
{
  "image_data": "/9j/4AAQSkZJRgABAQ..."
}
```
```

--------------------------------

### GET /plugins/explorer.js

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the JavaScript extensions for Orthanc Explorer.

```APIDOC
## GET /plugins/explorer.js

### Description
Get JavaScript extensions to Orthanc Explorer.

### Method
GET

### Endpoint
/plugins/explorer.js
```

--------------------------------

### GET /peers

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all configured Orthanc peers.

```APIDOC
## GET /peers

### Description
List Orthanc peers.

### Method
GET

### Endpoint
/peers
```

--------------------------------

### GET /instances/{id}/module

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the module of a given instance.

```APIDOC
## GET /instances/{id}/module

### Description
Retrieves the module of a given instance.

### Method
GET

### Endpoint
`/instances/{id}/module}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **module** (object) - The module data of the instance.

#### Response Example
```json
{
  "module": {
    "Modality": "CT"
  }
}
```
```

--------------------------------

### GET /plugins/{id}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves details for a specific plugin.

```APIDOC
## GET /plugins/{id}

### Description
Get a specific plugin.

### Method
GET

### Endpoint
/plugins/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the plugin.
```

--------------------------------

### Work with DICOM Instances using PyOrthanc

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Demonstrates how to get instance by ID, access properties, retrieve tags, download files, and convert to pydicom datasets.

```python
from pyorthanc import Orthanc, Instance

client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Get instance by Orthanc ID
instance_id = client.get_instances()[0]
instance = Instance(instance_id, client)

# Access instance properties
print(f"SOP Instance UID: {instance.uid}")
print(f"File Size: {instance.file_size} bytes")
print(f"Instance Number: {instance.instance_number}")
print(f"Creation Date: {instance.creation_date}")

# Get DICOM tags
tags = instance.simplified_tags
print(f"Patient Name: {tags.get('PatientName')}")
print(f"Modality: {tags.get('Modality')}")

# Get specific tag content
content = instance.get_content_by_tag('PatientName')
print(f"Patient Name: {content}")

# Download DICOM file
dicom_bytes = instance.get_dicom_file_content()
with open('instance.dcm', 'wb') as f:
    f.write(dicom_bytes)

# Stream download for large files
instance.download('instance.dcm', with_progres=True)

# Convert to pydicom FileDataset for analysis
ds = instance.get_pydicom()
print(f"Rows: {ds.Rows}")
print(f"Columns: {ds.Columns}")
print(f"Pixel Spacing: {ds.PixelSpacing}")
```

--------------------------------

### Clone PyOrthanc Repo

Source: https://github.com/gacou54/pyorthanc/blob/main/examples/modalities.ipynb

Clone the PyOrthanc repository and navigate into the directory. This is the first step to set up the environment for the examples.

```shell
git clone https://github.com/gacou54/pyorthanc
cd pyorthanc
```

--------------------------------

### GET /instances/{id}/frames

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all available frames for a given instance.

```APIDOC
## GET /instances/{id}/frames

### Description
List all available frames for a given instance.

### Method
GET

### Endpoint
`/instances/{id}/frames`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **frames** (array) - A list of available frame identifiers.
```

--------------------------------

### GET /instances/{id}/file

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Downloads the DICOM file for a specific instance.

```APIDOC
## GET /instances/{id}/file

### Description
Download the DICOM file for a specific instance.

### Method
GET

### Endpoint
`/instances/{id}/file`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance to download.

### Response
#### Success Response (200)
- **dicom_file** (binary) - The DICOM file content.
```

--------------------------------

### GET /instances/{id}/rendered

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a rendered image of the instance.

```APIDOC
## GET /instances/{id}/rendered

### Description
Retrieves a rendered image of the instance.

### Method
GET

### Endpoint
`/instances/{id}/rendered}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **image_data** (string) - The rendered image data, typically base64 encoded.

#### Response Example
```json
{
  "image_data": "/9j/4AAQSkZJRgABAQ..."
}
```
```

--------------------------------

### GET /instances/{id}/simplified-tags

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves human-readable tags for a given instance.

```APIDOC
## GET /instances/{id}/simplified-tags

### Description
Retrieves human-readable tags for a given instance.

### Method
GET

### Endpoint
`/instances/{id}/simplified-tags}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **tags** (object) - Human-readable tags associated with the instance.

#### Response Example
```json
{
  "tags": {
    "PatientName": "Doe^John",
    "StudyDate": "20230101"
  }
}
```
```

--------------------------------

### GET /instances/{id}/frames/{frame}/preview

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decodes a preview of a specific frame of an instance.

```APIDOC
## GET /instances/{id}/frames/{frame}/preview

### Description
Decode a preview of a specific frame of an instance.

### Method
GET

### Endpoint
`/instances/{id}/frames/{frame}/preview`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **frame** (string) - Required - The identifier of the frame.

### Response
#### Success Response (200)
- **preview_image** (binary) - The preview image data.
```

--------------------------------

### GET /instances/{id}/content/{path}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the raw tag content for a specific instance and path.

```APIDOC
## GET /instances/{id}/content/{path}

### Description
Get raw tag content for a specific instance and path.

### Method
GET

### Endpoint
`/instances/{id}/content/{path}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **path** (string) - Required - The path to the content within the instance.

### Response
#### Success Response (200)
- **content** (binary) - The raw content of the specified tag.
```

--------------------------------

### Using Orthanc SDK in an Orthanc Script

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/api/orthanc_sdk.md

Example of how to use the orthanc_sdk within an Orthanc Python script to register a REST callback.

```APIDOC
## POST /test

### Description
Registers a REST callback for the '/test' endpoint.

### Method
POST

### Endpoint
/test

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **output** (orthanc_sdk.RestOutput) - The output object to send a response.

#### Response Example
```python
from pyorthanc import orthanc_sdk

def on_get(output: orthanc_sdk.RestOutput, *_, **__):
    output.AnswerBuffer('ok', 'text/plain')

orthanc_sdk.RegisterRestCallback('/test', on_get)
```
```

--------------------------------

### Initialize Synchronous Orthanc Connection

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Connect to an Orthanc server using the synchronous `Orthanc` client. Supports basic connection, authentication, and raw response retrieval. Use `return_raw_response=True` to get `httpx.Response` objects.

```python
from pyorthanc import Orthanc

# Basic connection without authentication
client = Orthanc('http://localhost:8042')

# Connection with authentication
client = Orthanc(
    url='http://localhost:8042',
    username='orthanc',
    password='orthanc'
)

# Get raw httpx.Response instead of serialized results
client_raw = Orthanc(
    'http://localhost:8042',
    username='orthanc',
    password='orthanc',
    return_raw_response=True
)
```

--------------------------------

### GET /instances/{id}/metadata

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

List all metadata associated with a specific instance.

```APIDOC
## GET /instances/{id}/metadata

### Description
List all metadata associated with a specific instance.

### Method
GET

### Endpoint
`/instances/{id}/metadata`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **metadata** (object) - A collection of metadata for the instance.
```

--------------------------------

### GET /peers/{id}/system

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves system information from a specific Orthanc peer.

```APIDOC
## GET /peers/{id}/system

### Description
Get peer system information.

### Method
GET

### Endpoint
/peers/{id}/system

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the peer.
```

--------------------------------

### GET /instances/{id}/labels

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

List all labels associated with a specific instance.

```APIDOC
## GET /instances/{id}/labels

### Description
List all labels associated with a specific instance.

### Method
GET

### Endpoint
`/instances/{id}/labels`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **labels** (array of strings) - A list of labels associated with the instance.
```

--------------------------------

### GET /instances/{id}/image-int16

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decode an image from an instance as a 16-bit integer.

```APIDOC
## GET /instances/{id}/image-int16

### Description
Decode an image from an instance as a 16-bit integer.

### Method
GET

### Endpoint
`/instances/{id}/image-int16`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **image_data** (array of integers) - The decoded image data as 16-bit integers.
```

--------------------------------

### GET /instances/{id}/metadata/{name}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves specific metadata for a given instance.

```APIDOC
## GET /instances/{id}/metadata/{name}

### Description
Retrieves specific metadata for a given instance.

### Method
GET

### Endpoint
`/instances/{id}/metadata/{name}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **name** (string) - Required - The name of the metadata to retrieve.

### Response
#### Success Response (200)
- **metadata** (object) - The requested metadata.

#### Response Example
```json
{
  "metadata": {
    "key": "value"
  }
}
```
```

--------------------------------

### GET /instances/{id}/frames/{frame}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists operations available for a specific frame within an instance.

```APIDOC
## GET /instances/{id}/frames/{frame}

### Description
List available operations for a specific frame within an instance.

### Method
GET

### Endpoint
`/instances/{id}/frames/{frame}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **frame** (string) - Required - The identifier of the frame.

### Response
#### Success Response (200)
- **operations** (array) - A list of available operations for the frame.
```

--------------------------------

### GET /instances/{id}/image-uint16

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decode an image from an instance as a 16-bit unsigned integer.

```APIDOC
## GET /instances/{id}/image-uint16

### Description
Decode an image from an instance as a 16-bit unsigned integer.

### Method
GET

### Endpoint
`/instances/{id}/image-uint16`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **image_data** (array of unsigned integers) - The decoded image data as 16-bit unsigned integers.
```

--------------------------------

### GET /instances/{id}/image-uint8

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decode an image from an instance as an 8-bit unsigned integer.

```APIDOC
## GET /instances/{id}/image-uint8

### Description
Decode an image from an instance as an 8-bit unsigned integer.

### Method
GET

### Endpoint
`/instances/{id}/image-uint8`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **image_data** (array of unsigned integers) - The decoded image data as 8-bit unsigned integers.
```

--------------------------------

### Run PyOrthanc Tests

Source: https://github.com/gacou54/pyorthanc/blob/main/README.md

Execute PyOrthanc tests using Docker Compose. This command starts three containers: a Python image for testing, an Orthanc instance, and a second Orthanc instance acting as a modality.

```shell
docker compose run test
```

--------------------------------

### GET /instances/{id}/matlab

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decode a frame from an instance for use in Matlab.

```APIDOC
## GET /instances/{id}/matlab

### Description
Decode a frame from an instance in a format suitable for Matlab.

### Method
GET

### Endpoint
`/instances/{id}/matlab`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **matlab_data** (object) - Data decoded for Matlab compatibility.
```

--------------------------------

### GET /instances/{id}/frames/{frame}/rendered

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Render a specific frame within an instance.

```APIDOC
## GET /instances/{id}/frames/{frame}/rendered

### Description
Render a frame for a given instance.

### Method
GET

### Endpoint
`/instances/{id}/frames/{frame}/rendered`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **frame** (string) - Required - The identifier of the frame.

### Response
#### Success Response (200)
- **image** (image format) - The rendered image of the frame.
```

--------------------------------

### List Resources and Get System Info

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Perform basic operations to list all patients, studies, series, and instances from the Orthanc server. Also retrieves system information, including the Orthanc version.

```python
# Basic operations - list all resources
patient_ids = client.get_patients()  # Returns list of patient Orthanc IDs
study_ids = client.get_studies()     # Returns list of study Orthanc IDs
series_ids = client.get_series()     # Returns list of series Orthanc IDs
instance_ids = client.get_instances() # Returns list of instance Orthanc IDs

# Get system information
system_info = client.get_system()
print(f"Orthanc Version: {system_info['Version']}")
```

--------------------------------

### GET, DELETE, PUT /instances/{id}/labels/{label}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Operations related to a specific label of an instance.

```APIDOC
## GET, DELETE, PUT /instances/{id}/labels/{label}

### Description
Perform operations (get, delete, or test) on a specific label associated with an instance.

### Method
GET, DELETE, PUT

### Endpoint
`/instances/{id}/labels/{label}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **label** (string) - Required - The specific label to operate on.

### Response
#### Success Response (200)
- **status** (string) - Indicates the result of the operation (e.g., 'success', 'not found').
```

--------------------------------

### GET /peers/{id}/configuration

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the configuration details for a specific Orthanc peer.

```APIDOC
## GET /peers/{id}/configuration

### Description
Get peer configuration.

### Method
GET

### Endpoint
/peers/{id}/configuration

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the peer.
```

--------------------------------

### Manage Asynchronous Orthanc Jobs

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Shows how to start, monitor, and manage asynchronous Orthanc jobs like anonymization. Includes checking job status, progress, errors, and accessing results.

```python
from pyorthanc import Orthanc, Patient
from pyorthanc.jobs import State

client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Start an async job (e.g., anonymization)
patient = Patient(client.get_patients()[0], client)
job = patient.anonymize_as_job()

# Monitor job status
print(f"Job ID: {job.id_}")
print(f"Job Type: {job.type}")
print(f"State: {job.state}")
print(f"Progress: {job.progress}%")
print(f"Priority: {job.priority}")
print(f"Creation Time: {job.creation_time}")

# Check for errors
if job.state == State.failure:
    print(f"Error Code: {job.error}")
    print(f"Error Details: {job.error_details}")

# Wait for completion with custom interval
job.wait_until_completion(time_interval=1)  # Check every 1 second

# Access job result
if job.state == State.success:
    result_id = job.content['ID']
    new_patient = Patient(result_id, client)
    print(f"Created new patient: {new_patient.patient_id}")

# List all jobs via client
all_jobs = client.get_jobs()
for job_id in all_jobs:
    job_info = client.get_jobs_id(job_id)
    print(f"Job {job_id}: {job_info['State']}")
```

--------------------------------

### Register Custom REST Endpoint

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Defines and registers a custom REST API endpoint '/hello-world' that responds to GET requests with a plain text message and rejects other methods.

```python
def handle_hello(output: orthanc_sdk.RestOutput, uri: str, **request):
    """Custom REST API endpoint"""
    if request['method'] == 'GET':
        output.AnswerBuffer('Hello from plugin!', 'text/plain')
    else:
        output.SendMethodNotAllowed('GET')

orthanc_sdk.RegisterRestCallback('/hello-world', handle_hello)
```

--------------------------------

### Get pydicom Dataset from Instance ID

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Demonstrates how to retrieve a pydicom dataset object directly using an Orthanc instance ID and the Orthanc client.

```python
# Get pydicom dataset directly from instance ID
ds = util.get_pydicom(client, instance_orthanc_id)
```

--------------------------------

### Get Uploaded Instances

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/api/upload.md

The `upload` function returns a list of `pyorthanc.Instance` objects representing the uploaded DICOM instances. This can be useful for further processing or verification.

```python
from pyorthanc import Orthanc, upload

orthanc = Orthanc(url='http://localhost:8042')

# Note that `upload` returns a list of the uploaded instances `list[pyorthanc.Instance]`
instances = upload(orthanc, 'directory/path')
print(instances)
```

--------------------------------

### Initialize PyOrthanc Client

Source: https://github.com/gacou54/pyorthanc/blob/main/examples/find_data.ipynb

Connect to your Orthanc server using its URL, username, and password. Ensure your Orthanc server is running and accessible.

```python
import pyorthanc

# Creating the Orthanc client
orthanc = pyorthanc.Orthanc(
    url='http://localhost:8042',  # URL of you Orthanc server
    username='orthanc',  # Using the default username
    password='orthanc',  # Using the default password
)
```

--------------------------------

### GET /tools/generate-uid

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Generates a DICOM UID.

```APIDOC
## GET /tools/generate-uid

### Description
Generates a DICOM UID.

### Method
GET

### Endpoint
/tools/generate-uid
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/contributing.md

Change the current directory to the cloned Pyorthanc project folder.

```shell
cd pyorthanc
```

--------------------------------

### GET /instances/{id}/frames/{frame}/raw.gz

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Access the compressed raw data of a specific frame within an instance.

```APIDOC
## GET /instances/{id}/frames/{frame}/raw.gz

### Description
Access compressed raw frame data for a given instance and frame.

### Method
GET

### Endpoint
`/instances/{id}/frames/{frame}/raw.gz`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
- **frame** (string) - Required - The identifier of the frame.

### Response
#### Success Response (200)
- **data** (binary) - The compressed raw frame data.
```

--------------------------------

### GET /modalities

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all DICOM modalities.

```APIDOC
## GET /modalities

### Description
List DICOM modalities.

### Method
GET

### Endpoint
/modalities
```

--------------------------------

### GET /tools/dicom-conformance

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the DICOM conformance statement.

```APIDOC
## GET /tools/dicom-conformance

### Description
Retrieves the DICOM conformance statement.

### Method
GET

### Endpoint
/tools/dicom-conformance
```

--------------------------------

### Build PyOrthanc Docker Image

Source: https://github.com/gacou54/pyorthanc/blob/main/docker/README.md

Use this command to build the Docker image. Specify the PYORTHANC_VERSION and ORTHANC_VERSION build arguments.

```shell
docker build --build-arg PYORTHANC_VERSION=1.18.0 --build-arg ORTHANC_VERSION=24.9.1  -t ylemarechal/orthanc-pyorthanc:24.9.1 .
```

--------------------------------

### Configuration and Utility Functions

Source: https://github.com/gacou54/pyorthanc/blob/main/scripts/data/python-sdk.txt

Functions for setting descriptions, properties, metrics, and root URIs.

```APIDOC
## SetDescription

### Description
Generated from C function OrthancPluginSetDescription()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## SetGlobalProperty

### Description
Generated from C function OrthancPluginSetGlobalProperty()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## SetMetricsValue

### Description
Generated from C function OrthancPluginSetMetricsValue()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## SetRootUri

### Description
Generated from C function OrthancPluginSetRootUri()

### Method
N/A

### Endpoint
N/A
```

--------------------------------

### HttpGet Function

Source: https://github.com/gacou54/pyorthanc/blob/main/scripts/data/python-sdk.txt

Performs an HTTP GET request.

```APIDOC
## Function: HttpGet

### Description
Generated from C function OrthancPluginHttpGet().

### Endpoint
N/A (This is a function call, not an HTTP endpoint)

### Parameters
N/A

### Request Body
N/A

### Response
N/A
```

--------------------------------

### GET /studies/{id}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves information about a specific study.

```APIDOC
## GET /studies/{id}

### Description
Get information about a specific study.

### Method
GET

### Endpoint
`/studies/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the study.
```

--------------------------------

### Instance Resource - Work with DICOM Instances

Source: https://context7.com/gacou54/pyorthanc/llms.txt

This section details how to interact with individual DICOM instances using the Instance class, including downloading, accessing tags, and converting to pydicom datasets.

```APIDOC
## Instance Resource - Work with DICOM Instances

### Description
The `Instance` class represents a single DICOM instance and provides methods to download, access DICOM tags, and convert to pydicom datasets.

### Method
Various methods are available on the `Instance` object, including `get_instances`, `__init__`, `uid`, `file_size`, `instance_number`, `creation_date`, `simplified_tags`, `get_content_by_tag`, `get_dicom_file_content`, `download`, and `get_pydicom`.

### Endpoint
This class interacts with the Orthanc API endpoints related to instances, typically under `/instances`.

### Parameters
#### Path Parameters
- **instance_id** (str) - Required - The unique identifier for the DICOM instance.

#### Query Parameters
None explicitly defined for the `Instance` class methods in this context.

#### Request Body
Not applicable for direct `Instance` object instantiation or property access.

### Request Example
```python
from pyorthanc import Orthanc, Instance

client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Get instance by Orthanc ID
instance_id = client.get_instances()[0]
instance = Instance(instance_id, client)

# Access instance properties
print(f"SOP Instance UID: {instance.uid}")
print(f"File Size: {instance.file_size} bytes")
print(f"Instance Number: {instance.instance_number}")
print(f"Creation Date: {instance.creation_date}")

# Get DICOM tags
tags = instance.simplified_tags
print(f"Patient Name: {tags.get('PatientName')}")
print(f"Modality: {tags.get('Modality')}")

# Get specific tag content
content = instance.get_content_by_tag('PatientName')
print(f"Patient Name: {content}")

# Download DICOM file
dicom_bytes = instance.get_dicom_file_content()
with open('instance.dcm', 'wb') as f:
    f.write(dicom_bytes)

# Stream download for large files
instance.download('instance.dcm', with_progres=True)

# Convert to pydicom FileDataset for analysis
ds = instance.get_pydicom()
print(f"Rows: {ds.Rows}")
print(f"Columns: {ds.Columns}")
print(f"Pixel Spacing: {ds.PixelSpacing}")
```

### Response
#### Success Response (200)
Responses vary based on the method called. Property access returns specific values (e.g., string for UID, int for file size). Methods like `get_dicom_file_content` return bytes, and `get_pydicom` returns a pydicom `FileDataset` object.

#### Response Example
```json
{
  "SOP Instance UID": "1.2.3.4.5.6.7.8.9",
  "File Size": 102400,
  "Instance Number": 1,
  "Creation Date": "20230101T100000.000Z",
  "PatientName": "Doe^John",
  "Modality": "CT",
  "Rows": 512,
  "Columns": 512,
  "Pixel Spacing": [0.5, 0.5]
}
```
```

--------------------------------

### POST /tools/create-media

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Creates DICOMDIR media.

```APIDOC
## POST /tools/create-media

### Description
Creates DICOMDIR media.

### Method
POST

### Endpoint
/tools/create-media
```

--------------------------------

### Orthanc SDK Import Logic

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/api/orthanc_sdk.md

Demonstrates how the Orthanc SDK handles the availability of the actual 'orthanc' module.

```APIDOC
## Orthanc SDK Import Logic

### Description
This section explains the import mechanism of the Orthanc SDK. It attempts to import the actual `orthanc` module. If the `orthanc` module is not found (e.g., when running outside of an Orthanc environment), it falls back to using the `orthanc_sdk` which provides mock objects for linting and autocompletion.

### Method
N/A (Code logic)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
try:
    from orthanc import *

except ModuleNotFoundError:
    """Orthanc SDK methods wrapped in python (plugin version 4.0)"""
    # The orthanc_sdk module provides mock objects when 'orthanc' is not available.
    pass
```

### Response
N/A
```

--------------------------------

### GET /jobs/{id}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a specific job by its ID.

```APIDOC
## GET /jobs/{id}

### Description
Get job.

### Method
GET

### Endpoint
/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job.
```

--------------------------------

### GetOrthancDirectory Function

Source: https://github.com/gacou54/pyorthanc/blob/main/scripts/data/python-sdk.txt

Retrieves the main directory path of the Orthanc installation.

```APIDOC
## Function: GetOrthancDirectory

### Description
Generated from C function OrthancPluginGetOrthancDirectory().

### Endpoint
N/A (This is a function call, not an HTTP endpoint)

### Parameters
N/A

### Request Body
N/A

### Response
N/A
```

--------------------------------

### GET /studies/{id}/attachments

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Lists all attachments for a specific study.

```APIDOC
## GET /studies/{id}/attachments

### Description
List attachments for a specific study.

### Method
GET

### Endpoint
`/studies/{id}/attachments`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the study.
```

--------------------------------

### POST /tools/create-archive

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Creates a ZIP archive of resources.

```APIDOC
## POST /tools/create-archive

### Description
Creates a ZIP archive of resources.

### Method
POST

### Endpoint
/tools/create-archive
```

--------------------------------

### GET /patients/{id}/statistics

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves statistics for a specific patient.

```APIDOC
## GET /patients/{id}/statistics

### Description
Get patient statistics.

### Method
GET

### Endpoint
/patients/{id}/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the patient.
```

--------------------------------

### GET /jobs/{id}/{key}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the output of a specific job.

```APIDOC
## GET /jobs/{id}/{key}

### Description
Get job output.

### Method
GET

### Endpoint
/jobs/{id}/{key}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the job.
- **key** (string) - Required - The key for the job output.
```

--------------------------------

### GET /instances/{id}/statistics

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves statistics for a specific instance.

```APIDOC
## GET /instances/{id}/statistics

### Description
Get instance statistics.

### Method
GET

### Endpoint
/instances/{id}/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
```

--------------------------------

### Initialize Asynchronous Orthanc Connection

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Connect to an Orthanc server using the asynchronous `AsyncOrthanc` client for non-blocking operations. Use `async with` for proper resource management.

```python
import asyncio
from pyorthanc import AsyncOrthanc

async def main():
    # Create async client
    async with AsyncOrthanc('http://localhost:8042', username='orthanc', password='orthanc') as client:
        # Async operations
        patients = await client.get_patients()
        studies = await client.get_studies()

        # Get patient information
        if patients:
            patient_info = await client.get_patients_id(patients[0])
            print(f"Patient: {patient_info['MainDicomTags']['PatientName']}")

asyncio.run(main())
```

--------------------------------

### Tools Metrics API

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

API endpoint to get real-time metrics from Orthanc.

```APIDOC
## GET /tools/metrics

### Description
Get real-time metrics.

### Method
GET

### Endpoint
/tools/metrics
```

--------------------------------

### GET /studies/{id}/attachments/{name}

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a specific attachment for a study.

```APIDOC
## GET /studies/{id}/attachments/{name}

### Description
Get information about a specific attachment for a study.

### Method
GET

### Endpoint
`/studies/{id}/attachments/{name}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the study.
- **name** (string) - Required - The name of the attachment.
```

--------------------------------

### StorageArea Class Methods

Source: https://github.com/gacou54/pyorthanc/blob/main/scripts/data/python-sdk.txt

Methods for managing storage areas, including creation, reading, and removal.

```APIDOC
## StorageArea.ReconstructMainDicomTags

### Description
Generated from C function OrthancPluginReconstructMainDicomTags()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## StorageArea.StorageAreaCreate

### Description
Generated from C function OrthancPluginStorageAreaCreate()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## StorageArea.StorageAreaRead

### Description
Generated from C function OrthancPluginStorageAreaRead()

### Method
N/A

### Endpoint
N/A
```

```APIDOC
## StorageArea.StorageAreaRemove

### Description
Generated from C function OrthancPluginStorageAreaRemove()

### Method
N/A

### Endpoint
N/A
```

--------------------------------

### GET /studies/{id}/archive

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a ZIP archive of a specific study.

```APIDOC
## GET /studies/{id}/archive

### Description
Get information about a specific study.

### Method
GET

### Endpoint
`/studies/{id}/archive`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the study.
```

--------------------------------

### GET /instances/{id}/tags

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves DICOM tags for a specific instance.

```APIDOC
## GET /instances/{id}/tags

### Description
Get DICOM tags.

### Method
GET

### Endpoint
/instances/{id}/tags

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
```

--------------------------------

### GET /instances/{id}/study

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the parent study for a specific instance.

```APIDOC
## GET /instances/{id}/study

### Description
Get parent study.

### Method
GET

### Endpoint
/instances/{id}/study

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.
```

--------------------------------

### POST /instances/{id}/export

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Writes DICOM data of an instance to the filesystem.

```APIDOC
## POST /instances/{id}/export

### Description
Write DICOM data of an instance onto the filesystem.

### Method
POST

### Endpoint
`/instances/{id}/export`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance to export.

### Request Body
- **destination** (string) - Required - The filesystem path where the DICOM data should be written.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the export was successful.
```

--------------------------------

### GET /instances/{id}/series

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the parent series of a given instance.

```APIDOC
## GET /instances/{id}/series

### Description
Retrieves the parent series of a given instance.

### Method
GET

### Endpoint
`/instances/{id}/series}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **series_id** (string) - The ID of the parent series.

#### Response Example
```json
{
  "series_id": "series_xyz789"
}
```
```

--------------------------------

### Query and Retrieve from PACS using PyOrthanc Modality

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Demonstrates how to establish a connection to a remote PACS using the Modality class and perform C-ECHO and C-FIND operations.

```python
from pyorthanc import Orthanc, Modality

client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Create modality connection (modality must be configured in Orthanc)
modality = Modality(client, 'REMOTE_PACS')

# Test connection with C-ECHO
if modality.echo():
    print("Successfully connected to PACS")

# Query studies with C-FIND
response = modality.find({
    'Level': 'Study',
    'Query': {
        'PatientID': '12345*',
        'StudyDate': '20230101-20231231',
        'ModalitiesInStudy': 'CT'
    }
})

```

--------------------------------

### Create a New Git Branch

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/contributing.md

Create a new Git branch for your changes. Replace `your-branch-name` with a descriptive name for your branch.

```shell
git checkout -b your-branch-name
```

--------------------------------

### GET /instances/{id}/pdf

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the embedded PDF representation of an instance.

```APIDOC
## GET /instances/{id}/pdf

### Description
Retrieves the embedded PDF representation of an instance.

### Method
GET

### Endpoint
`/instances/{id}/pdf}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **pdf_data** (string) - The PDF data, typically base64 encoded.

#### Response Example
```json
{
  "pdf_data": "JVBERi0xLjQKJc..."
}
```
```

--------------------------------

### GET /instances/{id}/patient

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves the parent patient of a given instance.

```APIDOC
## GET /instances/{id}/patient

### Description
Retrieves the parent patient of a given instance.

### Method
GET

### Endpoint
`/instances/{id}/patient}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **patient_id** (string) - The ID of the parent patient.

#### Response Example
```json
{
  "patient_id": "patient_abc123"
}
```
```

--------------------------------

### POST /instances/{id}/reconstruct

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Reconstructs tags and optionally files of an instance.

```APIDOC
## POST /instances/{id}/reconstruct

### Description
Reconstructs tags and optionally files of an instance.

### Method
POST

### Endpoint
`/instances/{id}/reconstruct}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance to reconstruct.

#### Request Body
- **reconstruct_files** (boolean) - Optional - Whether to reconstruct files. Defaults to false.

### Request Example
```json
{
  "reconstruct_files": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Instance reconstruction initiated."
}
```
```

--------------------------------

### Query and Retrieve DICOM Data

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Demonstrates how to query for studies, review the response, and retrieve results using C-MOVE or C-STORE. Also shows how to perform a direct C-GET retrieval if supported.

```python
print(f"Query ID: {response['ID']}")
print(f"Found {len(response['answers'])} matching studies")
for answer in response['answers']:
    print(f"  Patient: {answer.get('PatientName')}")
    print(f"  Study Date: {answer.get('StudyDate')}")
    print(f"  Description: {answer.get('StudyDescription')}")

# Retrieve results to Orthanc with C-MOVE
modality.move(response['ID'], {'TargetAet': 'ORTHANC'})

# Or retrieve to a different modality
modality.move(response['ID'], {'TargetAet': 'ANOTHER_PACS'})

# Store data to remote modality with C-STORE
instance_id = client.get_instances()[0]
result = modality.store(instance_id)
print(f"Store result: {result}")

# C-GET (retrieve directly, if supported by remote)
modality.get(
    level='Study',
    resources={'StudyInstanceUID': '1.2.3.4.5.6.7.8.9'}
)
```

--------------------------------

### POST /tools/execute-script

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Executes a Lua script.

```APIDOC
## POST /tools/execute-script

### Description
Executes a Lua script.

### Method
POST

### Endpoint
/tools/execute-script
```

--------------------------------

### GET /instances/{id}/header

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieve the DICOM meta-header for a specific instance.

```APIDOC
## GET /instances/{id}/header

### Description
Get the DICOM meta-header for a specific instance.

### Method
GET

### Endpoint
`/instances/{id}/header`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **header** (object) - The DICOM meta-header information.
```

--------------------------------

### Create Modality Object and Echo

Source: https://github.com/gacou54/pyorthanc/blob/main/examples/modalities.ipynb

Create a Modality object for easier interaction and perform a C-ECHO to verify the connection. This operation acts as a ping to the modality.

```python
my_modality = pyorthanc.Modality(orthanc, 'my_modality')

assert my_modality.echo()  # Ask Orthanc to perform a C-ECHO (i.e. a ping) to the modality, validating the connection (returns True if OK).
```

--------------------------------

### GET /patients/{id}/studies

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Retrieves a list of studies associated with a specific patient.

```APIDOC
## GET /patients/{id}/studies

### Description
Get child studies for a patient.

### Method
GET

### Endpoint
/patients/{id}/studies

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the patient.
```

--------------------------------

### GET /instances/{id}/numpy

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

Decodes an instance into a NumPy array for numerical processing.

```APIDOC
## GET /instances/{id}/numpy

### Description
Decodes an instance into a NumPy array for numerical processing.

### Method
GET

### Endpoint
`/instances/{id}/numpy}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the instance.

### Response
#### Success Response (200)
- **numpy_array** (array) - The instance data as a NumPy array.

#### Response Example
```json
{
  "numpy_array": [
    [1, 2, 3],
    [4, 5, 6]
  ]
}
```
```

--------------------------------

### Work with Series Data in PyOrthanc

Source: https://context7.com/gacou54/pyorthanc/llms.txt

Demonstrates how to retrieve series metadata, navigate to parent study and patient, access instances, and download series data. Requires an Orthanc client and a valid series ID.

```python
from pyorthanc import Orthanc, Series

client = Orthanc('http://localhost:8042', username='orthanc', password='orthanc')

# Get series by Orthanc ID
series_id = client.get_series()[0]
series = Series(series_id, client)

# Access series properties
print(f"Modality: {series.modality}")
print(f"Series Description: {series.description}")
print(f"Series UID: {series.uid}")
print(f"Series Number: {series.series_number}")
print(f"Series Date: {series.date}")
print(f"Manufacturer: {series.manufacturer}")
print(f"Protocol Name: {series.protocol_name}")
print(f"Body Part: {series.body_part_examined}")

# Navigate to parent study and patient
study = series.parent_study
patient = series.parent_patient

# Access child instances
for instance in series.instances:
    print(f"Instance: {instance.uid}")
    print(f"  File Size: {instance.file_size} bytes")
    print(f"  Instance Number: {instance.instance_number}")

# Download series as ZIP
series.download('series_archive.zip', with_progres=True)
```

--------------------------------

### Get Remote Modalities

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/tutorial/quickstart.md

Retrieve a list of connected remote modalities from the Orthanc server.

```python
modalities = orthanc.get_modalities()
```

--------------------------------

### Tools Metrics Prometheus API

Source: https://github.com/gacou54/pyorthanc/blob/main/docs/cheat_sheet.md

API endpoint to get metrics in a format suitable for Prometheus.

```APIDOC
## GET /tools/metrics-prometheus

### Description
Get metrics for Prometheus.

### Method
GET

### Endpoint
/tools/metrics-prometheus
```