Add rotate and project

[ternaus]

Adresses: #2118

Summary by Sourcery

Add the RotateAndProject transformation to apply 3D rotation and perspective projection to images, along with corresponding tests and documentation updates.

New Features:

• Introduce the RotateAndProject transformation, which applies 3D rotation to an image and projects it back to a 2D plane using perspective projection. This feature supports images, masks, keypoints, and bounding boxes, maintaining aspect ratios and handling different center calculations.

Documentation:

• Update README.md to include documentation for the new RotateAndProject transformation.

Tests:

• Add tests for the new RotateAndProject transformation, including tests for 3D rotation matrices and projection matrix properties.

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR introduces a new geometric transformation called RotateAndProject that simulates viewing a 2D image from different 3D viewpoints. The implementation applies 3D rotation to an image and projects it back to a 2D plane using perspective projection, handling all target types consistently (images, masks, keypoints, and bounding boxes).

Sequence diagram for RotateAndProject transformation

sequenceDiagram
    actor User
    participant RotateAndProject
    participant fgeometric
    User->>RotateAndProject: Initialize with parameters
    RotateAndProject->>fgeometric: get_projection_matrix(image_shape, x_angle, y_angle, z_angle, focal_length, center)
    fgeometric-->>RotateAndProject: Return projection matrix
    RotateAndProject->>fgeometric: get_projection_matrix for bbox
    fgeometric-->>RotateAndProject: Return bbox projection matrix
    RotateAndProject->>User: Return transformed image and bboxes

Loading

Class diagram for RotateAndProject

classDiagram
    class RotateAndProject {
        - tuple[float, float] x_angle_range
        - tuple[float, float] y_angle_range
        - tuple[float, float] z_angle_range
        - tuple[float, float] focal_range
        - int pad_mode
        - ColorType pad_val
        - ColorType mask_pad_val
        - int interpolation
        - int mask_interpolation
        - float p
        + get_params_dependent_on_data(params: dict[str, Any], data: dict[str, Any]) dict[str, Any]
        + get_transform_init_args_names() tuple[str, ...]
        + apply_to_bboxes(bboxes: np.ndarray, matrix_bbox: np.ndarray, max_height: int, max_width: int, **params: Any) np.ndarray
    }
    RotateAndProject --|> Perspective
    class Perspective {
        <<abstract>>
    }

Loading

File-Level Changes

Change	Details	Files
Added new RotateAndProject transformation class	Implemented 3D rotation and perspective projection functionality Added support for X, Y, Z rotation angles and focal length parameters Handled different center calculations for images/keypoints vs bounding boxes Added configuration options for padding, interpolation, and border modes	albumentations/augmentations/geometric/rotate.py
Added new geometric utility functions	Implemented get_rotation_matrix_3d for 3D rotation calculations Added get_projection_matrix for perspective transform calculations Enhanced center calculation functions with improved documentation	albumentations/augmentations/geometric/functional.py
Added comprehensive test coverage	Added tests for 3D rotation matrix calculations Added tests for projection matrix properties Added integration tests for the new transformation	tests/functional/test_geometric.py tests/test_transforms.py
Updated documentation and package configuration	Added RotateAndProject to the README's transform list Added the transform to the test definitions	README.md tests/aug_definitions.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: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 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

All modified and coverable lines are covered by tests ✅

Project coverage is 90.07%. Comparing base (b1a79c2) to head (053b28d).
Report is 291 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##           main    #2159       +/-   ##
=========================================
+ Coverage      0   90.07%   +90.07%     
=========================================
  Files         0       48       +48     
  Lines         0     8628     +8628     
=========================================
+ Hits          0     7772     +7772     
- Misses        0      856      +856     

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

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests