fiftyone.utils.utils3d¶

3D utilities.

Copyright 2017-2022, Voxel51, Inc.
voxel51.com

Classes:

OrthographicProjectionMetadata(*args, **kwargs)

Class for storing metadata about orthographic projections.

Functions:

`compute_cuboid_iou`(gt, pred[, gt_crowd])	Computes the IoU between the given ground truth and predicted cuboids.
`compute_orthographic_projection_image`(…[, …])	Generates an orthographic projection image for the given PCD file onto the specified plane (default xy plane).
`compute_orthographic_projection_images`(…)	Computes orthographic projection images for the point clouds in the given collection.

fiftyone.utils.utils3d.compute_cuboid_iou(gt, pred, gt_crowd=False)¶

Computes the IoU between the given ground truth and predicted cuboids.

Parameters

gt – a fiftyone.core.labels.Detection
pred – a fiftyone.core.labels.Detection
gt_crowd (False) – whether the ground truth cuboid is a crowd

Returns

the IoU, in [0, 1]

class fiftyone.utils.utils3d.OrthographicProjectionMetadata(*args, **kwargs)¶

Bases: fiftyone.core.odm.embedded_document.DynamicEmbeddedDocument, fiftyone.core.labels._HasMedia

Class for storing metadata about orthographic projections.

Parameters

filepath (None) – the path to the orthographic projection on disk
min_bound (None) – the [xmin, ymin] of the image in the projection plane
max_bound (None) – the [xmax, ymax] of the image in the projection plane
width – the width of the image, in pixels
height – the height of the image, in pixels

Attributes:

`STRICT`
`field_names`	An ordered tuple of the public fields of this document.
`filepath`	A unicode string field.
`height`	A 32 bit integer field.
`max_bound`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`min_bound`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`width`	A 32 bit integer field.

Methods:

`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, …])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)
`validate`([clean])	Ensure that all fields’ values are valid and that required fields are present.

Classes:

my_metaclass

alias of mongoengine.base.metaclasses.DocumentMetaclass

filepath¶

A unicode string field.

Parameters

description (None) – an optional description
info (None) – an optional info dict

min_bound¶

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict

max_bound¶

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict

width¶

A 32 bit integer field.

Parameters

description (None) – an optional description
info (None) – an optional info dict

height¶

A 32 bit integer field.

Parameters

description (None) – an optional description
info (None) – an optional info dict

STRICT = False¶

clean()¶

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)¶

Clears the field from the document.

Parameters: field_name – the field name
Raises: ValueError – if the field does not exist

copy()¶

Returns a deep copy of the document.

Returns: a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶

Generates a customizable string representation of the document.

Parameters

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns

a string representation of the document

property field_names¶: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)¶

field_to_python(field_name, value)¶

classmethod from_dict(d, extended=False)¶

Loads the document from a BSON/JSON dictionary.

Parameters

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns

a SerializableDocument

classmethod from_json(s)¶

Loads the document from a JSON string.

Returns: a SerializableDocument

get_field(field_name)¶

Gets the field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

get_text_score()¶: Get text score from text query

has_field(field_name)¶

Determines whether the document has a field of the given name.

Parameters: field_name – the field name
Returns: True/False

iter_fields()¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns: an iterator that emits (name, value) tuples

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)¶

Merges the contents of the given document into this document.

Parameters

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass¶

alias of mongoengine.base.metaclasses.DocumentMetaclass Methods:

mro

Return a type’s method resolution order.

set_field(field_name, value, create=True)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises

ValueError – if field_name is not an allowed field name or does not exist and create == False

to_dict(extended=False)¶

Serializes this document to a BSON/JSON dictionary.

Parameters: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns: a dict

to_json(pretty_print=False)¶

Serializes the document to a JSON string.

Parameters: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns: a JSON string

to_mongo(*args, **kwargs)¶

validate(clean=True)¶

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

fiftyone.utils.utils3d.compute_orthographic_projection_images(samples, size, output_dir, rel_dir=None, in_group_slice=None, out_group_slice=None, metadata_field='orthographic_projection_metadata', shading_mode=None, colormap=None, subsampling_rate=None, projection_normal=None, bounds=None)¶

Computes orthographic projection images for the point clouds in the given collection.

This operation will populate OrthographicProjectionMetadata instances for each projection in the metadata_field of each sample.

Examples:

import fiftyone as fo
import fiftyone.utils.utils3d as fou3d
import fiftyone.zoo as foz

dataset = foz.load_zoo_dataset("quickstart-groups")
view = dataset.select_group_slices("pcd")

fou3d.compute_orthographic_projection_images(view, (-1, 512), "/tmp/proj")

session = fo.launch_app(view)

Parameters

samples – a fiftyone.core.collections.SampleCollection
size – the desired (width, height) for the generated maps. Either dimension can be None or negative, in which case the appropriate aspect-preserving value is used
output_dir – an output directory in which to store the images/maps
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier that is joined with output_dir to generate an output path for each image. This argument allows for populating nested subdirectories in output_dir that match the shape of the input paths
in_group_slice (None) – the name of the group slice containing the point cloud data. Only applicable if samples is a grouped collection. If samples is a grouped collection and this parameter is not provided, the first point cloud slice will be used
out_group_slice (None) – the name of a group slice to which to add new samples containing the feature images/maps. Only applicable if samples is a grouped collection
metadata_field ("orthographic_projection_metadata") – the name of the field in which to store OrthographicProjectionMetadata instances for each projection
shading_mode (None) – an optional shading algorithm for the points. Supported values are ("intensity", "rgb", or "height"). The "intensity" and "rgb" options are only valid if the PCD’s header contains the "rgb" flag. By default, all points are shaded white
colormap (None) –
an optional colormap to use when shading gradients, formatted as either:
- a dict mapping values in [0, 1] to (R, G, B) tuples in [0, 255]
- a list of of (R, G, B) tuples in [0, 255] that cover [0, 1] linearly spaced
subsampling_rate (None) – an optional unsigned int that, if provided, defines a uniform subsampling rate. The selected point indices are [0, k, 2k, …], where k = subsampling_rate
projection_normal (None) – the normal vector of the plane onto which to perform the projection. By default, (0, 0, 1) is used
bounds (None) – an optional ((xmin, ymin, zmin), (xmax, ymax, zmax)) tuple defining the field of view in the projected plane for which to generate each map. Either element of the tuple or any/all of its values can be None, in which case a tight crop of the point cloud along the missing dimension(s) are used

fiftyone.utils.utils3d.compute_orthographic_projection_image(filepath, size, shading_mode=None, colormap=None, subsampling_rate=None, projection_normal=None, bounds=None)¶

Generates an orthographic projection image for the given PCD file onto the specified plane (default xy plane).

The returned image is a three-channel array encoding the intensity, height, and density of the point cloud.

Parameters

filepath – the path to the .pcd file
size – the desired (width, height) for the generated maps. Either dimension can be None or negative, in which case the appropriate aspect-preserving value is used
shading_mode (None) – an optional shading algorithm for the points. Supported values are ("intensity", "rgb", or "height"). The "intensity" and "rgb" options are only valid if the PCD’s header contains the "rgb" flag. By default, all points are shaded white
colormap (None) –
an optional colormap to use when shading gradients, formatted as either:
- a dict mapping values in [0, 1] to (R, G, B) tuples in [0, 255]
- a list of of (R, G, B) tuples in [0, 255] that cover [0, 1] linearly spaced
subsampling_rate (None) – an unsigned int that, if defined, defines a uniform subsampling rate. The selected point indices are [0, k, 2k, …], where k = subsampling_rate
projection_normal (None) – the normal vector of the plane onto which to perform the projection. By default, (0, 0, 1) is used
bounds (None) – an optional ((xmin, ymin, zmin), (xmax, ymax, zmax)) tuple defining the field of view for which to generate each map in the projected plane. Either element of the tuple or any/all of its values can be None, in which case a tight crop of the point cloud along the missing dimension(s) are used

Returns

a tuple of

the orthographic projection image
an OrthographicProjectionMetadata instance