Add plasma brightness contrast

[ternaus]

Fixes:
#2103
#2104

Summary by Sourcery

Add a new PlasmaBrightnessContrast transform to the library, allowing for spatially-varying brightness and contrast adjustments using plasma fractal patterns. Update documentation and tests to include this new feature.

New Features:

• Introduce PlasmaBrightnessContrast transform to apply plasma fractal patterns for modifying image brightness and contrast.

Enhancements:

• Refactor the order of parameters in several transform initializations for consistency.

Documentation:

• Add documentation for the new PlasmaBrightnessContrast transform in the README.

Tests:

• Add test case for the new PlasmaBrightnessContrast transform in the augmentation definitions.

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR introduces a new image augmentation transform called PlasmaBrightnessContrast that applies spatially-varying brightness and contrast adjustments using plasma fractal patterns. The implementation uses the Diamond-Square algorithm to generate organic-looking patterns that create natural, non-uniform modifications to the image. The PR also includes some parameter order standardization across multiple transforms to maintain consistency.

Class diagram for PlasmaBrightnessContrast

classDiagram
    class PlasmaBrightnessContrast {
        - tuple[float, float] brightness_range
        - tuple[float, float] contrast_range
        - int plasma_size
        - float roughness
        - bool|None always_apply
        - float p
        + PlasmaBrightnessContrast(tuple[float, float] brightness_range=(-0.3, 0.3), tuple[float, float] contrast_range=(-0.3, 0.3), int plasma_size=256, float roughness=3.0, bool|None always_apply=None, float p=0.5)
        + get_params_dependent_on_data(dict[str, Any] params, dict[str, Any] data) dict[str, Any]
        + apply(np.ndarray img, float brightness_factor, float contrast_factor, np.ndarray plasma_pattern, **params: Any) np.ndarray
        + get_transform_init_args_names() tuple[str, ...]
    }
    PlasmaBrightnessContrast --|> ImageOnlyTransform : Inherits

Loading

Class diagram for new functions in functional.py

classDiagram
    class functional {
        + get_grid_size(int size, tuple[int, int] target_shape) int
        + random_offset(int current_size, int total_size, float roughness, np.random.Generator random_generator) float
        + initialize_grid(int grid_size, np.random.Generator random_generator) np.ndarray
        + square_step(np.ndarray pattern, int y, int x, int step, int grid_size, float roughness, np.random.Generator random_generator) float
        + diamond_step(np.ndarray pattern, int y, int x, int half, int grid_size, float roughness, np.random.Generator random_generator) float
        + generate_plasma_pattern(tuple[int, int] target_shape, int size, float roughness, np.random.Generator random_generator) np.ndarray
        + apply_plasma_brightness_contrast(np.ndarray img, float brightness_factor, float contrast_factor, np.ndarray plasma_pattern) np.ndarray
    }

Loading

File-Level Changes

Change	Details	Files
Added new PlasmaBrightnessContrast transform for spatially-varying image adjustments	Implemented Diamond-Square algorithm for plasma pattern generation Added brightness and contrast adjustment functionality using plasma patterns Added comprehensive documentation with mathematical formulation and references Added parameter validation and initialization schema	albumentations/augmentations/transforms.py albumentations/augmentations/functional.py
Standardized parameter ordering across multiple transforms	Moved 'p' parameter before 'always_apply' in transform constructors Updated parameter order in various transform classes for consistency	albumentations/augmentations/transforms.py albumentations/augmentations/tk/transform.py
Updated project documentation and test infrastructure	Added PlasmaBrightnessContrast to README.md transform list Added PlasmaBrightnessContrast to 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 - here's some feedback:

Overall Comments:

• Consider standardizing parameter order across all transforms - some instances still have always_apply before p while most have been updated to have p before always_apply

Here's what I looked at during the review

• 🟢 General issues: all looks good
• 🟢 Security: all looks good
• 🟡 Testing: 1 issue 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

All modified and coverable lines are covered by tests ✅

Project coverage is 90.25%. Comparing base (b1a79c2) to head (8950edd).
Report is 284 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##           main    #2152       +/-   ##
=========================================
+ Coverage      0   90.25%   +90.25%     
=========================================
  Files         0       48       +48     
  Lines         0     8366     +8366     
=========================================
+ Hits          0     7551     +7551     
- Misses        0      815      +815     

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