dgp.utils package¶

Subpackages¶

dgp.utils.accumulate module¶

Useful utilities for accumulating sensory information over time

dgp.utils.accumulate.accumulate_points(point_datums, target_datum, transform_boxes=False)¶

Accumulates lidar or radar points by transforming all datums in point_datums to the frame used in target_datum.

point_datums: list[dict]: List of datum dictionaries to accumulate
target_datum: dict: A single datum to use as the reference frame and reference time.
transform_boxes: bool, optional: Flag to denote if cuboid annotations and instance ids should be used to warp points to the target frame. Only valid for Lidar. Default: False.

p_target: dict: A new datum with accumulated points and an additional field ‘accumulation_offset_t’ that indicates the delta in microseconds between the target_datum and the given point.

dgp.utils.accumulate.points_in_cuboid(query_points, cuboid)¶

Tests if a point is contained by a cuboid. Assumes points are in the same frame as the cuboid, i.e, cuboid.pose translates points in the cuboid local frame to the query_point frame.

query_points: np.ndarray: Numpy array shape (N,3) of points.
cuboid: dgp.utils.structures.bounding_box_3d.BoundingBox3D: Cuboid in same reference frame as query points

in_view: np.ndarray: Numpy boolean array shape (N,) where a True entry denotes a point insided the cuboid

dgp.utils.annotation module¶

dgp.utils.annotation.get_depth_from_point_cloud(dataset, scene_idx, sample_idx_in_scene, cam_datum_name, pc_datum_name)¶

Generate the depth map in the camera view using the provided point cloud datum within the sample.

dataset: dgp.dataset.BaseDataset: Inherited base dataset to augment with depth data.
scene_idx: int: Index of the scene.
sample_idx_in_scene: int: Index of the sample within the scene at scene_idx.
cam_datum_name: str: Name of camera datum within the sample.
pc_datum_name: str: Name of the point cloud datum within the sample.

depth: np.ndarray: Depth map from the camera’s viewpoint.

dgp.utils.annotation.is_empty_annotation(annotation_file, annotation_type)¶

Check if JSON style annotation files are empty

annotation_file: str: Path to JSON file containing annotations for 2D/3D bounding boxes
annotation_type: object: Protobuf pb2 object we want to load into.

bool:: True if empty annotation, otherwise False

dgp.utils.cache module¶

dgp.utils.cache.clear_cache(directory='/home/runner/.dgp/cache')¶

Clear DGP cache to avoid growing disk-usage.

directory: str, optional: A pathname to the directory used by DGP for caching. Default: DGP_CACHE_DIR.

dgp.utils.cache.diskcache(protocol='npz', cache_dir=None)¶

Disk-caching method/function decorator that caches results into dgp cache for arbitrary pickle-able / numpy objects.

protocol: str, optional: Serialization protocol. Choices: {npz, pkl}. Default: “npz” (numpy).
cache_dir: str, optional: Directory to cache instead of the default DGP cache. Default: None.

dgp.utils.camera module¶

General-purpose class for cameras.

class dgp.utils.camera.Camera(K, D=None, p_cw=None)¶

Bases: object

Camera class with well-defined intrinsics and extrinsics.

property Kinv¶

Analytic inverse camera intrinsic (K^-1)

Kinv: np.ndarray (33): Inverse camera matrix K^-1.

property P¶: Projection matrix

property cx¶

property cy¶

classmethod from_params(fx, fy, cx, cy, p_cw=None, distortion=None)¶

Create camera batch from calibration parameters.

fx: float: Camera focal length along x-axis.
fy: float: Camera focal length along y-axis.
cx: float: Camera x-axis principal point.
cy: float: Camera y-axis principal point.
p_cw: Pose: Pose from world to camera frame.
distortion: dict[str, float], optional: Optional dictionary of distortion parameters k1,k2,.. etc. Default: None.

Camera: Camera object with relevant intrinsics.

property fx¶

property fy¶

in_frustum(X, height, width)¶

Given a set of 3D points, return a boolean index of points in the camera frustum

X: np.ndarray: 3D spatial coordinates for each pixel IN THE CAMERA FRAME. Shape is (N x 3).
height: int: Height of image.
width: int: Width of image.

inside_frustum: np.ndarray: Bool array for X which are inside frustum

project(Xw)¶

Project 3D points from specified reference frame onto image plane

Xw: np.ndarray: 3D spatial coordinates for each pixel in the world reference frame. Shape is (N x 3).

x: np.ndarray (N x 2): 2D image coordinates for each pixel in the specified

reference frame.

property rodrigues¶

Retrieve the Rodrigues rotation.

rvec: np.ndarray (3,): Rodrigues rotation

static scale_intrinsics(K, x_scale, y_scale)¶

Scale intrinsic matrix (B33, or 33) given x and y-axes scales. Note: This function works for both torch and numpy.

K: np.ndarray: Camera calibration matrix. Shape is (3 x 3).
x_scale: float: x-axis scale factor.
y_scale: float: y-axis scale factor.

np.array of shape (3x3): Scaled camera intrinsic matrix

transform(X, frame)¶

unproject(points_in_2d)¶

Project points from 2D into 3D given known camera intrinsics

points_in_2d: np.ndarray: Array of shape (N, 2)

points_in_3d: np.ndarray: Array of shape (N, 3) of points projected into 3D

class dgp.utils.camera.Distortion(D=array([0., 0., 0., 0., 0.], dtype=float32))¶

Bases: object

Distortion via distortion parameters or full distortion map

property coefficients¶

distorion_map()¶

dgp.utils.camera.camera_matrix_from_pbobject(intrinsics)¶

Convert CameraIntrinsics pbobject to 3x3 camera matrix

intrinsics: CameraIntrinsics_pb2: Protobuf containing cx, cy, fx, fy, skew

K: np.ndarray: Camera matrix

dgp.utils.camera.generate_depth_map(camera, Xw, shape)¶

Render pointcloud on image.

camera: Camera: Camera object with appropriately set extrinsics wrt world.
Xw: np.ndarray: 3D point cloud (x, y, z) in the world coordinate. Shape is (N x 3).
shape: np.ndarray: Output depth image shape as (H, W).

depth: np.array: Rendered depth image.

dgp.utils.camera.pbobject_from_camera_matrix(K, distortion=None)¶

Convert camera intrinsic matrix into pb object.

K: np.ndarray: Camera Intrinsic Matrix
distortion: dict[str, float]: Dictionary of distortion params i.e, k1,k2,p1,p2,k3,k4,xi,alpha etc

intrinsics: geometry_pb2.CameraIntrinsics: Camera Intrinsic object

dgp.utils.cli_utils module¶

Various utility functions for Click options

dgp.utils.cli_utils.add_options(**kwargs)¶

Decorator function to add a list of Click options to a Click subcommand.

**kwargs: dict: The options keyword argument shall be a list of string options to extend a Click CLI.

dgp.utils.colors module¶

This file contains definitions of predefined RGB colors, and color-related utility functions.

dgp.utils.colors.adjust_lightness(color, factor=1.0)¶

Adjust lightness of an RGB color.

color: Tuple[int]: RGB color
factor: float, optional: Factor of lightness adjustment. Default: 1.0.

Tuple[int]: Adjusted RGB color.

dgp.utils.colors.color_borders(img, color, thickness=10)¶

Draw a frame (i.e. the 4 sides) of image.

img: np.ndarray: Input image with shape of (H, W, 3) and unit8 type.
color: Tuple[int]: Color to draw the frame.
thickness: int, optional: Thickness of the frame. Default: 10.

img_w_frame: np.ndarray: Image with colored frame.

dgp.utils.colors.get_unique_colors(num_colors, in_bgr=False, cmap='tab20')¶

Use matplotlib color maps (‘tab10’ or ‘tab20’) to get given number of unique colors.

CAVEAT: matplotlib only supports default qualitative color palletes of fixed number, up to 20.

num_colors: int: Number of colors. Must be less than 20.
in_bgr: bool, optional: Whether or not to return the color in BGR order. Default: False.
cmap: str, optional: matplotlib colormap name (https://matplotlib.org/tutorials/colors/colormaps.html) Must be a qualitative color map. Default: “tab20”.

List[Tuple[int]]: List of colors in 3-tuple.

dgp.utils.dataset_conversion module¶

Useful utilities for pre-processing datasets

class dgp.utils.dataset_conversion.DatasetGen(version, raw_path, local_output_path)¶

Bases: object

COLORMAP = {}¶

DATASET_NAME = ''¶

DESCRIPTION = ''¶

EMAIL = 'ml@tri.global'¶

ID_TO_NAME = {}¶

IS_THING = {}¶

NAME_TO_ID = {}¶

PUBLIC = True¶

convert()¶

Parse raw data into DGP format and return the dataset json.

dataset_json_path: str: Dataset json path

NotImplementedError: Unconditionally.

static open_image(filename)¶

Returns an image given a filename.

filename: str: A pathname of an image to open.

PIL.Image: Image that was opened.

populate_metadata()¶

Populate boilerplate fields for dataset conversion. Statistics, size, etc… are recomputed during conversion

NotImplementedError: Unconditionally.

populate_ontologies()¶

Populate ontologies’ fields for dataset conversion.

NotImplementedError: Unconditionally.

populate_statistics()¶

Compute dataset (image/point_cloud) statistics.

NotImplementedError: Unconditionally.

write_dataset(upload=False)¶

Write the final scene dataset JSON.

upload: bool, optional: If True, upload the dataset to the scene pool in s3. Default: False.

scene_dataset_json_path: str: Path of the scene dataset JSON file created.

class dgp.utils.dataset_conversion.MergeSceneDatasetGen(scene_dataset_json_paths, description, version, local_output_path=None, bucket_path=None, name=None, email=None)¶

Bases: object

Class to merge multiple scene dataset JSONs together.

scene_dataset_json_paths: list: List of scene dataset JSON paths.
description: str: Description of the dataset.
version: str: Version of the dataset.
local_output_path: str, default: None: Local path to save merged scene dataset JSON
bucket_path: str: Where merged dataset should be saved to on s3 (defaults to that of the first dataset)
name: str, default: None: Name of the dataset
email: str, default: None: Email of the dataset creator

merge_scene_split_files()¶: Aggregate scene JSON paths together.

write_dataset(upload=False)¶

Write the final scene dataset JSON.

upload: bool, optional: If true, upload the dataset to the scene pool in s3. Default: False.

scene_dataset_json_path: str: Path of the scene dataset JSON file created.

dgp.utils.dataset_conversion.bgr2id(color)¶

Function converting color to instance id. This function the the conversion function used by COCO dataset. We adapted this function from the panoptic api: `https://github.com/cocodataset/panopticapi` Parameters ———- color: list

A list of 3 channel color intensity in rgb.

id: int: A single id encoded by the 3 channel color intensity.

dgp.utils.dataset_conversion.compute_image_statistics(image_list, image_open_fn, single_process=False, num_processes=None)¶

Given a list of images (paths to files), return the per channel mean and stdev. Also returns a dictionary mapping filename to image size

image_list: list: List of str of filepaths to images that can be opened by PIL
image_open_fn: function: Function to open image files in image_list, i.e. PIL.Image.open
single_process: bool: If it’s True, it gets image stats in single process for debugging. Defaults to False.
num_processes: int: A number of process in multiprocessing.Pool. If it’s None, it uses cpu count. Defaults to None.

global_mean: np.ndarray: Channel wise mean of images over images in given list
global_stdevr: np.ndarray: Channel wise standard deviation of images in given list
all_image_sizes: dict: Dict mapping from filenames to image sizes (C, H, W)

ValueError: Raised if all the images are invalid extensions.

dgp.utils.dataset_conversion.generate_uid_from_image(image)¶

Given a unique identifier, return the SHA1 hash hexdigest. Used for creating unique frame IDs

image: PIL.Image: Image to be hashed

Hexdigest of image content

dgp.utils.dataset_conversion.generate_uid_from_instance_segmentation_2d_annotation(annotation)¶

Given a unique identifier, return the SHA1 hash hexdigest.

annotation: np.array: instance_segmentation_2d annotation to be hashed

Hexdigest of annotation content

TypeError: Raised if annotation is not of type np.uint16 or np.uint23.
ValueError: Raised if annotation is not 2-dimensional.

dgp.utils.dataset_conversion.generate_uid_from_point_cloud(point_cloud)¶

Given a unique identifier, return the SHA1 hash hexdigest. Used for creating unique datum IDs

point_cloud: np.ndarray: Point cloud to be hashed

Hexdigest of point cloud

dgp.utils.dataset_conversion.generate_uid_from_semantic_segmentation_2d_annotation(annotation)¶

Given a unique identifier, return the SHA1 hash hexdigest.

annotation: np.array: semantic_segmentation_2d annotation to be hashed

Hexdigest of annotation content

TypeError: Raised if annotation is not of type np.uint8.
ValueError: Raised if annotation is not 2-dimensional.

dgp.utils.dataset_conversion.get_date()¶: Get today’s date. In format yyyy-mm-dd

dgp.utils.dataset_conversion.get_datetime_proto()¶

Returns current date time proto in UTC.

datetime_proto: google.protobuf.timestamp_pb2.Timestamp: Current date time proto object in UTC.

dgp.utils.dataset_conversion.make_dir(dir_path, exist_ok=False)¶

Create a directory and catch the error if it already exists.

dir_path: str: Directory to create
exist_ok: bool: Raise error if directory exists when this is set to False

dir_path: str: Created directory name

dgp.utils.dataset_conversion.parse_all_files_in_directory(directory)¶

Walk through subdirectories and pull all filenames

directory: str: Path to directory to recurse

file_list: list: Full paths to the files in all subdirectories

dgp.utils.dataset_conversion.read_cloud_ply(file)¶

Read pointcloud PLY file into numpy array(s)

file: str: Filename with pointcloud. It should have .ply extension

tuple

points: numpy array [N, 3]
Point cloud of (x, y, z) coordinates in Lidar frame
intensities: numpy array [N, ]
If present in source file, measured intensities. Otherwise empty array
timestamps: numpy array [N, ]
If present in source file, array of measurements timestamps. Otherwise empty array

TypeError: Raised if data type is not supported

dgp.utils.dataset_conversion.rgb2id(color)¶

Function converting color to instance id. This function the the conversion function used by COCO dataset. We adapted this function from the panoptic api: `https://github.com/cocodataset/panopticapi` Parameters ———- color: list

A list of 3 channel color intensity in rgb.

id: int: A single id encoded by the 3 channel color intensity.

dgp.utils.dataset_conversion.write_cloud_ply(file, points, intensities=None, timestamps=None)¶

Write pointcloud and, if provided, intensities and timestamps to PLY standard output

file: str: Filename to save cloud . It should have .ply extension
points: numpy array [N, 3] float64: Point cloud of (x, y, z) coordinates in Lidar frame
intensities: numpy array [N, ] uint8: Measured intensities
timestamps: numpy array [N, ] float64: Array of measurements timestamps

dgp.utils.datasets module¶

dgp.utils.datasets.get_split_to_scenes(dataset)¶

Retrieve a dictionary of split to scenes of a DGP-compliant scene dataset.

dataset: dgp.proto.dataset_pb2.SceneDataset: SceneDataset proto object.

split_to_scene_json: dict: A dictionary of split to a list of scene JSONs.
split_to_scene_dir: dict: A dictionary of split to a list of scene_dirs.

dgp.utils.pose module¶

General-purpose class for rigid-body transformations.

class dgp.utils.pose.Pose(wxyz=array([1., 0., 0., 0.], dtype=float32), tvec=array([0., 0., 0.], dtype=float32), reference_coordinate_system='')¶

Bases: object

SE(3) rigid transform class that allows compounding of 6-DOF poses and provides common transformations that are commonly seen in geometric problems.

copy()¶

Return a copy of this pose object.

Pose: Copied pose object.

classmethod from_matrix(transformation_matrix, reference_coordinate_system='')¶

Initialize pose from 4x4 transformation matrix

transformation_matrix: np.ndarray: 4x4 containing rotation/translation
reference_coordinate_system: str: Reference coordinate system this Pose (Transform) is expressed with respect to

Pose

classmethod from_rotation_translation(rotation_matrix, tvec, reference_coordinate_system='')¶

Initialize pose from rotation matrix and translation vector.

rotation_matrixnp.ndarray: 3x3 rotation matrix
tvecnp.ndarray: length-3 translation vector
reference_coordinate_system: str: Reference coordinate system this Pose (Transform) is expressed with respect to

inverse(new_reference_coordinate_system='')¶

Returns a new Pose that corresponds to the inverse of this one.

new_reference_coordinate_system: str: The reference coordinate system the inverse Pose (Transform) is expressed with respect to. I.e. the name of the current Pose

Pose: new_reference_coordinate_system pose

classmethod load(pose_proto)¶

Initialize pose from 4x4 transformation matrix

pose_proto: Pose_pb2: Pose as defined in proto/geometry.proto

Pose

property matrix¶

Returns a 4x4 homogeneous matrix of the form [R t; 0 1]

result: np.ndarray: 4x4 homogeneous matrix

property rotation¶

Return the rotation component of the pose as a Quaternion object.

Quaternion: Rotation component of the Pose object.

property rotation_matrix¶

Returns the 3x3 rotation matrix (R)

np.ndarray: 3x3 rotation matrix

to_proto()¶

Convert Pose into pb object.

pose_0S: Pose_pb2: Pose as defined in proto/geometry.proto

property translation¶

Return the translation component of the pose as a np.ndarray.

np.ndarray: Translation component of the Pose object.

dgp.utils.protobuf module¶

dgp.utils.protobuf.generate_uid_from_pbobject(pb_object)¶

Given a pb object, return the deterministic SHA1 hash hexdigest. Used for creating unique IDs.

pb_object: object: A protobuf pb2 object to be hashed.

Hexdigest of annotation content

dgp.utils.protobuf.get_latest_scene(s3_scene_jsons)¶

From a list of ‘scene.json’ and/or ‘scene_<sha1>.json’ paths in s3, return a Scene object for the one with the latest timestamp. Parameters ———- s3_scene_jsons: List[str]

List of ‘scene.json’ or ‘scene_<sha1>.json’ paths in s3

latest_scene: dgp.proto.scene_pb2.Scene: Scene pb object with the latest creation timestamp.
scene_json_path: str: S3 Path to the latest scene JSON.

This function can be called on the output:: out, _ = s3_recursive_list(os.path.join(scene_s3_dir, ‘scene’)

which is grabbing all ‘scene*’ files from the Scene directory

dgp.utils.protobuf.open_feature_ontology_pbobject(ontology_file)¶

Open feature ontology objects.

ontology_file: str: JSON ontology file path to load.

ontology: FeatureOntology object: Desired Feature Ontology pb2 object to be opened. Returns None if neither fails to load.

dgp.utils.protobuf.open_ontology_pbobject(ontology_file)¶

Open ontology objects, first attempt to open V2 before trying V1.

ontology_file: str or bytes: JSON ontology file path to load or bytestring.

ontology: Ontology object: Desired Ontology pb2 object to be opened (either V2 or V1). Returns None if neither fails to load.

dgp.utils.protobuf.open_pbobject(path, pb_class)¶

Load JSON as a protobuf (pb2) object.

Any calls to load protobuf objects from JSON in this repository should be through this function. Returns None if the loading failed.

path: str: Local JSON file path or remote scene dataset JSON URI to load.
pb_class: object: Protobuf pb2 object we want to load into.

pb_object: pb2 object: Desired pb2 object to be opened.

dgp.utils.protobuf.open_remote_pb_object(s3_object_uri, pb_class)¶

Load JSON as a protobuf (pb2) object from S3 remote

s3_object_uri: str: Remote scene dataset JSON URI.
pb_class: object: Protobuf pb2 object we want to load into.

pb_object: pb2 object: Desired pb2 object to be opened.

ValueError: Raised if s3_object_uri is not a valid S3 path.

dgp.utils.protobuf.parse_pbobject(source, pb_class)¶

Like open_pboject but source can be a path or a bytestring

source: str or bytes: Local JSON file path, remote s3 path to object, or bytestring of serialized object
pb_class: object: Protobuf pb2 object we want to load into.

pb_object: pb2 object or None: Desired pb2 ojbect to be parsed or None if loading fails

dgp.utils.protobuf.save_pbobject_as_json(pb_object, save_path)¶

Save protobuf (pb2) object to JSON file with our standard indent, key ordering, and other settings.

Any calls to save protobuf objects to JSON in this repository should be through this function.

pb_object: object: Protobuf pb2 object we want to save to file
save_path: str: If save path is a JSON, serialized object is saved to that path. If save path is directory, the pb_object is saved in <save_path>/<pb_object_sha>.json.

save_path: str: Returns path to saved pb_object JSON

dgp.utils.statistics module¶

dgp.utils.statistics.get_scene_class_statistics(scene, scene_dir, annotation_enum, ontology=None)¶

Given a DGP scene, return class counts of the annotations in the scene.

scene: dgp.proto.scene_pb2.Scene: Scene Object.
scene_dir: string: s3 URL or local path to scene.
annotation_enum: dgp.proto.ontology_pb2.AnnotationType: Annotation type enum
ontology: dgp.proto.ontology_pb2.Ontology or None: Stats will be computed for this ontology. If None, the ontology will be read from the scene.

scene_stats: OrderedDict

class_name: int: Counts of annotations for each class.

dgp.utils.statistics.get_scene_statistics(scene, verbose=True)¶

Given a DGP scene, return simple statistics (counts) of the scene.

scene: dgp.proto.scene_pb2.Scene: Scene Object.
verbose: bool, optional: Print the stats if True. Default: True.

scene_stats: OrderedDict

num_samples: int: Number of samples in the Scene
num_images: int: Number of image datums in the Scene.
num_point_clouds: int: Number of point_cloud datums in the Scene.
<datum_type>_<annotation_type>: int: Number of <datum_type> with associated <annotation_type> annotation files.

dgp.utils.testing module¶

exception dgp.utils.testing.SkipTest¶

Bases: Exception

Raise this exception in a test to skip it.

Usually you can use TestCase.skipTest() or one of the skipping decorators instead of raising this directly.

dgp.utils.testing.assert_allclose(actual, desired, rtol=1e-07, atol=0, equal_nan=True, err_msg='', verbose=True)¶

Raises an AssertionError if two objects are not equal up to desired tolerance.

The test is equivalent to allclose(actual, desired, rtol, atol) (note that allclose has different default values). It compares the difference between actual and desired to atol + rtol * abs(desired).

New in version 1.5.0.

actualarray_like: Array obtained.
desiredarray_like: Array desired.
rtolfloat, optional: Relative tolerance.
atolfloat, optional: Absolute tolerance.
equal_nanbool, optional.: If True, NaNs will compare equal.
err_msgstr, optional: The error message to be printed in case of failure.
verbosebool, optional: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired are not equal up to specified precision.

assert_array_almost_equal_nulp, assert_array_max_ulp

>>> x = [1e-5, 1e-3, 1e-1]
>>> y = np.arccos(np.cos(x))
>>> np.testing.assert_allclose(x, y, rtol=1e-5, atol=0)

dgp.utils.testing.assert_almost_equal(actual, desired, decimal=7, err_msg='', verbose=True)¶

Raises an AssertionError if two items are not equal up to desired precision.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

The test verifies that the elements of actual and desired satisfy.

abs(desired-actual) < 1.5 * 10**(-decimal)

That is a looser test than originally documented, but agrees with what the actual implementation in assert_array_almost_equal did up to rounding vagaries. An exception is raised at conflicting values. For ndarrays this delegates to assert_array_almost_equal

actualarray_like: The object to check.
desiredarray_like: The expected object.
decimalint, optional: Desired precision, default is 7.
err_msgstr, optional: The error message to be printed in case of failure.
verbosebool, optional: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired are not equal up to specified precision.

assert_allclose: Compare two array_like objects for equality with desired: relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

>>> from numpy.testing import assert_almost_equal
>>> assert_almost_equal(2.3333333333333, 2.33333334)
>>> assert_almost_equal(2.3333333333333, 2.33333334, decimal=10)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 10 decimals
 ACTUAL: 2.3333333333333
 DESIRED: 2.33333334

>>> assert_almost_equal(np.array([1.0,2.3333333333333]),
...                     np.array([1.0,2.33333334]), decimal=9)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 9 decimals

Mismatched elements: 1 / 2 (50%)
Max absolute difference: 6.66669964e-09
Max relative difference: 2.85715698e-09
 x: array([1.         , 2.333333333])
 y: array([1.        , 2.33333334])

dgp.utils.testing.assert_approx_equal(actual, desired, significant=7, err_msg='', verbose=True)¶

Raises an AssertionError if two items are not equal up to significant digits.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

Given two numbers, check that they are approximately equal. Approximately equal is defined as the number of significant digits that agree.

actualscalar: The object to check.
desiredscalar: The expected object.
significantint, optional: Desired precision, default is 7.
err_msgstr, optional: The error message to be printed in case of failure.
verbosebool, optional: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired are not equal up to specified precision.

assert_allclose: Compare two array_like objects for equality with desired: relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

>>> np.testing.assert_approx_equal(0.12345677777777e-20, 0.1234567e-20)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345671e-20,
...                                significant=8)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345672e-20,
...                                significant=8)
Traceback (most recent call last):
    ...
AssertionError:
Items are not equal to 8 significant digits:
 ACTUAL: 1.234567e-21
 DESIRED: 1.2345672e-21

the evaluated condition that raises the exception is

>>> abs(0.12345670e-20/1e-21 - 0.12345672e-20/1e-21) >= 10**-(8-1)
True

dgp.utils.testing.assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True)¶

Raises an AssertionError if two objects are not equal up to desired precision.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

The test verifies identical shapes and that the elements of actual and desired satisfy.

abs(desired-actual) < 1.5 * 10**(-decimal)

That is a looser test than originally documented, but agrees with what the actual implementation did up to rounding vagaries. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

xarray_like: The actual object to check.
yarray_like: The desired, expected object.
decimalint, optional: Desired precision, default is 6.
err_msgstr, optional: The error message to be printed in case of failure.
verbosebool, optional: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired are not equal up to specified precision.

assert_allclose: Compare two array_like objects for equality with desired: relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

the first assert does not raise an exception

>>> np.testing.assert_array_almost_equal([1.0,2.333,np.nan],
...                                      [1.0,2.333,np.nan])

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33339,np.nan], decimal=5)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 5 decimals

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 6.e-05
Max relative difference: 2.57136612e-05
 x: array([1.     , 2.33333,     nan])
 y: array([1.     , 2.33339,     nan])

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33333, 5], decimal=5)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not almost equal to 5 decimals

x and y nan location mismatch:
 x: array([1.     , 2.33333,     nan])
 y: array([1.     , 2.33333, 5.     ])

dgp.utils.testing.assert_array_equal(x, y, err_msg='', verbose=True)¶

Raises an AssertionError if two array_like objects are not equal.

Given two array_like objects, check that the shape is equal and all elements of these objects are equal (but see the Notes for the special handling of a scalar). An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

The usual caution for verifying equality with floating point numbers is advised.

xarray_like: The actual object to check.
yarray_like: The desired, expected object.
err_msgstr, optional: The error message to be printed in case of failure.
verbosebool, optional: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired objects are not equal.

assert_allclose: Compare two array_like objects for equality with desired: relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

When one of x and y is a scalar and the other is array_like, the function checks that each element of the array_like object is equal to the scalar.

The first assert does not raise an exception:

>>> np.testing.assert_array_equal([1.0,2.33333,np.nan],
...                               [np.exp(0),2.33333, np.nan])

Assert fails with numerical imprecision with floats:

>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
...                               [1, np.sqrt(np.pi)**2, np.nan])
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not equal

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 4.4408921e-16
Max relative difference: 1.41357986e-16
 x: array([1.      , 3.141593,      nan])
 y: array([1.      , 3.141593,      nan])

Use assert_allclose or one of the nulp (number of floating point values) functions for these cases instead:

>>> np.testing.assert_allclose([1.0,np.pi,np.nan],
...                            [1, np.sqrt(np.pi)**2, np.nan],
...                            rtol=1e-10, atol=0)

As mentioned in the Notes section, assert_array_equal has special handling for scalars. Here the test checks that each value in x is 3:

>>> x = np.full((2, 5), fill_value=3)
>>> np.testing.assert_array_equal(x, 3)

dgp.utils.testing.assert_array_less(x, y, err_msg='', verbose=True)¶

Raises an AssertionError if two array_like objects are not ordered by less than.

Given two array_like objects, check that the shape is equal and all elements of the first object are strictly smaller than those of the second object. An exception is raised at shape mismatch or incorrectly ordered values. Shape mismatch does not raise if an object has zero dimension. In contrast to the standard usage in numpy, NaNs are compared, no assertion is raised if both objects have NaNs in the same positions.

xarray_like: The smaller object to check.
yarray_like: The larger object to compare.
err_msgstring: The error message to be printed in case of failure.
verbosebool: If True, the conflicting values are appended to the error message.

AssertionError: If actual and desired objects are not equal.

assert_array_equal: tests objects for equality assert_array_almost_equal: test objects for equality up to precision

>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1.1, 2.0, np.nan])
>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1, 2.0, np.nan])
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not less-ordered

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 1.
Max relative difference: 0.5
 x: array([ 1.,  1., nan])
 y: array([ 1.,  2., nan])

>>> np.testing.assert_array_less([1.0, 4.0], 3)
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not less-ordered

Mismatched elements: 1 / 2 (50%)
Max absolute difference: 2.
Max relative difference: 0.66666667
 x: array([1., 4.])
 y: array(3)

>>> np.testing.assert_array_less([1.0, 2.0, 3.0], [4])
Traceback (most recent call last):
    ...
AssertionError:
Arrays are not less-ordered

(shapes (3,), (1,) mismatch)
 x: array([1., 2., 3.])
 y: array([4])

dgp.utils.testing.assert_between(value, low, high, low_inclusive=True, high_inclusive=True)¶

Assert value is inside the specified range. Parameters ———- value : comparable

Value to be asserted.

lowcomparable: Range lower bound.
highcomparable: Range upper bound.
low_inclusivebool, optional: Allow case when value == low. Default: True.
high_inclusivebool, optional: Allow case when value == high. Default: True.

dgp.utils.testing.assert_equal(first, second, msg=None)¶: Fail if the two objects are unequal as determined by the ‘==’ operator.

dgp.utils.testing.assert_false(expr, msg=None)¶: Check that the expression is false.

dgp.utils.testing.assert_greater(a, b, msg=None)¶: Just like self.assertTrue(a > b), but with a nicer default message.

dgp.utils.testing.assert_greater_equal(a, b, msg=None)¶: Just like self.assertTrue(a >= b), but with a nicer default message.

dgp.utils.testing.assert_less(a, b, msg=None)¶: Just like self.assertTrue(a < b), but with a nicer default message.

dgp.utils.testing.assert_less_equal(a, b, msg=None)¶: Just like self.assertTrue(a <= b), but with a nicer default message.

dgp.utils.testing.assert_not_equal(first, second, msg=None)¶: Fail if the two objects are equal as determined by the ‘!=’ operator.

dgp.utils.testing.assert_raises(expected_exception, *args, **kwargs)¶

Fail unless an exception of class expected_exception is raised by the callable when invoked with specified positional and keyword arguments. If a different type of exception is raised, it will not be caught, and the test case will be deemed to have suffered an error, exactly as for an unexpected exception.

If called with the callable and arguments omitted, will return a context object used like this:

with self.assertRaises(SomeException):
    do_something()

An optional keyword argument ‘msg’ can be provided when assertRaises is used as a context object.

The context manager keeps a reference to the exception as the ‘exception’ attribute. This allows you to inspect the exception after the assertion:

with self.assertRaises(SomeException) as cm:
    do_something()
the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

dgp.utils.testing.assert_true(expr, msg=None)¶: Check that the expression is true.

dgp.utils.visualization_engine module¶

dgp.utils.visualization_engine.visualize_dataset_2d(dataset, camera_datum_names=None, max_num_items=None, caption_fn=None, show_instance_id=False, output_video_file=None, output_video_fps=30, class_colormap=None, adjust_lightness_factor=1.0, font_scale=1, rgb_resize_factor=0.5)¶

Visualize 2D annotations of a synchronized DGP dataset (e.g. SynchronizedSceneDataset, ParallelDomainScene). The output is a video, either rendered on X window or a video file, that visualize 2D bounding boxes and optionally instance segmentation masks.

dataset: _SynchronizedDataset: A multimodel dataset of which __getitem__ returns a list of OrderedDict, one item for each datum.
camera_datum_names: None or List[str], optional: Names of camera_datums. If None, then use all datums whose type is image and are available in all scenes. In the output video, the image visualizations are tiled in row-major order according to the order of this list. Default: None.
max_num_items: None or int, optional: If not None, then show only up to this number of items. This is useful for debugging a large dataset. Default: None.
caption_fn: Callable, optional: A function that take as input a _SynchronizedDataset and index, and return a text (str). The text is put as caption at the top left corner of video. Default: None.
show_instance_id: bool, optional: Option to show instance id instead of instance class name on annotated images. Default: False.
output_video_file: None or str, optional: If not None, then write the visualization on a video of this name. It must ends with .avi. Default: None.
output_video_fps: int, optional: Frame rate of the video. Default: 30
class_colormap: dict or None, optional: Dict of class name to RGB color tuple. If None, then use class color defined in dataset. Default: None.
adjust_lightness_factor: float, optional: Enhance the brightness of colormap by this factor. Default: 1.0.
font_scale: float, optional: Font scale used for all text. Default: 1.
rgb_resize_factor: float, optional: Resize images by this factor before tiling them into a single panel. Default: 0.5.

dgp.utils.visualization_engine.visualize_dataset_3d(dataset, lidar_datum_names=None, camera_datum_names=None, render_pointcloud_on_images=True, show_instance_id_on_bev=True, max_num_items=None, caption_fn=None, output_video_file=None, output_video_fps=30, class_colormap=None, adjust_lightness_factor=1.0, rgb_resize_factor=0.5, rgb_border_thickness=4, bev_metric_width=100.0, bev_metric_height=100.0, bev_pixels_per_meter=10.0, bev_polar_step_size_meters=10, bev_forward=(1, 0, 0), bev_left=(0, 1, 0), bev_background_clr=(0, 0, 0), bev_font_scale=0.5, bev_line_thickness=4, bbox3d_font_scale=1.0, bbox3d_line_thickness=4, pc_rgb_cmap=<matplotlib.colors.LinearSegmentedColormap object>, pc_rgb_norm_depth=10, pc_rgb_dilation=3, radar_datum_names=None, render_radar_pointcloud_on_images=True)¶

Visualize 3D annotations and pointclouds of a synchronized DGP dataset (e.g. SynchronizedSceneDataset, ParallelDomainScene). The output is a video, either rendered on X window or a video file, that visualize 3D bounding boxes and pointcloud 1) from a BEV view and 2) projected on cameras. Parameters ———- dataset: _SynchronizedDataset

A multimodel dataset of which __getitem__ returns a list of OrderedDict, one item for each datum.

lidar_datum_names: None or List[str], optional: Names of lidar datums. If None, then use all datums whose type is point_cloud and are available in all scenes. Default: None.
camera_datum_names: None or List[str], optional: Names of camera_datums. If None, then use all datums whose type is image and are available in all scenes. In the output video, the image visualizations are tiled in row-major order according to the order of this list. Default: None.
render_pointcloud_on_images: bool, optional: Whether or not to render projected pointclouds on images. Default: True.
show_instance_id_on_bev: bool, optional: If True, then show instance_id on a corner of 3D bounding boxes in BEV view. If False, then show class_name instead. Default: True.
max_num_items: None or int, optional: If not None, then show only up to this number of items. This is useful for debugging a large dataset. Default: None.
caption_fn: Callable, optional: A function that take as input a _SynchronizedDataset and index, and return a text (str). The text is put as caption at the top left corner of video. Default: None.
output_video_file: None or str, optional: If not None, then write the visualization on a video of this name. It must ends with .avi. Default: None.
output_video_fps: int, optional: Frame rate of the video. Default: 30.
class_colormap: dict, optional: Dict of class name to RGB color tuple. If None, then use class color defined in dataset. Default: None.
adjust_lightness_factor: float, optional: Enhance the brightness of colormap by this factor. Default: 1.0.
rgb_resize_factor: float, optional: Resize images by this factor before tiling them into a single panel. Default: 0.5.
rgb_border_thickness: int, optional: Put a colored boundary on camera visualization of this thickness before tiling them into single panel. Default: 4.
bev_metric_width: float, optional: See BEVImage for this keyword argument. Default: 100.0.
bev_metric_height: float, optional: See BEVImage for this keyword argument. Default: 100.0.
bev_pixels_per_meter: float, optional: See BEVImage for this keyword argument. Default: 10.0.
bev_polar_step_size_meters: int, optional: See BEVImage for this keyword argument. Default: 10.
bev_forward: tuple of int, optional: See BEVImage for this keyword argument. Default: (1, 0, 0).
bev_left: tuple of int, optional: See BEVImage for this keyword argument. Default: (0, 1, 0).
bev_background_clr: tuple of int: See BEVImage for this keyword argument. Default: (0, 0, 0).
bev_font_scale: float: See BEVImage for this keyword argument. Default: 0.5.
bev_line_thickness: int: See BEVImage for this keyword argument. Default: 4.
bbox3d_font_scale: float: See geometry.BoundingBox3D for this keyword argument. Default: 1.0.
bbox3d_line_thickness: int: See geometry.BoundingBox3D for this keyword argument. Default: 4.
pc_rgb_cmap: optional: See render_pointcloud_on_image() for this keyword argument. The value type comes from matplotlib.cm.get_cmap. Default: MPL_JET_CMAP.
pc_rgb_norm_depth: int, optional: See render_pointcloud_on_image() for this keyword argument. Default: 10.
pc_rgb_dilation: int, optional: See render_pointcloud_on_image() for this keyword argument. Default: 3.
radar_datum_names: List[str], optional: Names of the radar datums. Default: None
render_radar_pointcloud_on_images: bool, optional: Whether or not to render projected radar pointclouds on images. Default: True.

dgp.utils.visualization_engine.visualize_dataset_sample_2d(dataset, scene_idx, sample_idx, camera_datum_names=None, show_instance_id=False, class_colormap=None, adjust_lightness_factor=1.0, rgb_resize_factor=0.5)¶

Visualize 2D annotations of a single sample from a synchronized DGP dataset (e.g. SynchronizedSceneDataset, ParallelDomainScene). The output is a tuple dictionaries of images keyed by camera datum name (bounding box images, semantic segmentation images).

dataset: _SynchronizedDataset: A multimodel dataset of which __getitem__ returns a list of OrderedDict, one item for each datum.
scene_idx: int: The scene index into the dataset.
sample_idx: int: The sample index into the scene.
camera_datum_names: None or List[str], optional: Names of camera_datums. If None, then use all datums whose type is image and are available in all scenes. In the output video, the image visualizations are tiled in row-major order according to the order of this list. Default: None.
show_instance_id: bool, optional: Option to show instance id instead of instance class name on annotated images. Default: False.
class_colormap: dict or None, optional: Dict of class name to RGB color tuple. If None, then use class color defined in dataset. Default: None.
adjust_lightness_factor: float, optional: Enhance the brightness of colormap by this factor. Default: 1.0.
rgb_resize_factor: float, optional: Resize images by this factor before tiling them into a single panel. Default: 0.5.

bbox_rgbdict of strnp.array: Dictionary of bounding box annotated images keyed by the camera datum name.
semantic_rgbdict of strnp.array: Dictionary of semantic segmentation images keyed by camera datum name.

dgp.utils.visualization_engine.visualize_dataset_sample_3d(dataset, scene_idx, sample_idx, lidar_datum_names=None, camera_datum_names=None, render_pointcloud_on_images=True, show_instance_id_on_bev=True, class_colormap=None, adjust_lightness_factor=1.0, rgb_resize_factor=0.5, rgb_border_thickness=4, bev_metric_width=100.0, bev_metric_height=100.0, bev_pixels_per_meter=10.0, bev_polar_step_size_meters=10, bev_forward=(1, 0, 0), bev_left=(0, 1, 0), bev_background_clr=(0, 0, 0), bev_font_scale=0.5, bev_line_thickness=4, bbox3d_font_scale=1.0, bbox3d_line_thickness=4, pc_rgb_cmap=<matplotlib.colors.LinearSegmentedColormap object>, pc_rgb_norm_depth=10, pc_rgb_dilation=3, radar_datum_names=None)¶

Visualize 3D annotations and pointclouds of a single sample of a DGP dataset (e.g. SynchronizedSceneDataset, ParallelDomainScene). The output is a dictionary of images keyed by camera datum name and ‘bev’ for the BEV image,

dataset: _SynchronizedDataset: A multimodel dataset of which __getitem__ returns a list of OrderedDict, one item for each datum.
scene_idx: int: scene index into dataset
sample_idx: int: index of sample in scene
lidar_datum_names: None or List[str], optional: Names of lidar datum. Default: None.
camera_datum_names: None or List[str], optional: Names of camera_datums. Default: None.
render_pointcloud_on_images: bool, optional: Whether or not to render projected pointclouds on images. Default: True.
show_instance_id_on_bev: bool, optional: If True, then show instance_id on a corner of 3D bounding boxes in BEV view. If False, then show class_name instead. Default: True.
class_colormap: dict or None, optional: Dict of class name to RGB color tuple. If None, then use class color defined in dataset. Default: None.
adjust_lightness_factor: float, optional: Enhance the brightness of colormap by this factor. Default: 1.0.
rgb_resize_factor: float, optional: Resize images by this factor before tiling them into a single panel. Default: 0.5.
rgb_border_thickness: int, optional: Put a colored boundary on camera visualization of this thickness before tiling them into single panel. Default: 4.
bev_metric_width: float, optional: See BEVImage for this keyword argument. Default: 100.0.
bev_metric_height: float, optional: See BEVImage for this keyword argument. Default: 100.0.
bev_pixels_per_meter: float, optional: See BEVImage for this keyword argument. Default: 10.0.
bev_polar_step_size_meters: int, optional: See BEVImage for this keyword argument. Default: 10.
bev_forward: tuple, optional: See BEVImage for this keyword argument. Default: (1, 0, 0).
bev_left: tuple, optional: See BEVImage for this keyword argument. Default: (0, 1, 0).
bev_background_clr: tuple, optional: See BEVImage for this keyword argument. Default: (0, 0, 0).
bev_font_scale: float, optional: See BEVImage for this keyword argument. Default: 0.5.
bev_line_thickness: int, optional: See BEVImage for this keyword argument. Default: 4.
bbox3d_font_scale: float, optional: See geometry.BoundingBox3D for these keyword arguments. Default: 1.0.
bbox3d_line_thickness: int, optional: See geometry.BoundingBox3D for these keyword arguments. Default: 4.
pc_rgb_cmap: optional: See render_pointcloud_on_image() for these keyword arguments. The value type comes from matplotlib.cm.get_cmap. Default: MPL_JET_CMAP.
pc_rgb_norm_depth: int, optional: See render_pointcloud_on_image() for these keyword arguments. Default: 10.
pc_rgb_dilation: int, optional: See render_pointcloud_on_image() for these keyword arguments. Default: 3.
radar_datum_names: None or List[str], optional: Names of the radar datums. Default: None.

resultsdict of strnp.array: Dictionary of images keyed by their camera datum name or ‘bev’ for the bird’s eye view.

dgp.utils.visualization_utils module¶

Visualization tools for a variety of tasks

class dgp.utils.visualization_utils.BEVImage(metric_width=100.0, metric_height=100.0, pixels_per_meter=10.0, polar_step_size_meters=10, forward=(1, 0, 0), left=(0, 1, 0), background_clr=(0, 0, 0), center_offset_w=0, center_offset_h=0)¶

Bases: object

A class for bird’s eye view visualization, which generates a canvas of bird’s eye view image,

The class concerns two types of transformations:

Extrinsics:

A pose of sensor wrt the body frame. The inputs of rendering functions (point_cloud and bboxes3d) are in this sensor frame.

BEV rotation:

This defines an axis-aligned transformation from the body frame to BEV frame. For this, it uses conventional definition of orientations in the body frame:

“forward” is a unit vector pointing to forward direction in the body frame. “left” is a unit vector pointing to left-hand-side in the body frame.

In BEV frame,: “forward” matches with right-hand-side of BEV image(x-axis) “left” matches with top of BEV image (negative y-axis)

The rendering is done by chaining the extrinsics and BEV rotation to transform the inputs to the BEV camera, and then apply an orthographic transformation.

metric_width: float, default: 100.: Metric extent of the view in width (X)
metric_height: float, default: 100.: Metric extent of the view in height (Y)
pixels_per_meter: float, default: 10.: Scale that expresses pixels per meter
polar_step_size_meters: int, default: 10: Metric steps at which to draw the polar grid
extrinsics: Pose, default: Identity pose: The pose of the sensor wrt the body frame (Sensor frame -> (Vehicle) Body frame). The input of rendering functions (i.e. point_cloud, bboxes3d) are assumed to be in the sensor frame.
forward, left: tuple[int], defaults: (1., 0., 0), (0., 1., 0.): Length-3 orthonormal vectors that represents “forward” and “left” direction in the body frame. The default values assumes the most standard body frame; i.e., x: forward, y: left z: up. These are used to construct a rotation transformation from the body frame to the BEV frame.
background_clr: tuple[int], defaults: (0, 0, 0): Background color in BGR order.
center_offset_w: int, default: 0: Offset in pixels to move ego center in BEV.
center_offset_h: int, default: 0: Offset in pixels to move ego center in BEV.

render_bounding_box_3d(bboxes3d, extrinsics=wxyz: +1.000 +0.000i +0.000j +0.000k, tvec: ([0.00 0.00 0.00]) wrt. ``, colors=((0, 255, 0), ), side_color_fraction=0.7, rear_color_fraction=0.5, texts=None, line_thickness=2, font_scale=0.5, font_colors=((255, 255, 255), ), markers=None, marker_scale=0.5, marker_colors=((255, 0, 0), ))¶

Render bounding box 3d in BEV perspective.

bboxes3d: List[BoundingBox3D]: 3D annotations in the sensor coordinate frame.
extrinsics: Pose, optional: The pose of the pointcloud sensor wrt the body frame (Sensor frame -> (Vehicle) Body frame). Default: Identity pose.
colors: Sequence[Tuple[int, int, int]], optional: Draw boxes using this color where each color is an RGB tuple. Default: (GREEN, ).
side_color_fraction: float, optional: A fraction in brightness of side edge colors of bounding box wrt the front face. Default: 0.6.
rear_color_fraction: float, optional: A fraction in brightness of rear face colors of bounding box wrt the front face. Default: 0.3.
texts: list of str, optional: 3D annotation category name. Default: None.
line_thickness: int, optional: Thickness of lines. Default: 2.
font_scale: float, optional: Font scale used for text labels. Default: 0.5.
font_colors: Sequence[Tuple[int, int, int]], optional: Color used for text labels. Default: (WHITE, ).
markers: List[int], optional: List of opencv markers to draw in bottom right corner of cuboid. Should be one of: cv2.MARKER_CROSS, cv2.MARKER_DIAMOND, cv2.MARKER_SQUARE, cv2.MARKER_STAR, cv2.MARKER_TILTED_CROSS, cv2.MARKER_TRIANGLE_DOWN, cv2.MARKER_TRIANGLE_UP, or None. Default: None.
marker_scale: float, optional: Scale factor for markers. Default: 0.5.
marker_colors: Sequence[Tuple[int, int, int]], optional: Draw markers using this color. Default: (RED, ).

render_camera_frustrum(intrinsics, extrinsics, width, color=(252, 226, 5), line_thickness=1)¶

Visualize the frustrum of camera by drawing two lines connecting the camera center and top-left / top-right corners of image plane.

intrinsics: np.ndarray: 3x3 intrinsics matrix
extrinsics: Pose: Pose of camera in body frame.
width: int: Width of image.
color: Tuple[int], optional: Color in RGB of line. Default: YELLOW.
line_thickness: int, optional: Thickness of line. Default: 1.

render_paths(paths, extrinsics=wxyz: +1.000 +0.000i +0.000j +0.000k, tvec: ([0.00 0.00 0.00]) wrt. ``, colors=((0, 255, 0), ), line_thickness=1, tint=1.0)¶

Render object paths on bev.

paths: list[list[Pose]]: List of object poses in the coordinate frame of the current timestep.
extrinsics: Pose, optional: The pose of the pointcloud sensor wrt the body frame (Sensor frame -> (Vehicle) Body frame). Default: Identity pose.
colors: List[Tuple[int, int, int]], optional: Draw path using this color. Default: (GREEN, ).
line_thickness: int, optional: Thickness of lines. Default: 1.
tint: float, optional: Mulitiplicative factor applied to color used to darken lines. Default: 1.0.

render_point_cloud(point_cloud, extrinsics=wxyz: +1.000 +0.000i +0.000j +0.000k, tvec: ([0.00 0.00 0.00]) wrt. ``, color=(100, 100, 100))¶

Render point cloud in BEV perspective.

point_cloud: np.ndarray: 3D cloud points in the sensor coordinate frame. Shape is (N, 3).
extrinsics: Pose, optional: The pose of the pointcloud sensor wrt the body frame (Sensor frame -> (Vehicle) Body frame). Default: Identity pose.
color: Tuple[int], optional: Color in RGB to render the points. Default: GRAY.

render_radar_point_cloud(point_cloud, extrinsics=wxyz: +1.000 +0.000i +0.000j +0.000k, tvec: ([0.00 0.00 0.00]) wrt. ``, color=(255, 0, 0), velocity=None, velocity_scale=1, velocity_max_pix=0.05)¶

Render radar point cloud in BEV perspective.

point_cloud: np.ndarray: Point cloud in rectangular coordinates of sensor frame. Shape is (N, 3).
extrinsics: Pose, optional: The pose of the pointcloud sensor wrt the body frame (Sensor frame -> (Vehicle) Body frame). Default: Identity pose.
color: Tuple[int], optional: Color in RGB to render the points. Default: RED.
velocity: np.ndarray, optional: Velocity vector of points. Shape: (N, 3). Default: None.
velocity_scale: float, optional: Factor to scale velocity vector by. Default: 1.0.
velocity_max_pix: float, optional: Maximum length of velocity vector rendering in percent of image width. Default: 0.05.

reset()¶: Reset the canvas to a blank image with guideline circles of various radii.

dgp.utils.visualization_utils.make_caption(dataset, idx, prefix='')¶

Make caption that tells scene directory and sample index.

dataset: BaseDataset: BaseDataset. e.g. ParallelDomainScene(Dataset), SynchronizedScene(Dataset).
idx: int: Image index.
prefix: str, optional: Caption prefix. Default: “”.

caption: str: Caption of the image

dgp.utils.visualization_utils.mosaic(items, scale=1.0, pad=3, grid_width=None)¶

Creates a mosaic from list of images.

items: List[np.ndarray]: List of images to mosaic.
scale: float, optional: Scale factor applied to images. scale > 1.0 enlarges images. Default: 1.0.
pad: int, optional: Padding size of the images before mosaic. Default: 3.
grid_width: int, optional: Mosaic width or grid width of the mosaic. Default: None.

image: np.array of shape (H, W, 3): Image mosaic

dgp.utils.visualization_utils.ontology_to_viz_colormap(ontology, void_class_id=255)¶

Grabs semseg viz-ready colormap from DGP Ontology object

ontology: dgp.proto.ontology_pb2.Ontology: DGP ontology object for which we want to create a viz-friendly colormap look-up
void_class_id: int, optional: Class ID used to denote VOID or IGNORE in ontology. Default: 255.

colormap: np.int64 array: Shape is (num_classes, 3), where num_classes includes the VOID class colormap[i, :] is the BGR triplet for class ID i, with colormap[-1, :] being the color for the VOID class

Class ID’s are assumed to be contiguous and 0-indexed, with VOID class as the last item in the ontology (if VOID is not in the ontology, then black color is assigned to it and appended to colormap)

dgp.utils.visualization_utils.print_status(image, text)¶

Adds a status bar at the bottom of image, with provided text.

image: np.ndarray: Image to print status on. Shape is (H, W, 3).
text: str: Text to be printed.

image: np.array of shape (H, W, 3): Image with status printed

dgp.utils.visualization_utils.render_bbox2d_on_image(img, bboxes2d, instance_masks=None, colors=None, texts=None, line_thickness=4)¶

Render list of bounding box2d on image.

img: np.ndarray: Image to render bounding boxes onto.
bboxes2d: np.ndarray: Array of 2d bounding box (x, y, w, h). Shape is (N x 4).
instance_masks: list, optional: List of binary instance masks cropped to (w,h). Default: None.
colors: list, optional: List of color tuples. Default: None.
texts: list, optional: List of str classes. Default: None.
line_thickness: int, optional: Line thickness value for bounding box edges. Default: 4.

img: np.array: Image with rendered bounding boxes.

dgp.utils.visualization_utils.render_pointcloud_on_image(img, camera, Xw, cmap=<matplotlib.colors.LinearSegmentedColormap object>, norm_depth=10, dilation=3)¶

Render pointcloud on image.

img: np.ndarray: Image to render bounding boxes onto.
camera: Camera: Camera object with appropriately set extrinsics wrt world.
Xw: np.ndarray: 3D point cloud (x, y, z) in the world coordinate. Shape is (N x 3).
cmap: matplotlib.colors.Colormap, optional: Colormap used for visualizing the inverse depth. Default: MPL_JET_CMAP.
norm_depth: float, optional: Depth value to normalize (inverse) pointcloud depths in color mapping. Default: 10.0.
dilation: int, optional: Dilation factor applied on each point. Default: 3.

img: np.array: Image with rendered point cloud.

dgp.utils.visualization_utils.render_radar_pointcloud_on_image(img, camera, point_cloud, cmap=<matplotlib.colors.LinearSegmentedColormap object>, norm_depth=10, velocity=None, velocity_scale=1, velocity_max_pix=0.05)¶

Render radar pointcloud on image.

img: np.ndarray: Image to render bounding boxes onto.
camera: Camera: Camera object with appropriately set extrinsics wrt world.
point_cloud: np.ndarray: point cloud in spherical coordinates of radar sensor frame. Shape is (N x 8).
cmap: matplotlib.colors.Colormap: Colormap used for visualizing the inverse depth.
norm_depth: float, optional: Depth value to normalize (inverse) pointcloud depths in color mapping. Default: 10.
velocity: np.ndarray: Velocity vector of points. Shape is (N, 3). Default: None.
velocity_scale: float, optional: Factor to scale velocity vector by. Default: 1.0.
velocity_max_pix: float, optional: Maximum length of velocity vector rendering in percent of image width. Default: 0.05.

img: np.array: Image with rendered point cloud.

dgp.utils.visualization_utils.visualize_bev(lidar_datums, class_colormap, show_instance_id_on_bev=False, id_to_name=None, camera_datums=None, camera_colors=None, bev_metric_width=100, bev_metric_height=100, bev_pixels_per_meter=10, bev_polar_step_size_meters=10, bev_forward=(1, 0, 0), bev_left=(0, 1, 0), bev_background_clr=(0, 0, 0), bev_line_thickness=4, bev_font_scale=0.5, radar_datums=None, instance_colormap=None, cuboid_caption_fn=None, marker_fn=None, marker_scale=0.5, show_paths_on_bev=False, bev_center_offset_w=0, bev_center_offset_h=0)¶

Create BEV visualization that shows pointcloud, 3D bounding boxes, and optionally camera frustrums. Parameters ———- lidar_datums: List[OrderedDict]

List of lidar datums as a dictionary.

class_colormap: Dict: Mapping from class IDs to RGB colors.
show_instance_id_on_bev: Bool, optional: If True, then show instance_id on a corner of 3D bounding boxes in BEV view. If False, then show class_name instead. Default: False.
id_to_name: OrderedDict, optional: Mapping from class IDs to class names. Default: None.
camera_datums: List[OrderedDict], optional: List of camera datums as a dictionary. Default: None.
camera_colors: List[Tuple[int]], optional: List of RGB colors associated with each camera. The colors are used to draw frustrum. Default: None.
bev_metric_width: int, optional: See BEVImage for this keyword argument. Default: 100.
bev_metric_height: int, optional: See BEVImage for this keyword argument. Default: 100.
bev_pixels_per_meter: int, optional: See BEVImage for this keyword argument. Default: 10.
bev_polar_step_size_meters: int, optional: See BEVImage for this keyword argument. Default: 10.
bev_forward: tuple of int, optional: See BEVImage for this keyword argument. Default: (1, 0, 0)
bev_left: tuple of int, optional: See BEVImage for this keyword argument. Default: (0, 1, 0)
bev_background_clr: tuple of int, optional: See BEVImage for this keyword argument. Default: (0, 0, 0)
bev_line_thickness: int, optional: See BEVImage for this keyword argument. Default: 4.
bev_font_scale: float, optional: See BEVImage for this keyword argument. Default: 0.5.
radar_datums: List[OrderedDict], optional: List of radar datums to visualize. Default: None.
instance_colormap: Dict, optional: Mapping from instance id to RGB colors. Default: None.
cuboid_caption_fn: Callable, optional: Function taking a BoundingBox3d object and returning a tuple with the caption string, and the rgb value for that caption. e.g., ( ‘car’, (255,0,0) ). Signature: f(BoundingBox3d) -> Tuple[String, Tuple[3]] Default: None.
marker_fn: Callable, optional: Function taking a BoundingBox3d object and returning a tuple with the caption a marker id, and the rgb value for that marker. e.g., ( cv2.MARKER_DIAMOND, (255,0,0) ). Marker should be one of cv2.MARKER_CROSS, cv2.MARKER_DIAMOND, cv2.MARKER_SQUARE, cv2.MARKER_STAR, cv2.MARKER_TILTED_CROSS, cv2.MARKER_TRIANGLE_DOWN, cv2.MARKER_TRIANGLE_UP, or None. Signature: f(BoundingBox3d) -> Tuple[int,Tuple[3]] Default: None.
marker_scale: float, optional: Default: 0.5.
show_paths_on_bev: bool, optional: If true draw a path for each cuboid. Paths are stored in cuboid attributes under the ‘path’ key, i.e., path = cuboid.attributes[‘path’], paths are themselves a list of pose objects transformed to the correct frame. This method does not handle creating or transforming the paths. Default: False.
bev_center_offset_w: int, optional: Offset in pixels to move ego center in BEV. Default: 0.
bev_center_offset_h: int, optional: Offset in pixels to move ego center in BEV. Default: 0.

np.ndarray: BEV visualization as an image.

dgp.utils.visualization_utils.visualize_bounding_box_2d(image, bounding_box_2d, ontology, debug=False)¶

DGP-friendly bounding_box_2d visualization util

image: np.ndarray: Image to visualize boxes on in BGR format. Data type is uint8. Shape is (H, W, 3).
bounding_box_2d: dgp.proto.annotations_pb2.BoundingBox2DAnnotations: Bounding box annotations.
ontology: dgp.proto.ontology_pb2.Ontology: Ontology with which to visualize (for colors and class names).
debug: bool, optional: If True render image until key-press. Default: False.

viz: np.uint8 array: BGR visualization with bounding boxes shape: (H, W, 3)

dgp.utils.visualization_utils.visualize_cameras(camera_datums, id_to_name, lidar_datums=None, rgb_resize_factor=1.0, bbox3d_font_scale=1.0, bbox3d_line_thickness=4, pc_rgb_cmap=<matplotlib.colors.LinearSegmentedColormap object>, pc_rgb_norm_depth=10, pc_rgb_dilation=3, radar_datums=None)¶

Create camera visualization that shows 3D bounding boxes, and optionally projected pointcloud. Parameters ———- camera_datums: List[OrderedDict]

List of camera datums as a dictionary.

id_to_name: OrderedDict: Mapping from class IDs to class names.
lidar_datums: List[OrderedDict] or None, optional: List of lidar datums as a dictionary. If given, then draw pointcloud contained in all datums. Default: None.
rgb_resize_factor: float, optional: Resize images by this factor before tiling them into a single panel. Default: 1.0.
bbox3d_font_scale: float, optional: Font scale used for text labels. Default: 1.0.
bbox3d_line_thickness: int, optional: Thickness of lines used for drawing 3D bounding boxes. Default: 4.
pc_rgb_cmap: color_map: A matplotlib color map. Default: MPL_JET_CMAP.
pc_rgb_norm_depth: int, optional: Depth value to normalize (inverse) pointcloud depths in color mapping. Default: 10.
pc_rgb_dilation: int, optional: Dilation factor applied on each point in pointcloud. Default: 3.
radar_datums: List[OrderedDict], optional: List of radar datums to visualize. Default: None.

rgb_viz: List[np.ndarray]: List of camera visualization images, one for each camera.

dgp.utils.visualization_utils.visualize_semantic_segmentation_2d(semantic_segmentation_2d, ontology, void_class_id=255, image=None, alpha=0.3, debug=False)¶

Constructs a visualization of a semseg frame (either ground truth or predictions), provided an ontology

semantic_segmentation_2d: np.array: Per-pixel class ID’s for a single input image, with void_class_id being the IGNORE class shape: (H, W)
ontology: dgp.proto.ontology_pb2.Ontology: Ontology under which we want to visualize the semseg frame
void_class_id: int, optional: ID in semantic_segmentation_2d that denotes VOID or IGNORE. Default: 255.
image: np.ndarray, optional: If specified then will blend image into visualization with weight alpha. Element type is uint8. Default: None.
alpha: float, optional: If image is specified, then will visualize an image/semseg blend with alpha weight given to image. Default: 0.3.
debug: bool, optional: If True then visualize frame to display. Default: True.

colored_semseg: np.uint8: Visualization of semantic_segmentation_2d frame, in BGR shape: (H, W, 3)

Module contents¶

dgp.utils.tqdm(*args, **kwargs)¶

Quick Links

Table of Contents

Previous topic

Next topic

dgp.utils package¶

Subpackages¶

dgp.utils.accumulate module¶

dgp.utils.annotation module¶

dgp.utils.cache module¶

dgp.utils.camera module¶

dgp.utils.cli_utils module¶

dgp.utils.colors module¶

dgp.utils.dataset_conversion module¶

dgp.utils.datasets module¶

dgp.utils.pose module¶

dgp.utils.protobuf module¶

dgp.utils.statistics module¶

dgp.utils.testing module¶

dgp.utils.visualization_engine module¶

dgp.utils.visualization_utils module¶

Module contents¶