/object2urdf

Manage a library of objects for use in pybullet physics

Primary LanguagePython

object2urdf

Manage a library of objects for use in pybullet physics

Installation

Install the release version

This package is available on pypi, so anyone can install it with pip: pip install object2urdf

Install the most-recent development version

  1. Clone the package from the github repo
  2. Navigate into the main folder
  3. pip install .

Usage

Set up YCB objects

  1. Download the 16k laser scan from the YCB Benchmarks website.
  2. Unzip the folder. You'll now be able to find several files, some of which we use
    • Files named textured include both object geometry and texture maps.
    • Files named nontextured include only object geometry.
  3. Notes:
    • All of these object files are in units of meters.

Set up custom objects

  1. Make your object in CAD or a 3D modeling software, and export it as either an .OBJ or .STL file.
    • .OBJ files can be rendered with a texture (using an .MTL file) and collisions with convex objects can be handled correctly (this utillity to handles that).
    • .STL files can only be rendered without textures, and the collision boundary will only be the convex hull of the object. (This is due to the limitations of the Bullet physics engine)
  2. Set up your file structure
    • Each object set needs its own directory.
    • Inside your directory for the object set, create a subdirectory for each new object. The subdirectory name will be used as the object name.
  3. Place all of the relevant geometry and texture files into that subdirectory. Filenames must all match, with correct file extensions
    • Supported geometry must be either an .OBJ or .STL file.
    • Textures can be added to .OBJ files using an accompanying .MTL file. Linking to this is handled within the .OBJ file.
    • .MTL files usually refer to an image texture (jpg or png) that gets mapped onto the object.

Auto-generate URDFs

  1. Set up your file structure per the instructions for custom objects above.
    • Each object set directory must have its own _prototype.urdf template file. This is where default units, colors, and masses are adjusted.
    • If objects are buried in sub-subdirectories within each object's directory, this utility will still find them. However, only one URDF is generated from each object directory.
    • Geometry must be generated from a .OBJ or .STL file, with .OBJ taking priority if multiple are found in the same folder
    • (optional) Add object-specific overrides to a .OVR file in the same folder. Filenames must all match
      • This can be things like the object's mass, orientations, etc.
      • This file should be an XML similar to the file in the fancy_cube >> holder example.
  2. Use the package to automatically generate URDFs for your object library.
    • Start with the "build_object_library.py" example.
    • This example will place all URDFs into their respective object set directories, but you can change the output location by passing the output_folder argument to build_urdf or build_library
    • Due to limitations of Bullet's rigid body collision detection, concave objects must be split into several convex objects using a convex decomposition. You can do this with the ObjectUrdfBuilder class by passing decompose_concave=True to the build_urdf or build_library functions. The URDF builder will then generate a decomposed file, place it next to the original object file, and link to it as the collision geometry in the object's URDF.
    • Set the center of mass of the object via a variety of options:
      • By default, this package uses trimesh to calculate the center of mass of objects from thier geometry.
      • To turn this behavior off and use the URDF or ORV files, pass center = None to the build_urdf or build_library functions
      • You can also use the geometric center (centroid) of the model with center = 'geometric'
      • You can also use faces of the bounding box: set center equal to one of the following: 'top', 'bottom', 'xy_pos', 'xy_neg', 'xz_pos', 'xz_neg', 'yz_pos', 'yz_neg'

Use objects in simulation

Just import the object's URDF:

object_urdf = "fancy_cube/small_holder.urdf"
boxStartPos = [0, 0, 0.5]
boxStartOr = p.getQuaternionFromEuler(np.deg2rad([0, 0, 0]))
boxId = p.loadURDF(object_urdf, boxStartPos, boxStartOr)