database

Classes for access and storage of 3D models, images, grasps, and grasp quality metrics from Dex-Net.

class dexnet.database.Database(access_level=’READ_ONLY’)

Abstract class for Dex-Net databases. Main purpose is to wrap individual datasets.

access_level

str – level of access, READ_ONLY versus READ_WRITE versus WRITE, for the database

class dexnet.database.Hdf5Database(database_filename, access_level=’READ_ONLY’, cache_dir=’.dexnet’)

Wrapper for HDF5 databases with h5py.

database_filename

str – filenaame of HDF5 database, must have extension .hdf5

access_level

str – level of access, READ_ONLY versus READ_WRITE versus WRITE, for the database

cache_dir

str – directory to cache files used by the database wrapper class

datasets

list of Hdf5Dataset – datasets contained in this database

close()

Close the HDF5 file

create_dataset(dataset_name, obj_keys=[])

Create dataset with obj keys and add to the database.

Parameters:
  • dataset_name (str) – name of dataset to create
  • obj_keys (list of str) – keys of the objects to add to the dataset
Returns:

the created dataset

Return type:

Hdf5Dataset

create_linked_dataset(dataset_name, graspable_list, nearest_neighbors)

Creates a new dataset that links to objects physically stored as part of another dataset. Not currently implemented

dataset(dataset_name)

Returns handles to individual Hdf5 datasets.

Parameters:dataset_name (str) – string name of the dataset
Returns:dataset wrapper for the given name, if it exists, None otherwise
Return type:obj Hdf5Dataset
flush()

Flushes the file

class dexnet.database.Dataset

Abstract class for different dataset implementations. Only Hdf5 is currently supported

class dexnet.database.Hdf5Dataset(dataset_name, data, cache_dir=None, start_index=0, end_index=None)

Wrapper for HDF5 datasets with h5py.

dataset_name

str – fname of the dataset

data

h5py.Group – Hdf5 group corresponding to the data

cache_dir

str – directory to cache files used by the dataset

start_index

int – initial object index to use for iteration

end_index

int – final object index to use for iteration

attach_metadata_func(metadata_name, metadata_func, overwrite=False, store_func=True)

Attach a function that computes a given metadata from a Mesh3D object

Parameters:
  • metadata_name (str) – name of metadata type to attach function to
  • metadata_func (function) – function that computes metric from Mesh3D object. Must return type consistent with what was set in create_metadata Note that for manually set metadata you can attach an object that isn’t a function
  • overwrite (boolean) – if True, overwrites existing metadata function
  • store_func (boolean) – if True, attempts to use dill to serialize the function and store it in the database for later use.
Returns:

True if succesful, False otherwise

Return type:

bool

available_metrics(key, gripper=’pr2’)

Returns a list of the metrics computed for a given object.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
Returns:

list of names of metric computed and stored for the object

Return type:

list of str

compute_object_metadata(key, metadata_names=None, force_overwrite=False)

Computes and stores metadata for object and metadata type(s) specified

Parameters:
  • key (str) – key of object to store metadata for
  • metadata_name (list of str) – Name of metadata types to compute. if None computes all
  • force_overwrite (bool) – whether or not to overwrite existing metadata with the same name
Returns:

True if successful, False if aborted due to existing data

Return type:

bool

connected_components(key)

Returns a dict of the connected components of the given mesh. Returns None if connected components are unavailable.

Parameters:key (str) – key of object
Returns::obj:`dict` mapping :obj:`str` to – dict of connected components of the mesh. Keys are there for indexing.
Return type:obj:`Mesh3D
convex_pieces(key)

Read the set of convex pieces for the given key, if they exist.

Parameters:key (str) – key of object to read convex pieces for
Returns:list of convex pieces of object, or None if they do not exist
Return type:list of Mesh3D
Raises:ValueError : If the key is not in the dataset
create_graspable(key, mesh=None, sdf=None, stable_poses=None, mass=1.0)

Creates a graspable object in the given dataset

Parameters:
  • key (str) – name of the object, for indexing
  • mesh (Mesh3D) – mesh for object geometry
  • sdf (Sdf3D) – signed distance field for object contact computations
  • stable_poses (list of StablePose) – stable poses of the object
  • mass (float) – mass of the object in kilograms
Raises:

ValueError – If the key is already in the dataset

create_metadata(metadata_name, metadata_type, metadata_description=’No description’)

Creates an object metadata with the given name for easier access.

Parameters:
  • metadata_name (str) – name of new metadata type
  • metadata_type (str) –
    type of metadata. Must be {‘scalar’, ‘array’}.
    primitive: anything that can be a non-object numpy scalar array: numpy array with non-object dtype
  • metadata_description (str) – Description (helptext) for metadata. Optional
Returns:

True if creation was successful, False otherwise

Return type:

bool

create_metric(metric_name, metric_config)

Creates a grasp quality metric with the given name for easier access.

Parameters:
  • metric_name (str) – name of new grasp quality metric
  • metric_config (GraspQualityConfig) – configuration specifying parameters of a given metric
Returns:

True if creation was successful, False otherwise

Return type:

bool

delete_convex_pieces(key)

Delete convex pieces for an object from the dataset.

Parameters:key (str) – name of the object to delete pieces for
Returns:True if object deleted, False otherwise
Return type:bool
delete_graspable(key)

Delete a graspable from the dataset.

Parameters:key (str) – name of the object to delete
Returns:True if object deleted, False otherwise
Return type:bool
delete_grasps(key, gripper=’pr2’, stable_pose_id=None)

Deletes a set of grasps associated with the given gripper.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
Returns:

True if grasps were deleted for the given object and gripper, False otherwise

Return type:

bool

delete_metadata(metadata_name)

Deletes a metadata type from the database.

Parameters:metadata_name (str) – name of metadata to delete
delete_metric(metric_name)

Deletes a metric from the database.

Parameters:metric_name (str) – name of metric to delete
delete_rendered_images(key, stable_pose_id=None, render_mode=’depth’)

Delete previously rendered images.

Parameters:
  • key (str) – key of object
  • stable_pose_id (str) – id of stable pose to index images for
  • render_mode (perception.RenderMode) – modality of images to index (e.g. depth or segmask)
Returns:

whether or not the images were deleted

Return type:

bool

get_metadata_desc(metadata_name)

Returns description for metadata type

Parameters:metadata_name (str) – Name of metadata to return description for
get_metadata_types()

Returns a dictionary mapping metadata names to metadata types

grasp_metric(key, grasp, metric_name, gripper, stable_pose_id=None)

Return a single grasp metric, computing and storing if necessary. Not yet implemented.

grasp_metrics(key, grasps, gripper=’pr2’, stable_pose_id=None)

Returns a list of grasp metric dictionaries fot the list of grasps provided to the database.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
Returns:

dictionary mapping grasp ids to dictionaries that map metric names to numeric values

Return type:

list of dict

graspable(key)

Read in the GraspableObject3D corresponding to given key.

Parameters:key (str) – the string key of the object to index
Returns:the graspable object corresponding to the given key
Return type:GraspableObject3D
Raises:ValueError – If the key is not found in the dataset
grasps(key, gripper=’pr2’, stable_pose_id=None)

Returns the list of grasps for the given graspable and gripper, optionally associated with the given stable pose.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
Returns:

stored grasps for the object and gripper, empty list if gripper not found

Return type:

list of dexnet.grasping.ParallelJawPtGrasp3D

has_grasps(key, gripper=’pr2’, stable_pose_id=None)

Checks if grasps exist for a given object.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
Returns:

True if dataset contains grasps for the given object and gripper, False otherwise

Return type:

bool

has_metadata(metadata_name)

Checks if a metadata type already exists

has_metric(metric_name)

Checks if a metric already exists

has_rendered_images(key, stable_pose_id=None, render_mode=’depth’)

Checks whether or not a graspable has rendered images for the given stable pose and image type.

Parameters:
  • key (str) – key of object
  • stable_pose_id (str) – id of stable pose to index images for
  • render_mode (perception.RenderMode) – modality of images to index (e.g. depth or segmask)
Returns:

whether or not the dataset has images for the given pose and modality

Return type:

bool

mesh(key)

Read the mesh for the given key.

Parameters:key (str) – key of object to read mesh for
Returns:mesh of object
Return type:Mesh3D
Raises:ValueError : If the key is not in the dataset
metadata

h5py.Group – Types and optional descriptions/functions for metadata in the dataset

metadata_func(metadata_name)

Returns function associated with metadata

metadata_names

list of str – Names of available metadata

metric(metric_name)

Reads a metric config from the database.

Parameters:metric_name (str) – name of the metric to read
Returns:configuration of grasp metric, None if metric does not exist
Return type:GraspQualityConfig
metric_names

list of str – Names of aviailable metrics

metrics

h5py.Group – Data for available metrics in the dataset

name

str – Name of the dataset

next()

Read the next object file in the list.

Returns:the next graspable object in the iteration
Return type:GraspableObject3D
num_objects

int – number of objects in the dataset.

obj_mesh_filename(key, scale=1.0, output_dir=None, overwrite=False)

Writes an obj file in the database “cache” directory and returns the path to the file. Does not overwrite existing files by default. Typically used for integration with other libraries that require mesh files as .obj.

Parameters:
  • key (str) – key of object to write mesh for
  • scale (float) – optional rescaling factor
  • output_dir (str) – directory to save to, if None saves to cache dir
  • overwrite (bool) – whether or not to overwrite an existing file with the same name
Returns:

filename of .obj file

Return type:

str

object(key)

h5py.Group : Data for objects in the dataset

object_keys

list of str – Names of all objects in the dataset.

object_metadata(key)

Returns a dictionary of object metadata for the object

Parameters:
  • key (str) – key of object to check metadata for
  • metadata_type (list of str) –
Returns:

dictionary mapping metadata names to numeric/numpy list values

Return type:

dict

objects

h5py.Group – Data containing handles of objects. Acts like a dictionary mapping object keys to object data.

rendered_image_types(key, stable_pose_id=None)

Return a list of the available rendered image modalities.

Parameters:
  • key (str) – key of object
  • stable_pose_id (str) – id of stable pose to index images for
Returns:

list of available rendered image modes

Return type:

list of str

rendered_images(key, stable_pose_id=None, render_mode=’depth’)

Rendered images for the given object for the given render mode.

Parameters:
  • key (str) – key of object
  • stable_pose_id (str) – id of stable pose to index images for
  • render_mode (perception.RenderMode) – modality of images to index (e.g. depth or segmask)
Returns:

list of stored images for the given object

Return type:

list of perception.ObjectRender

sorted_grasps(key, metric, gripper=’pr2’, stable_pose_id=None)

Returns the list of grasps for the given graspable sorted by decreasing quality according to the given metric.

Parameters:
  • key (str) – key of object to check metrics for
  • metric (str) – name of metric to use for sorting
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
Returns:

  • list of dexnet.grasping.ParallelJawPtGrasp3D – stored grasps for the object and gripper sorted by metric in descending order, empty list if gripper not found
  • list of float – values of metrics for the grasps sorted in descending order, empty list if gripper not found

stable_pose(key, stable_pose_id)

Stable pose of stable pose id for object key

Parameters:
  • key (str) – key of object
  • stable_pose_id (obj:str) – id of stable pose to index
Returns:

requested stable pose

Return type:

StablePose

Raises:

ValueError – If stable pose id is unrecognized

stable_poses(key, min_p=0.0)

Stable poses for object key.

Parameters:
  • key (str) – key of object
  • min_p (float) – min stable pose probability to return
Returns:

list of stable poses for the given object

Return type:

list of StablePose

stl_mesh_filename(key, scale=1.0, output_dir=None, overwrite=False)

Writes an stl file in the database “cache” directory and returns the path to the file. Does not overwrite existing files by default. Typically used for integration with other libraries that require mesh files as .obj.

Parameters:
  • key (str) – key of object to write mesh for
  • scale (float) – optional rescaling factor
  • output_dir (str) – directory to save to, if None saves to cache dir
  • overwrite (bool) – whether or not to overwrite an existing file with the same name
Returns:

filename of .stl file

Return type:

str

store_connected_components(key, connected_components, force_overwrite=False)

Store the connected components of the mesh

Parameters:
  • key (str) – key of object
  • connected_components (list of Mesh3D) – connected components to write
  • force_overwrite (bool) – True if existing connected components should be overwritten
Returns:

whether or not the connected components were written

Return type:

bool

store_convex_pieces(key, convex_pieces, force_overwrite=False)

Associates convex pieces with the given object.

Parameters:
  • key (str) – key of object
  • convex_pieces (list of meshpy.Mesh3D) – convex pieces to store
  • force_overwrite (bool) – whether or not to overwrite convex pieces
Returns:

True if convex pieces were stored for the given object, False otherwise

Return type:

bool

store_grasp_metrics(key, grasp_metric_dict, gripper=’pr2’, stable_pose_id=None, force_overwrite=False)

Add grasp metrics in grasp_metric_dict to the data associated with grasps.

Parameters:
  • key (str) – key of object to store metrics for
  • grasp_metric_dict (dict mapping int to dict mapping str to float) – mapping from grasp ids to a dictionary mapping metric names to numeric values
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
  • force_overwrite (bool) – whether or not to overwrite existing metrics with the same name
Returns:

True if succcessful, False if aborted due to existing data

Return type:

bool

store_grasps(key, grasps, gripper=’pr2’, stable_pose_id=None, force_overwrite=False)

Associates grasps in list grasps with the given object. Optionally associates the grasps with a single stable pose.

Parameters:
  • key (str) – key of object to check metrics for
  • gripper (str) – name of gripper
  • stable_pose_id (str) – id of stable pose
  • force_overwrite (bool) – whether or not to overwrite grasps with the same id
Returns:

True if grasps were stored for the given object and gripper, False otherwise

Return type:

bool

store_mesh(key, mesh, force_overwrite=False)

Associates a mesh with the given object.

Parameters:
  • key (str) – key of object
  • mesh (meshpy.Mesh3D) – mesh to store
  • force_overwrite (bool) – whether or not to overwrite
Returns:

True if mesh stored for the given object, False otherwise

Return type:

bool

store_object_metadata(key, metadata_dict, force_overwrite=False)

Manually write metadata

Parameters:
  • key (str) – key of object to store metadata for
  • metadata_dict (dict mapping str to primatives/np arrays) – Dictionary of metadata to write. Maps metadata name to the metadata
  • force_overwrite (bool) – whether or not to overwrite existing metadata with the same name
Returns:

True if successful, False if aborted due to existing data

Return type:

bool

store_rendered_images(key, rendered_images, stable_pose_id=None, render_mode=’depth’, force_overwrite=False)

Store rendered images of the object for a given stable pose. :param key: key of object :type key: str :param rendered_images: list of images rendered for the given object :type rendered_images: list of ObjectRender :param stable_pose_id: id of stable pose to index images for :type stable_pose_id: obj:str :param render_mode: modality of images to index (e.g. depth or segmask) :type render_mode: perception.RenderMode :param force_overwrite: True if existing images should be overwritten :type force_overwrite: bool

Returns:whether or not the images were written
Return type:bool
store_stable_poses(key, stable_poses, force_overwrite=False)

Associates stable poses with the given object.

Parameters:
  • key (str) – key of object
  • stable_poses (list of meshpy.StablePose) – stable poses to store
  • force_overwrite (bool) – whether or not to overwrite stable poses
Returns:

True if grasps were stored for the given object, False otherwise

Return type:

bool

subset(start_index, end_index)

Returns a subset of the dataset (should be used for iterating only)

Parameters:
  • start_index (int) – index of first object key in subset
  • end_index (int) – index of last object key in subset
Returns:

Dataset containing only the specified subset

Return type:

Hdf5Dataset

urdf_mesh_filename(key, output_dir=None, overwrite=True)

Writes a urd file in the database “cache” directory and returns the path to the file. Overwrites existing files by default. Typically used for integration with other libraries that require mesh files as .obj.

Parameters:
  • key (str) – key of object to write mesh for
  • scale (float) – optional rescaling factor
  • output_dir (str) – directory to save to, if None saves to cache dir
  • overwrite (bool) – whether or not to overwrite an existing file with the same name
Returns:

filename of .urdf file

Return type:

str

class dexnet.database.Hdf5ObjectFactory

Functions for reading and writing new objects from HDF5 fields. Should not be called directly.

static connected_components(data)

Returns a dict of all connected components in the object

static grasp_metrics(grasps, data)

Returns a dictionary of the metrics for the given grasps

static grasps(data)

Return a list of grasp objects from the data provided in the HDF5 dictionary

static mesh_3d(data)

Converts HDF5 data provided in dictionary data to a mesh object

static object_metadata(data, metadata_types)

Returns a dictionary of the metadata for the given object

static sdf_3d(data)

Converts HDF5 data provided in dictionary data to an SDF object

static stable_pose(data, stable_pose_id)

Read out a stable pose object

static stable_poses(data)

Read out a list of stable pose objects

static write_connected_components(connected_components, data, force_overwrite=False)

Writes a list of connected components

static write_grasp_metrics(grasp_metric_dict, data, force_overwrite=False)

Write grasp metrics to database

static write_grasps(grasps, data, force_overwrite=False)

Writes grasps to HDF5 data provided in data

static write_mesh_3d(mesh, data)

Writes mesh object to HDF5 data provided in data

static write_object_metadata(metadata_dict, data, metadata_types, force_overwrite=False)

Writes metadata to HDF5 group for object

static write_rendered_images(rendered_images, data, force_overwrite=False)

Write rendered images to database

static write_sdf_3d(sdf, data)

Writes sdf object to HDF5 data provided in data

static write_stable_poses(stable_poses, data, force_overwrite=False)

Writes stable poses to HDF5 data provided in data

class dexnet.database.MeshProcessor(filename, cache_dir)

Preprocessing of mesh files into graspable objects for planning with Dex-Net.

Parameters:
  • filename (str) – name of the mesh file to process
  • cache_dir (str) – directory to store intermediate files to
generate_graspable(config)

Generates a graspable object based on the given configuration.

Parameters:config (dict) – dictionary containing values for preprocessing parameters (preprocessing meshlab script, object density, object scale, object rescaling type, path to the SDFGen binary, the dimension of the sdf grid, the amount of sdf padding to use, and the min probability of stable poses to prune)

Notes

Required configuration key-value pairs in Other Parameters.

Other Parameters:
 
  • obj_density (float) – density of object
  • obj_scale (float) – scale of object
  • path_to_sdfgen (str) – path to the SDFGen binary
  • sdf_dim (int) – dimensions of signed distance field grid
  • sdf_padding (int) – how much to pad the boundary of the sdf grid
  • stp_min_prob (float) – minimum probability for stored stable poses
class dexnet.database.RescalingType

Enum to specify different rules for rescaling meshes