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.
- 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.
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 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 INDEX_FILE will print the series tree for the given index file.
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 |
|---|---|---|---|
--help, -h |
boolean | Show this message and exit. | False |