{
  "name": "BaseVTKReader",
  "main": {
    "name": "BaseVTKReader",
    "namespace": "sofa::component::io::mesh::basevtkreader",
    "module": "Sofa.Component.IO.Mesh",
    "include": "sofa/component/io/mesh/BaseVTKReader.h",
    "doc": "",
    "inherits": [
      "BaseObject"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "newVTKDataIO",
        "return_type": "BaseVTKDataIO *",
        "params": [
          {
            "name": "typestr",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "newVTKDataIO",
        "return_type": "BaseVTKDataIO *",
        "params": [
          {
            "name": "typestr",
            "type": "const int &"
          },
          {
            "name": "num",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "readVTK",
        "return_type": "bool",
        "params": [
          {
            "name": "filename",
            "type": "const char *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "readFile",
        "return_type": "bool",
        "params": [
          {
            "name": "filename",
            "type": "const char *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "BaseVTKReader",
    "description": "The BaseVTKReader is an abstract base class for reading VTK (Visualization Toolkit) files in the SOFA framework, enabling the loading and processing of geometric data stored in VTK formats.",
    "parameters": [],
    "returns": [
      {
        "name": "readVTK",
        "description": "Method to read a VTK file using the readFile function. It takes a filename as input and returns true if the operation was successful."
      },
      {
        "name": "readFile",
        "description": "Abstract method that must be implemented by derived classes, which handles reading from the given file. It is called internally by readVTK."
      }
    ],
    "methods": [
      {
        "name": "readVTK(const char* filename)",
        "description": "Reads a VTK file specified by the provided filename. It relies on the readFile method to perform the actual file reading operation and returns true if the file was successfully read.",
        "parameters": [
          {
            "name": "filename",
            "type": "const char*",
            "description": "The path to the VTK file."
          }
        ]
      },
      {
        "name": "readFile(const char* filename)",
        "description": "An abstract method that must be overridden by derived classes. This function is responsible for reading and processing data from a given file in various VTK formats.",
        "parameters": [
          {
            "name": "filename",
            "type": "const char*",
            "description": "The path to the file."
          }
        ]
      },
      {
        "name": "VTKDataIO",
        "description": "A template class within BaseVTKReader that handles input/output operations for data of any type T, including reading from a string or stream in both binary and text formats, resizing data arrays, swapping byte orders (for big-endian systems), and writing to an output file.",
        "parameters": [],
        "methods": [
          {
            "name": "resize(int n)",
            "description": "Resizes the internal storage array for T type elements based on the given size. If a new size is provided, any previously allocated memory is freed before allocating space for the new size."
          },
          {
            "name": "read(const string& s, int n, int binary)",
            "description": "Reads data from a string s into an internal storage array of T type elements. It supports both text and binary formats as indicated by the 'binary' parameter."
          },
          {
            "name": "read(const string& s, int binary)",
            "description": "Determines the size of the input data in the string s and calls read with this determined size and a specified binary flag."
          },
          {
            "name": "read(istream& in, int n, int binary)",
            "description": "Reads 'n' elements from an input stream into the internal storage. It handles both text and binary formats based on the provided parameter."
          },
          {
            "name": "write(ofstream& out, int n, int groups, int binary)",
            "description": "Writes up to 'n' T type elements from internal storage to a given output file stream in either text or binary format depending on the value of 'binary'.",
            "parameters": [
              {
                "name": "out",
                "type": "ofstream&",
                "description": "Output file stream"
              },
              {
                "name": "n",
                "type": "int",
                "description": "Number of elements to write"
              },
              {
                "name": "groups",
                "type": "int",
                "description": "Grouping value for text output, only relevant when 'binary' is false."
              },
              {
                "name": "binary",
                "type": "int",
                "description": "Flag indicating if the data should be written in binary format (true) or as text (false)."
              }
            ]
          },
          {
            "name": "swap()",
            "description": "Reverses byte order for all elements stored internally, used when converting between big-endian and little-endian formats.",
            "parameters": []
          },
          {
            "name": "createSofaData()",
            "description": "Creates a SOFA framework data object containing the VTK data. This function is specific to T type elements and returns this new data object.",
            "returns": [
              {
                "type": "BaseData*",
                "description": "A pointer to a newly created BaseData object."
              }
            ]
          },
          {
            "name": "getData()",
            "description": "Returns a const pointer to the internal storage array holding the VTK data. The type T must be specified by the derived class.",
            "returns": [
              {
                "type": "const void*",
                "description": "Pointer to the internally stored VTK data."
              }
            ]
          }
        ]
      },
      {
        "name": "nestedDataSize",
        "description": "A member variable used within the VTKDataIO template class, indicating whether the T type is a vector or single value. This information impacts how data swapping and reading operations are performed.",
        "type": "int"
      }
    ],
    "notes": [
      "The BaseVTKReader provides an infrastructure for creating readers that can interpret different types of VTK files within SOFA framework applications.",
      "Specific file format implementations must derive from this class and implement the readFile method to support a specific variant of the VTK format."
    ]
  },
  "maths": {
    "maths": "The BaseVTKReader component in the SOFA framework is designed to handle the reading of VTK (Visualization Toolkit) files, which are used for representing geometric data such as points, lines, and polygons. The mathematical and physical descriptions of this component can be broken down into several key components:\n\n1. **Data Representation**:\n   - VTK Files: These contain structured or unstructured datasets with attributes attached to each point (vertices). Mathematically, the geometric data is represented by coordinates in a three-dimensional Euclidean space. For instance, points are denoted as vectors \\( P = (x,y,z) \\).\n   - Attributes: Besides geometry, VTK files can also contain scalar and vector fields defined over these points or cells (e.g., temperature as a scalar field or velocity as a vector field). Mathematically, these are functions that map each point in the dataset to a real number (scalar field) or another 3D vector (vector field).\n\n2. **File Parsing**:\n   - The `readVTK` and `readFile` methods handle parsing VTK files into usable data structures within SOFA. This involves parsing text or binary representations of the coordinates, attributes, and connectivity information.\n   - Mathematical Operation: For binary formats, byte swapping may be required if the endianness of the machine reading the file differs from that used to write it. The `swapT` function performs this operation by reversing the order of bytes within a data element.\n\n3. **Data Storage and Management**:\n   - `VTKDataIO<T>` is a template class specialized for different types (e.g., float, double) which handles data storage in memory after parsing.\n   - The `resize`, `getData`, `read`, `write` methods manage the dynamic allocation and manipulation of datasets. For example, resizing dynamically allocates or deallocates memory based on the number of elements needed: \\( resize(n): allocate \text{ } n \times sizeof(T) \text{ bytes}\\).\n   - The data is stored in contiguous blocks of memory, facilitating efficient access by iterators or pointers.\n\n4. **Data Conversion**:\n   - When converting VTK datasets to SOFA's internal representation (e.g., `type::vector<T>`), the component must ensure that each geometric point and its attributes are properly mapped from one data structure to another.\n   - Mathematical Operation: For example, a set of points \\( \textbf{P} = \begin{bmatrix} P_1 & P_2 & \text{...} & P_n \\\text{where } P_i = (x,y,z) \text{ for } i=1,...,n \\\\end{bmatrix}\\), must be copied into a vector structure, ensuring that each \\(P_i\\) is correctly indexed and accessible.\n\n5. **Efficiency and Performance**:\n   - The use of `std::vector` and direct memory manipulation via pointers ensures efficient storage and access to data. This is crucial for performance in real-time simulations or large-scale datasets.\n   - Binary file reading directly into a buffer (e.g., `in.read((char*)data, n *sizeof(T));`) leverages the speed of binary format over text-based representations, reducing parsing overhead.\n\n6. **Interoperability with SOFA Components**:\n   - The creation of SOFA-compatible data structures (`BaseData* createSofaData()`) allows seamless integration with other simulation components within the framework. This ensures that VTK data can be directly used in physical simulations or visualizations without further conversion.\n\nIn summary, the BaseVTKReader component mathematically and physically facilitates the translation of external geometric and attribute datasets into a form usable by SOFA's internal physics engines and visualization tools, ensuring correct representation and efficient processing."
  },
  "summary": {
    "abstract": "BaseVTKReader is an abstract base class for reading VTK files in the SOFA framework, enabling the loading of geometric data into simulation components.",
    "sheet": "# BaseVTKReader\n\n## Overview\nBaseVTKReader is an abstract base class designed to handle the parsing and loading of VTK (Visualization Toolkit) files within the SOFA framework. It facilitates the conversion of external geometric datasets into a form usable by other SOFA components for simulation purposes.\n\n## Parameters and Data\nThe BaseVTKReader does not expose any specific data fields or parameters beyond those inherited from its parent class `BaseObject`. Its functionality is primarily defined through method implementations rather than configurable settings.\n\n## Dependencies and Connections\nBaseVTKReader typically requires other SOFA components that handle the simulation aspects, such as force fields, solvers, and visualizers. It fits into the scene graph by providing geometric data to these components for further processing."
  }
}