pydicom.fileset.FileSet

class pydicom.fileset.FileSet(ds: Optional[Union[Dataset, str, PathLike]] = None)[source]

Representation of a DICOM File-set.

__init__(ds: Optional[Union[Dataset, str, PathLike]] = 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: Optional[str]

Return the File-set ID (if available) or None.

property UID: UID

Return the File-set’s UID.

add(ds_or_path: Union[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: Union[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 dcmread, Dataset
from pydicom.data import get_testdata_file
from pydicom.fileset import FileSet, RecordNode
from pydicom.uid import generate_uid

# The instance to be added
ds = dcmread(get_testdata_file("CT_small.dcm"))

# 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

See also

add()

clear() None[source]

Clear the File-set.

copy(path: Union[str, PathLike], force_implicit: bool = False) FileSet[source]

Copy the File-set to a new root directory and return the copied File-set.

Changes staged to the original FileSet will be applied to the new File-set. The original FileSet will remain staged.

Parameters
  • path (str or PathLike) – The root directory where the File-set is to be copied to.

  • force_implicit (bool, optional) – If True force the DICOMDIR file to be encoded using Implicit VR Little Endian which is non-conformant to the DICOM Standard (default False).

Returns

The copied File-set as a FileSet.

Return type

pydicom.fileset.FileSet

property descriptor_character_set: Optional[str]

Return the Specific Character Set of File-set Descriptor File (if available) or None.

property descriptor_file_id: Optional[str]

Return the File-set Descriptor File ID (if available) or None.

find(load: bool = False, **kwargs: Any) List[FileInstance][source]

Return matching instances in the File-set

Limitations

  • Only single value matching is supported so neither PatientID=['1234567', '7654321'] or PatientID='1234567', PatientID='7654321' will work (although the first example will work if the Patient ID is actually multi-valued).

  • Repeating group and private elements cannot be used when searching.

Parameters
  • load (bool, optional) – If True, then load the SOP Instances belonging to the File-set and perform the search against their available elements. Otherwise (default) search only the elements available in the corresponding directory records (more efficient, but only a limited number of elements are available).

  • **kwargs – Search parameters, as element keyword=value (i.e. PatientID='1234567', StudyDescription="My study".

Returns

A list of matching instances.

Return type

list of pydicom.fileset.FileInstance

find_values(elements: Union[str, int, List[Union[str, int]]], instances: Optional[List[FileInstance]] = None, load: bool = False) Union[List[Any], Dict[Union[str, int], List[Any]]][source]

Return a list of unique values for given element(s).

Parameters
  • elements (str, int or pydicom.tag.BaseTag, or list of these) – The keyword or tag of the element(s) to search for.

  • instances (list of pydicom.fileset.FileInstance, optional) – Search within the given instances. If not used then all available instances will be searched.

  • load (bool, optional) – If True, then load the SOP Instances belonging to the File-set and perform the search against their available elements. Otherwise (default) search only the elements available in the corresponding directory records (more efficient, but only a limited number of elements are available).

Returns

  • If single element was queried: A list of value(s) for the element available in the instances.

  • If list of elements was queried: A dict of element value pairs with lists of value(s) for the elements available in the instances.

Return type

list of object(s), or dict of lists of object(s)

property is_staged: bool

Return True if the File-set is new or has changes staged.

load(ds_or_path: Union[Dataset, str, PathLike], include_orphans: bool = True, raise_orphans: bool = False) None[source]

Load an existing File-set.

Existing File-sets that do not use the same directory structure as pydicom will be staged to be moved to a new structure. This is because the DICOM Standard attaches no semantics to how the files in a File-set are to be structured so it’s impossible to determine what the layout will be when changes are to be made.

Parameters
  • ds_or_path (pydicom.dataset.Dataset, str or PathLike) – An existing File-set’s DICOMDIR, either as a Dataset or the path to the DICOMDIR file as str or pathlike.

  • include_orphans (bool, optional) – If True (default) include instances referenced by orphaned directory records in the File-set.

  • raise_orphans (bool, optional) – If True then raise an exception if orphaned directory records are found in the File-set (default False).

property path: Optional[str]

Return the absolute path to the File-set root directory as str (if set) or None otherwise.

remove(instance: Union[FileInstance, List[FileInstance]]) None[source]

Stage instance(s) for removal from the File-set.

If the instance has been staged for addition to the File-set, calling remove() will cancel the staging and the instance will not be added.

Parameters

instance (pydicom.fileset.FileInstance or a list of FileInstance) – The instance(s) to remove from the File-set.

write(path: Optional[Union[str, PathLike]] = None, use_existing: bool = False, force_implicit: bool = False) None[source]

Write the File-set, or changes to the File-set, to the file system.

Warning

If modifying an existing File-set it’s strongly recommended that you follow standard data management practices and ensure that you have an up-to-date backup of the original data.

By default, for both new or existing File-sets, pydicom uses the following directory structure semantics when writing out changes:

  • For instances defined using the standard four-levels of directory records (i.e. PATIENT/STUDY/SERIES + one of the record types such as IMAGE or RT DOSE): PTxxxxxx/STxxxxxx/SExxxxxx/ with a filename such as IMxxxxxx (for IMAGE), where the first two characters are dependent on the record type and xxxxxx is a numeric or alphanumeric index.

  • For instances defined using the standard one-level directory record (i.e. PALETTE, IMPLANT): a filename such as PAxxxxxx (for PALETTE).

  • For instances defined using PRIVATE directory records then the structure will be along the lines of P0xxxxxx/P1xxxxxx/P2xxxxxx for PRIVATE/PRIVATE/PRIVATE, PTxxxxxx/STxxxxxx/P2xxxxxx for PATIENT/STUDY/PRIVATE.

When only changes to the DICOMDIR file are required or instances have only been removed from an existing File-set you can use the use_existing keyword parameter to keep the existing directory structure and only update the DICOMDIR file.

Parameters
  • path (str or PathLike, optional) – For new File-sets, the absolute path to the root directory where the File-set will be written. Using path with an existing File-set will raise ValueError.

  • use_existing (bool, optional) – If True and no instances have been added to the File-set (removals are OK), then only update the DICOMDIR file, keeping the current directory structure rather than converting everything to the semantics used by pydicom for File-sets (default False).

  • force_implicit (bool, optional) – If True force the DICOMDIR file to be encoded using Implicit VR Little Endian which is non-conformant to the DICOM Standard (default False).

Raises

ValueError – If use_existing is True but instances have been staged for addition to the File-set.