Data Fields

Methods

{
  "name": "RandomPointDistributionInSurface",
  "namespace": "sofa::component::engine::generate",
  "module": "Sofa.Component.Engine.Generate",
  "include": "sofa/component/engine/generate/RandomPointDistributionInSurface.h",
  "doc": "Engine distributing points over a surface randomly.\n\nThis class extrudes a surface",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "randomSeed",
      "type": "unsigned int",
      "xmlname": "randomSeed",
      "help": "Set a specified seed for random generation (0 for \\\"true pseudo-randomness\\\" "
    },
    {
      "name": "isVisible",
      "type": "bool",
      "xmlname": "isVisible",
      "help": "is Visible ?"
    },
    {
      "name": "drawOutputPoints",
      "type": "bool",
      "xmlname": "drawOutputPoints",
      "help": "Output points visible ?"
    },
    {
      "name": "minDistanceBetweenPoints",
      "type": "Real",
      "xmlname": "minDistanceBetweenPoints",
      "help": "Min Distance between 2 points (-1 for true randomness)"
    },
    {
      "name": "numberOfInPoints",
      "type": "unsigned int",
      "xmlname": "numberOfInPoints",
      "help": "Number of points inside"
    },
    {
      "name": "numberOfTests",
      "type": "unsigned int",
      "xmlname": "numberOfTests",
      "help": "Number of tests to find if the point is inside or not (odd number)"
    },
    {
      "name": "f_vertices",
      "type": "VecCoord",
      "xmlname": "vertices",
      "help": "Vertices"
    },
    {
      "name": "f_inPoints",
      "type": "VecCoord",
      "xmlname": "inPoints",
      "help": "Points inside the surface"
    },
    {
      "name": "f_outPoints",
      "type": "VecCoord",
      "xmlname": "outPoints",
      "help": "Points outside the surface"
    }
  ],
  "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": "doUpdate",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getBBox",
      "return_type": "void",
      "params": [
        {
          "name": "minBBox",
          "type": "Vec3 &"
        },
        {
          "name": "maxBBox",
          "type": "Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "generateRandomDirections",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "generateRandomPoint",
      "return_type": "Vec3",
      "params": [
        {
          "name": "minBBox",
          "type": "const Vec3 &"
        },
        {
          "name": "maxBBox",
          "type": "const Vec3 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isInside",
      "return_type": "bool",
      "params": [
        {
          "name": "p",
          "type": "Coord"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "testDistance",
      "return_type": "bool",
      "params": [
        {
          "name": "p",
          "type": "Coord"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The RandomPointDistributionInSurface component is designed to generate points that are either inside or outside a given surface, which is defined by vertices and triangular faces.",
  "parameters": {
    "randomSeed": {
      "type": "unsigned int",
      "default_value": 0,
      "description": "Sets the seed for random number generation. A value of 0 initializes with the current time."
    },
    "isVisible": {
      "type": "bool",
      "default_value": true,
      "description": "Determines whether generated points are visualized."
    },
    "drawOutputPoints": {
      "type": "bool",
      "default_value": false,
      "description": "If true, also visualizes the points that were determined to be outside the surface."
    },
    "minDistanceBetweenPoints": {
      "type": "Real",
      "default_value": 0.1,
      "description": "Minimum distance between two generated points; set to -1 for no restriction."
    },
    "numberOfInPoints": {
      "type": "unsigned int",
      "default_value": 10,
      "description": "Target number of points to generate inside the surface."
    },
    "numberOfTests": {
      "type": "unsigned int",
      "default_value": 5,
      "description": "Number of tests (must be an odd number) used to determine whether a point is inside or outside the surface."
    }
  },
  "inputs": {
    "vertices": {
      "type": "VecCoord",
      "description": "The vertices defining the points of the input mesh."
    },
    "triangles": {
      "type": "vector<Triangle>",
      "description": "Indices specifying the triangular faces formed by the vertices."
    }
  },
  "outputs": {
    "inPoints": {
      "type": "VecCoord",
      "description": "Generated points that are inside the specified surface."
    },
    "outPoints": {
      "type": "VecCoord",
      "description": "Generated points that are outside the specified surface."
    }
  },
  "operation_details": {
    "getBBox": "Calculates and returns the bounding box (minimum and maximum coordinates) of the vertices.",
    "generateRandomDirections": "Generates random direction vectors used for point generation tests.",
    "generateRandomPoint": "Generates a random point within the bounding box defined by the minimum and maximum vertex coordinates.",
    "isInside": "Determines whether a given point is inside or outside the surface, using a ray-tracing method with specified number of tests.",
    "testDistance": "Checks if a generated point meets the minimum distance requirement from other points already determined to be inside the surface.",
    "doUpdate": "Performs the main operation of generating the required number of inside and outside points by iterating within a safe limit to avoid infinite loops.",
    "draw": "Visualizes the generated inside and outside points using different colors if specified."
  },
  "maths": "The RandomPointDistributionInSurface component is designed to generate points that are either inside or outside a given surface, which is defined by vertices and triangular faces. The mathematical and physical aspects of this component can be described as follows:\n\n### Governing Equations and Operators\n- **Random Point Generation**: Points are generated randomly within the bounding box defined by the minimum and maximum coordinates of the vertices.\n  \n  \\[ r = (r_x, r_y, r_z) \\]\n  where each component is uniformly distributed between the corresponding min and max values:\n  \n  \\[ r_i \text{ drawn from } [\\min(r_{i,\text{vertices}}), \\max(r_{i,\text{vertices}})] \\quad \\text{for} \\; i = x, y, z. \\]\n\n- **Distance Checking**: Points are checked for minimum distance between them to ensure a certain level of distribution uniformity.\n  \n  For point \\( p_i \\) and each other generated point \\( p_j \\):\n  \n  \\[ (p_i - p_j)^T(p_i - p_j) < d_{\text{min}}^2. \\]\n\n### Constitutive or Kinematic Laws Involved\n- **Random Point Distribution**: Points are uniformly distributed within the bounding box defined by the vertices of the surface. The randomness is controlled through a seed value.\n  \n  - **Seed Initialization**: If a specific random seed (non-zero) is set, it ensures reproducibility; otherwise, a pseudo-random sequence is generated based on the current time.\n\n- **Bounding Box Calculation**: The bounding box is determined by the minimum and maximum coordinates of the vertices defining the surface.\n  \n  For a vertex \\( v_i = (v_{i,x}, v_{i,y}, v_{i,z}) \\):\n  \n  \\[ \\minBBox = (\\min(v_{i,x}), \\min(v_{i,y}), \\min(v_{i,z})), \\]\n  \\[ \\maxBBox = (\\max(v_{i,x}), \\max(v_{i,y}), \\max(v_{i,z})). \\]\n\n### Role in the Global FEM Pipeline\n- **Random Point Generation**: This component operates independently of the standard FEM pipeline and is used primarily for generating random points within a defined surface. It does not contribute to mass matrix (M), stiffness matrix (K), internal force (f_int), or residual (R).\n  \n- **Assembly Phase**: The component generates points, which can be used as input for other components such as force fields or constraints.\n\n### Numerical Methods and Discretization Choices\n- **Randomness Generation**: Uses a random number generator initialized with either a specified seed or the current time if no seed is provided.\n  \n  - **Uniform Distribution**: Points are uniformly distributed within a bounding box defined by the vertices of the surface.\n  - **Distance Checking**: Ensures that points are not closer than a minimum distance (\\(d_{\text{min}}\")). This helps in avoiding point clustering and maintaining a more uniform distribution.\n\n### Integration into Variational / Lagrangian Mechanics Framework\n- The RandomPointDistributionInSurface component does not directly contribute to the variational or Lagrangian mechanics framework. Instead, it serves as a utility for generating points that can be used as input for other components within the FEM pipeline such as force fields and constraints.\n  \n  - **Boundary Conditions**: The generated points can serve as locations for boundary conditions (e.g., applying forces or constraints).\n  - **Meshing**: Points inside the surface can be used to refine a mesh, enabling more detailed simulations in certain regions.\n\nIn summary, while the RandomPointDistributionInSurface component does not directly participate in solving FEM equations, it provides essential functionality for generating points within and outside a specified surface. This can be particularly useful for tasks such as initializing boundary conditions or refining mesh resolution.",
  "abstract": "The RandomPointDistributionInSurface engine generates points randomly within a surface's bounding box, ensuring a minimum distance between points if specified.",
  "sheet": "# RandomPointDistributionInSurface\n\n## Overview\n\nThis component is an engine that distributes points over a given surface in a random manner. It ensures that the generated points are either inside or outside the surface and can enforce a minimum distance between points to avoid clustering.\n\n## Mathematical Model\n\n### Point Generation\nPoints are uniformly distributed within the bounding box defined by the vertices of the surface:\n\n\\[ r = (r_x, r_y, r_z) \\]\nwhere each component is drawn from the interval \\\\[ [\text{min}(v_{i,x}), \text{max}(v_{i,x})] \\\\], \\\\[ [\text{min}(v_{i,y}), \text{max}(v_{i,y})] \\\\], and \\\\[ [\text{min}(v_{i,z}), \text{max}(v_{i,z})] \\\\].\n\n### Distance Checking\nPoints are checked to ensure they maintain a minimum distance from each other:\n\nFor point \\( p_i \\) and each other generated point \\( p_j \\):\n\n\\[ (p_i - p_j)^T(p_i - p_j) < d_{\\text{min}}^2. \\]\n\n## Parameters and Data\n\n- **randomSeed**: Set a specified seed for random generation (0 for true pseudo-randomness). Type: `unsigned int`.\n- **isVisible**: Determines if the component is visible in the scene. Type: `bool`.\n- **drawOutputPoints**: Controls whether output points are visible. Type: `bool`.\n- **minDistanceBetweenPoints**: Minimum distance between two points (-1 for true randomness). Type: `Real`.\n- **numberOfInPoints**: Number of points inside the surface. Type: `unsigned int`.\n- **numberOfTests**: Number of tests to determine if a point is inside or not (odd number). Type: `unsigned int`.\n- **f_vertices**: Vertices defining the surface. Type: `VecCoord`.\n- **f_inPoints**: Points inside the surface. Type: `VecCoord`.\n- **f_outPoints**: Points outside the surface. Type: `VecCoord`."
}