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
ofHdf5Dataset
– 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
ofstr
) – keys of the objects to add to the dataset
Returns: the created dataset
Return type: - dataset_name (
-
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 datasetReturns: 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
- metadata_name (
-
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
ofstr
- key (
-
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
ofstr
) – 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
- key (
-
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 objectReturns: :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 forReturns: list of convex pieces of object, or None if they do not exist Return type: list
ofMesh3D
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
ofStablePose
) – stable poses of the object - mass (float) – mass of the object in kilograms
Raises: ValueError
– If the key is already in the dataset- key (
-
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
- metadata_name (
-
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
- metric_name (
-
delete_convex_pieces
(key)¶ Delete convex pieces for an object from the dataset.
Parameters: key ( str
) – name of the object to delete pieces forReturns: 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 deleteReturns: 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
- key (
-
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
- key (
-
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
ofdict
- key (
-
graspable
(key)¶ Read in the GraspableObject3D corresponding to given key.
Parameters: key ( str
) – the string key of the object to indexReturns: 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: - key (
-
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
- key (
-
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
- key (
-
mesh
(key)¶ Read the mesh for the given key.
Parameters: key ( str
) – key of object to read mesh forReturns: 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
ofstr
– Names of available metadata
-
metric
(metric_name)¶ Reads a metric config from the database.
Parameters: metric_name ( str
) – name of the metric to readReturns: configuration of grasp metric, None if metric does not exist Return type: GraspQualityConfig
-
metric_names
¶ list
ofstr
– 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
- key (
-
object
(key)¶ h5py.Group
: Data for objects in the dataset
-
object_keys
¶ list
ofstr
– 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
ofstr
) –
Returns: dictionary mapping metadata names to numeric/numpy list values
Return type: dict
- key (
-
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
ofstr
- key (
-
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
ofperception.ObjectRender
- key (
-
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
ofdexnet.grasping.ParallelJawPtGrasp3D
– stored grasps for the object and gripper sorted by metric in descending order, empty list if gripper not foundlist
of float – values of metrics for the grasps sorted in descending order, empty list if gripper not found
- key (
-
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- key (
-
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
ofStablePose
- key (
-
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
- key (
-
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
ofMesh3D
) – 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
- key (
-
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
ofmeshpy.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
- key (
-
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
mappingint
todict
mappingstr
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
- key (
-
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
- key (
-
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
- key (
-
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
mappingstr
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
- key (
-
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
ofObjectRender
: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: boolReturns: 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
ofmeshpy.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
- key (
-
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: - start_index (
-
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
- key (
-
-
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
-
static
-
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
- filename (
-
class
dexnet.database.
RescalingType
¶ Enum to specify different rules for rescaling meshes