diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ac32855..6284a5f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -50,12 +50,4 @@ repos: hooks: - id: pyright args: ["--threads", "24"] - # additional_dependencies: [ - # colorama, - # tqdm, - # numpy, - # deprecated, - # psutil, - # tabulate, - # ] pass_filenames: false diff --git a/docs/contributing.md b/docs/contributing.md index 4f6b83f..1eb5c0a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -245,7 +245,7 @@ To add a new preprocessing command: 1. Create script in `itkit/process/` 2. Add entry point in `pyproject.toml` -3. Document in `docs/preprocessing.md` +3. Create documentation in `docs/itk_*.md` and update `mkdocs.yml` 4. Add tests in `tests/` 5. Support common flags (`--mp`, `--help`) diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index f0aaa86..0000000 --- a/docs/faq.md +++ /dev/null @@ -1,388 +0,0 @@ -# FAQ and Troubleshooting - -Frequently asked questions and common issues with ITKIT. - -## Installation Issues - -### Q: I get import errors after installation - -**A:** Try reinstalling ITKIT with force-reinstall: - -```bash -pip install itkit --force-reinstall -``` - -If the issue persists, check that all dependencies are installed: - -```bash -pip install -r requirements.txt -``` - -### Q: SimpleITK installation fails - -**A:** SimpleITK requires specific system libraries. Try: - -```bash -# Update pip first -pip install --upgrade pip - -# Install SimpleITK -pip install SimpleITK -``` - -On Linux, you may need system packages: - -```bash -sudo apt-get install python3-dev -``` - -### Q: PyQt6 GUI won't start - -**A:** Ensure you installed the GUI dependencies: - -```bash -pip install "itkit[gui]" -``` - -If running on a server without display: - -```bash -export QT_QPA_PLATFORM=offscreen -itkit-app -``` - -### Q: Version conflicts with other packages - -**A:** Use a virtual environment to isolate ITKIT: - -```bash -python -m venv itkit_env -source itkit_env/bin/activate # On Windows: itkit_env\Scripts\activate -pip install itkit -``` - -## Usage Issues - -### Q: itk_check reports mismatched spacing but images look correct - -**A:** Medical images can have very small spacing differences due to floating-point precision. Use tolerance in your checks: - -```bash -# Instead of exact values, use ranges -itk_check check /data --min-spacing 0.9 0.9 0.9 --max-spacing 1.1 1.1 1.1 -``` - -### Q: itk_resample produces incorrect output - -**A:** Check: - -1. **Coordinate order:** ITKIT uses Z, Y, X order -2. **Field type:** Use `dataset` for both images and labels, or specify `image`/`label` appropriately -3. **Spacing values:** Ensure they're in millimeters - -Correct usage: - -```bash -itk_resample dataset /src /dst --spacing 1.0 1.0 1.0 # Z Y X order -``` - -### Q: Patches extracted with itk_patch are all background - -**A:** Adjust the foreground ratio threshold: - -```bash -itk_patch /src /dst \ - --patch-size 96 96 96 \ - --patch-stride 48 48 48 \ - --minimum-foreground-ratio 0.01 # Lower threshold -``` - -Or keep some empty patches: - -```bash -itk_patch /src /dst \ - --patch-size 96 96 96 \ - --patch-stride 48 48 48 \ - --keep-empty-label-prob 0.2 -``` - -### Q: Multiprocessing (--mp) doesn't speed things up - -**A:** Multiprocessing overhead can exceed benefits for small datasets. Use it only when: - -- Dataset has many samples (>50) -- Individual files are large -- I/O is not the bottleneck - -Control number of workers: - -```bash -itk_resample dataset /src /dst --spacing 1.0 1.0 1.0 --mp --workers 4 -``` - -### Q: GUI DPI is too small/large - -**A:** Set the Qt scale factor: - -```bash -# Double size -QT_SCALE_FACTOR=2 itkit-app - -# Half size -QT_SCALE_FACTOR=0.5 itkit-app -``` - -## Dataset Issues - -### Q: My dataset structure doesn't match ITKIT format - -**A:** You need to reorganize your data. ITKIT requires: - -```plaintext -dataset/ -├── image/ -│ └── files -└── label/ - └── files -``` - -Use symbolic links if you don't want to copy: - -```bash -mkdir -p dataset/image dataset/label -ln -s /original/images/* dataset/image/ -ln -s /original/labels/* dataset/label/ -``` - -Or use `itk_check` in symlink mode: - -```bash -itk_check symlink /original/mixed --output /dataset/organized -``` - -### Q: Image and label have different sizes - -**A:** This indicates preprocessing issues. Ensure: - -1. Labels were created from the same source images -2. Both underwent the same preprocessing -3. Both have matching metadata - -To fix, resample both to the same space: - -```bash -itk_resample dataset /src /dst --spacing 1.0 1.0 1.0 -``` - -### Q: Conversion to MONAI/TorchIO format fails - -**A:** Verify: - -1. Input follows ITKIT format (image/ and label/ folders) -2. File names match between image/ and label/ -3. You have write permissions in output directory - -Debug by converting a single sample manually: - -```python -from itkit.io import sitk_toolkit -import SimpleITK as sitk - -image = sitk.ReadImage("dataset/image/case001.mha") -sitk.WriteImage(image, "test_output.nii.gz") -``` - -## Framework Integration Issues - -### Q: OpenMMLab imports fail - -**A:** Install the OneDL redistributions: - -```bash -pip install "itkit[advanced]" -``` - -### Q: MMEngine experiments won't start - -**A:** Check that required variables are set: - -```python -# In your experiment script -mm_workdir = "/path/to/workdir" -mm_testdir = "/path/to/testdir" -mm_configdir = "/path/to/configs" -``` - -And verify config directory structure: - -```plaintext -configs/ -└── 0.1.MyExperiment/ - ├── mgam.py - └── model.py -``` - -### Q: MONAI transforms not working with ITKIT datasets - -**A:** Ensure you're using MONAI-compatible dataset class: - -```python -from itkit.dataset import MONAI_PatchedDataset # Not ITKITBaseSegDataset - -dataset = MONAI_PatchedDataset( - root_dir="/data/patches", - transform=monai_transforms -) -``` - -### Q: PyTorch Lightning trainer fails - -**A:** Install MONAI (required for Lightning extensions): - -```bash -pip install --no-deps monai -``` - -## Performance Issues - -### Q: Processing is very slow - -**A:** Try these optimizations: - -1. **Use multiprocessing:** - - ```bash - itk_resample dataset /src /dst --spacing 1.0 1.0 1.0 --mp --workers 8 - ``` - -2. **Use faster file formats:** - - `.mha` is faster than `.nii.gz` (no compression overhead) - - Avoid `.mhd` with large `.raw` files on network storage - -3. **Reduce I/O:** - - Work on local disk, not network storage - - Use SSD instead of HDD - -4. **Batch operations:** - - Process entire directories instead of individual files - -### Q: Out of memory errors - -**A:** Solutions: - -1. **Extract patches instead of loading full volumes:** - - ```bash - itk_patch /data /patches --patch-size 96 96 96 - ``` - -2. **Reduce batch size in training** - -3. **Use gradient checkpointing** in model training - -4. **Process files sequentially** (don't use --mp) - -## Model Training Issues - -### Q: Model training crashes with CUDA out of memory - -**A:** Reduce memory usage: - -```python -# Smaller batch size -batch_size = 1 - -# Smaller patch size -patch_size = (64, 64, 64) # Instead of (128, 128, 128) - -# Mixed precision training -use_amp = True - -# Gradient checkpointing -model.enable_gradient_checkpointing() -``` - -### Q: Validation metrics are NaN or inf - -**A:** Check: - -1. **Label values:** Should be integers 0, 1, 2, ... (not one-hot) -2. **Normalization:** Images should be normalized appropriately -3. **Loss function:** Ensure it matches your task -4. **Learning rate:** May be too high - -### Q: Model converges but predictions are all background - -**A:** This indicates class imbalance. Solutions: - -1. **Use weighted loss:** - - ```python - loss = FocalLoss(alpha=0.25, gamma=2.0) - ``` - -2. **Filter patches during extraction:** - - ```bash - itk_patch /data /patches \ - --minimum-foreground-ratio 0.1 \ - --keep-empty-label-prob 0.1 - ``` - -3. **Adjust class weights** in loss function - -## File Format Issues - -### Q: Cannot read .dcm files - -**A:** DICOM files need special handling: - -```python -from itkit.io import dcm_toolkit - -# Read DICOM series (not individual files) -image = dcm_toolkit.read_dicom_series("/path/to/dicom/folder") -sitk.WriteImage(image, "output.mha") -``` - -### Q: .nii.gz files are huge - -**A:** NIfTI compression varies. To reduce size: - -```bash -# Convert to .mha (often smaller) -itk_convert format mha /data/nifti /data/mha - -# Or use higher compression -import gzip -# Compress with maximum compression level -``` - -### Q: File extensions don't match content - -**A:** Use ITKIT's conversion to standardize: - -```bash -itk_convert format mha /data/mixed /data/standardized -``` - -## Getting More Help - -If your issue isn't covered here: - -1. **Check documentation:** - - [Installation Guide](installation.md) - - [Quick Start](quickstart.md) - - [Preprocessing Guide](preprocessing.md) - -2. **Search existing issues:** - - [GitHub Issues](https://github.com/MGAMZ/ITKIT/issues) - -3. **Ask for help:** - - Open a new issue with detailed description - - Include error messages and minimal reproducible example - - Contact: [312065559@qq.com](mailto:312065559@qq.com) - -4. **Report bugs:** - - Follow the [Contributing Guide](contributing.md) - - Provide system information (OS, Python version, ITKIT version) diff --git a/docs/index.md b/docs/index.md index 39da04d..26819f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,15 +12,16 @@ Welcome to the ITKIT documentation! ITKIT is a user-friendly toolkit built on `S - **[Quick Start](quickstart.md)** - Get started with basic usage and examples - **[Dataset Structure](dataset_structure.md)** - Understand the required dataset format -### Core Features +### Processing Tools -- **[Preprocessing Tools](preprocessing.md)** - Comprehensive guide to ITK preprocessing commands - - Image checking and validation - - Resampling and orientation - - Patch extraction - - Data augmentation - - Label extraction - - Format conversion +- **[Overview](preprocessing.md)** - General notes and best practices +- **[itk_check](itk_check.md)** - Image checking and validation +- **[itk_resample](itk_resample.md)** - Resampling to target spacing/size +- **[itk_orient](itk_orient.md)** - Image re-orientation +- **[itk_patch](itk_patch.md)** - Patch extraction +- **[itk_aug](itk_aug.md)** - Data augmentation +- **[itk_extract](itk_extract.md)** - Label extraction +- **[itk_convert](itk_convert.md)** - Format conversion ### Advanced Topics @@ -75,7 +76,7 @@ Welcome to the ITKIT documentation! ITKIT is a user-friendly toolkit built on `S **Ready to preprocess data?** -- See [Preprocessing Tools](preprocessing.md) for command documentation +- See [Processing Tools](preprocessing.md) for command documentation and overview. - Use the GUI: `pip install "itkit[gui]"` then `itkit-app` **Building models?** diff --git a/docs/itk_aug.md b/docs/itk_aug.md new file mode 100644 index 0000000..b19eff1 --- /dev/null +++ b/docs/itk_aug.md @@ -0,0 +1,37 @@ +# itk_aug + +Perform data augmentation on ITK image files. + +## Usage + +```bash +itk_aug [options] +``` + +## Parameters + +- `img_folder`: Folder with source image `.mha` files +- `lbl_folder`: Folder with source label `.mha` files +- `-oimg, --out-img-folder OUT_IMG`: Optional folder to save augmented images +- `-olbl, --out-lbl-folder OUT_LBL`: Optional folder to save augmented labels +- `-n, --num N`: Number of augmented samples to generate per source sample +- `--mp`: Enable multiprocessing +- `--random-rot Z Y X`: Max random rotation degrees for Z Y X axes (three ints, order Z, Y, X) + +## Notes + +- Only files present in both `img_folder` and `lbl_folder` are processed +- Augmented files are written only if corresponding output folders are provided +- Currently supports: **RandomRotate3D** + +## Examples + +```bash +# Generate 5 augmented samples per input with random rotation +itk_aug /data/images /data/labels \ + -oimg /data/aug_images \ + -olbl /data/aug_labels \ + -n 5 \ + --random-rot 15 15 15 \ + --mp +``` diff --git a/docs/itk_check.md b/docs/itk_check.md new file mode 100644 index 0000000..b0c0b8e --- /dev/null +++ b/docs/itk_check.md @@ -0,0 +1,43 @@ +# itk_check + +Check ITK image-label sample pairs to verify they meet size and spacing requirements. + +## Usage + +```bash +itk_check [options] +``` + +## Modes + +- **check**: Validate image/label pairs against size/spacing rules and report non-conforming samples (no file changes) +- **delete**: Remove image and label files for samples that fail validation +- **copy**: Copy valid image/label pairs to the specified output directory +- **symlink**: Create symbolic links for valid image/label pairs in the output directory + +## Parameters + +- `sample_folder`: Root folder containing `image/` and `label/` subfolders +- `-o, --output OUT`: Output directory (required for `copy` and `symlink` modes) +- `--min-size Z Y X`: Minimum size per dimension (three integers; -1 = ignore) +- `--max-size Z Y X`: Maximum size per dimension (three integers; -1 = ignore) +- `--min-spacing Z Y X`: Minimum spacing per dimension (three floats; -1 = ignore) +- `--max-spacing Z Y X`: Maximum spacing per dimension (three floats; -1 = ignore) +- `--same-spacing A B`: Two dimensions (X|Y|Z) that must have equal spacing +- `--same-size A B`: Two dimensions (X|Y|Z) that must have equal size +- `--mp`: Enable multiprocessing + +## Examples + +```bash +# Check dataset without modifications +itk_check check /data/dataset --min-size 32 32 32 + +# Copy valid samples to new location +itk_check copy /data/dataset --output /data/valid_dataset \ + --min-spacing 0.5 0.5 0.5 \ + --max-spacing 2.0 2.0 2.0 + +# Check that X and Y spacing are equal +itk_check check /data/dataset --same-spacing X Y +``` diff --git a/docs/itk_convert.md b/docs/itk_convert.md new file mode 100644 index 0000000..579cb07 --- /dev/null +++ b/docs/itk_convert.md @@ -0,0 +1,116 @@ +# itk_convert + +Convert ITKIT datasets between different formats and frameworks. + +## Subcommands + +- **format**: Convert medical image file formats +- **monai**: Convert to MONAI Decathlon format +- **torchio**: Convert to TorchIO format + +## Format Conversion + +Convert medical image files between different formats while preserving metadata. + +### Usage + +```bash +itk_convert format [options] +``` + +### Supported Formats + +- `mha`: MetaImage (single file) +- `mhd`: MetaImage Header (with separate .raw file) +- `nii.gz`: Compressed NIfTI +- `nii`: NIfTI (uncompressed) +- `nrrd`: Nearly Raw Raster Data + +### Parameters + +- `target_format`: Target file format +- `source_folder`: Path to ITKIT dataset +- `dest_folder`: Path to output dataset +- `--mp`: Enable multiprocessing +- `--workers N`: Number of worker processes + +### Examples + +```bash +# Convert MHA to compressed NIfTI +itk_convert format nii.gz /data/mha_dataset /data/nifti_dataset + +# Convert to NRRD with multiprocessing +itk_convert format nrrd /data/input /data/output --mp --workers 8 + +# Convert MHD to MHA +itk_convert format mha /data/mhd_dataset /data/mha_dataset +``` + +## MONAI Conversion + +Convert ITKIT dataset to MONAI Decathlon format. + +### Usage + +```bash +itk_convert monai [options] +``` + +### Parameters + +- `source_folder`: Path to ITKIT dataset +- `dest_folder`: Path to output dataset in MONAI format +- `--name`: Dataset name for the manifest file (default: `ITKITDataset`) +- `--description`: Dataset description for the manifest file +- `--modality`: Primary imaging modality (default: `CT`) +- `--split`: Which split to treat the data as: `train` | `val` | `test` | `all` (default: `train`) +- `--labels`: Label names in order (e.g., `background liver tumor`). Index 0 is background +- `--mp`: Enable multiprocessing +- `--workers N`: Number of worker processes + +### Output + +- Converted files in `.nii.gz` format +- `dataset.json` manifest file +- `meta.json` ITKIT-style metadata + +### Examples + +```bash +itk_convert monai /data/itkit_dataset /data/monai_dataset \ + --name MyDataset \ + --modality CT \ + --labels background liver tumor \ + --mp +``` + +## TorchIO Conversion + +Convert ITKIT dataset to TorchIO format. + +### Usage + +```bash +itk_convert torchio [options] +``` + +### Parameters + +- `source_folder`: Path to ITKIT dataset +- `dest_folder`: Path to output dataset in TorchIO format +- `--no-csv`: Skip creating `subjects.csv` manifest file +- `--mp`: Enable multiprocessing +- `--workers N`: Number of worker processes + +### Output + +- Converted files in `.nii.gz` format +- `subjects.csv` manifest file (unless `--no-csv` is specified) +- `meta.json` ITKIT-style metadata + +### Examples + +```bash +itk_convert torchio /data/itkit_dataset /data/torchio_dataset --mp +``` diff --git a/docs/itk_extract.md b/docs/itk_extract.md new file mode 100644 index 0000000..5fb1eee --- /dev/null +++ b/docs/itk_extract.md @@ -0,0 +1,36 @@ +# itk_extract + +Extract specified classes from ITK semantic segmentation maps. + +## Usage + +```bash +itk_extract [options] +``` + +## Parameters + +- `source_folder`: Folder containing source images +- `dest_folder`: Destination folder to save extracted label files (created if missing) +- `mappings`: One or more label mappings in `"source:target"` format (e.g., `"1:0"` `"5:1"`) +- `-r, --recursive`: Recursively process subdirectories and preserve relative paths +- `--mp`: Enable multiprocessing +- `--workers N`: Number of worker processes for multiprocessing + +## Output + +- Remapped label files written to `dest_folder` (extensions normalized to `.mha`) +- `extract_meta.json`: Per-sample metadata +- `extract_configs.json`: Configuration used + +## Examples + +```bash +# Extract liver (label 1) and tumor (label 5), renumber to 0 and 1 +itk_extract /data/labels /data/extracted "1:0" "5:1" --mp + +# Extract specific organs from multi-organ segmentation +itk_extract /data/multi_organ /data/liver_kidney \ + "1:1" "2:2" \ + --recursive --mp +``` diff --git a/docs/itk_orient.md b/docs/itk_orient.md new file mode 100644 index 0000000..dabb9c4 --- /dev/null +++ b/docs/itk_orient.md @@ -0,0 +1,38 @@ +# itk_orient + +Orient ITK image-label sample pairs to a specified orientation. + +## Usage + +```bash +itk_orient [options] +``` + +## Parameters + +- `src_dir`: Source directory containing `.mha` files (recursive scan) +- `dst_dir`: Destination directory (preserves relative directory structure; must differ from `src_dir`) +- `orient`: Target orientation string for SimpleITK.DICOMOrient (e.g., `LPI`, `RAS`) +- `--mp`: Use multiprocessing to convert files in parallel + +## Common Orientations + +- **LPI**: Left-Posterior-Inferior (common in medical imaging) +- **RAS**: Right-Anterior-Superior (neuroimaging standard) +- **LPS**: Left-Posterior-Superior + +## Notes + +- Skips files already present in `dst_dir` +- Preserves folder layout +- Writes converted `.mha` files to `dst_dir` + +## Examples + +```bash +# Orient to LPI +itk_orient /data/source /data/oriented LPI --mp + +# Orient to RAS (neuroimaging standard) +itk_orient /data/source /data/ras_oriented RAS +``` diff --git a/docs/itk_patch.md b/docs/itk_patch.md new file mode 100644 index 0000000..9dba34c --- /dev/null +++ b/docs/itk_patch.md @@ -0,0 +1,43 @@ +# itk_patch + +Extract patches from ITK image-label sample pairs for training. + +## Usage + +```bash +itk_patch --patch-size SIZE --patch-stride STRIDE [options] +``` + +## Parameters + +- `src_folder`: Source root containing `image/` and `label/` subfolders +- `dst_folder`: Destination root to save patches +- `--patch-size`: Patch size as single int or three ints (Z Y X) +- `--patch-stride`: Patch stride as single int or three ints (Z Y X) +- `--minimum-foreground-ratio`: Minimum label foreground ratio to keep a patch (float, default 0.0) +- `--keep-empty-label-prob`: Probability to keep patches with only background (0.0-1.0) +- `--still-save-when-no-label`: If set and label missing, save patches regardless +- `--mp`: Use multiprocessing to process cases in parallel + +## Output + +- Patches saved under `dst_folder//` with image and label patch files +- `crop_meta.json`: Summary of extraction and available annotations + +## Examples + +```bash +# Extract 96x96x96 patches with 48-voxel stride +itk_patch /data/dataset /data/patches \ + --patch-size 96 96 96 \ + --patch-stride 48 48 48 \ + --mp + +# Extract patches with foreground filtering +itk_patch /data/dataset /data/patches \ + --patch-size 128 128 128 \ + --patch-stride 64 64 64 \ + --minimum-foreground-ratio 0.1 \ + --keep-empty-label-prob 0.2 \ + --mp +``` diff --git a/docs/itk_resample.md b/docs/itk_resample.md new file mode 100644 index 0000000..af2b068 --- /dev/null +++ b/docs/itk_resample.md @@ -0,0 +1,48 @@ +# itk_resample + +Resample ITK image-label sample pairs to a target spacing or size. + +## Usage + +```bash +itk_resample [options] +``` + +## Field Types + +- **image**: For image data (uses linear interpolation, preserves data type) +- **label**: For label/segmentation data (uses nearest neighbor interpolation) +- **dataset**: Processes both `image/` and `label/` subfolders with appropriate settings + +## Parameters + +- `source_folder`: Folder containing source image files +- `dest_folder`: Destination folder for resampled files (created if missing) +- `--spacing Z Y X`: Target spacing per dimension (ZYX order). Use -1 to ignore a dimension +- `--size Z Y X`: Target size per dimension (ZYX order). Use -1 to ignore a dimension +- `--target-folder PATH`: Folder of reference images (mutually exclusive with `--spacing/--size`) +- `-r, --recursive`: Recursively process subdirectories, preserving layout +- `--mp`: Enable multiprocessing +- `--workers N`: Number of worker processes for multiprocessing + +## Output + +- Resampled files in `dest_folder` +- `resample_configs.json`: Configuration used for resampling +- `meta.json`: Metadata for the resampled dataset + +## Examples + +```bash +# Resample entire dataset to 1.0mm isotropic spacing +itk_resample dataset /data/source /data/resampled \ + --spacing 1.0 1.0 1.0 --mp + +# Resample only in-plane, keep Z spacing +itk_resample image /data/source /data/resampled \ + --spacing -1 0.5 0.5 + +# Resample to match reference dataset +itk_resample dataset /data/source /data/resampled \ + --target-folder /data/reference --mp +``` diff --git a/docs/preprocessing.md b/docs/preprocessing.md index d37843d..6599ca4 100644 --- a/docs/preprocessing.md +++ b/docs/preprocessing.md @@ -5,396 +5,14 @@ ITKIT provides comprehensive command-line tools for medical image preprocessing. ## General Notes - **Coordinate Order**: All dimension arguments use **Z, Y, X** order (Z→0, Y→1, X→2) -- **Help**: Use `--help` with any command to see detailed usage information -- **Multiprocessing**: Most commands support `--mp` flag for parallel processing +- **Help**: Use '--help' with any command to see detailed usage information +- **Multiprocessing**: Most commands support '--mp' flag for parallel processing - **Progress**: Commands display progress bars using tqdm -## itk_check - -Check ITK image-label sample pairs to verify they meet size and spacing requirements. - -### Usage - -```bash -itk_check [options] -``` - -### Modes - -- **check**: Validate image/label pairs against size/spacing rules and report non-conforming samples (no file changes) -- **delete**: Remove image and label files for samples that fail validation -- **copy**: Copy valid image/label pairs to the specified output directory -- **symlink**: Create symbolic links for valid image/label pairs in the output directory - -### Parameters - -- `sample_folder`: Root folder containing `image/` and `label/` subfolders -- `-o, --output OUT`: Output directory (required for `copy` and `symlink` modes) -- `--min-size Z Y X`: Minimum size per dimension (three integers; -1 = ignore) -- `--max-size Z Y X`: Maximum size per dimension (three integers; -1 = ignore) -- `--min-spacing Z Y X`: Minimum spacing per dimension (three floats; -1 = ignore) -- `--max-spacing Z Y X`: Maximum spacing per dimension (three floats; -1 = ignore) -- `--same-spacing A B`: Two dimensions (X|Y|Z) that must have equal spacing -- `--same-size A B`: Two dimensions (X|Y|Z) that must have equal size -- `--mp`: Enable multiprocessing - -### Examples - -```bash -# Check dataset without modifications -itk_check check /data/dataset --min-size 32 32 32 - -# Copy valid samples to new location -itk_check copy /data/dataset --output /data/valid_dataset \ - --min-spacing 0.5 0.5 0.5 \ - --max-spacing 2.0 2.0 2.0 - -# Check that X and Y spacing are equal -itk_check check /data/dataset --same-spacing X Y -``` - ---- - -## itk_resample - -Resample ITK image-label sample pairs to a target spacing or size. - -### Usage - -```bash -itk_resample [options] -``` - -### Field Types - -- **image**: For image data (uses linear interpolation, preserves data type) -- **label**: For label/segmentation data (uses nearest neighbor interpolation) -- **dataset**: Processes both `image/` and `label/` subfolders with appropriate settings - -### Parameters - -- `source_folder`: Folder containing source image files -- `dest_folder`: Destination folder for resampled files (created if missing) -- `--spacing Z Y X`: Target spacing per dimension (ZYX order). Use -1 to ignore a dimension -- `--size Z Y X`: Target size per dimension (ZYX order). Use -1 to ignore a dimension -- `--target-folder PATH`: Folder of reference images (mutually exclusive with `--spacing/--size`) -- `-r, --recursive`: Recursively process subdirectories, preserving layout -- `--mp`: Enable multiprocessing -- `--workers N`: Number of worker processes for multiprocessing - -### Output - -- Resampled files in `dest_folder` -- `resample_configs.json`: Configuration used for resampling -- `meta.json`: Metadata for the resampled dataset - -### Examples - -```bash -# Resample entire dataset to 1.0mm isotropic spacing -itk_resample dataset /data/source /data/resampled \ - --spacing 1.0 1.0 1.0 --mp - -# Resample only in-plane, keep Z spacing -itk_resample image /data/source /data/resampled \ - --spacing -1 0.5 0.5 - -# Resample to match reference dataset -itk_resample dataset /data/source /data/resampled \ - --target-folder /data/reference --mp -``` - ---- - -## itk_orient - -Orient ITK image-label sample pairs to a specified orientation. - -### Usage - -```bash -itk_orient [options] -``` - -### Parameters - -- `src_dir`: Source directory containing `.mha` files (recursive scan) -- `dst_dir`: Destination directory (preserves relative directory structure; must differ from `src_dir`) -- `orient`: Target orientation string for SimpleITK.DICOMOrient (e.g., `LPI`, `RAS`) -- `--mp`: Use multiprocessing to convert files in parallel - -### Common Orientations - -- **LPI**: Left-Posterior-Inferior (common in medical imaging) -- **RAS**: Right-Anterior-Superior (neuroimaging standard) -- **LPS**: Left-Posterior-Superior - -### Notes - -- Skips files already present in `dst_dir` -- Preserves folder layout -- Writes converted `.mha` files to `dst_dir` - -### Examples - -```bash -# Orient to LPI -itk_orient /data/source /data/oriented LPI --mp - -# Orient to RAS (neuroimaging standard) -itk_orient /data/source /data/ras_oriented RAS -``` - ---- - -## itk_patch - -Extract patches from ITK image-label sample pairs for training. - -### Usage - -```bash -itk_patch --patch-size SIZE --patch-stride STRIDE [options] -``` - -### Parameters - -- `src_folder`: Source root containing `image/` and `label/` subfolders -- `dst_folder`: Destination root to save patches -- `--patch-size`: Patch size as single int or three ints (Z Y X) -- `--patch-stride`: Patch stride as single int or three ints (Z Y X) -- `--minimum-foreground-ratio`: Minimum label foreground ratio to keep a patch (float, default 0.0) -- `--keep-empty-label-prob`: Probability to keep patches with only background (0.0-1.0) -- `--still-save-when-no-label`: If set and label missing, save patches regardless -- `--mp`: Use multiprocessing to process cases in parallel - -### Output - -- Patches saved under `dst_folder//` with image and label patch files -- `crop_meta.json`: Summary of extraction and available annotations - -### Examples - -```bash -# Extract 96x96x96 patches with 48-voxel stride -itk_patch /data/dataset /data/patches \ - --patch-size 96 96 96 \ - --patch-stride 48 48 48 \ - --mp - -# Extract patches with foreground filtering -itk_patch /data/dataset /data/patches \ - --patch-size 128 128 128 \ - --patch-stride 64 64 64 \ - --minimum-foreground-ratio 0.1 \ - --keep-empty-label-prob 0.2 \ - --mp -``` - ---- - -## itk_aug - -Perform data augmentation on ITK image files. - -### Usage - -```bash -itk_aug [options] -``` - -### Parameters - -- `img_folder`: Folder with source image `.mha` files -- `lbl_folder`: Folder with source label `.mha` files -- `-oimg, --out-img-folder OUT_IMG`: Optional folder to save augmented images -- `-olbl, --out-lbl-folder OUT_LBL`: Optional folder to save augmented labels -- `-n, --num N`: Number of augmented samples to generate per source sample -- `--mp`: Enable multiprocessing -- `--random-rot Z Y X`: Max random rotation degrees for Z Y X axes (three ints, order Z, Y, X) - -### Notes - -- Only files present in both `img_folder` and `lbl_folder` are processed -- Augmented files are written only if corresponding output folders are provided -- Currently supports: **RandomRotate3D** - -### Examples - -```bash -# Generate 5 augmented samples per input with random rotation -itk_aug /data/images /data/labels \ - -oimg /data/aug_images \ - -olbl /data/aug_labels \ - -n 5 \ - --random-rot 15 15 15 \ - --mp -``` - ---- - -## itk_extract - -Extract specified classes from ITK semantic segmentation maps. - -### Usage - -```bash -itk_extract [options] -``` - -### Parameters - -- `source_folder`: Folder containing source images -- `dest_folder`: Destination folder to save extracted label files (created if missing) -- `mappings`: One or more label mappings in `"source:target"` format (e.g., `"1:0"` `"5:1"`) -- `-r, --recursive`: Recursively process subdirectories and preserve relative paths -- `--mp`: Enable multiprocessing -- `--workers N`: Number of worker processes for multiprocessing - -### Output - -- Remapped label files written to `dest_folder` (extensions normalized to `.mha`) -- `extract_meta.json`: Per-sample metadata -- `extract_configs.json`: Configuration used - -### Examples - -```bash -# Extract liver (label 1) and tumor (label 5), renumber to 0 and 1 -itk_extract /data/labels /data/extracted "1:0" "5:1" --mp - -# Extract specific organs from multi-organ segmentation -itk_extract /data/multi_organ /data/liver_kidney \ - "1:1" "2:2" \ - --recursive --mp -``` - ---- - -## itk_convert - -Convert ITKIT datasets between different formats and frameworks. - -### Subcommands - -- **format**: Convert medical image file formats -- **monai**: Convert to MONAI Decathlon format -- **torchio**: Convert to TorchIO format - -### Format Conversion - -Convert medical image files between different formats while preserving metadata. - -#### Usage - -```bash -itk_convert format [options] -``` - -#### Supported Formats - -- `mha`: MetaImage (single file) -- `mhd`: MetaImage Header (with separate .raw file) -- `nii.gz`: Compressed NIfTI -- `nii`: NIfTI (uncompressed) -- `nrrd`: Nearly Raw Raster Data - -#### Parameters - -- `target_format`: Target file format -- `source_folder`: Path to ITKIT dataset -- `dest_folder`: Path to output dataset -- `--mp`: Enable multiprocessing -- `--workers N`: Number of worker processes - -#### Examples - -```bash -# Convert MHA to compressed NIfTI -itk_convert format nii.gz /data/mha_dataset /data/nifti_dataset - -# Convert to NRRD with multiprocessing -itk_convert format nrrd /data/input /data/output --mp --workers 8 - -# Convert MHD to MHA -itk_convert format mha /data/mhd_dataset /data/mha_dataset -``` - -### MONAI Conversion - -Convert ITKIT dataset to MONAI Decathlon format. - -#### Usage - -```bash -itk_convert monai [options] -``` - -#### Parameters - -- `source_folder`: Path to ITKIT dataset -- `dest_folder`: Path to output dataset in MONAI format -- `--name`: Dataset name for the manifest file (default: `ITKITDataset`) -- `--description`: Dataset description for the manifest file -- `--modality`: Primary imaging modality (default: `CT`) -- `--split`: Which split to treat the data as: `train` | `val` | `test` | `all` (default: `train`) -- `--labels`: Label names in order (e.g., `background liver tumor`). Index 0 is background -- `--mp`: Enable multiprocessing -- `--workers N`: Number of worker processes - -#### Output - -- Converted files in `.nii.gz` format -- `dataset.json` manifest file -- `meta.json` ITKIT-style metadata - -#### Examples - -```bash -itk_convert monai /data/itkit_dataset /data/monai_dataset \ - --name MyDataset \ - --modality CT \ - --labels background liver tumor \ - --mp -``` - -### TorchIO Conversion - -Convert ITKIT dataset to TorchIO format. - -#### Usage - -```bash -itk_convert torchio [options] -``` - -#### Parameters - -- `source_folder`: Path to ITKIT dataset -- `dest_folder`: Path to output dataset in TorchIO format -- `--no-csv`: Skip creating `subjects.csv` manifest file -- `--mp`: Enable multiprocessing -- `--workers N`: Number of worker processes - -#### Output - -- Converted files in `.nii.gz` format -- `subjects.csv` manifest file (unless `--no-csv` is specified) -- `meta.json` ITKIT-style metadata - -#### Examples - -```bash -itk_convert torchio /data/itkit_dataset /data/torchio_dataset --mp -``` - ---- - ## Best Practices -1. **Use multiprocessing**: Add `--mp` flag for large datasets to speed up processing -2. **Check before processing**: Always run `itk_check` before other operations +1. **Use multiprocessing**: Add '--mp' flag for large datasets to speed up processing +2. **Check before processing**: Always run 'itk_check' before other operations 3. **Preserve originals**: Work on copies of your data, never modify originals 4. **Pipeline operations**: Chain commands to create preprocessing pipelines 5. **Validate outputs**: Check a few samples manually after each processing step diff --git a/mkdocs.yml b/mkdocs.yml index 5253252..e0c38a0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,15 +17,21 @@ nav: - Installation: installation.md - Quick Start: quickstart.md - Dataset Structure: dataset_structure.md - - Core Features: - - Preprocessing Tools: preprocessing.md + - Processing Tools: + - Overview: preprocessing.md + - itk_check: itk_check.md + - itk_resample: itk_resample.md + - itk_orient: itk_orient.md + - itk_patch: itk_patch.md + - itk_aug: itk_aug.md + - itk_extract: itk_extract.md + - itk_convert: itk_convert.md - Advanced Topics: - Framework Integration: framework_integration.md - Neural Network Models: models.md - Supported Datasets: datasets.md - Community: - Contributing: contributing.md - - FAQ & Troubleshooting: faq.md plugins: - search