lidar_aug package

Subpackages

Submodules

lidar_aug.transformations module

This module contains the transformation functions. These are bindings to the underlying C++ code without a Python wrapper around them.

class lidar_aug.transformations.DistributionRange

Bases: pybind11_object

class lidar_aug.transformations.DistributionRanges

Bases: pybind11_object

class lidar_aug.transformations.NoiseType

Bases: pybind11_object

Indicates how the noise is added:

Members:

UNIFORM : The noise values are drawn from a uniform distribution.

SALT_PEPPER : Half of the added values have the maximum intensity, the other half the minimum intensity.

MIN : The noise values are equal to the minimum intensity.

MAX : The noise values are equal to the maximum intensity.

MAX = <NoiseType.MAX: 3>
MIN = <NoiseType.MIN: 2>
SALT_PEPPER = <NoiseType.SALT_PEPPER: 1>
UNIFORM = <NoiseType.UNIFORM: 0>
property name
property value
lidar_aug.transformations.apply_transformation(points: torch.Tensor, transformation_matrix: torch.Tensor) → None

Applies a transformation matrix to an entire point cloud with the shape (B, N, F), where B is the number of batches, N is the number of points and F has the size 4 and shape [x, y, z, i].

Parameters:

  • points – is the point cloud that the transformation matrix is applied to.

  • transformation_matrix – is the transformation matrix.

lidar_aug.transformations.change_sparse_representation(input: torch.Tensor, batch_idx: int) → torch.Tensor

Changes the representation of a sparse tensor from a flat 2D tensor (N, F), where F is the number of features to a 3D tensor (B, n, f), where B is the number of batches, n is the number of tensors in each batch and f is the number of features (equal to F-1). 0s are used for padding.

Parameters:

  • input – is the input tensor.

  • batch_idx – is the index of the batch index.

Returns:

a new tensor with 0s for padding.

lidar_aug.transformations.delete_labels_by_min_points(points: torch.Tensor, labels: torch.Tensor, names: torch.Tensor, min_points: int) → Tuple[torch.Tensor, torch.Tensor]

Checks the amount of points for each bounding box. If the number of points is smaller than a given threshold, the box is removed along with its label.

Parameters:

  • points – is the point_cloud.

  • labels – are the bounding boxes of objects.

  • names – are the names/labels of these boxes.

  • min_points – is the point threshold.

Returns:

The batch with the new labels and the batch with the new names.

lidar_aug.transformations.flip_random(points: torch.Tensor, labels: torch.Tensor, prob: int) → None

Flips all the points in the point cloud with a probability of prob % in the direction of the y-axis. The points and labels are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. This transformation only uses the points coordinates as well as the coordinates and angle of the labels.

Parameters:

  • points – is the point cloud containing the points that will be flipped.

  • labels – are the corresponding labels.

  • prob – is the probability with which the points should be flipped.

lidar_aug.transformations.intensity_noise(points: torch.Tensor, sigma: float, max_intensity: lidar_aug.point_cloud.IntensityRange) → None

Shifts the intensity value of every point in the point cloud by a random amount drawn from a normal distribution. The points are expected to have the shape (B, N, F), where B is the number of batch, N is the number of points in each batch and F is the number of features.This transformation only uses the fourth feature ‘intensity’ of points.

Parameters:

  • points – is the point cloud with all the points.

  • sigma – is the standard deviation of the normal distribution.

  • max_intensity – is the maximum intensity value (either 1 or 255, depending on the dataset).

lidar_aug.transformations.intensity_shift(points: torch.Tensor, sigma: float, max_intensity: lidar_aug.point_cloud.IntensityRange) → None

Shifts the intensity value of every point in the point cloud by a single value drawn from a normal distribution. The points are expected to have the shape (B, N, F), where B is the number of batch, N is the number of points in each batch and F is the number of features.This transformation only uses the fourth feature ‘intensity’ of points.

Parameters:

  • points – is the point cloud with all the points.

  • sigma – is the standard deviation of the normal distribution.

  • max_intensity – is the maximum intensity value (either 1 or 255, depending on the dataset).

lidar_aug.transformations.local_to_local_transform(from_pose: torch.Tensor, to_pose: torch.Tensor) → torch.Tensor

Creates a transformation matrix from the local system into a ‘target’ coordinate frame. The expected input shape for both tensors is (6) -> (x, y, z, roll, yaw, pitch).

Parameters:

  • from_pose – is the local coordinate frame (x, y, z, roll, yaw, pitch).

  • to_pose – is the target coordinate frame (x, y, z, roll, yaw, pitch).

Returns:

the homogeneous transformation matrix into the target coordinate frame.

lidar_aug.transformations.local_to_world_transform(lidar_pose: torch.Tensor) → torch.Tensor

Creates a transformation matrix from the local system into the global coordinate frame. The expected input shape is (6) -> (x, y, z, roll, yaw, pitch).

Parameters:

lidar_pose – is the local coordinate frame (x, y, z, roll, yaw, pitch).

Returns:

the homogeneous transformation matrix into the global coordinate frame.

lidar_aug.transformations.random_noise(points: torch.Tensor, sigma: float, ranges: lidar_aug.transformations.DistributionRanges, noise_type: lidar_aug.transformations.NoiseType, max_intensity: lidar_aug.point_cloud.IntensityRange) → torch.Tensor

Adds random amount of points (drawn using a normal distribution) at random coordinates (within predetermined ranges) with a random intensity according to specific noise type. The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features, with F = 4; (x, y, z, i).

Parameters:

  • points – is the point cloud that the points will be added to.

  • sigma – is the standard deviation of the normal distribution that is used to draw the number of points to be added.

  • ranges – are the boundaries in (min and max (x, y, z) values) in which the new points can be created.

  • noise_type – is one of a number of ‘patterns’ that can be used to generate the points.

  • max_intensity – is the maximum intensity value in the dataset.

Returns:

a new tensor with the shape (B, M, F) containing the points of the input tensor points and the newly generated points.

lidar_aug.transformations.random_point_noise(points: torch.Tensor, sigma: float) → None

Moves each point in the point cloud randomly. How much each coordinate is changed is decided by values drawn from a normal distribution. The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. This transformation only uses the first 3 features (x, y, z) of points.

Parameters:

  • points – is the point cloud from which each point is moved.

  • sigma – is the standard deviation of the normal distribution.

lidar_aug.transformations.rotate_deg(points: torch.Tensor, angle: float) → None

Rotates a batch of points along the ‘z’ axis (yaw). The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features.

Parameters:

  • points – is the point cloud that the rotation is applied to.

  • angle – is the angle (in degrees) by which the points are to be rotated.

lidar_aug.transformations.rotate_rad(points: torch.Tensor, angle: float) → None

Rotates a batch of points along the ‘z’ axis (yaw). The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features.

Parameters:

  • points – is the point cloud that the rotation is applied to.

  • angle – is the angle (in radians) by which the points are to be rotated.

lidar_aug.transformations.rotate_random(points: torch.Tensor, labels: torch.Tensor, sigma: float) → None

Rotates points and labels. The number of degrees that they are rotated by is determined by a randomly generated value from a normal distribution. The points and labels are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. This transformation only uses the points coordinates as well as the coordinates and angle of the labels.

Parameters:

  • points – is the point cloud that the rotation is applied to.

  • labels – are the labels belonging to the point cloud that the rotation is applied to.

  • sigma – is the standard deviation of the normal distribution.

lidar_aug.transformations.scale_local(points: torch.Tensor, labels: torch.Tensor, sigma: float, max_scale: float) → None

Scales the points that are part of a box and the corresponding labels by a random factor.

This factor is drawn from a truncated normal distribution. The truncated normal distribution has a mean of 1. The standard deviation, as well as upper and lower limits are determined by the function parameters. The points and labels are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. For this transformation, the first 3 features (x, y, z) of the points and the features 4 to 6 of labels (_, _, _, w, h, l) are used.

Parameters:

  • points – is the point cloud that contains the points that will be scaled.

  • labels – are the labels belonging to the aforementioned point cloud.

  • sigma – is the standard deviation of the truncated normal distribution.

  • max_scale – is the upper limit of the truncated normal distribution. The lower limit is the inverse.

lidar_aug.transformations.scale_points(points: torch.Tensor, scaling_factor: float) → None

Scales points by a constant factor. The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. For this transformation, only the first 3 features (x, y, z) are used.

Parameters:

  • points – is the point cloud whose points are scaled.

  • scaling_factor – is the factor that the (x, y, z) coordinates are multiplied by.

lidar_aug.transformations.scale_random(points: torch.Tensor, labels: torch.Tensor, sigma: float, max_scale: float) → None

Scales the points and labels by a random factor. This factor is drawn from a truncated normal distribution. The truncated normal distribution has a mean of 1. The standard deviation, as well as upper and lower limits are determined by the function parameters. The points and labels are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. For this transformation, the first 3 features (x, y, z) of the points and the first 6 of labels (x, y, z, w, h, l) are used.

Parameters:

  • points – is the point cloud that contains the points that will be scaled.

  • labels – are the labels belonging to the aforementioned point cloud.

  • sigma – is the standard deviation of the truncated normal distribution.

  • max_scale – is the upper limit of the truncated normal distribution. The lower limit is the inverse.

lidar_aug.transformations.thin_out(points: torch.Tensor, sigma: float) → torch.Tensor

Randomly generates a percentage from a norma distribution, which determines how many items should be ‘thinned out’. From that percentage random indices are uniformly drawn (in a random order, where each index is unique).

Finally, a new tensor is created containing the items present at those indices. The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features.

Parameters:

  • points – is the point cloud.

  • sigma – is the standard deviation of the distribution that generates the percentage.

Returns:

a new tensor with the shape (B, M, F) containing the new set of points.

lidar_aug.transformations.transform_along_ray(points: torch.Tensor, sigma: float) → None

Moves each point in the point cloud randomly along a ray. How much it is moved is decided by a value drawn from a normal distribution. The points are expected to have the shape (B, N, F), where B is the number of batch, N is the number of points in each batch and F is the number of features.This transformation only uses the first 3 features (x, y, z) of points.

Parameters:

  • points – is the point cloud from which each point is moved.

  • sigma – is the standard deviation of the normal distribution.

lidar_aug.transformations.translate(points: torch.Tensor, translation: torch.Tensor) → None

Moves batches of points by a specific amount. The points are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. For this transformation, only the first 3 features (x, y, z) are used.

Parameters:

  • points – is the point cloud with the points are to be moved.

  • translation – is the translation vector that specifies by how much they points are moved.

lidar_aug.transformations.translate_random(points: torch.Tensor, labels: torch.Tensor, sigma: float) → None

Generates a random (3D) translation vector using a normal distribution and applies it to all the points and labels. The points and labels are expected to have the shape (B, N, F), where B is the number of batches, N is the number of points in each batch and F is the number of features. For this transformation, only the first 3 features (x, y, z) are used.

Parameters:

  • points – is the point cloud with the points that are translated.

  • labels – are the labels belonging to the aforementioned point cloud.

  • sigma – is the standard deviation of the normal distribution.

lidar_aug.point_cloud module

This module contains some utility functions.

class lidar_aug.point_cloud.IntensityRange

Bases: pybind11_object

Defines options for maximum intensity values. Intensity goes from [0; MAX_INTENSITY], where MAX_INTENSITY is either 1 or 255.

Members:

MAX_INTENSITY_1

MAX_INTENSITY_255

MAX_INTENSITY_1 = <IntensityRange.MAX_INTENSITY_1: 1>
MAX_INTENSITY_255 = <IntensityRange.MAX_INTENSITY_255: 255>
property name
property value
lidar_aug.point_cloud.get_max_intensity() → int

Get the current value of the maximum intensity global state tracker.

Returns:

an int representing the maximum intensity value.

lidar_aug.point_cloud.set_max_intensity(val: lidar_aug.point_cloud.IntensityRange) → None

Set the global state tracker for the maximum intensity.

Parameters:

val – is the new maximum intensity (member of IntensityRange).

lidar_aug.weather_simulations module

This module contains the weather simulations. These are bindings to the underlying C++ code without a Python wrapper around them.

class lidar_aug.weather_simulations.Distribution

Bases: pybind11_object

Different options to determine which statistical distribution shouldbe used to sample the particles for some weather simulations.

Members:

EXPONENTIAL : Exponential distribution.

LOG_NORMAL : Log normal distribution.

GM : GM distribution.

EXPONENTIAL = <Distribution.EXPONENTIAL: 0>
GM = <Distribution.GM: 2>
LOG_NORMAL = <Distribution.LOG_NORMAL: 1>
property name
property value
class lidar_aug.weather_simulations.FogParameter

Bases: pybind11_object

Different parameters for the fog model/simulation.

Members:

DIST : Optimization of the distance distribution between the points.

CHAMFER : Optimization of the chamfer distance.

CHAMFER = <FogParameter.CHAMFER: 1>
DIST = <FogParameter.DIST: 0>
property name
property value
lidar_aug.weather_simulations.fog(*args, **kwargs)

Overloaded function.

  1. fog(point_cloud: torch.Tensor, prob: float, metric: lidar_aug.weather_simulations.FogParameter, sigma: float, mean: int) -> Optional[List[torch.Tensor]]

Applies a fog simulation to a point cloud with a chance of prob %. The point cloud has the shape (B, N, F) where B is the number of batches, N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • prob – is the probability with which the simulation is applied.

  • metric – is a parameter used to control the simulation.

  • sigma – is the standard deviation used to draw the viewing distance in the fog.

  • mean – is the mean that is used to draw the viewing distance in the fog.

Returns:

A list of B tensors with P points that the simulation has been applied to or None.

  1. fog(point_cloud: torch.Tensor, metric: lidar_aug.weather_simulations.FogParameter, viewing_dist: float, max_intensity: lidar_aug.point_cloud.IntensityRange = <IntensityRange.MAX_INTENSITY_1: 1>) -> torch.Tensor

Applies a fog simulation to a point cloud. The point cloud has the shape (N, F) where N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • metric – is a parameter used to control the simulation.

  • viewing_dist – is the viewing distance in the fog.

  • max_intensity – is the maximum intensity value of a point.

Returns:

a new point cloud with the old points as a base but after applying the simulation.

lidar_aug.weather_simulations.rain(*args, **kwargs)

Overloaded function.

  1. rain(point_cloud: torch.Tensor, dims: lidar_aug.transformations.DistributionRanges, num_drops: int, precipitation: float, d: lidar_aug.weather_simulations.Distribution, max_intensity: lidar_aug.point_cloud.IntensityRange = <IntensityRange.MAX_INTENSITY_1: 1>) -> torch.Tensor

Applies a rain simulation to a point cloud. The point cloud has the shape (N, F) where N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • dims – set the upper and lower bounds of the uniform distribution used to draw new points for the noise filter.

  • num_drops – is the number of rain drops per m^3.

  • precipitation – is the precipitation rate and determines the raindrop size distribution.

  • d – is the distribution function used when sampling the particles.

  • max_intensity – is the maximum intensity of the points in the point cloud.

Returns:

a new point cloud with the old points as a base but after applying the simulation.

  1. rain(point_cloud: torch.Tensor, noise_filter_path: str, num_drops_sigma: int, precipitation_sigma: float, prob: float) -> Optional[torch.Tensor]

Applies a rain simulation to a point cloud with a chance of prob %. The point cloud has the shape (N, F) where N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • noise_filter_path – is the path to the directory containing the npz files with the noise filter data.

  • num_drops_sigma – is the standard deviation for the number of drops (used to find the correct noise filter).

  • precipitation_sigma – is the standard deviation for the precipitation rate (used to find the correct noise filter).

  • prob – is the probability that the simulation will be executed.

Returns:

a new point cloud with the old points as a base but after applying the simulation.

lidar_aug.weather_simulations.snow(*args, **kwargs)

Overloaded function.

  1. snow(point_cloud: torch.Tensor, dims: lidar_aug.transformations.DistributionRanges, num_drops: int, precipitation: float, scale: int, max_intensity: lidar_aug.point_cloud.IntensityRange = <IntensityRange.MAX_INTENSITY_1: 1>) -> torch.Tensor

Applies a snow simulation to a point cloud. The point cloud has the shape (N, F) where N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • dims – set the upper and lower bounds of the uniform distribution used to draw new points for the noise filter.

  • num_drops – is the number of snowflakes per m^3.

  • precipitation – is the precipitation rate and determines the snowflake size distribution.

  • scale – is used to scale the size of the sampled particles when generating the noise filter.

  • max_intensity – is the maximum intensity of the points in the point cloud.

Returns:

a new point cloud with the old points as a base but after applying the simulation.

  1. snow(point_cloud: torch.Tensor, noise_filter_path: str, num_drops_sigma: int, precipitation_sigma: float, scale: int, prob: float) -> Optional[torch.Tensor]

Applies a snow simulation to a point cloud with a chance of prob %. The point cloud has the shape (N, F) where N is the number of points and F is the number of features, which is 4; (x, y, z, i).

Parameters:

  • point_cloud – is the point cloud that the simulation is applied to.

  • noise_filter_path – is the path to the directory containing the npz files with the noise filter data.

  • num_drops_sigma – is the standard deviation for the number of snowflakes (used to find the correct noise filter).

  • precipitation_sigma – is the standard deviation for the precipitation rate (used to find the correct noise filter).

  • scale – is used to scale the size of the sampled particles when generating the noise filter.

  • prob – is the probability that the simulation will be executed.

Returns:

a new point cloud with the old points as a base but after applying the simulation.

lidar_aug.evaluation module

This module contains code to evaluate predictions by calculating IOU metrics and average precision values.

class lidar_aug.evaluation.ResultDict

Bases: pybind11_object

Wrapping type around a C++ std::map<std::uint8_t, std::map<std::string, std::vector<float>>>.

Converts into a Python dict[int, dict[str, list[float]]].

items(self: lidar_aug.evaluation.ResultDict) → lidar_aug.evaluation.ItemsView[int, Dict[str, List[float]]]
keys(self: lidar_aug.evaluation.ResultDict) → lidar_aug.evaluation.KeysView[int]
values(self: lidar_aug.evaluation.ResultDict) → lidar_aug.evaluation.ValuesView[Dict[str, List[float]]]
lidar_aug.evaluation.calculate_false_and_true_positive_2d(detection_boxes: torch.Tensor, detection_score: torch.Tensor, ground_truth_box: torch.Tensor, iou_threshold: float, results: std::map<unsigned char, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > >, std::less<unsigned char>, std::allocator<std::pair<unsigned char const, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > > > > >) → None

Calculates the false and true positive rate of a set of predictions against a set of ground truth binding boxes by calculating the ‘intersection over union’ (IOU) for 2D boxes. The results are saved in a result_dict structure.

Parameters:

  • detection_boxes – The 2D object detection box.

  • detection_score – The detection scores used to index the detection boxes.

  • ground_truth_box – The 2D ground truth box containing the actual object.

  • iou_threshold – The threshold that determines wether the prediction is accurate or not.

  • results – A ResultDict that is filled with the results of the calculations.

lidar_aug.evaluation.calculate_false_and_true_positive_3d(detection_boxes: torch.Tensor, detection_score: torch.Tensor, ground_truth_box: torch.Tensor, iou_threshold: float, results: std::map<unsigned char, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > >, std::less<unsigned char>, std::allocator<std::pair<unsigned char const, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > > > > >) → None

Calculates the false and true positive rate of a set of predictions against a set of ground truth binding boxes by calculating the ‘intersection over union’ (IOU) for 3D boxes. The results are saved in a result_dict structure.

Parameters:

  • detection_boxes – The 3D object detection box.

  • detection_score – The detection scores used to index the detection boxes.

  • ground_truth_box – The 3D ground truth box containing the actual object.

  • iou_threshold – The threshold that determines wether the prediction is accurate or not.

  • results – A ResultDict that is filled with the results of the calculations.

lidar_aug.evaluation.evaluate(results: std::map<unsigned char, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > >, std::less<unsigned char>, std::allocator<std::pair<unsigned char const, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > > > > >, global_sort_detections: bool) → Annotated[List[float], FixedSize(3)]

Calculages the average precision of a set of results with the IOU thresholds of 0.3, 0.5 & 0.7.

Parameters:

  • results – The results for which the average precision is calculated

  • global_sort_detections – Enables/Disables the sorting of true and false positive values

Returns:

A list with the average precision values for the IOU thresholds of 0.3, 0.5 & 0.7.

lidar_aug.evaluation.make_result_dict(input: dict) → std::map<unsigned char, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > >, std::less<unsigned char>, std::allocator<std::pair<unsigned char const, std::map<std::string, std::vector<float, std::allocator<float> >, std::less<std::string>, std::allocator<std::pair<std::string const, std::vector<float, std::allocator<float> > > > > > > >

Create a result_dict aka std::map<std::uint8_t, std::map<std::string, std::vector<float>>> from a dict[int, dict[str, list[float]]].

Parameters:

input – A Python dict[int, dict[str, list[float]]].

Returns:

A ResultDict (C++ std::map<std::uint8_t, std::map<std::string, std::vector<float>>>).

Module contents