{
  "name": "BaseElement",
  "main": {
    "name": "BaseElement",
    "namespace": "sofa::simulation::xml",
    "module": "Sofa.framework.Simulation.Common",
    "include": "sofa/simulation/common/xml/BaseElement.h",
    "doc": "",
    "inherits": [
      "BaseObjectDescription"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "getObject",
        "return_type": "sofa::core::objectmodel::Base *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "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": "newName",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getType",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setType",
        "return_type": "void",
        "params": [
          {
            "name": "newType",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getParent",
        "return_type": "sofa::core::objectmodel::BaseObjectDescription *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getParentElement",
        "return_type": "BaseElement *",
        "params": [],
        "is_virtual": false,
        "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": "setBaseFile",
        "return_type": "void",
        "params": [
          {
            "name": "newBaseFile",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSrcFile",
        "return_type": "const int &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setSrcFile",
        "return_type": "void",
        "params": [
          {
            "name": "newSrcFile",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSrcLine",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setSrcLine",
        "return_type": "void",
        "params": [
          {
            "name": "l",
            "type": "const int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isFileRoot",
        "return_type": "bool",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getIncludeNodeType",
        "return_type": "IncludeNodeType",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setIncludeNodeType",
        "return_type": "void",
        "params": [
          {
            "name": "t",
            "type": "IncludeNodeType"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "presenceAttribute",
        "return_type": "bool",
        "params": [
          {
            "name": "s",
            "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": "addReplaceAttribute",
        "return_type": "void",
        "params": [
          {
            "name": "attr",
            "type": "const int &"
          },
          {
            "name": "val",
            "type": "const char *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "findNode",
        "return_type": "BaseElement *",
        "params": [
          {
            "name": "nodeName",
            "type": "const char *"
          },
          {
            "name": "absolute",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "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": "pushObjects",
        "return_type": "void",
        "params": [
          {
            "name": "result",
            "type": "Sequence &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "pushNamedObjects",
        "return_type": "void",
        "params": [
          {
            "name": "result",
            "type": "Map &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setParent",
        "return_type": "bool",
        "params": [
          {
            "name": "newParent",
            "type": "BaseElement *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addChild",
        "return_type": "bool",
        "params": [
          {
            "name": "child",
            "type": "BaseElement *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeChild",
        "return_type": "bool",
        "params": [
          {
            "name": "child",
            "type": "BaseElement *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "initNode",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "init",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "begin",
        "return_type": "child_iterator<Node>",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "end",
        "return_type": "child_iterator<Node>",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "Create",
        "return_type": "BaseElement *",
        "params": [
          {
            "name": "nodeClass",
            "type": "const int &"
          },
          {
            "name": "name",
            "type": "const int &"
          },
          {
            "name": "type",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `BaseElement` class in the SOFA framework is a fundamental building block for constructing and managing simulation scenes. It inherits from `sofa::core::objectmodel::BaseObjectDescription` and serves as a node within the scene graph, representing various elements such as objects, mappings, and other components.\n\n### Role and Purpose:\n- **Hierarchical Management**: Manages hierarchical relationships between different nodes in the simulation scene. It maintains parent-child relationships through methods like `getParent`, `setParent`, `addChild`, and `removeChild`.\n- **Attribute Handling**: Provides mechanisms to manage node attributes, including setting and removing attributes (`setName`, `setType`, `presenceAttribute`, `removeAttribute`).\n- **Initialization**: Ensures proper initialization of nodes through methods like `initNode` and `init`. These methods facilitate setting up the simulation environment by resolving file paths and initializing children recursively.\n\n### Interactions with Other Components:\n- **BaseObjectDescription**: Inherits from this class, providing base functionality for object descriptions in SOFA.\n- **Factory Pattern**: Uses a factory pattern to create instances of different node types via `Create` method, ensuring polymorphic behavior.\n- **Scene Graph Navigation**: Supports methods like `findNode` and `find`, enabling traversal through the scene graph to locate specific nodes or objects based on their names.\n\n### Practical Usage Guidance:\n- **Initialization**: Nodes should be initialized using `init` and `initNode` methods. The former ensures that all child nodes are properly initialized recursively.\n- **Attribute Management**: Use methods like `setName`, `setType`, `presenceAttribute`, and `removeAttribute` to manage node attributes effectively, ensuring the configuration of simulation elements is correctly set up.\n- **Hierarchical Navigation**: Utilize methods such as `findNode`, `begin`, and `end` for hierarchical traversal and manipulation within the scene graph structure."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of `BaseElement` in the SOFA Framework\n\n## Overview\nThe `BaseElement` class in the SOFA (Simulation Open-Framework Architecture) framework serves as a foundational node within the hierarchical scene graph structure used to represent and manage simulation components. It facilitates various operations such as hierarchical management, attribute handling, and initialization of elements within the simulation environment.\n\n## Hierarchical Management\nThe `BaseElement` class manages relationships between nodes in the hierarchy through methods like `getParent`, `setParent`, `addChild`, and `removeChild`. These relationships can be represented mathematically using a tree data structure. Let's denote:\n- \\(N_i\\) as node \\(i\\)\n- \\(P(N_i)\\) as the parent of node \\(i\\)\n- \\(C(N_i) = \\{N_{j_1}, N_{j_2}, ..., N_{j_k}\\}\\) as the set of children of node \\(i\\).\n\nThe hierarchical relationship can be defined recursively:\n$$\nP(N_i) = \\text{parent of } N_i,\n$$\nand for each child \\(N_j \\in C(N_i)\\):\n$$\nP(N_j) = N_i.\n$$\nThe `addChild` and `removeChild` methods manipulate these relationships:\n- Adding a child node \\(N_j\\) to \\(N_i\\): \n$$\nC(N_i) \\leftarrow C(N_i) \\cup \\{N_j\\}, \\quad P(N_j) = N_i.\n$$\n- Removing a child node \\(N_j\\) from \\(N_i\\):\n$$\nC(N_i) \\leftarrow C(N_i) - \\{N_j\\}, \\quad P(N_j) = \\text{nullptr}.\n$$\n\n## Attribute Handling\nThe `BaseElement` class provides methods to manage node attributes, such as names and types. Attributes can be viewed mathematically as mappings from nodes to attribute values:\n- Let \\(A_i\\) denote the set of attributes for node \\(N_i\\).\n- Each attribute \\(a_{ij} \\in A_i\\) is a key-value pair: \n$$\na_{ij} = (k_{ij}, v_{ij}),\n$$\nwhere \\(k_{ij}\\) is the attribute key and \\(v_{ij}\\) is its value.\n\nThe `setName` and `setType` methods update these attributes:\n- Setting the name of node \\(N_i\\):\n$$\na_{i,\\text{name}} = (\\text{name}, v_{\\text{new}}).\n$$\n- Similarly for setting type:\n$$\na_{i,\\text{type}} = (\\text{type}, v_{\\text{new}}).\n$$\nThe `presenceAttribute` method checks if an attribute is present in the set \\(A_i\\), and the `removeAttribute` method removes a specified key from \\(A_i\\):\n- Checking presence:\n$$\n\\exists k \\in A_i \\mid k = \\text{key}.\n$$\n- Removing an attribute:\n$$\nA_i \\leftarrow A_i - \\{(k_{ij}, v_{ij}) | k_{ij} = \\text{key}\\}.\n$$\n\n## Initialization\nThe `BaseElement` class includes methods for initializing nodes (`initNode`) and their children recursively (`init`). The initialization process involves resolving file paths and setting up the environment. Mathematically, this can be represented as a recursive function:\n- Let \\(I(N_i)\\) denote the initialization of node \\(N_i\\).\n- Initialization involves setting up local attributes and child nodes:\n$$\nI(N_i) = (\\text{setup local attributes}) + \\sum_{j \\in C(N_i)} I(N_j).\n$$\nThe `init` method ensures that all children are initialized by calling `initNode` on each child recursively.\n\n## Scene Graph Navigation\nThe scene graph can be navigated using methods like `findNode`. The traversal operation from a node \\(N_i\\) to find another node \\(N_k\\) with a given name can be represented as a search function over the subtree rooted at \\(N_i\\). Let \\(F(N_i, n)\\) denote finding a node named \\(n\\) starting from node \\(N_i\\):\n$$\nF(N_i, n) = \n\\begin{cases} \nN_i & \\text{if } N_i.\\text{name} = n, \\\\\n\\bigcup_{j \\in C(N_i)} F(N_j, n) & \\text{otherwise}. \n\\end{cases}\n$$\nThe `findNode` method uses this logic to recursively search through the scene graph until it finds a node with the specified name or reaches the root of the tree.\n\n## Summary\nThe `BaseElement` class provides essential functionalities for managing hierarchical relationships, attributes, and initialization within the SOFA framework. The mathematical representation helps in understanding these operations as mappings, sets, and recursive functions over nodes in the scene graph."
  },
  "summary": {
    "abstract": "`BaseElement` manages hierarchical relationships, attribute handling, and initialization of nodes within the SOFA scene graph.",
    "sheet": "# BaseElement\n\n## Overview\nThe `BaseElement` class in the SOFA framework serves as a fundamental node for managing hierarchical relationships, attribute handling, and initialization of elements within the simulation environment. It inherits from `sofa::core::objectmodel::BaseObjectDescription`, providing essential functionalities such as setting names, types, and parent-child relationships.\n\n## Parameters and Data\nThe significant methods exposed by `BaseElement` include:\n- **getObject**: Returns a pointer to the base object associated with this element (`sofa::core::objectmodel::Base *`).\n- **getName** and **setName**: Retrieve or set the name of the node as an integer value.\n- **getType** and **setType**: Retrieve or set the type of the node as an integer value.\n- **getParent** and **setParent**: Manage parent-child relationships by retrieving or setting the parent element (`BaseElement *`).\n- **getSrcFile**, **setSrcFile**, **getSrcLine**, **setSrcLine**: Handle source file information for debugging purposes.\n- **isFileRoot**: Determines if the node is a root in its file context.\n- **presenceAttribute** and **removeAttribute**: Check or remove attributes based on their keys.\n- **addReplaceAttribute**: Add or replace an attribute with a given value.\n- **findNode** and **find**: Traverse the scene graph to locate nodes by name.\n- **addChild** and **removeChild**: Manage child elements within the hierarchy.\n- **initNode** and **init**: Initialize the node and its children recursively.\n\n## Dependencies and Connections\n`BaseElement` typically requires or exchanges data with other components such as `sofa::core::objectmodel::BaseObjectDescription`. It fits into the scene graph by managing hierarchical relationships, attribute handling, and initialization processes. The class is essential for constructing and maintaining the structure of simulation scenes.\n\n## Practical Notes\nNodes should be initialized using the `init` and `initNode` methods to ensure proper setup of attributes and children recursively. Attribute management can be performed using methods like `setName`, `setType`, `presenceAttribute`, and `removeAttribute`. Hierarchical navigation within the scene graph is supported by methods such as `findNode`, `begin`, and `end`."
  }
}