Dicom find

dicom_find

Functions:

Name	Description
convert_to_case_insensitive	Deprecated helper kept for compatibility.
filter_valid_dicoms	Yield valid DICOM file paths from a directory.
find_dicoms	Locate DICOM files in a specified directory.

convert_to_case_insensitive

convert_to_case_insensitive(extension: str) -> str

Deprecated helper kept for compatibility.

Source code in src/imgtools/dicom/dicom_find.py

def convert_to_case_insensitive(extension: str) -> str:
    """Deprecated helper kept for compatibility."""
    if not extension:
        return ""

    lower_extension = extension.lower()
    return "".join(
        f"[{char.lower()}{char.upper()}]" for char in lower_extension
    )

filter_valid_dicoms

filter_valid_dicoms(
    directory: pathlib.Path,
    check_header: bool,
    case_sensitive: bool,
    search_input: typing.List[str] | None,
    extension: str,
    recursive: bool,
) -> typing.Generator[pathlib.Path, None, None]

Yield valid DICOM file paths from a directory.

Unlike the original glob/rglob implementation, this traversal follows nested symlinked directories.

Source code in src/imgtools/dicom/dicom_find.py

def filter_valid_dicoms(
    directory: Path,
    check_header: bool,
    case_sensitive: bool,
    search_input: List[str] | None,
    extension: str,
    recursive: bool,
) -> Generator[Path, None, None]:
    """
    Yield valid DICOM file paths from a directory.

    Unlike the original glob/rglob implementation, this traversal follows
    nested symlinked directories.
    """
    normalized_extension = _normalize_extension(extension)

    logger.debug(
        "Searching for DICOM files",
        directory=directory,
        recursive=recursive,
        follow_symlinks=True,
        check_header=check_header,
        case_sensitive=case_sensitive,
        search_input=search_input,
        extension=normalized_extension,
    )

    for file in _iter_files_following_symlinks(directory, recursive):
        if not _matches_extension(file, normalized_extension, case_sensitive):
            continue

        if not _matches_search_input(file, search_input):
            continue

        if _is_valid_dicom(file, check_header):
            yield file.absolute()

find_dicoms

find_dicoms(
    directory: pathlib.Path,
    recursive: bool = True,
    check_header: bool = False,
    extension: str = "dcm",
    case_sensitive: bool = False,
    limit: int | None = None,
    search_input: typing.List[str] | None = None,
) -> typing.List[pathlib.Path]

Locate DICOM files in a specified directory.

This function scans a directory for files matching the specified extension and validates them as DICOM files based on the provided options. It supports recursive search, nested symbolic links to directories, and optional header validation to confirm file validity.

Parameters:

Name	Type	Description	Default
directory	pathlib.Path	The directory in which to search for DICOM files.	required
recursive	bool	Whether to include subdirectories in the search.	True
check_header	bool	Whether to validate files by checking for a valid DICOM header. - If True, perform DICOM header validation (slower but more accurate). - If False, skip header validation and rely on extension and file checks.	False
extension	str	File extension to search for (e.g., "dcm"). If empty, consider all files regardless of extension.	"dcm"
case_sensitive	bool	Whether to perform a case-sensitive search for the file extension.	False
limit	int	Maximum number of DICOM files to return. If None, return all found files.	None
search_input	typing.List[str]	List of terms to filter files by. Only files containing all terms in their paths will be included. If None, no filtering is applied.	None

Returns:

Type	Description
typing.List[pathlib.Path]	A list of valid DICOM file paths found in the directory.

Source code in src/imgtools/dicom/dicom_find.py

def find_dicoms(
    directory: Path,
    recursive: bool = True,
    check_header: bool = False,
    extension: str = "dcm",
    case_sensitive: bool = False,
    limit: int | None = None,
    search_input: List[str] | None = None,
) -> List[Path]:
    """Locate DICOM files in a specified directory.

    This function scans a directory for files matching the specified extension
    and validates them as DICOM files based on the provided options. It supports
    recursive search, nested symbolic links to directories, and optional header
    validation to confirm file validity.

    Parameters
    ----------
    directory : Path
        The directory in which to search for DICOM files.
    recursive : bool
        Whether to include subdirectories in the search.
    check_header : bool
        Whether to validate files by checking for a valid DICOM header.
            - If `True`, perform DICOM header validation (slower but more accurate).
            - If `False`, skip header validation and rely on extension and file checks.
    extension : str, default="dcm"
        File extension to search for (e.g., "dcm"). If empty, consider all files
        regardless of extension.
    case_sensitive : bool, default=False
        Whether to perform a case-sensitive search for the file extension.
    limit : int, optional
        Maximum number of DICOM files to return. If `None`, return all found files.
    search_input : List[str], optional
        List of terms to filter files by. Only files containing all terms
        in their paths will be included. If `None`, no filtering is applied.

    Returns
    -------
    List[Path]
        A list of valid DICOM file paths found in the directory.
    """
    files = filter_valid_dicoms(
        directory=directory,
        check_header=check_header,
        case_sensitive=case_sensitive,
        search_input=search_input,
        extension=extension or "",
        recursive=recursive,
    )

    return list(islice(files, limit)) if limit else list(files)