added downsample arg to ThinPlateSpline

[ExtReMLapin]

ported from albumentations-team/albumentations#2572

Summary by Sourcery

Add a downsample_factor option to ThinPlateSpline and update its parameter-generation logic to build a coarser deformation grid and resize it to the original image size.

New Features:

• Introduce downsample_factor parameter to ThinPlateSpline augmentation to compute control grids at a lower resolution.

Enhancements:

• Generate TPS maps on a coarse grid and upsample via OpenCV interpolation to full resolution for performance optimization.

[sourcery-ai]

Reviewer's Guide

Introduces a downsample_factor parameter to ThinPlateSpline and replaces full-resolution TPS mapping with a downsampled grid followed by interpolation to improve performance.

Class diagram for ThinPlateSpline with downsample_factor

classDiagram
    class ThinPlateSpline {
        +interpolation
        +border_mode
        +value
        +mask_value
        +scale_range
        +num_control_points
        +downsample_factor
        +get_params_dependent_on_data(params)
    }

Loading

Flow diagram for TPS mapping with downsampling and interpolation

flowchart TD
    A[Start get_params_dependent_on_data] --> B[Generate src_points]
    B --> C[Generate dst_points with random displacement]
    C --> D[Compute TPS weights]
    D --> E[Create coarse grid using downsample_factor]
    E --> F[Apply TPS transform to coarse grid]
    F --> G[Reshape to coarse map_x_coarse, map_y_coarse]
    G --> H[Interpolate coarse maps to full resolution]
    H --> I[Return map_x, map_y]

Loading

File-Level Changes

Change	Details	Files
Added downsample_factor parameter and attribute initialization	Added downsample_factor argument (default=1) to constructor Stored downsample_factor on the instance	albumentations/augmentations/geometric/distortion.py
Replaced full-resolution grid with coarse grid and upsampled mapping	Computed coarse grid dimensions using downsample_factor Generated coarse meshgrid via np.linspace Applied TPS transform on coarse points and reshaped to coarse grid Interpolated coarse map_x/map_y to full resolution with cv2.resize	albumentations/augmentations/geometric/distortion.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. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the 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 exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

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.

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull Request Overview

This PR adds a downsample_factor parameter to the ThinPlateSpline augmentation, generating a coarser TPS grid and resizing it back to full resolution to improve performance.

• Introduce downsample_factor argument in __init__ and store it on the instance.
• Compute a coarse sampling grid, apply TPS transform, then upsample via OpenCV.
• Return full-resolution map_x and map_y based on the interpolated coarse grid.

Comments suppressed due to low confidence (3)

albumentations/augmentations/geometric/distortion.py:1048

• Add input validation in the constructor to ensure downsample_factor is an integer >= 1, so that invalid (zero or negative) values cannot cause division-by-zero or other errors.

        downsample_factor: int = 1,

albumentations/augmentations/geometric/distortion.py:1048

• Update the class and method docstrings to describe the new downsample_factor parameter, its valid range, and how it affects the generated TPS maps.

        downsample_factor: int = 1,

albumentations/augmentations/geometric/distortion.py:1068

• Add unit tests covering cases where downsample_factor > 1, verifying that the coarse-to-full interpolation yields maps with the expected shape and transforms.

        height, width = params["shape"][:2]

[sourcery-ai]

Hey @ExtReMLapin - I've reviewed your changes - here's some feedback:

• Add validation to ensure downsample_factor is a positive integer greater than zero to prevent invalid grid computations.
• Clamp or enforce a minimum coarse grid size so that coarse_height and coarse_width never collapse to zero when downsample_factor is large relative to the image dimensions.
• Consider exposing the interpolation method used in cv2.resize (or aligning it with the existing interpolation parameter) so users can control the map upsampling behavior.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Add validation to ensure downsample_factor is a positive integer greater than zero to prevent invalid grid computations.
- Clamp or enforce a minimum coarse grid size so that coarse_height and coarse_width never collapse to zero when downsample_factor is large relative to the image dimensions.
- Consider exposing the interpolation method used in cv2.resize (or aligning it with the existing interpolation parameter) so users can control the map upsampling behavior.

---

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.}

[ExtReMLapin]

I have read the CLA Document and I hereby sign the CLA

[ExtReMLapin]

Please don't go full Ultralytics with this license. We don't need another Ted Kaczynski.

[ternaus]

@ExtReMLapin I do not like any licenses for open source, except permissive like MIT, Apaches, etc

But I do not see any other way to support the development financially. Dual license is not the best solution, just the least worst of ones that I can think of.

[ternaus]

And you need to set up pre-commit hook and run it: https://github.com/albumentations-team/AlbumentationsX/blob/main/docs/contributing/environment_setup.md#4-set-up-pre-commit-hooks

[ternaus]

You also need to add distortion_factor to InitSchema, so that it's range would be checked on init by pydantic

something like:

downsample_factor: int = Field(ge=1)