pydicom.fileset.FileSet¶

class pydicom.fileset.FileSet(ds: Dataset | str | PathLike | None = None)[source]¶

Representation of a DICOM File-set.

__init__(ds: Dataset | str | PathLike | None = None) → None[source]¶

Create or load a File-set.

Parameters:: ds (pydicom.dataset.Dataset, str or PathLike, optional) – If loading a File-set, the DICOMDIR dataset or the path to the DICOMDIR file.

Methods

`__init__`([ds])	Create or load a File-set.
`add`(ds_or_path)	Stage an instance for addition to the File-set.
`add_custom`(ds_or_path, leaf)	Stage an instance for addition to the File-set using custom records.
`clear`()	Clear the File-set.
`copy`(path[, force_implicit])	Copy the File-set to a new root directory and return the copied File-set.
`find`([load])	Return matching instances in the File-set
`find_values`(elements[, instances, load])	Return a list of unique values for given element(s).
`load`(ds_or_path[, include_orphans, ...])	Load an existing File-set.
`remove`(instance)	Stage instance(s) for removal from the File-set.
`write`([path, use_existing, force_implicit])	Write the File-set, or changes to the File-set, to the file system.

Attributes

`ID`	Return the File-set ID (if available) or `None`.
`UID`	Return the File-set's UID.
`descriptor_character_set`	Return the Specific Character Set of File-set Descriptor File (if available) or `None`.
`descriptor_file_id`	Return the File-set Descriptor File ID (if available) or `None`.
`is_staged`	Return `True` if the File-set is new or has changes staged.
`path`	Return the absolute path to the File-set root directory as `str` (if set) or `None` otherwise.

property ID: str | None¶: Return the File-set ID (if available) or None.

property UID: UID¶: Return the File-set’s UID.

add(ds_or_path: Dataset | str | PathLike) → FileInstance[source]¶

Stage an instance for addition to the File-set.

If the instance has been staged for removal then calling add() will cancel the staging and the instance will not be removed.

Parameters:: ds_or_path (pydicom.dataset.Dataset, str or PathLike) – The instance to add to the File-set, either as a Dataset or the path to the instance.
Returns:: The FileInstance that was added.
Return type:: FileInstance

See also

add_custom()

add_custom(ds_or_path: Dataset | str | PathLike, leaf: RecordNode) → FileInstance[source]¶

Stage an instance for addition to the File-set using custom records.

This method allows you to add a SOP instance and customize the directory records that will be used when writing the DICOMDIR file. It must be used when you require PRIVATE records and may be used instead of modifying DIRECTORY_RECORDERS with your own record definition functions when the default functions aren’t suitable.

The following elements will be added automatically to the supplied directory records if required and not present:

(0004,1400) Offset of the Next Directory Record
(0004,1410) Record In-use Flag
(0004,1420) Offset of Referenced Lower-Level Directory Entity
(0004,1500) Referenced File ID
(0004,1510) Referenced SOP Class UID in File
(0004,1511) Referenced SOP Instance UID in File
(0004,1512) Referenced Transfer Syntax UID in File

If the instance has been staged for removal then calling add_custom() will cancel the staging and the instance will not be removed.

Examples

Add a SOP Instance using a two record hierarchy of PATIENT -> PRIVATE

from pydicom import Dataset, examples
from pydicom.fileset import FileSet, RecordNode
from pydicom.uid import generate_uid

# The instance to be added
ds = examples.ct

# Define the leaf node (the PRIVATE record)
record = Dataset()
record.DirectoryRecordType = "PRIVATE"
record.PrivateRecordUID = generate_uid()
leaf_node = RecordNode(record)

# Define the top node (the PATIENT record)
record = Dataset()
record.DirectoryRecordType = "PATIENT"
record.PatientID = ds.PatientID
record.PatientName = ds.PatientName
top_node = RecordNode(record)

# Set the node relationship
leaf_node.parent = top_node

# Add the instance to the File-set
fs = FileSet()
instance = fs.add_custom(ds, leaf_node)

Parameters:

ds_or_path (pydicom.dataset.Dataset, str or PathLike) – The instance to add to the File-set, either as a Dataset or the path to the instance.
leaf (pydicom.fileset.RecordNode) – The leaf node for the instance, should have its ancestors nodes set correctly as well as their corresponding directory records. Should have no more than 7 ancestors due to the semantics used by FileSet when creating the directory structure.

Returns:

The FileInstance that was added.

Return type:

FileInstance