WaterDropletPerturber

class nrtk.impls.perturb_image.environment.WaterDropletPerturber(*, size_range: Sequence[float] = [0.0, 1.0], num_drops: int = 20, blur_strength: float = 0.25, psi: float = 1.5707963267948966, n_air: float = 1.0, n_water: float = 1.33, f_x: int = 400, f_y: int = 400, seed: int | None = None, is_static: bool = False)

Implements the physics-based, photorealistic water/rain droplet model.

The WaterDropletPerturber class simulates the effects of rain/water droplets on an image similar to the rain drops on a window, car-windshield, etc. The equations defined for this model are based on the dynamics, geometry and photometry of a water/rain droplet.

Attributes:

size_range (Sequence[float]):

Range of size multiplier values used for computing the size of the water droplet. The minimum effective droplet size is 0.1 (in glass coordinate units); values below 0.1 will be clamped to 0.1. Zero-sized droplets are not supported. To reduce the number of droplets, use the num_drops parameter instead.

num_drops (int):

Target number of water droplets.

blur_strength (float):

Strength of Gaussian blur operation.

psi (float):

Angle between the camera line-of-sight and glass plane (radians).

n_air (float):

Density of air.

n_water (float):

Density of water.

f_x (int):

Camera focal length in x direction (cm).

f_y (int):

Camera focal length in y direction (cm).

seed (int | None):

Random seed for reproducibility. None for non-deterministic behavior.

is_static (bool):

If True, resets RNG after each call for consistent results.

Methods

blur	Blur the area within the boundaries of the droplets.
ccw_sort	Returns sorted points in counterclockwise order around a center point.
from_config	Instantiate a new instance of this class given the configuration JSON-compliant dictionary encapsulating initialization arguments.
get_bezier_curve	Given an array of points, create a curve through those points.
get_config	Returns the current configuration of the WaterDropletPerturber instance.
get_default_config	Returns the default configuration with size_range as a list for JSON serialization.
get_impls	Discover plugins, skipping any entrypoints that fail to load.
get_random_points_within_min_dist	Function to create n random points in the unit square, which are min_dst apart, then scale them.
get_type_string	Returns the fully qualified type string of the PerturbImage class or its subclass.
is_usable	Check whether this class is available for use.
perturb	Applies the Water Droplet perturbation effect to the provided input image.
render	Rendering the image with the Water Droplet effect.

__init__(*, size_range: Sequence[float] = [0.0, 1.0], num_drops: int = 20, blur_strength: float = 0.25, psi: float = 1.5707963267948966, n_air: float = 1.0, n_water: float = 1.33, f_x: int = 400, f_y: int = 400, seed: int | None = None, is_static: bool = False) → None

Initializes the WaterDropletPerturber.

Args:

size_range:

Range of size multiplier values used for computing the size of the water droplet. Defaults to [0.0, 1.0]. The minimum effective droplet size is 0.1 (in glass coordinate units); values below 0.1 are clamped to 0.1. Zero-sized droplets are not supported. To reduce the number of droplets, use num_drops instead.

num_drops:

Target number of water droplets.

blur_strength:

Strength of Gaussian blur operation.

psi:

Angle between the line-of-sight and glass plane (radians).

n_air:

Density of air.

n_water:

Density of water.

f_x:

Camera focal length in x direction (cm).

f_y:

Camera focal length in y direction (cm).

seed:

Random seed for reproducible results. Defaults to None for non-deterministic behavior.

is_static:

If True and seed is provided, resets RNG after each perturb call for consistent results across multiple calls (useful for video frame processing).

If any of the parameters are absent, the following values will be set as defaults:

size_range = [0.0, 1.0] num_drops = 20 blur_strength = 0.25 psi = 90.0 / 180.0 * np.pi n_air = 1.0 n_water = 1.33 f_x = 400 f_y = 400 seed = None is_static = False

blur(*, image: ndarray[Any, Any], rain_image: ndarray[Any, Any], mask: ndarray[Any, Any]) → ndarray[Any, Any]

Blur the area within the boundaries of the droplets.

Args:

image (np.ndarray):

Input Image.

rain_image (np.ndarray):

Image rendered with Water droplet effect.

mask (np.ndarray):

Image mask.

Returns:

Output of blur operation applied on the rain_image.

static ccw_sort(points: ndarray[Any, Any]) → ndarray[Any, Any]

Returns sorted points in counterclockwise order around a center point.

static get_bezier_curve(*, points: ndarray[Any, Any], rad: float = 0.2, edgy: float = 0.0, tol: float = 1e-08) → tuple[ndarray[Any, Any], ndarray[Any, Any]]

Given an array of points, create a curve through those points.

Args:

points:

arrays of points to create curve through

rad:

a number between 0 and 1 to steer the distance of control points.

edgy:

controls how “edgy” the curve is, edgy=0 is smoothest.

tol:

controls the tolerance used when comparing angles. Default is 1e-8.

Returns:

a tuple of point arrays that represent a Bezier curve

get_config() → dict[str, Any]

Returns the current configuration of the WaterDropletPerturber instance.

classmethod get_default_config() → dict[str, Any]

Returns the default configuration with size_range as a list for JSON serialization.

static get_random_points_within_min_dist(*, rng: Generator, n: int = 5, scale: float = 0.8, min_dst: float | None = None, recursive: int = 0) → ndarray[Any, Any]

Function to create n random points in the unit square, which are min_dst apart, then scale them.

Args:

rng:

numpy random generator to use

n:

number of random points to create

scale:

how much to scale points once recursion is finished

min_dst:

minimum distance between the random points

recursive:

current number of recursive loops

Returns:

a random array of points within a minimum distance

perturb(*, image: ndarray[Any, Any], boxes: Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None = None, **kwargs: Any) → tuple[ndarray[Any, Any], Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None]

Applies the Water Droplet perturbation effect to the provided input image.

Args:

image:

The image to be perturbed.

boxes:

Bounding boxes for source detections.

kwargs:

Additional perturbation keyword arguments (currently unused).

Returns:

The perturbed image and bounding boxes scaled to perturbed image shape.

render(image: ndarray[Any, Any]) → tuple[ndarray[Any, Any], ndarray[Any, Any]]

Rendering the image with the Water Droplet effect.

Args:

image: Input Image.

Returns:

Image rendered with Water Droplet effect and an image mask.