ConditionalRandomTransform#

class ConditionalRandomTransform(p=0.5, axes=('x', 'y', 'z'), buffer_size=0.05, bounds=((-1, 1), (-1, 1), (-1, 1)))[source]#

Bases: object

Wall-aware random translation that keeps points inside fixed bounds.

For each requested axis, only acts when the cloud touches a wall (its min or max comes within buffer_size of the axis bounds); fully interior axes are skipped. When triggered (with probability p per qualifying axis), it draws a uniform translation from the feasible range that keeps all points within bounds while preserving the cloud’s contact with whichever wall(s) it was already near. Shifts coord in place and applies the same translation to v3 vertex metadata. Requires coord; a no-op if coord is absent. Registered as ConditionalRandomTransform – use this string as the type in a transform=[...] config list.

Parameters:

  • p (float) – per-axis probability of applying a translation when the cloud is near a wall on that axis. Defaults to 0.5.

  • axes (str | Sequence[str]) – which of "x", "y", "z" to consider. A bare string is wrapped into a single-element tuple. Defaults to ("x", "y", "z").

  • buffer_size (float) – margin (in coordinate units) defining how close to a bound counts as “near a wall” and the contact band to preserve. Defaults to 0.05.

  • bounds (tuple[tuple[float, float], ...]) – per-axis (low, high) limits the translated points must stay within. Defaults to ((-1, 1), (-1, 1), (-1, 1)).

Note

Assumes coordinates are already normalized into the bounds frame (e.g. after NormalizeCoord). Intended for detector-volume data where a particle’s contact with a TPC wall is physically meaningful and must survive augmentation.

Example

>>> import numpy as np, random
>>> from pimm.datasets.transform import ConditionalRandomTransform
>>> np.random.seed(0); random.seed(0)
>>> data = {"coord": np.array([[-0.99, 0., 0.], [-0.5, 0., 0.]], dtype="f4")}
>>> # x hugs the -1 wall, so a random translation is drawn that keeps it
>>> # in bounds and still touching that wall:
>>> out = ConditionalRandomTransform(p=1.0, axes=("x",))(data)
>>> bool(out["coord"][:, 0].min() >= -1.0)  # never pushed past the wall
True
>>> bool(out["coord"][:, 0].min() <= -0.95)  # still within the contact band
True