### Volume Channel Management Example

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/volume.md

Demonstrates how to use methods for accessing and manipulating channel dimensions in a Highdicom Volume. This includes getting specific channel values, extracting a single channel, and permuting channel axes.

```python
import numpy as np
import highdicom as hd

# Array with three spatial dimensions plus 3 color channels and 4 optical
# paths
array = np.random.randint(0, 10, size=(1, 50, 50, 3, 4))

# Names of the 4 optical paths
path_names = ['path1', 'path2', 'path3', 'path4']

vol = hd.Volume.from_components(
    direction=np.eye(3),
    center_position=[98.1, 78.4, 23.1],
    spacing=[2.0, 0.5, 0.5],
    coordinate_system="SLIDE",
    array=array,
    channels={
        hd.RGB_COLOR_CHANNEL_DESCRIPTOR: ['R', 'G', 'B'],
        'OpticalPathIdentifier': path_names
    },
)

assert (
    vol.get_channel_values('OpticalPathIdentifier') ==
    path_names
)

# Get a new volume containing just optical path 'path2'
path_2_vol = vol.get_channel(OpticalPathIdentifier='path2')

# Swap the two channel axes by descriptor
permuted_vol = vol.permute_channel_axes(
    ['OpticalPathIdentifier', 'RGBColorChannel']
)

# Swap the two channel axes by index
permuted_vol = vol.permute_channel_axes_by_index([1, 0])
```

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

### get_observer_contexts

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get observer contexts.

```APIDOC
## get_observer_contexts

### Description
Get observer contexts.

### Parameters
* **observer_type** (*Union* *[*[*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept) *,* *pydicom.sr.coding.Code* *,* *None* *]* *,* *optional*) – Type of observer (“Device” or “Person”) for which should be filtered

### Returns
Observer contexts

### Return type
List[[highdicom.sr.ObserverContext](#highdicom.sr.ObserverContext)]
```

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

### name property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the name of the device.

```APIDOC
## property name *: str | None*

### Description
name of device

### Type
Union[str, None]
```

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

### Example Derivation Image Sequence Structure

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/seg.md

This example shows the expected structure of the 'Derivation Image Sequence' within the 'Per Frame Functional Groups Sequence' for a segmentation. Viewers often rely on this sequence to determine the spatial placement of segmentation frames.

```text
[(0008,9124)  Derivation Image Sequence  1 item(s) ----
   (0008,2112)  Source Image Sequence  1 item(s) ----
      (0008,1150) Referenced SOP Class UID            UI: CT Image Storage
      (0008,1155) Referenced SOP Instance UID         UI: 1.3.6.1.4.1.5962.1.1.0.0.0.1196530851.28319.0.96
      (0028,135A) Spatial Locations Preserved         CS: 'YES'
      (0040,A170)  Purpose of Reference Code Sequence  1 item(s) ----
         (0008,0100) Code Value                          SH: '121322'
         (0008,0102) Coding Scheme Designator            SH: 'DCM'
         (0008,0104) Code Meaning                        LO: 'Source image for image processing operation'
         ---------
      ---------
   (0008,9215)  Derivation Code Sequence  1 item(s) ----
      (0008,0100) Code Value                          SH: '113076'
      (0008,0102) Coding Scheme Designator            SH: 'DCM'
      (0008,0104) Code Meaning                        LO: 'Segmentation'
      ---------
   ---------
(0020,9111)  Frame Content Sequence  1 item(s) ----
   (0020,9157) Dimension Index Values              UL: [1, 1]
   ---------
(0020,9113)  Plane Position Sequence  1 item(s) ----
   (0020,0032) Image Position (Patient)            DS: [-125.000000, -128.100006, 105.519997]
   ---------
(0062,000A)  Segment Identification Sequence  1 item(s) ----
   (0062,000B) Referenced Segment Number           US: 1
   ---------
]
```

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

### ObserverContext Initialization and Methods

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Documentation for initializing an ObserverContext and methods for managing its content items.

```APIDOC
### ObserverContext

Bases: `Template`

[TID 1002](http://dicom.nema.org/medical/dicom/current/output/chtml/part16/chapter_A.html#sect_TID_1002)
Observer Context

* **Parameters:**
  * **observer_type** ([*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept)) – type of observer (see [CID 270](http://dicom.nema.org/medical/dicom/current/output/chtml/part16/sect_CID_270.html) “Observer Type” for options)
  * **observer_identifying_attributes** (*Union* *[*[*highdicom.sr.PersonObserverIdentifyingAttributes*](#highdicom.sr.PersonObserverIdentifyingAttributes) *,* [*highdicom.sr.DeviceObserverIdentifyingAttributes*](#highdicom.sr.DeviceObserverIdentifyingAttributes) *]*) – observer identifying attributes

## append

### Description
Append a content item to the sequence.

### Parameters
* **item** ([*highdicom.sr.ContentItem*](#highdicom.sr.ContentItem)) – SR Content Item

## clear

### Description
Remove all items from S.

## extend

### Description
Extend multiple content items to the sequence.

### Parameters
* **val** (*Iterable* *[*[*highdicom.sr.ContentItem*](#highdicom.sr.ContentItem) *,* [*highdicom.sr.ContentSequence*](#highdicom.sr.ContentSequence) *]*) – SR Content Items
```

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

### Install highdicom from source

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/installation.md

Clone the highdicom repository from GitHub and install it locally.

```bash
git clone https://github.com/imagingdatacommons/highdicom ~/highdicom
```

```bash
pip install ~/highdicom
```

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

### Create a Basic Volume Object

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/volume.md

Instantiate a Volume object by providing a NumPy array and an affine transformation matrix. Specify the coordinate system used for the affine matrix. Access array and affine properties after creation.

```python
import numpy as np
import highdicom as hd


array = np.zeros((32, 256, 256), dtype=np.uint8)
affine = np.array(
    [
        [1.0, 0.0, 0.0, 10.0],
        [0.0, 0.4, 0.0, 20.0],
        [0.0, 0.0, 0.4, -5.0],
        [0.0, 0.0, 0.0,  1.0],
    ]
)

vol = hd.Volume(
    array=array,
    affine=affine,
    coordinate_system="PATIENT",
)

# Once created, you can access the array and the affine via properties
assert np.array_equal(vol.array, array)
assert np.array_equal(vol.affine, affine)

# The datatype of the array, its shape, and the spatial shape (not
# including any channels, see below), may be accessed via
# properties
print(vol.dtype)
# uint8

print(vol.shape)
# (32, 256, 256)

print(vol.spatial_shape)
# (32, 256, 256)
```

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

### Install highdicom using conda

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/installation.md

Install the highdicom package from the conda-forge channel.

```none
conda install conda-forge::highdicom
```

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

### Install highdicom using pip

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/installation.md

Install the pre-built package of highdicom from PyPi.

```none
pip install highdicom
```

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

### ContributingEquipment.for_image_acquisition class method

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Creates an item describing image acquisition of a given image dataset.

```APIDOC
## *classmethod* highdicom.ContributingEquipment.for_image_acquisition

### Description
Create an item describing image acquisition of a given image dataset.

### Parameters
* **dataset** (*pydicom.Dataset*) – Image dataset.

### Returns
Contributing equipment object describing the acquisition of the image in the provided dataset.

### Return type
[highdicom.ContributingEquipment](#highdicom.ContributingEquipment)

### Raises
* **ValueError:** – If the dataset does not represent an image.
* **AttributeError:** – If the dataset does not contain the Manufacturer attribute, or it is empty.
```

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

### Install highdicom with JPEG support

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/installation.md

Install highdicom along with the necessary packages for full JPEG transfer syntax support, including GPL-licensed components.

```none
pip install 'highdicom[libjpeg]'
```

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

### SpecimenDescription Constructor

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Initializes a new instance of the SpecimenDescription class. This class represents a dataset describing a specimen.

```APIDOC
## class highdicom.SpecimenDescription

### Description
Dataset describing a specimen.

### Parameters
* **specimen_id** (*str*) – Identifier of the examined specimen
* **specimen_uid** (*str*) – Unique identifier of the examined specimen
* **specimen_location** (*Union* *[**str* *,* *Tuple* *[**float* *,* *float* *,* *float* *]* *]* *,* *optional*) – Location of the examined specimen relative to the container
    provided either in form of text or in form of spatial X, Y, Z
    coordinates specifying the position (offset) relative to the
    three-dimensional slide coordinate system in millimeter (X, Y) and
    micrometer (Z) unit.
* **specimen_preparation_steps** (*Sequence* *[*[*highdicom.SpecimenPreparationStep*](#highdicom.SpecimenPreparationStep) *]* *,* *optional*) – Steps that were applied during the preparation of the examined
    specimen in the laboratory prior to image acquisition
* **specimen_type** (*Union* *[**pydicom.sr.coding.Code* *,* [*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept) *]* *,* *optional*) – The anatomic pathology specimen type of the specimen (see [CID 8103](http://dicom.nema.org/medical/dicom/current/output/chtml/part16/sect_CID_8103.html)
    “Anatomic Pathology Specimen Type” for options).
* **specimen_short_description** (*str* *,* *optional*) – Short description of the examined specimen.
* **specimen_detailed_description** (*str* *,* *optional*) – Detailed description of the examined specimen.
* **issuer_of_specimen_id** ([*highdicom.IssuerOfIdentifier*](#highdicom.IssuerOfIdentifier) *,* *optional*) – Description of the issuer of the specimen identifier
* **primary_anatomic_structures** (*Sequence* *[**Union* *[**pydicom.sr.Code* *,* [*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept) *]* *]*) – Body site at which specimen was collected
```

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

### Create Segmentation Instance (CT)

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/quickstart.md

Create a Segmentation instance from source images and a mask for a CT scan. Requires defining segment descriptions and other metadata.

```python
import highdicom as hd
import numpy as np
from pydicom.sr.codedict import codes

# Assume image_datasets and mask are already defined
# Example placeholder values:
image_datasets = [] # Replace with actual source image datasets
mask = np.zeros((10, 10), dtype=np.uint8)

description_segment_1 = hd.seg.SegmentDescription(
    segment_number=1,
    segment_label='first segment',
    segmented_property_category=codes.cid7150.Tissue,
    segmented_property_type=codes.cid7166.ConnectiveTissue,
    algorithm_type=hd.seg.SegmentAlgorithmTypeValues.AUTOMATIC,
    tracking_uid=hd.UID(),
    tracking_id='test segmentation'
)

# Create the Segmentation instance
seg_dataset = hd.seg.Segmentation(
    source_images=image_datasets,
    pixel_array=mask,
    segmentation_type=hd.seg.SegmentationTypeValues.BINARY,
    segment_descriptions=[description_segment_1],
    series_instance_uid=hd.UID(),
    series_number=2,
    sop_instance_uid=hd.UID(),
    instance_number=1,
    manufacturer='Manufacturer',
    manufacturer_model_name='Model',
    software_versions='v1',
    device_serial_number='Device XYZ',
    series_description='Example Single Frame CT Segmentation',
)

print(seg_dataset)

seg_dataset.save_as("seg.dcm")
```

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

### get_image_measurement_groups

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get imaging measurements of images.

```APIDOC
## get_image_measurement_groups

### Description
Get imaging measurements of images.
Finds (and optionally filters) content items contained in the CONTAINER content item “Measurement Group” as specified by TID 1501 “Measurement and Qualitative Evaluation Group”.

### Parameters
* **tracking_uid** (*Union* *[**str* *,* *None* *]* *,* *optional*) – Unique tracking identifier
* **finding_type** (*Union* *[*[*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept) *,* *pydicom.sr.coding.Code* *,* *None* *]* *,* *optional*) – Finding
* **finding_site** (*Union* *[*[*highdicom.sr.CodedConcept*](#highdicom.sr.CodedConcept) *,* *pydicom.sr.coding.Code* *,* *None* *]* *,* *optional*) – Finding site
* **referenced_sop_instance_uid** (*Union* *[**str* *,* *None* *]* *,* *optional*) – SOP Instance UID of the referenced instance.
* **referenced_sop_class_uid** (*Union* *[**str* *,* *None* *]* *,* *optional*) – SOP Class UID of the referenced instance.

### Returns
Sequence of content items for each matched measurement group

### Return type
List[[highdicom.sr.MeasurementsAndQualitativeEvaluations](#highdicom.sr.MeasurementsAndQualitativeEvaluations)]
```

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

### Loading and Querying SR Documents

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/quickstart.md

Loads an SR document from a file and demonstrates how to find various content items within it, such as containers, observers, measurements, findings, and regions of interest. Requires `highdicom`, `pydicom`, and `pathlib`.

```python
from pathlib import Path

import highdicom as hd
from pydicom.sr.codedict import codes
from pydicom.dcmread import dcmread
from highdicom.sr.values import RelationshipTypeValues, ValueTypeValues

# Path to SR document instance stored as PS3.10 file
document_file = Path('/path/to/document/file')

# Load document from file on disk
sr_dataset = dcmread(str(document_file))

# Find all content items that may contain other content items.
containers = hd.sr.utils.find_content_items(
    dataset=sr_dataset,
    relationship_type=RelationshipTypeValues.CONTAINS
)
print(containers)

# Query content of SR document, where content is structured according
# to TID 1500 "Measurement Report"
if sr_dataset.ContentTemplateSequence[0].TemplateIdentifier == 'TID1500':
    # Determine who made the observations reported in the document
    observers = hd.sr.utils.find_content_items(
        dataset=sr_dataset,
        name=codes.DCM.PersonObserverName
    )
    print(observers)

    # Find all imaging measurements reported in the document
    measurements = hd.sr.utils.find_content_items(
        dataset=sr_dataset,
        name=codes.DCM.ImagingMeasurements,
        recursive=True
    )
    print(measurements)

    # Find all findings reported in the document
    findings = hd.sr.utils.find_content_items(
        dataset=sr_dataset,
        name=codes.DCM.Finding,
        recursive=True
    )
    print(findings)

    # Find regions of interest (ROI) described in the document
    # in form of spatial coordinates (SCOORD)
    regions = hd.sr.utils.find_content_items(
        dataset=sr_dataset,
        value_type=ValueTypeValues.SCOORD,
        recursive=True
    )
    print(regions)
```

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

### Instantiate Dataset, Apply Model, and Collect Data

Source: https://github.com/imagingdatacommons/highdicom/blob/master/examples/notebooks/segmentation_slide_microscopy.ipynb

Instantiates the custom Dataset, iterates through its frames, applies the segmentation model to each frame, and collects the original image frames and generated masks. The collected data is then stacked into NumPy arrays.

```python
dataset = Dataset(
    url='https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs',
    study_id='1.2.392.200140.2.1.1.1.2.799008771.3960.1519719403.819',
    series_id='1.2.392.200140.2.1.1.1.3.799008771.3960.1519719403.820',
    instance_id='1.2.392.200140.2.1.1.1.4.799008771.3960.1519719570.834'
)

inputs = []
outputs = []
for i in range(len(dataset)):
    image_frame = dataset[i]
    mask_frame = model(image_frame)
    inputs.append(image_frame)
    outputs.append(mask_frame)

image = numpy.stack(inputs)
mask = numpy.stack(outputs)
```

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

### Measurements.unit

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the coded unit of the measurement.

```APIDOC
## Measurements.unit

### Description
coded unit

### Type
[highdicom.sr.CodedConcept](#highdicom.sr.CodedConcept)
```

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

### extend

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Extends the KeyObjectSelection sequence with multiple content items.

```APIDOC
## extend(val: Iterable[[ContentItem](#highdicom.sr.ContentItem)] | [ContentSequence](#highdicom.sr.ContentSequence))

### Description
Extend multiple content items to the sequence.

### Parameters:
* **val** (*Iterable* *[*[*highdicom.sr.ContentItem*](#highdicom.sr.ContentItem) *,* [*highdicom.sr.ContentSequence*](#highdicom.sr.ContentSequence) *]*) – SR Content Items

### Returns:
None
```

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

### SubjectContextDevice Class Methods (from_sequence)

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Constructs a SubjectContextDevice object from a sequence of datasets.

```APIDOC
## *classmethod* from_sequence(sequence: Sequence[Dataset], is_root: bool = False) -> Self

### Description
Construct object from a sequence of datasets.

### Parameters:
* **sequence** (*Sequence* *[**pydicom.dataset.Dataset* *]*) – Datasets representing SR Content Items of template
  TID 1010 “Subject Context, Device”
* **is_root** (*bool* *,* *optional*) – Whether the sequence is used to contain SR Content Items that are
  intended to be added to an SR document at the root of the document
  content tree
* **Returns:**
  Content Sequence containing SR Content Items
* **Return type:**
  [highdicom.sr.SubjectContextDevice](#highdicom.sr.SubjectContextDevice)
```

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

### Measurements.name

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the coded name of the measurement.

```APIDOC
## Measurements.name

### Description
coded name

### Type
[highdicom.sr.CodedConcept](#highdicom.sr.CodedConcept)
```

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

### shape

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the shape of the underlying array.

```APIDOC
## shape

### Description
Shape of the underlying array. For objects of type [`highdicom.VolumeGeometry`](#highdicom.VolumeGeometry), this is equivalent to .shape.

### Method
*property* shape *: tuple[int, ...]*

### Parameters
None

### Returns
Tuple of integers representing the shape of the underlying array.

### Return type
Tuple[int, …]
```

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

### Read Segmentation File

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Demonstrates how to read a segmentation file using `hd.seg.segread`. Ensure the file path is correct.

```python
>>> import highdicom as hd
>>> 
>>> seg = hd.seg.segread('data/test_files/seg_image_ct_binary.dcm')
```

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

### Construct Key Object Selection Document from Dataset

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Use this class method to create a Key Object Selection Document instance from an existing pydicom Dataset. Ensure the dataset represents a Key Object Selection Document.

```python
KeyObjectSelectionDocument.from_dataset(dataset)
```

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

### index

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get the index of a given item.

```APIDOC
## index

### Description
Get the index of a given item.

### Parameters
* **val** ([*highdicom.sr.ContentItem*](#highdicom.sr.ContentItem)) – SR Content Item

### Returns
Index of the item in the sequence

### Return type
int
```

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

### from_dataset Class Method

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Create a LUT from an existing Dataset.

```APIDOC
## *classmethod* from_dataset(dataset: Dataset, copy: bool = True) → Self

Create a LUT from an existing Dataset.

* **Parameters:**
  * **dataset** (*pydicom.Dataset*) – Dataset representing a LUT.
  * **copy** (*bool*) – If True, the underlying dataset is deep-copied such that the
    original dataset remains intact. If False, this operation will
    alter the original dataset in place.
* **Returns:**
  Constructed object
* **Return type:**
  [highdicom.LUT](#highdicom.LUT)
```

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

### index

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get the index of a given item in a sequence.

```APIDOC
## index(val: [ContentItem](#highdicom.sr.ContentItem)) -> int

### Description
Get the index of a given item.

### Parameters
#### Path Parameters
- **val** ([ContentItem](#highdicom.sr.ContentItem)) - SR Content Item

### Returns
Index of the item in the sequence

### Return type
int
```

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

### serial_number property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the serial number of the device.

```APIDOC
## property serial_number *: str | None*

### Description
device serial number

### Type
Union[str, None]
```

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

### MicroscopyBulkSimpleAnnotations Constructor

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Constructs an instance of the Microscopy Bulk Simple Annotations SOP class. This class is used for the Microscopy Bulk Simple Annotations IOD.

```APIDOC
## class highdicom.ann.MicroscopyBulkSimpleAnnotations

### Description
SOP class for the Microscopy Bulk Simple Annotations IOD.

### Parameters
* **source_images** (*Sequence* *[**pydicom.dataset.Dataset* *]*) – Image instances from which annotations were derived. In case of
  “2D” Annotation Coordinate Type, only one source image shall be
  provided. In case of “3D” Annotation Coordinate Type, one or more
  source images may be provided. All images shall have the same
  Frame of Reference UID.
* **annotation_coordinate_type** (*Union* *[**str* *,* [*highdicom.ann.AnnotationCoordinateTypeValues*](#highdicom.ann.AnnotationCoordinateTypeValues) *]*) – Type of coordinates (two-dimensional coordinates relative to origin
  of Total Pixel Matrix in pixel unit or three-dimensional
  coordinates relative to origin of Frame of Reference (Slide) in
  millimeter/micrometer unit)
* **annotation_groups** (*Sequence* *[*[*highdicom.ann.AnnotationGroup*](#highdicom.ann.AnnotationGroup) *]*) – Groups of annotations (vector graphics and corresponding
  measurements)
* **series_instance_uid** (*str*) – UID of the series
* **series_number** (*int*) – Number of the series within the study
* **sop_instance_uid** (*str*) – UID that should be assigned to the instance
* **instance_number** (*int*) – Number that should be assigned to the instance
* **manufacturer** (*Union* *[**str* *,* *None* *]*) – Name of the manufacturer (developer) of the device (software)
  that creates the instance
* **manufacturer_model_name** (*str*) – Name of the device model (name of the software library or
  application) that creates the instance
* **software_versions** (*Union* *[**str* *,* *Tuple* *[**str* *]* *]*) – Version(s) of the software that creates the instance
* **device_serial_number** (*str*) – Manufacturer’s serial number of the device
* **content_description** (*Union* *[**str* *,* *None* *]* *,* *optional*) – Description of the annotation
* **content_creator_name** (*Union* *[**str* *,* *pydicom.valuerep.PersonName* *,* *None* *]* *,* *optional*) – Name of the creator of the annotation (if created manually)
* **transfer_syntax_uid** (*str* *,* *optional*) – UID of transfer syntax that should be used for encoding of
  data elements.
* **content_label** (*Union* *[**str* *,* *None* *]* *,* *optional*) – Content label
* **contributing_equipment** (*Sequence* *[*[*highdicom.ContributingEquipment*](#highdicom.ContributingEquipment) *]*  *|* *None* *,* *optional*) – Additional equipment that has contributed to the acquisition,
  creation or modification of this instance.
* **kwargs** (*Any* *,* *optional*) – Additional keyword arguments that will be passed to the constructor
  of highdicom.base.SOPClass
```

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

### Load and Parse Microscopy Bulk Annotation (ANN) Objects

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/quickstart.md

Demonstrates loading a microscopy annotation file, finding specific annotation groups (e.g., nuclei), and extracting graphic data and measurements. Requires the `highdicom` and `pydicom` libraries.

```python
from pydicom.sr.codedict import codes
from pydicom.sr.coding import Code
import highdicom as hd

# Load a bulk annotation file and convert to highdicom object
ann_dataset = hd.ann.annread('data/test_files/sm_annotations.dcm')

# Search for annotation groups by filtering for annotated property type of
# 'nucleus', and take the first such group
group = ann.get_annotation_groups(
    annotated_property_type=Code('84640000', 'SCT', 'Nucleus'),
)[0]

# Determine the graphic type and the number of annotations
assert group.number_of_annotations == 2
assert group.graphic_type == hd.ann.GraphicTypeValues.POINT

# Get the graphic data as a list of numpy arrays, we have to pass the
# coordinate type from the parent object here
graphic_data = group.get_graphic_data(
    coordinate_type=ann.AnnotationCoordinateType
)

# For annotations of graphic type "POINT" and coordinate type "SCOORD" (2D
# image coordinates), each annotation is a (1 x 2) NumPy array
assert graphic_data[0].shape == (1, group.number_of_annotations)

# Annotations may also optionally contain measurements
names, values, units = group.get_measurements(name=codes.SCT.Area)

# The name and the unit are returned as a list of CodedConcepts
# and the values are returned in a numpy array of shape (number of
# annotations x number of measurements)
assert names[0] == codes.SCT.Area
assert units[0] == codes.UCUM.SquareMicrometer
assert values.shape == (group.number_of_annotations, 1)
```

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

### physical_location property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the physical location of the device.

```APIDOC
## property physical_location *: str | None*

### Description
location of device

### Type
Union[str, None]
```

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

### model_name property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the name of the device model.

```APIDOC
## property model_name *: str | None*

### Description
name of device model

### Type
Union[str, None]
```

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

### Create Comprehensive 3D SR Document

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/tid1500.md

Initializes a Comprehensive 3D SR document, incorporating the measurement report and referencing all evidence datasets. Requires essential DICOM metadata like series number and UIDs.

```python
from pydicom.sr.codedict import codes
import highdicom as hd

# Create the Structured Report instance
sr_dataset = hd.sr.Comprehensive3DSR(
    evidence=[...],  # all datasets referenced in the report
    content=measurement_report,
    series_number=1,
    series_instance_uid=hd.UID(),
    sop_instance_uid=hd.UID(),
    instance_number=1,
    manufacturer='Manufacturer',
    series_description='Example Structured Report',
)
```

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

### manufacturer_name property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the name of the device manufacturer.

```APIDOC
## property manufacturer_name *: str | None*

### Description
name of device manufacturer

### Type
Union[str, None]
```

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

### Creating Microscopy Bulk Simple Annotations (ANN)

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/quickstart.md

Creates a Microscopy Bulk Simple Annotation object to store a large number of annotations efficiently. This example demonstrates defining graphic data, measurements, and annotation groups for nuclei. Requires `highdicom`, `pydicom`, and `numpy`.

```python
from pydicom.sr.codedict import codes
from pydicom.sr.coding import Code
import highdicom as hd
import numpy as np

# Load a slide microscopy image from the highdicom test data (if you have
# cloned the highdicom git repo)
sm_image = hd.imread('data/test_files/sm_image.dcm')

# Graphic data containing two nuclei, each represented by a single point
# expressed in 2D image coordinates
graphic_data = [
    np.array([[34.6, 18.4]]),
    np.array([[28.7, 34.9]]),
]

# You may optionally include measurements corresponding to each annotation
# This is a measurement object representing the areas of each of the two
# nuclei
area_measurement = hd.ann.Measurements(
    name=codes.SCT.Area,
    unit=codes.UCUM.SquareMicrometer,
    values=np.array([20.4, 43.8]),
)

# An annotation group represents a single set of annotations of the same
# type. Multiple such groups may be included in a bulk annotations object
# This group represents nuclei annotations produced by a manual "algorithm"
nuclei_group = hd.ann.AnnotationGroup(
    number=1,
    uid=hd.UID(),
    label='nuclei',
    annotated_property_category=codes.SCT.AnatomicalStructure,
    annotated_property_type=Code('84640000', 'SCT', 'Nucleus'),
    algorithm_type=hd.ann.AnnotationGroupGenerationTypeValues.MANUAL,
    graphic_type=hd.ann.GraphicTypeValues.POINT,
    graphic_data=graphic_data,
    measurements=[area_measurement],
)

# Include the annotation group in a bulk annotation object
bulk_annotations = hd.ann.MicroscopyBulkSimpleAnnotations(
    source_images=[sm_image],
    annotation_coordinate_type=hd.ann.AnnotationCoordinateTypeValues.SCOORD,
    annotation_groups=[nuclei_group],
    series_instance_uid=hd.UID(),
    series_number=10,
    sop_instance_uid=hd.UID(),
    instance_number=1,
    manufacturer='MGH Pathology',
    manufacturer_model_name='MGH Pathology Manual Annotations',
    software_versions='0.0.1',
    device_serial_number='1234',
    content_description='Nuclei Annotations',
    series_description='Example Microscopy Annotations',
)

bulk_annotations.save_as('nuclei_annotations.dcm')
```

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

### KeyObjectSelectionDocument Class Methods

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Methods for constructing and referencing Key Object Selection Documents.

```APIDOC
## classmethod from_dataset(dataset: Dataset) -> Self

### Description
Construct object from an existing dataset.

### Parameters
* **dataset** (*pydicom.dataset.Dataset*) – Dataset representing a Key Object Selection Document

### Returns
Key Object Selection Document

### Return type
[highdicom.ko.KeyObjectSelectionDocument](#highdicom.ko.KeyObjectSelectionDocument)
```

```APIDOC
## resolve_reference(sop_instance_uid: str) -> tuple[str, str, str]

### Description
Resolve reference for an object included in the document content.

### Parameters
* **sop_instance_uid** (*str*) – SOP Instance UID of a referenced object

### Returns
Study, Series, and SOP Instance UID

### Return type
Tuple[str, str, str]
```

```APIDOC
## property transfer_syntax_uid : UID

### Description
TransferSyntaxUID.

### Type
[highdicom.UID](#highdicom.UID)
```

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

### PixelToReferenceTransformer.affine

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get the 4x4 affine transformation matrix.

```APIDOC
## property affine : ndarray

### Description
4x4 affine transformation matrix

### Returns
- **ndarray** - The 4x4 affine transformation matrix.
```

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

### spacing_between_slices

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the spacing between consecutive slices in millimeters.

```APIDOC
## property spacing_between_slices

### Description

float:

Spacing between consecutive slices in millimeter units.

Assumes that frames are stacked down axis 0, rows down axis 1, and columns down axis 2 (the convention used to create volumes from images).

### Type

float
```

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

### Create Segmentation Pyramid with Downsampling Factors

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/seg.md

This example demonstrates creating a multi-resolution segmentation series by specifying a single source image and segmentation mask, along with desired downsample factors. The function automatically generates downsampled versions of the segmentation.

```python
import highdicom as hd
import numpy as np


# Use an example slide microscopy image from the highdicom test data
# directory
sm_image = hd.imread('data/test_files/sm_image.dcm')

# The source image has multiple frames/tiles, but here we create a mask
# corresponding to the entire total pixel matrix
mask = np.zeros(
    (
        sm_image.TotalPixelMatrixRows,
        sm_image.TotalPixelMatrixColumns
    ),
    dtype=np.uint8,
)
mask[38:43, 5:41] = 1

property_category = hd.sr.CodedConcept("91723000", "SCT", "Anatomical Structure")
property_type = hd.sr.CodedConcept("84640000", "SCT", "Nucleus")
segment_descriptions = [
    hd.seg.SegmentDescription(
        segment_number=1,
        segment_label='Segment #1',
        segmented_property_category=property_category,
        segmented_property_type=property_type,
        algorithm_type=hd.seg.SegmentAlgorithmTypeValues.MANUAL,
    ),
]

# This will create a segmentation series of three images: one at the
# original source image resolution (implicit), one at half the size, and
# another at a quarter of the original size.
seg_pyramid = hd.seg.create_segmentation_pyramid(
    source_images=[sm_image],
    pixel_arrays=[mask],
    segmentation_type=hd.seg.SegmentationTypeValues.BINARY,
    segment_descriptions=segment_descriptions,
    series_instance_uid=hd.UID(),
    series_number=1,
    manufacturer='Foo Corp.',
    manufacturer_model_name='Slide Segmentation Algorithm',
    software_versions='0.0.1',
    device_serial_number='1234567890',
    downsample_factors=[2.0, 4.0],
    series_description='Segmentation Pyramid',
)

```

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

### physical_volume

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the total volume in cubic millimeters.

```APIDOC
## physical_volume

### Description
Total volume in cubic millimeter.

### Method
*property* physical_volume *: float*

### Parameters
None

### Returns
Float representing the total volume in cubic millimeters.

### Return type
float
```

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

### Create Volume with RGB and Custom Channels

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/volume.md

Construct a Volume object from components, including spatial and channel dimensions. The channels dictionary maps descriptors to their values, and the order is significant.

```python
import numpy as np
import highdicom as hd

# Array with three spatial dimensions plus 3 color channels and 4 optical
# paths
array = np.random.randint(0, 10, size=(1, 50, 50, 3, 4))

# Names of the 4 optical paths
path_names = ['path1', 'path2', 'path3', 'path4']

vol = hd.Volume.from_components(
    direction=np.eye(3),
    center_position=[98.1, 78.4, 23.1],
    spacing=[2.0, 0.5, 0.5],
    coordinate_system="SLIDE",
    array=array,
    channels={
        hd.RGB_COLOR_CHANNEL_DESCRIPTOR: ['R', 'G', 'B'],
        'OpticalPathIdentifier': path_names
    },
)

# The total shape of the volume includes the channel dimensions
assert vol.shape == (1, 50, 50, 3, 4)

# But the spatial shape excludes them
assert vol.spatial_shape == (1, 50, 50)

# The channel shape includes only the channel dimensions, not the spatial
# dimensions
assert vol.channel_shape == (3, 4)
assert vol.number_of_channel_dimensions == 2

# You can access the descriptors like this
assert vol.channel_descriptors == (
    hd.RGB_COLOR_CHANNEL_DESCRIPTOR,
    hd.ChannelDescriptor('OpticalPathIdentifier'),
)
```

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

### physical_extent

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Gets the side lengths of the volume in millimeters.

```APIDOC
## physical_extent

### Description
Side lengths of the volume in millimeters.

### Method
*property* physical_extent *: tuple[float, float, float]*

### Parameters
None

### Returns
Tuple of three floats representing the side lengths in millimeters.

### Return type
tuple[float, float, float]
```

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

### Create Segmentation Instance (Slide Microscopy)

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/quickstart.md

Derive a Segmentation image from a multi-frame Slide Microscopy (SM) image. This involves reading the SM image, creating a mask, and defining segment descriptions.

```python
from pathlib import Path

import highdicom as hd
import numpy as np
from pydicom.sr.codedict import codes

# Path to multi-frame SM image instance stored as PS3.10 file
image_file = Path('/path/to/image/file')

# Read SM Image data set from PS3.10 files on disk
image_dataset = hd.imread(str(image_file))

# Create a binary segmentation mask
mask = np.max(image_dataset.pixel_array, axis=3) > 1

# Describe the algorithm that created the segmentation
algorithm_identification = hd.AlgorithmIdentificationSequence(
    name='test',
    version='v1.0',
    family=codes.cid7162.ArtificialIntelligence
)

# Describe the segment
description_segment_1 = hd.seg.SegmentDescription(
    segment_number=1,
    segment_label='first segment',
    segmented_property_category=codes.cid7150.Tissue,
    segmented_property_type=codes.cid7166.ConnectiveTissue,
    algorithm_type=hd.seg.SegmentAlgorithmTypeValues.AUTOMATIC,
    algorithm_identification=algorithm_identification,
    tracking_uid=hd.UID(),
    tracking_id='test segmentation of slide microscopy image'
)

# Create the Segmentation instance
seg_dataset = hd.seg.Segmentation(
    source_images=[image_dataset],
    pixel_array=mask,
    segmentation_type=hd.seg.SegmentationTypeValues.BINARY,
    segment_descriptions=[description_segment_1],
    series_instance_uid=hd.UID(),
    series_number=2,
    sop_instance_uid=hd.UID(),
    instance_number=1,
    manufacturer='Manufacturer',
    manufacturer_model_name='Model',
    software_versions='v1',
    device_serial_number='Device XYZ',
    series_description='Example Multi-frame Segmentation',
)

print(seg_dataset)
```

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

### SoftcopyVOILUTTransformation Constructor

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Initializes a SoftcopyVOILUTTransformation object. It can be configured with window center/width, window explanation, VOI LUT function, specific VOI LUTs, or referenced images.

```APIDOC
## class highdicom.pr.SoftcopyVOILUTTransformation

### Description
Dataset describing the VOI LUT Transformation as part of the Pixel Transformation Sequence to transform the modality pixel values into pixel values that are of interest to a user or an application. The description is specific to the application of the VOI LUT Transformation in the context of a Softcopy Presentation State, where potentially only a subset of explicitly referenced images should be transformed.

### Parameters
* **window_center** (*Union* *[**float* *,* *Sequence* *[**float* *]* *,* *None* *]* *,* *optional*) – Center value of the intensity window used for display.
* **window_width** (*Union* *[**float* *,* *Sequence* *[**float* *]* *,* *None* *]* *,* *optional*) – Width of the intensity window used for display.
* **window_explanation** (*Union* *[**str* *,* *Sequence* *[**str* *]* *,* *None* *]* *,* *optional*) – Free-form explanation of the window center and width.
* **voi_lut_function** (*Union* *[*[*highdicom.VOILUTFunctionValues*](#highdicom.VOILUTFunctionValues) *,* *str* *,* *None* *]* *,* *optional*) – Description of the LUT function parametrized by `window_center` and `window_width`.
* **voi_luts** (*Union* *[**Sequence** *[*[*highdicom.VOILUT*](#highdicom.VOILUT) *]* *,* *None* *]* *,* *optional*) – Intensity lookup tables used for display.
* **referenced_images** (*Union* *[*[*highdicom.ReferencedImageSequence*](#highdicom.ReferencedImageSequence) *,* *None* *]* *,* *optional*) – Images to which the VOI LUT Transformation described in this dataset applies. Note that if unspecified, the VOI LUT Transformation applies to every frame of every image referenced in the presentation state object that this dataset is included in.

#### NOTE
Either `window_center` and `window_width` should be provided or `voi_luts` should be provided, or both. `window_explanation` should only be provided if `window_center` is provided.
```

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

### lut_data Property

Source: https://github.com/imagingdatacommons/highdicom/blob/master/docs/package.md

Get the LUT data array.

```APIDOC
## *property* lut_data *: ndarray*

LUT data

* **Type:**
  numpy.ndarray
```