Add pad if needed3d

[ternaus]

Summary by Sourcery

Add support for 3D volumetric data transformations, including PadIfNeeded3D for padding and ToTensor3D for tensor conversion. Enhance the composition module to handle 3D data and update documentation and tests accordingly.

New Features:

• Introduce PadIfNeeded3D transform for 3D volumetric data, allowing padding to specified minimum dimensions or divisibility requirements.

Enhancements:

• Refactor preprocessing and validation logic in the composition module to handle 3D data and improve code organization.
• Add ToTensor3D transform to convert 3D volumes and masks to PyTorch tensors, with optional channel transposition.

Documentation:

• Update documentation to include new 3D transforms and their usage.

Tests:

• Add comprehensive tests for PadIfNeeded3D transform, including shape validation, position handling, and fill value checks.
• Introduce tests for ToTensor3D to ensure correct tensor conversion and shape handling.
• Add tests to verify 3D transform targets and their documentation consistency.

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR introduces support for 3D transforms in the Albumentations library, starting with the PadIfNeeded3D transform. The implementation includes a new base class Transform3D, supporting infrastructure for 3D operations, and comprehensive test coverage. The changes maintain compatibility with existing 2D transforms while adding specialized handling for volumetric data.

Class diagram for 3D Transform Support

classDiagram
    class Transform3D {
        +apply_to_images(images: np.ndarray, *args, **params) np.ndarray
        +apply_to_masks(masks: np.ndarray, *args, **params) np.ndarray
        +apply_to_bboxes(bboxes: np.ndarray, **params) np.ndarray
        +apply_to_keypoints(keypoints: np.ndarray, **params) np.ndarray
        +targets dict[str, Callable[..., Any]]
    }
    class PadIfNeeded3D {
        +min_zyx: tuple[int, int, int] | None
        +pad_divisor_zyx: tuple[int, int, int] | None
        +position: Literal["center", "random"]
        +fill: ColorType
        +fill_mask: ColorType
        +apply_to_images(images: np.ndarray, padding: tuple[int, int, int, int, int, int], **params) np.ndarray
        +apply_to_masks(masks: np.ndarray, padding: tuple[int, int, int, int, int, int], **params) np.ndarray
    }
    Transform3D <|-- PadIfNeeded3D
    class ToTensor3D {
        +transpose_mask: bool
        +apply_to_images(images: np.ndarray, **params) torch.Tensor
        +apply_to_masks(masks: np.ndarray, **params) torch.Tensor
    }
    Transform3D <|-- ToTensor3D
    class ToTensorV2 {
        +apply_to_images(images: np.ndarray, **params) torch.Tensor
        +apply_to_masks(masks: np.ndarray, **params) torch.Tensor
    }
    BasicTransform <|-- ToTensorV2
    BasicTransform <|-- ToTensor3D
    class BasicTransform {
        +apply(img: np.ndarray, *args, **params) np.ndarray
    }

Loading

File-Level Changes

Change	Details	Files
Added new Transform3D base class for handling 3D transformations	Created Transform3D class inheriting from DualTransform Implemented specialized apply_to_images and apply_to_masks methods for 3D data Added validation for 3D transform inputs and outputs Disabled unsupported operations like bounding boxes and keypoints for 3D transforms	albumentations/core/transforms_interface.py
Implemented PadIfNeeded3D transform for volumetric data padding	Added support for minimum size requirements in z, y, x dimensions Implemented divisibility padding for 3D volumes Added position-based padding (center/random) Added separate fill values for images and masks	albumentations/augmentations/transforms3d/transforms.py albumentations/augmentations/transforms3d/functional.py
Added ToTensor3D transform for PyTorch integration	Implemented conversion from numpy arrays to PyTorch tensors for 3D data Added support for channel transposition in 3D volumes Added mask handling with optional channel transposition	albumentations/pytorch/transforms.py
Updated core infrastructure to support 3D transforms	Modified composition logic to handle 3D data types Updated serialization support for 3D transforms Added 3D transform filtering in utility functions Updated documentation generation for 3D transforms	albumentations/core/composition.py tools/make_transforms_docs.py tests/utils.py
Added comprehensive test coverage for 3D transforms	Added tests for PadIfNeeded3D functionality Added tests for ToTensor3D conversion Added tests for 3D transform targets Added tests for 2D/3D compatibility	tests/transforms3d/test_transforms.py tests/transforms3d/test_targets.py tests/transforms3d/test_pytorch.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @ternaus - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 2 issues found
• 🟢 Security: all looks good
• 🟡 Testing: 3 issues found
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[codecov]

Codecov Report

Attention: Patch coverage is 88.88889% with 21 lines in your changes missing coverage. Please review.

Project coverage is 89.61%. Comparing base (b1a79c2) to head (a087dd9).
Report is 310 commits behind head on main.

Files with missing lines	Patch %	Lines
albumentations/core/pydantic.py	62.50%	6 Missing ⚠️
albumentations/core/transforms_interface.py	75.00%	6 Missing ⚠️
...entations/augmentations/transforms3d/transforms.py	93.75%	3 Missing ⚠️
albumentations/pytorch/transforms.py	89.28%	3 Missing ⚠️
albumentations/core/composition.py	95.74%	2 Missing ⚠️
...entations/augmentations/transforms3d/functional.py	94.73%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##           main    #2196       +/-   ##
=========================================
+ Coverage      0   89.61%   +89.61%     
=========================================
  Files         0       50       +50     
  Lines         0     8603     +8603     
=========================================
+ Hits          0     7710     +7710     
- Misses        0      893      +893     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.