{
  "name": "BaseSimulationExporter",
  "main": {
    "name": "BaseSimulationExporter",
    "namespace": "sofa::simulation::_basesimulationexporter_",
    "module": "Sofa.framework.Simulation.Core",
    "include": "sofa/simulation/BaseSimulationExporter.h",
    "doc": "Component that export something from the scene could inherit from this class\n    as it implement an uniform handling of the different data attributes.",
    "inherits": [
      "BaseObject"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_exportEveryNbSteps",
        "type": "unsigned int",
        "xmlname": "exportEveryNumberOfSteps",
        "help": "export file only at specified number of steps (0=disable, default=0)"
      },
      {
        "name": "d_exportAtBegin",
        "type": "bool",
        "xmlname": "exportAtBegin",
        "help": "export file before the simulation starts, once the simulation is initialized (default=false)"
      },
      {
        "name": "d_exportAtEnd",
        "type": "bool",
        "xmlname": "exportAtEnd",
        "help": "export file when the simulation is over and cleanup is called, i.e. just before deleting the simulation (default=false)"
      },
      {
        "name": "d_isEnabled",
        "type": "bool",
        "xmlname": "enable",
        "help": "Enable or disable the component. (default=true)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reinit",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "cleanup",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "handleEvent",
        "return_type": "void",
        "params": [
          {
            "name": "event",
            "type": "Event *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "doInit",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "doReInit",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "write",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getOrCreateTargetPath",
        "return_type": "const int",
        "params": [
          {
            "name": "filename",
            "type": "const int &"
          },
          {
            "name": "autonumbering",
            "type": "bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "updateFromDataField",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BaseSimulationExporter` is an abstract class in SOFA that provides a uniform handling of export-related functionalities for simulation components. This class inherits from `BaseObject`, making it part of the core object model within SOFA.\n\n**Role and Purpose**: \n- The primary role of this component is to facilitate the exporting of simulation data at specified intervals, either at the beginning or end of a simulation, or periodically during the simulation run. It serves as an abstract base class for concrete exporter components that need to implement their specific export logic.\n\n**Interactions with Other Components**: \n- `BaseSimulationExporter` interacts with other SOFA components through events such as `AnimateEndEvent` and `SimulationInitDoneEvent`, which trigger the export functionality. It listens to these events to determine when to call its `write()` method, which is a pure virtual function that must be implemented by derived classes.\n- The component maintains data fields that control its behavior, such as `exportEveryNumberOfSteps`, `exportAtBegin`, and `exportAtEnd`. These can be configured via the SOFA scene graph or programmatically.\n\n**Practical Usage Guidance**: \n- Derived classes must implement the `write()` method to define their specific export logic. This class provides a standardized way to handle common attributes like file paths, step counters, and enabling/disabling the exporter.\n- Users can configure when data should be exported using the provided data fields such as `exportEveryNumberOfSteps`, which allows setting the interval for exporting at regular intervals during the simulation steps."
  },
  "maths": {
    "maths": "The `BaseSimulationExporter` is an abstract class in the SOFA framework that provides uniform handling for exporting simulation data at specified intervals. This class serves as a base class for concrete exporter components and facilitates the export functionality without directly involving any mathematical or physical computations. Below is a detailed description of its role, interactions, and behavior within the simulation environment.\n\n### Role and Purpose\n- **Primary Functionality**: The `BaseSimulationExporter` enables exporting simulation data at specific intervals: periodically during the simulation, at the beginning (once initialization is done), or at the end of the simulation. It acts as an abstract base class, meaning derived classes must implement their specific export logic.\n\n### Data Fields and Configuration\n- **exportEveryNumberOfSteps**: This field controls how often data should be exported during the simulation steps. If set to a non-zero value, data is exported every `N` steps where `N` is this value.\n- **exportAtBegin**: A boolean flag that determines whether data should be exported when the simulation initialization is complete.\n- **exportAtEnd**: Another boolean flag indicating if data should be exported at the end of the simulation before cleanup.\n- **enable**: This field controls whether the exporter component is enabled or disabled. By default, it is set to `true` (enabled).\n\n### Event Handling and Triggers\n- The class listens for specific events such as `AnimateEndEvent` and `SimulationInitDoneEvent`. These events are used to trigger the export functionality.\n    - **AnimateEndEvent**: This event triggers at the end of each animation step. If `exportEveryNumberOfSteps` is set, it increments a counter (`m_stepCounter`) and checks if the current step number is divisible by this interval value. If true, it calls the `write()` method to perform the export.\n    - **SimulationInitDoneEvent**: This event triggers once the simulation initialization is complete. If both `exportAtBegin` and `enable` are set to `true`, it immediately calls the `write()` method for initial data export.\n- The `cleanup()` method checks if `exportAtEnd` and `enable` are `true`. If so, it calls the `write()` method during cleanup before the simulation ends.\n\n### Derived Class Responsibilities\n- Any derived class must implement the pure virtual function `write()`, which defines the specific export logic. This could involve writing data to a file, sending it over a network, or any other form of output.\n\n### Path and Naming Conventions\n- The class ensures that filenames are valid paths by using utility functions like `FileSystem::cleanPath()` and `FileSystem::ensureFolderForFileExists()`. If no filename is specified, the component's name is used as the default.\n\n### Summary\nThe `BaseSimulationExporter` acts as a base for exporting simulation data in SOFA. It provides event-driven triggers to control when data should be exported based on user-defined intervals and conditions. While it does not perform any direct mathematical or physical computations, its role is critical for managing the export process seamlessly within the framework."
  },
  "summary": {
    "abstract": "`BaseSimulationExporter` facilitates exporting simulation data at specified intervals during initialization, periodically, or at the end of a simulation run. It serves as an abstract base class for concrete exporter components that must implement their specific export logic.",
    "sheet": "# BaseSimulationExporter\n\n## Overview\nThe `BaseSimulationExporter` is an abstract class in SOFA that provides uniform handling for exporting simulation data at specified intervals during initialization, periodically, or at the end of a simulation run. It serves as an abstract base class for concrete exporter components that must implement their specific export logic.\n\n## Parameters and Data\n- **exportEveryNumberOfSteps**: Controls how often data should be exported during the simulation steps (default=0).\n- **exportAtBegin**: Determines whether data should be exported when the simulation initialization is complete (default=false).\n- **exportAtEnd**: Indicates if data should be exported at the end of the simulation before cleanup (default=false).\n- **enable**: Controls whether the exporter component is enabled or disabled (default=true).\n\n## Dependencies and Connections\nThe `BaseSimulationExporter` interacts with other SOFA components through events such as `AnimateEndEvent` and `SimulationInitDoneEvent`, which trigger the export functionality. It listens to these events to determine when to call its `write()` method, which is a pure virtual function that must be implemented by derived classes.\n\n## Practical Notes\nDerived classes must implement the `write()` method to define their specific export logic. Users can configure when data should be exported using the provided data fields such as `exportEveryNumberOfSteps`, which allows setting the interval for exporting at regular intervals during the simulation steps."
  }
}