New primitive implementation

[JonasBreuling]

I'm interested in adding a new primitive to the library. Specifically, a deformed cylinder (with arbitrary oriented caps and possibly different radii; i think this is the convex hull of two oriented disks) as depicted in the figure below.

According to support_functions.cpp and geometric_shapes.h this requires to implement

• the support function getShapeSupport
• the support point getShapeSupportSet
• the class definition DeformedCylinder : public ShapeBase

Open questions:

• what else has to be implemented?
• what is cylinder->getSweptSphereRadius(); this is possibly important for a new primitive

If this can be done, I would like to proceed with the convex hull of two oriented rectangles.

[lmontaut]

Hey @JonasBreuling, sorry for the late reply!
I asked Claude (see below) to make a summary of what's needed to fully support a shape in Coal and I agree with it.
I'm adding it to this issue for reference, but you can start by doing only a few things:

• class definition DeformedCylinder : public ShapeBase
• add a new entry in the NODE_TYPE enum (so that internal algos can efficiently dispatch to your shape)
• implement getShapeSupport

If you want to use your shape using coal's collide API:

• add your shape to the collision functions matrix thanks to the new NODE_TYPE entry (you don't have to fill the entire matrix at first, only the pairs you intend to support)
• modify src/narrowphase/minkowski_difference.cpp so that GJK's support calls are properly dispatched on your new shape

If you want support for contact patches (this is often more complicated than implementing the support function):

• implement getShapeSupportSet
• add your shape to the contact patch functions matrix
• modify src/contact_patch/contact_patch_solver.cpp to properly dispatch your new shape's support set function

Let me know if you have more questions.

  Summary: Adding a New Primitive Shape

  1. Define the NODE_TYPE enum entry

  File: include/coal/collision_object.h:64-90

  Add your shape to the NODE_TYPE enum:
  GEOM_YOUR_SHAPE,  // Add before NODE_COUNT

  2. Create the shape class

  File: include/coal/shape/geometric_shapes.h

  Inherit from ShapeBase and implement:
  - Constructor(s)
  - clone() - polymorphic copy
  - computeLocalAABB() - bounding box computation
  - getNodeType() - returns your GEOM_* enum
  - computeVolume() / computeMomentofInertia()
  - minInflationValue() / inflated()
  - isEqual() - equality check

  3. Implement shape methods

  File: src/shape/geometric_shapes.cpp

  Implement computeLocalAABB() and any non-inline methods.

  4. Add GJK support function

  Header: include/coal/narrowphase/support_functions.h
  Implementation: src/narrowphase/support_functions.cpp
  Implementation of GJK shape dispatch: src/narrowphase/minkowski_difference.cpp

  This is the core algorithm piece - computes the support point in a given direction.

  5. Register in dispatch matrices (~63 entries total)

  Each matrix needs entries for your shape vs all other shapes + BVH + HeightField variants:
  

  │ File  │ Pattern │ 
  │ src/collision_func_matrix.cpp │ ShapeShapeCollide<YourShape, OtherShape> │  
  │ src/distance_func_matrix.cpp │ ShapeShapeDistance<YourShape, OtherShape> │
  │ src/contact_patch_func_matrix.cpp │ ShapeShapeContactPatch<YourShape, OtherShape> │

  6. Add serialization

  File: include/coal/serialization/geometric_shapes.h

  template <class Archive>
  void serialize(Archive& ar, coal::YourShape& shape, const unsigned int) {
    ar& make_nvp("base", boost::serialization::base_object<coal::ShapeBase>(shape));
    ar& make_nvp("param", shape.param);
  }
  COAL_SERIALIZATION_DECLARE_EXPORT(::coal::YourShape)

  7. Add Python bindings

  Boost.Python: python/collision-geometries.cc:462-473
  Nanobind: python-nb/shapes.cc:244-252

  Both need constructor bindings, attribute access, clone, pickle, and serialization.

  8. Write tests

  - test/geometric_shapes.cpp - C++ unit tests

[JonasBreuling]

Thank you for the detailed answer. I will give it a try!

[JonasBreuling]

One follow up question. Why Inneed to implement the dispatch matrix entries (63 entries). I thought using GJK circuments this?