imgtools CLI#
imgtools#
A collection of tools for working with medical imaging data.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--quiet, -q |
boolean | Suppress all logging except errors, overrides verbosity options. | False |
--verbose, -v |
integer range (0 and above) |
Increase verbosity of logging, overrides environment variable. (0-3: ERROR, WARNING, INFO, DEBUG). | 0 |
--version |
boolean | Show the version and exit. | False |
-h, --help |
boolean | Show this message and exit. | False |
Subcommands
- autopipeline: Core utility to process messy DICOM data into organized NIfTI files.
- dicomfind: A tool to find DICOM files.
- dicomshow: Display and extract DICOM file metadata in a readable table format.
- dicomsort: Sorts DICOM files into directories based on their tags.
- index: Crawl DICOM directory and create a database index.
- interlacer: Visualize DICOM series relationships after indexing.
- nnunet-pipeline: Process medical images in nnUNet format.
imgtools autopipeline#
Core utility to process messy DICOM data into organized NIfTI files.
This command allows you to process medical images in a directory structure, apply transformations, and save the results to a specified output directory.
INPUT_DIRECTORY: Directory containing the input images. OUTPUT_DIRECTORY: Directory to save the processed images.
The default filename format is:
{SampleNumber}__{PatientID}/{Modality}_{SeriesInstanceUID}/{ImageID}.nii.gz
where:
- SampleNumber: The identifier for the sample after querying.
- PatientID: The ID of the patient.
- Modality: The imaging modality (e.g., CT, MRI).
- SeriesInstanceUID: The unique identifier for the series.
- ImageID: The cutomized identifier for the image.
- By default, the modality of the image
- If RTSTRUCT or SEG, uses custom format based on the roi_strategy roi_match_map and roi names. TODO:: explain this in the docs?
It is not recommended to change the default filename format to prevent overwriting files. The default format is designed to ensure that the output filenames are unique and informative. If you need to customize the output make sure to use a format that maintains uniqueness and clarity.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--filename-format, -f |
text | Format string for output filenames with placeholders for metadata values | {SampleNumber}__{PatientID}/{Modality}_{SeriesInstanceUID}/{ImageID}.nii.gz |
--modalities, -m |
text | List of modalities to process, in hierarchical order. For example, '--modalities CT,PT,RTSTRUCT' or '--modalities MR,SEG' | _required |
--existing-file-mode |
choice (overwrite | skip | fail) |
How to handle existing files | fail |
--update-crawl |
boolean | Force recrawling of the input directory | False |
--jobs, -j |
integer | Number of parallel jobs | None |
--spacing |
text | Resampling spacing as comma-separated values i.e '--spacing 1.0,1.0,1.0' | 0.0,0.0,0.0 |
--window-width |
float | Width of the window for intensity windowing | None |
--window-level |
float | Midpoint of the window for intensity windowing | None |
--roi-ignore-case / --roi-case-sensitive |
boolean | Perform case‑insensitive ROI matching (default: enabled) | True |
--roi-strategy |
choice (MERGE | KEEP_FIRST | SEPARATE) |
Strategy for handling ROI matches | SEPARATE |
--roi-allow-multi-matches / --roi-disallow-multi-matches |
boolean | Allow one ROI to match multiple keys in the match map | True |
--roi-on-missing-regex |
choice (IGNORE | WARN | ERROR) |
How to handle when no ROI matches any pattern | WARN |
--roi-match-map, -rmap |
text | ROI matching patterns in format 'key:pattern1,pattern2,...'. Can be used multiple times to specify multiple roi mappings. CLI arguments take precedence over entries in the YAML file, if common keys exist. | None |
--roi-match-yaml, -ryaml |
file | Path to YAML file containing ROI matching patterns. | None |
-h, --help |
boolean | Show this message and exit. | False |
imgtools dicomfind#
A tool to find DICOM files.
PATH is the directory to search for DICOM files.
SEARCH_INPUT is an optional list of substring(s) to search for in the DICOM files. If multiple substrings are provided, all substrings must match to return a result.
i.e dicomfind /path/to/directory/ "substring1" "substring2" "substring3"
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
-e, --extension |
text | File extension to look for. | dcm |
-c, --count |
boolean | Whether to just print the count of files found. This is useful for scripts. | False |
-l, --limit |
integer | The limit of results to return. | None |
-ch, --check-header |
boolean | Whether to check DICOM header for "DICM" signature. | False |
-s, --sorted |
boolean | Sort the results alphabetically. | False |
-h, --help |
boolean | Show this message and exit. | False |
imgtools dicomshow#
Display and extract DICOM file metadata in a readable table format.
FILE_PATH[::FIELD] specifies what to display: - FILE_PATH: Show all metadata from the DICOM file - FILE_PATH::FIELD: Extract only the specified field
FIELD syntax options: • Standard tag names: Modality, PatientName, SeriesDescription • Nested tags: tag.nested_tag • Array indexing: tag[0] • Combining methods: tag[0].nested_tag • DICOM hex tags: (0008,0060) for modality
Examples: imgtools dicomshow scan.dcm # Show all metadata imgtools dicomshow scan.dcm::Modality # Show only the modality imgtools dicomshow scan.dcm::PatientName # Extract patient name imgtools dicomshow scan.dcm::SequenceItem[0].Value # Access sequence data imgtools dicomshow scan.dcm::(0010,0010) # Use standard DICOM tag
Output is formatted as a color-coded table with field names and values.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pydicom, -p |
boolean | Use raw pydicom implementation instead of enhanced metadata extraction. Faster but excludes computed fields. | False |
--no-progress |
boolean | Disable progress bars when displaying large files. Use this when piping output or in scripts. | False |
-h, --help |
boolean | Show this message and exit. | False |
imgtools dicomsort#
Sorts DICOM files into directories based on their tags.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--action, -a |
choice (move | copy | symlink | hardlink) |
Action to perform on the files. | _required |
-n, --dry-run |
boolean | Do not move or copy files, just print what would be done. Always recommended to use this first to confirm the operation! | False |
-j, --num-workers |
integer | Number of worker processes to use for sorting. | 1 |
--truncate-uids, -t |
integer | Truncate the UIDs in the DICOM files to the specified length. Set to 0 to disable truncation. | 5 |
-h, --help |
boolean | Show this message and exit. | False |
imgtools index#
Crawl DICOM directory and create a database index.
-
looks for all DICOM files in the specified directory, extracts metadata, and builds a comprehensive index of the dataset.
-
The index includes information about the series, modalities, and other relevant details, making it easier to manage and analyze the DICOM files.
-
The output is saved in a structured format, including JSON and CSV files, which can be used for further processing or analysis.
-
By default, it saves the results in a ".imgtools" folder right next to your DICOM directory, but you can pick your own place to store them.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dicom-dir |
path | Path to the DICOM directory. | _required |
--output-dir |
path | Path to the output directory. If not specified, a directory named '.imgtools' will be created in the parent directory of the DICOM directory. | None |
--dataset-name |
text | Name of the dataset. If not specified, the name of the DICOM directory will be used. | None |
--n-jobs |
integer | Number of jobs to use for parallel processing. | 2 |
--force |
boolean | Force overwrite existing files. | False |
-h, --help |
boolean | Show this message and exit. | False |
imgtools interlacer#
Visualize DICOM series relationships after indexing.
This command will print the tree hierarchy of DICOM series relationships
similar to GNU/Linux tree command.
Only shows supported modalities.
`interlacer PATH will print the series tree for the given index file / directory.
If PATH is a path to an index.csv file, then the tree will be constructed using that index file. If instead PATH is a path to a directory, if the an index file for the directory exists it will be used to contruct the tree, otherwise the directory will be crawled first.
The index file should be a CSV file with the following columns: - SeriesInstanceUID - Modality - PatientID - StudyInstanceUID - folder - ReferencedSeriesUID
Visit https://bhklab.github.io/med-imagetools/ for more information.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--query-string, -q |
text | Comma-separated string of modalities to query (e.g., 'CT,MR'). |
Supported modalities: CT, PT, MR, SEG, RTSTRUCT, RTDOSE. | None |
| --group-by-root, -g | boolean | If True, group the returned dicoms by their root CT/MR/PT
node (i.e., avoid duplicate root nodes across results). | True |
| --n-jobs | integer | Number of jobs to use for parallel processing. | 2 |
| --force | boolean | Force overwrite existing files. | False |
| --help, -h | boolean | Show this message and exit. | False |
imgtools nnunet-pipeline#
Process medical images in nnUNet format.
This command allows you to process medical images in the nnUNet directory structure, apply transformations, and save the results to a specified output directory.
INPUT_DIRECTORY: Directory containing the input images. OUTPUT_DIRECTORY: Directory to save the processed images.
- SampleNumber: The identifier for the sample after querying.
- PatientID: The ID of the patient.
- Modality: The imaging modality (e.g., CT, MRI).
- SeriesInstanceUID: The unique identifier for the series.
- ImageID: The cutomized identifier for the image.
- By default, the modality of the image
- If RTSTRUCT or SEG, uses custom format based on the roi_strategy roi_match_map and roi names. TODO:: explain this in the docs?
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--modalities, -m |
text | List of modalities to process, in hierarchical order. For example, '--modalities CT,RTSTRUCT' or '--modalities MR,SEG' | _required |
--roi-match-yaml, -ryaml |
file | Path to YAML file containing ROI matching patterns. | _required |
--mask-saving-strategy, -ms |
choice (label_image | sparse_mask | region_mask) |
Strategy for saving masks. | label_image |
--existing-file-mode |
choice (overwrite | skip | fail) |
How to handle existing files | fail |
--update-crawl |
boolean | Force recrawling of the input directory | False |
--jobs, -j |
integer | Number of parallel jobs | None |
--spacing |
text | Resampling spacing as comma-separated values i.e '--spacing 1.0,1.0,1.0' | 0.0,0.0,0.0 |
--window-width |
float | Width of the window for intensity windowing | None |
--window-level |
float | Midpoint of the window for intensity windowing | None |
--roi-ignore-case / --roi-case-sensitive |
boolean | Perform case‑insensitive ROI matching (default: enabled) | True |
--roi-allow-multi-matches / --roi-disallow-multi-matches |
boolean | Allow one ROI to match multiple keys in the match map | True |
-h, --help |
boolean | Show this message and exit. | False |