{
  "name": "BaseContactMapper",
  "main": {
    "name": "BaseContactMapper",
    "namespace": "sofa::component::collision::response::mapper",
    "module": "Sofa.Component.Collision.Response.Mapper",
    "include": "sofa/component/collision/response/mapper/BaseContactMapper.h",
    "doc": "Base class common to all mappers able to provide a MechanicalState of a given type",
    "inherits": [],
    "templates": [
      "sofa::defaulttype::Rigid3Types",
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "createMapping",
        "return_type": "MMechanicalState *",
        "params": [
          {
            "name": "name",
            "type": "const char *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "cleanup",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resize",
        "return_type": "void",
        "params": [
          {
            "name": "size",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addPoint",
        "return_type": "int",
        "params": [
          {
            "name": "",
            "type": "const Coord &"
          },
          {
            "name": "",
            "type": "int"
          },
          {
            "name": "",
            "type": "Real &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addPointB",
        "return_type": "int",
        "params": [
          {
            "name": "P",
            "type": "const Coord &"
          },
          {
            "name": "elementId",
            "type": "int"
          },
          {
            "name": "r",
            "type": "Real &"
          },
          {
            "name": "",
            "type": "const sofa::type::Vec3 &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addPointB",
        "return_type": "int",
        "params": [
          {
            "name": "P",
            "type": "const Coord &"
          },
          {
            "name": "elementId",
            "type": "int"
          },
          {
            "name": "r",
            "type": "Real &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "update",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateXfree",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "Create",
        "return_type": "BaseContactMapper<DataTypes> *",
        "params": [
          {
            "name": "model",
            "type": "core::CollisionModel *"
          },
          {
            "name": "name",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `BaseContactMapper` is an abstract class in the SOFA framework, specifically designed to handle contact mappings between collision models and mechanical states. It serves as a base for specialized mappers that can provide a MechanicalState of a given type, typically used in collision response mechanisms.\n\n### Role and Purpose\n- **Role**: `BaseContactMapper` acts as an interface for creating specific types of mappers that translate contact information (such as points of intersection) into mechanical states. This is crucial for handling forces and constraints arising from collisions between objects in simulations.\n- **Purpose**: It ensures a consistent way to handle the mapping of collision data, which can vary depending on the nature of the collision model and its associated mechanical properties.\n\n### Interactions with Other Components\n- **Collision Models**: `BaseContactMapper` interacts closely with `core::CollisionModel`, as it requires instances of these models for initialization. This interaction facilitates the translation between detected collisions and their corresponding mechanical responses.\n- **Mechanical States**: It provides a MechanicalState (`MMechanicalState`) that represents how collision forces are applied to objects in the simulation, typically by implementing methods like `createMapping` and `updateXfree`. \n\n### Practical Usage Guidance\n- **Templating**: The class is templated over types such as `sofa::defaulttype::Vec3Types` and `sofa::defaulttype::Rigid3Types`, allowing flexibility in handling different data representations.\n- **Virtual Methods**: Key methods like `createMapping`, `cleanup`, `resize`, `addPoint`, and `updateXfree` are pure virtual, meaning any derived class must implement these to ensure proper functionality. \n\n### Data Fields\n- The provided metadata does not list explicit data fields for `BaseContactMapper`. This implies that the specific implementations (specialized mappers) will define their own set of attributes and methods as needed."
  },
  "maths": {
    "maths": "The `BaseContactMapper` is an abstract class in the SOFA framework designed to handle contact mappings between collision models and mechanical states. Its primary role is to translate detected collisions into mechanical forces and constraints, ensuring a consistent interface for different types of collision models and their associated mechanical properties.\n\n### Mathematical and Physical Description\n\n1. **Mechanical State Representation**:\n   - The `BaseContactMapper` class provides an abstract interface for creating a MechanicalState (`MMechanicalState`) that represents how collision forces are applied to objects in the simulation. This involves methods such as `createMapping`, which generates the mechanical state based on detected contact points.\n\n2. **Collision Handling**:\n   - The class interacts with `core::CollisionModel` instances, allowing it to translate detected collisions into mechanical responses. Specifically, it handles point-to-point or surface-to-surface contacts by adding these points to a mapping and updating the mechanical state accordingly.\n   - Methods like `addPoint(const Coord& P, Index elementId, Real& r)` and `addPointB(const Coord& P, Index elementId, Real& r, const sofa::type::Vec3& baryP)` are used to add detected contact points to the mapping. The `baryP` parameter is used when dealing with local coordinate systems.\n\n3. **Interface Methods**:\n   - **createMapping(const char* name)**: Creates a mechanical state for handling collision forces. This method must be implemented by derived classes, ensuring that the specific mechanics of force application are handled correctly.\n   - **cleanup()**: Cleans up any resources used by the mapper, typically called when the simulation is stopping or transitioning to another phase.\n   - **resize(Size size)**: Resizes internal data structures based on the number of contact points. This ensures efficient memory management and handling of varying numbers of contacts during simulations.\n\n4. **Update Methods**:\n   - **update()**: Updates the mapping to reflect any changes in collision state, ensuring that forces are applied correctly as collisions evolve over time.\n   - **updateXfree()**: Specifically updates the free degrees of freedom (e.g., positions and velocities) based on the current mechanical state resulting from collisions.\n\n5. **Template Specialization**:\n   - The class is templated over types such as `sofa::defaulttype::Vec3Types` and `sofa::defaulttype::Rigid3Types`, allowing flexibility in handling different data representations and ensuring that the mapper can be used with various types of collision models.\n\n### Role in Simulation Framework\n\n- **Collision Response**: The `BaseContactMapper` plays a critical role in the collision response mechanism by translating detected collisions into mechanical forces, which are then applied to objects in the simulation. This ensures accurate and physically plausible behavior when objects interact or collide.\n\n- **Flexibility**: By providing an abstract interface with pure virtual methods, the class allows for flexible implementation of specific contact mapping strategies tailored to different types of collision models and mechanical properties. This flexibility is essential for handling a wide range of simulation scenarios and physical systems within the SOFA framework."
  },
  "summary": {
    "abstract": "`BaseContactMapper` is an abstract class providing an interface for creating specific contact mappers, translating collision information into mechanical states for applying forces and constraints in SOFA simulations.",
    "sheet": "# BaseContactMapper\n\n**Overview**\n\nThe `BaseContactMapper` serves as an abstract base class for creating specialized contact mappers that translate detected collisions into mechanical states. It ensures a consistent interface for handling different types of collision models and their associated mechanical properties.\n\n**Dependencies and Connections**\n\n- **Collision Models**: Interacts with `core::CollisionModel` instances to detect and handle collisions, translating them into mechanical forces and constraints.\n- **Mechanical States**: Provides a MechanicalState (`MMechanicalState`) that represents how collision forces are applied to objects in the simulation. This involves methods like `createMapping`, which generates the mechanical state based on detected contact points.\n\n**Practical Notes**\n\n- The class is templated over types such as `sofa::defaulttype::Vec3Types` and `sofa::defaulttype::Rigid3Types`, allowing flexibility in handling different data representations.\n- Key methods like `createMapping`, `cleanup`, `resize`, `addPoint`, and `updateXfree` are pure virtual, meaning any derived class must implement these to ensure proper functionality."
  }
}