Mathematical and Physical Description of the BaseObjectDescription Component in SOFA Framework

Methods

{
  "name": "BaseObjectDescription",
  "namespace": "sofa::core::objectmodel",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/objectmodel/BaseObjectDescription.h",
  "doc": "Base Interface for classes containing the description of an object, used to construct it.\n This class defines what information are used as input (read from a file for instance) to create an object.\n This default implementation simply stores an attributes map and does not support any hierarchy.",
  "inherits": [],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "getObject",
      "return_type": "Base *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getName",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setName",
      "return_type": "void",
      "params": [
        {
          "name": "name",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getParent",
      "return_type": "BaseObjectDescription *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getBaseFile",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAttributeMap",
      "return_type": "const AttributeMap &",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAttributeList",
      "return_type": "void",
      "params": [
        {
          "name": "container",
          "type": "T &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "find",
      "return_type": "BaseObjectDescription *",
      "params": [
        {
          "name": "nodeName",
          "type": "const char *"
        },
        {
          "name": "absolute",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "findObject",
      "return_type": "Base *",
      "params": [
        {
          "name": "nodeName",
          "type": "const char *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAttribute",
      "return_type": "const char *",
      "params": [
        {
          "name": "attr",
          "type": "const int &"
        },
        {
          "name": "defaultVal",
          "type": "const char *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAttributeAsFloat",
      "return_type": "float",
      "params": [
        {
          "name": "attr",
          "type": "const int &"
        },
        {
          "name": "defaultVal",
          "type": "const float"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAttributeAsInt",
      "return_type": "int",
      "params": [
        {
          "name": "attr",
          "type": "const int &"
        },
        {
          "name": "defaultVal",
          "type": "const int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setAttribute",
      "return_type": "void",
      "params": [
        {
          "name": "attr",
          "type": "const int &"
        },
        {
          "name": "val",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeAttribute",
      "return_type": "bool",
      "params": [
        {
          "name": "attr",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFullName",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "logError",
      "return_type": "void",
      "params": [
        {
          "name": "s",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "logErrors",
      "return_type": "void",
      "params": [
        {
          "name": "e",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getErrors",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearErrors",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `BaseObjectDescription` class in the SOFA framework is designed to provide an interface for classes that contain descriptions used for constructing objects, typically read from configuration files or other input sources. Its primary purpose is to store and manage attributes necessary for object instantiation.",
  "key_features": [
    {
      "name": "Attribute Storage",
      "description": "Uses a map (`AttributeMap`) to store attribute-value pairs which can be accessed using various methods."
    },
    {
      "name": "Attribute Access Methods",
      "description": "Offers several methods to get and set attributes, including `getAttribute`, `setAttribute` and `removeAttribute`. Also provides conversion methods like `getAttributeAsFloat` and `getAttributeAsInt`."
    },
    {
      "name": "Error Handling",
      "description": "Includes mechanisms for logging errors during attribute parsing or object instantiation via `logError` and `logErrors` methods, with a list of accumulated error messages."
    },
    {
      "name": "Object Hierarchy Support",
      "description": "Although the class is designed to be extendable for hierarchical structures (like nodes in a scene graph), this default implementation does not directly support such hierarchies. Methods like `getParent` and `find` suggest intended future extension points or derived classes that might implement hierarchy."
    },
    {
      "name": "Object Reference",
      "description": "Maintains a reference to the constructed object via the `getObject` method, which can return the actual instantiated object or nullptr if not yet created."
    }
  ],
  "usage_scenarios": [
    {
      "scenario": "Configuring Objects from File",
      "details": "Attributes required for constructing an object are read from a file and stored in `BaseObjectDescription`. This class then provides the interface to access these attributes when instantiating objects during runtime."
    },
    {
      "scenario": "Hierarchical Object Management (Future Implementation)",
      "details": "In extended or derived classes, `find` and `getParent` methods can be implemented to support managing object hierarchies, such as scene graphs in simulation frameworks. This could allow for traversing the hierarchy of objects based on names or other identifiers."
    }
  ],
  "code_example": {
    "description": "Instantiation and usage example.",
    "example_code": "BaseObjectDescription* description = new BaseObjectDescription(\"myObjectName\", \"ObjectType\");\ndescription->setAttribute(\"mass\", \"5.0\");\nfloat massValue = description->getAttributeAsFloat(\"mass\", 1.0f);\nif (description->getObject() == nullptr) {\n    // Handle object not yet created\n}\n"
  },
  "maths": "# Mathematical and Physical Description of the BaseObjectDescription Component in SOFA Framework\n\n## Overview\nThe `BaseObjectDescription` class is part of the Simulation Open-Framework Architecture (SOFA) and serves as a fundamental interface for managing object descriptions, typically used to construct objects from configuration data. Its primary function revolves around storing attributes required for object instantiation and providing methods for accessing these attributes in various forms.\n\n## Core Functionalities\n### Attribute Management\n- **Attribute Map:** The class uses an `AttributeMap` to store key-value pairs representing the properties of an object being described or constructed. This map is a specialization of `std::map<std::string, Attribute>`, where `Attribute` is a custom type that encapsulates string values and access status.\n\n### Access Methods\n- **Name Management:** The methods `getName()` and `setName(const std::string& name)` allow for retrieving and setting the object's name. This is important in hierarchical structures or when identifying specific objects within configurations.\n\n- **Attribute Retrieval:** `getAttribute`, `getAttributeAsFloat`, and `getAttributeAsInt` provide mechanisms to retrieve attribute values either as strings, floats, or integers. These methods handle missing attributes by providing default values and log error messages if parsing fails for numerical types.\n\n### Hierarchical Navigation\n- The `getParent()` method returns the parent node in a potential hierarchical structure, while `find(const char* nodeName)` locates an object description within this hierarchy based on a name or relative path. This is particularly useful in complex configuration files where objects are nested and related to each other.\n\n### Object Discovery\n- **`getObject`:** Retrieves an actual object if it's already constructed. Otherwise, returns `nullptr`. Useful for dynamically linking descriptions with their corresponding instantiated forms.\n\n- **`findObject`:** Given a node name, this function finds the associated object by searching through the hierarchy and resolving any mechanical state links within contexts (e.g., getting a mechanical state from a context).\n\n### Error Handling\n- The class manages error logging using `logError`, `logErrors`, which store warnings or parsing issues in an internal vector. `getErrors` provides access to these messages, while `clearErrors` resets the error list.\n\n## Mathematical Considerations\nThe mathematical aspects of this component primarily concern numerical conversions and validations:\n- **Conversion Functions:** When retrieving attributes as floats (`getAttributeAsFloat`) or integers (`getAttributeAsInt`), the class uses string-to-number conversion functions (`strtof`, `strtol`). These functions parse strings to their respective number types, using locale-specific decimal separators for floating-point numbers.\n\n- **Validation and Error Handling:** For numerical parsing, validations are performed to ensure that entire attribute values were successfully parsed. If a value cannot be fully parsed (e.g., extraneous characters after the expected numeric format), default values are used, and error messages are logged. This mechanism ensures robustness against malformed configuration data.\n\n## Physical Interpretation\n- In the context of simulations and physical models within SOFA, attributes stored in `BaseObjectDescription` could represent parameters for physical objects such as masses, stiffness coefficients, or interaction properties. The ability to parse these attributes accurately is crucial for building reliable simulation environments based on external configurations.",
  "abstract": "`BaseObjectDescription` manages object descriptions used in constructing objects within the SOFA framework by storing and retrieving attribute information.",
  "sheet": "# BaseObjectDescription\n\n## Overview\nThe `BaseObjectDescription` class serves as an interface for managing object descriptions, typically used to construct objects from configuration data. It stores attributes required for object instantiation and provides methods for accessing these attributes in various forms.\n\n## Parameters and Data\n- **Attribute Map:** The class uses an `AttributeMap` to store key-value pairs representing the properties of an object being described or constructed.\n\n## Dependencies and Connections\nThis component does not have specific dependencies on other SOFA components but is used as a foundational element for constructing objects within the scene graph hierarchy."
}