The household_objects SQL database
This page documents the household_objects SQL database. It refers strictly to the database itself, as a SQL entity. For documentation of its ROS wrapper and usage inside of ROS, see the household_objects_database package.
Overview
Models
One of the guiding principles for building this database was to enable other researchers to replicate our physical experiments, and build on our results. The database was constructed using physical objects that are generally available from major retailers (while this current release is biased towards U.S.-based retailers, we hope that a future release can include international ones as well). The objects were divided into three categories: for the first two categories, all objects were obtained from a single retailer (IKEA and Target, respectively), while the third category contained a set of household objects commonly available in most retail stores. Most objects were chosen to be naturally graspable using a single hand (e.g. glasses, bowls, cans, etc.); a few were chosen as use cases for two-hand manipulation problems (e.g. power drills).
For each object, we acquired a 3D model of its surface (as a triangular mesh). To the best of our knowledge, no off-the-shelf tool exists that can be used to acquire such models for a large set of objects in a cost- and time-effective way. To perform the task, we used two different methods, each with its own advantages and limitations:
- for those objects that can be described as surfaces of rotation, we segmented a silhouette of the object against a known background, and used rotational symmetry to generate a complete mesh. This method can generate high-resolution, very precise models, but is only applicable to rotationally symmetrical objects.
for all other objects, we used the commercially available tool 3DSOM (Creative Dimension Software Ltd., U.K.). 3DSOM builds a model from multiple object silhouettes, and can not resolve object concavities and indentations.
In the current release of the database, one of the goals was that each database entry should correspond to a real, physical world objects. However, that is not always necessary. In general, by scaling a given 3D model, it is often possible to obtain a different model eliciting different grasps (since grasping is inherently scaled-dependent). To allow for this possibility in the future, all grasps in the database are computed on scaled_models, which are scaled versions of the original models. The current release only contains scaled models with a scale of 1.0, so there is a one-to-one relationship between original and scaled models.
The 3D geometry of each object is explicitly stored in the database. However, we have also allowed for the possibility of using external data files to hold data (such as the geometry in different formats, thumbnails, etc). The database allows for the possibility of storing an arbitrary number of links to files for each object. Obviously, in order to use this feature, you would need the relevant files as well as the database itself.
Grasps
For each object in the database, we used the GraspIt! simulator to compute a large number of grasp points for the PR2 gripper. We note that, in our current release, the definition of a good grasp is specific to this gripper, requiring both finger pads to be aligned with the surface of the object and further rewarding postures where the palm of the gripper is close to the object as well. We hope that future releases will also include grasp information for some of the robotic hands most commonly used in the research community.
Schema
These are the details of the database schema, organized by table, in roughly descending order of importance. All table fields are prefaced by the name of the table, except for those that act as foreign keys.
original_model
original_model_id (integer, primary key): the unique identifier of an original model in the database. Can be generated automatically upon insertion based on a sequence.
original_model_maker (text): the maker of that object, where available (e.g. IKEA, Coca-Cola, Pantene, etc.)
original_model_model (text): the model of that object (e.g. some_type_of_shampoo). The combination of original_model_model and original_model_maker is unique.
original_model_source (text): where we got the object from. Can have one of three values:
- IKEA (self-explanatory)
- Target (self-explanatory)
- household (a common household object that can be found in most retail stores)
original_model_description (text): a human-readable description of the object (never used in any of our algorithms, meant to help with database maintenance and locating the physical objects)
original_model_barcode (text): the barcode of the object (where available)
acquisition_method_name (text): the acquisition method used for building a 3D model of this object (see above). One of two values:
- orthographic
- 3dsom
scaled_model
scaled_model_id (int, primary key): a unique identifier for a scaled model, which is what all grasps in the database reference.
original_model_id (int): the original model that this scaled model references.
scaled_model_scale (double): the scaling factor (see above). Currently, the database only contains scaled models at scale 1.
mesh (holds the 3D object surface models)
original_model_id (int): the original model that this mesh is for
mesh_vertex_list (binary): the list of vertices of the mesh. A bitwise copy of a std::vector<sensor_msgs::Point3d> containing the vertices. The C++ and ROS wrappers for the database contain convenient functions for retrieving this data.
mesh_triangle_list (binary): the list of triangles of the mesh. A bitwise copy of a std::vector<int> containing the indexed triangles. The C++ and ROS wrappers for the database contain convenient functions for retrieving this data.
grasp
grasp_id (int): a unique identifier for each grasp
scaled_model_id (int): the scaled model that this grasp is for
hand_name (text): the hand for which this grasp was computed
grasp_energy (double): a measure of the quality of the grasp. Lower numbers indicate better grasps.
grasp_pregrasp_joints (double[]): a vector of doubles defining the hand posture for the pregrasp, with one value for each DOF of the hand
grasp_grasp_joints (double[]): a vector of doubles defining the hand posture for the final grasp, with one value for each DOF of the hand
grasp_pregrasp_position (double[]): a transform defining the position of the hand relative to the object for the pregrasp. Transforms are specified as [translation,quaternion], in the format [tx,ty,tz,qw,qx,qy,qz]
grasp_grasp_position (double[]): a transform defining the position of the hand relative to the object for the final grasp. Transforms are specified as [translation,quaternion], in the format [tx,ty,tz,qw,qx,qy,qz]
grasp_cluster_rep (bool): whether this grasp is considered representative for a larger set of grasps concentrated around the same area of the object. Used to prune down a large list of grasps to a smaller set of "cluster representatives" which span most of the surface of the object.
file_path (stores paths to miscellaneous files that can be associated with objects)
original_model_id (int): the model that this file is for
file_path_path (text): the path to the file, usually relative to MODEL_ROOT (see below)
file_type (text): the type of file (e.g. GEOMETRY_BINARY_X3D, THUMBNAIL_BINARY_PNG, etc)
model_set (used for defining subsets of objects to be used for particular experiments when you do not want to use all the objects in the database). The database comes with two such sets defined: REDUCED_EXPERIMENT_SET (containing 16 models) and DEBUG_EXPERIMENT_SET (containing 4 models)
model_set_name (text): a name associated with a model set
original_model_id (int): the id of an original model that is a member of that set.
variable (used for storing misc. variables). This is also used to store the MODEL_ROOT variable, used to define a base path that all paths in the file_path table are relative to.
variable_name (text): the name of the variable
variable_value (text): the value of the variable