Mathematical and Physical Description of the Distances Component

Data Fields

Methods

{
  "name": "Distances",
  "namespace": "sofa::component::engine::analyze",
  "module": "Sofa.Component.Engine.Analyze",
  "include": "sofa/component/engine/analyze/Distances.h",
  "doc": "Compute distances based on a grid.\n\nThis class computes distances between to set of mechanical objects.",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "data",
      "type": "DataTypes"
    },
    {
      "name": "d_showMapIndex",
      "type": "unsigned int",
      "xmlname": "showMapIndex",
      "help": "Frame DOF index on which display values."
    },
    {
      "name": "d_showDistanceMap",
      "type": "bool",
      "xmlname": "showDistancesMap",
      "help": "show the distance for each point of the target point set."
    },
    {
      "name": "d_showGoalDistanceMap",
      "type": "bool",
      "xmlname": "showGoalDistancesMap",
      "help": "show the distance for each point of the target point set."
    },
    {
      "name": "d_showTextScaleFactor",
      "type": "double",
      "xmlname": "showTextScaleFactor",
      "help": "Scale to apply on the text."
    },
    {
      "name": "d_showGradientMap",
      "type": "bool",
      "xmlname": "showGradients",
      "help": "show gradients for each point of the target point set."
    },
    {
      "name": "d_showGradientsScaleFactor",
      "type": "double",
      "xmlname": "showGradientsScaleFactor",
      "help": "scale for the gradients displayed."
    },
    {
      "name": "d_offset",
      "type": "Coord",
      "xmlname": "offset",
      "help": "translation offset between the topology and the point set."
    },
    {
      "name": "d_distanceType",
      "type": "sofa::helper::OptionsGroup",
      "xmlname": "Geodesic",
      "help": "type of distance to compute for inserted frames."
    },
    {
      "name": "d_initTarget",
      "type": "bool",
      "xmlname": "initTarget",
      "help": "initialize the target MechanicalObject from the grid."
    },
    {
      "name": "d_initTargetStep",
      "type": "int",
      "xmlname": "initTargetStep",
      "help": "initialize the target MechanicalObject from the grid using this step."
    },
    {
      "name": "d_harmonicMaxValue",
      "type": "double",
      "xmlname": "harmonicMaxValue",
      "help": "Max value used to initialize the harmonic distance grid."
    }
  ],
  "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": "computeDistanceMap",
      "return_type": "void",
      "params": [
        {
          "name": "beginElts",
          "type": "VecCoord"
        },
        {
          "name": "distMax",
          "type": "const double &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addElt",
      "return_type": "void",
      "params": [
        {
          "name": "elt",
          "type": "const Coord &"
        },
        {
          "name": "beginElts",
          "type": "VecCoord"
        },
        {
          "name": "distMax",
          "type": "const double &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDistances",
      "return_type": "void",
      "params": [
        {
          "name": "distances",
          "type": "VVD &"
        },
        {
          "name": "gradients",
          "type": "VecVecCoord &"
        },
        {
          "name": "goals",
          "type": "const VecCoord &"
        }
      ],
      "is_virtual": false,
      "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": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "core::objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    }
  ],
  "description": "The `Distances` class in SOFA is designed to compute distances between sets of mechanical objects based on a grid. It inherits from `DataEngine`, which enables it to perform computations and update data during the simulation process.\n\n**Role and Purpose:**\n- The primary role of `Distances` is to calculate different types of distance metrics (e.g., geodesic, harmonic) between sets of mechanical objects within a grid-based topology. It supports various methods for computing distances such as Geodesic, Harmonic, Stiffness Diffusion, Voronoi, and Harmonic with Stiffness.\n\n**Interactions with Other Components:**\n- The component requires a `DynamicSparseGridTopologyContainer` to define the grid on which distance calculations are performed. It also needs a `MechanicalState` object representing the target point set for computing distances.\n- Interactions are primarily through the scene graph and data fields, where it retrieves topological information from the container and mechanical state from objects in the simulation.\n\n**Practical Usage Guidance:**\n- To use `Distances`, specify the grid topology via `hexaContainerPath` and the target point set using `targetPath`. \n- Configure the distance type with `d_distanceType`, which can be one of Geodesic, Harmonic, Stiffness Diffusion, Voronoi, or Harmonic with Stiffness.\n- Use fields like `d_showDistanceMap`, `d_showGradientMap`, and `d_offset` to control how distances and gradients are displayed and computed relative to the grid topology.\n- The component can initialize target mechanical objects from the grid using `d_initTarget` and `d_initTargetStep`. \n\n**Data Fields:**\n- **Data Fields:** `data`, `d_showMapIndex`, `d_showDistanceMap`, `d_showGoalDistanceMap`, `d_showTextScaleFactor`, `d_showGradientMap`, `d_showGradientsScaleFactor`, `d_offset`, `d_distanceType`, `d_initTarget`, `d_initTargetStep`, `d_harmonicMaxValue`\n\n**Methods:**\n- `init()` initializes the component and ensures that necessary components like `DynamicSparseGridTopologyContainer` are available.\n- `reinit()` reinitializes the distance computations.\n- `doUpdate()` performs updates during simulation steps.\n- `computeDistanceMap()` computes distances for given points with an optional maximum distance limit.\n- `addElt()` adds new elements and recomputes the distance map accordingly.\n- `getDistances()` retrieves computed distances and gradients for a set of goals.",
  "maths": "# Mathematical and Physical Description of the `Distances` Component\n\nThe `Distances` component in SOFA is a specialized engine designed to compute various distance metrics between sets of mechanical objects within a grid-based topology. It offers several methods for computing distances, such as Geodesic, Harmonic, Stiffness Diffusion, Voronoi, and Harmonic with Stiffness. Below is an explanation of the mathematical and physical principles involved in these computations.\n\n## Distance Types\n\n### 1. Geodesic Distances\nGeodesic distance between two points on a surface is defined as the shortest path connecting them while staying within that surface. In a grid-based topology, this can be computed using Dijkstra's algorithm or other graph traversal methods.\n\nMathematically, let \\( P_1 \\) and \\( P_2 \\) be two points in the grid. The geodesic distance \\( d_{\text{geo}}(P_1, P_2) \\) is given by:\n\\[ d_{\text{geo}}(P_1, P_2) = \\min_{\\gamma} L(\\gamma), \\]\nwhere \\( \\\\gamma \\) represents all possible paths between \\( P_1 \\) and \\( P_2 \\), and \\( L(\\\\gamma) \\) is the length of the path.\n\n### 2. Harmonic Distances\nHarmonic distance is computed by solving a Poisson equation over the grid to find a harmonic function that interpolates between given boundary conditions (e.g., source and sink points). The resulting function assigns a value at each point in the domain, which can be interpreted as a measure of distance.\n\nMathematically, let \\( u(x) \\) be the harmonic function satisfying:\n\\[ \n\\begin{cases}\n-\\Delta u = 0 & \\text{in } \\Omega,\\\\\nu(x_i) = d_i & \\text{on } \\partial \\Omega,\n\\end{cases}\n\\]\nwhere \\( x_i \\) are the boundary points with known distances \\( d_i \\), and \\( \\\\Delta u \\) is the Laplacian operator. The harmonic distance from a point to a source can be given by evaluating this function at that point.\n\n### 3. Stiffness Diffusion Distances\nStiffness diffusion involves simulating a diffusion process where the rate of diffusion depends on the stiffness (or conductivity) of the material in each grid cell. The distance is computed as the time taken for the diffusion front to reach a given point from a source.\n\nMathematically, let \\( u(x,t) \\) be the concentration at position \\( x \\) and time \\( t \\). The diffusion equation with stiffness \\( k(x) \\) is:\n\\[ \n\\frac{\\partial u}{\\partial t} = k(x) \\Delta u + f(x),\n\\]\nwhere \\( f(x) \\) is a source term. The distance can be computed by solving this PDE and finding the time at which the concentration reaches a certain threshold.\n\n### 4. Voronoi Distances\nVoronoi distances are based on the Voronoi diagram, where each point in space is assigned to its nearest seed (source) point. The distance from any point to its closest seed defines the Voronoi distance.\n\nMathematically, given a set of seeds \\( S = \\{ s_1, s_2, ..., s_n \\} \\), the Voronoi cell for each seed \\( s_i \\) is defined as:\n\\[ V(s_i) = \\{ x : d(x, s_i) \\leq d(x, s_j), \\forall j \neq i \\},\n\\]\nwhere \\( d(x, y) \\) denotes the Euclidean distance between points \\( x \\) and \\( y \\).\n\n### 5. Harmonic with Stiffness Distances\nHarmonic distances can be modified to account for stiffness variations in the domain by solving a weighted Laplace equation where the weights are determined by the local stiffness.\n\nMathematically, this involves solving:\n\\[ \n-\\Delta (k(x) u(x)) = 0,\n\\]\nwhere \\( k(x) \\) is the stiffness function. The harmonic distance is then given by evaluating the solution to this equation at each point in the domain.\n\n## Physical Interpretation\nThe physical interpretation of these distances varies depending on the method used:\n- **Geodesic distances** are useful for finding the shortest path along a surface, which can be relevant in scenarios where objects move along constrained paths (e.g., within a deformable object).\n- **Harmonic distances** provide smooth interpolation between boundary conditions and are often used to model potential fields or heat diffusion.\n- **Stiffness diffusion distances** simulate how signals propagate through different materials with varying stiffness, which can be relevant in mechanical simulations where material properties affect signal transmission.\n- **Voronoi distances** are useful for defining regions of influence around multiple sources and can be applied in scenarios involving nearest neighbor searches or territorial划分。让我们继续处理剩余部分并完成JSON对象的构造以符合要求格式： {",
  "abstract": "The `Distances` component computes various types of distances between sets of mechanical objects within a grid-based topology, supporting Geodesic, Harmonic, Stiffness Diffusion, Voronoi, and Harmonic with Stiffness distance metrics.",
  "sheet": "# Distances\n\n## Overview\nThe `Distances` component in SOFA is an engine designed to compute various types of distances between sets of mechanical objects within a grid-based topology. It inherits from `DataEngine`, enabling it to perform computations and update data during the simulation process.\n\n## Mathematical Model\n### Distance Types\n#### Geodesic Distances\nGeodesic distance between two points on a surface is defined as the shortest path connecting them while staying within that surface. Mathematically, let \\( P_1 \\) and \\( P_2 \\) be two points in the grid. The geodesic distance \\( d_{\\text{geo}}(P_1, P_2) \\) is given by:\n\\[ d_{\\text{geo}}(P_1, P_2) = \\min_{\\gamma} L(\\gamma), \\]\nwhere \\( \\gamma \\) represents all possible paths between \\( P_1 \\) and \\( P_2 \\), and \\( L(\\gamma) \\) is the length of the path.\n\n#### Harmonic Distances\nHarmonic distance is computed by solving a Poisson equation over the grid to find a harmonic function that interpolates between given boundary conditions (e.g., source and sink points). Mathematically, let \\( u(x) \\) be the harmonic function satisfying:\n\\[\n\\begin{cases}\n-\\Delta u = 0 & \\text{in } \\Omega,\\\\\nu(x_i) = d_i & \\text{on } \\partial \\Omega,\n\\end{cases}\n\\]\nwhere \\( x_i \\) are the boundary points with known distances \\( d_i \\), and \\( \\Delta u \\) is the Laplacian operator. The harmonic distance from a point to a source can be given by evaluating this function at that point.\n\n#### Stiffness Diffusion Distances\nStiffness diffusion involves simulating a diffusion process where the rate of diffusion depends on the stiffness (or conductivity) of the material in each grid cell. Mathematically, let \\( u(x,t) \\) be the concentration at position \\( x \\) and time \\( t \\). The diffusion equation with stiffness \\( k(x) \\) is:\n\\[\n\\frac{\\partial u}{\\partial t} = k(x) \\Delta u + f(x),\n\\]\nwhere \\( f(x) \\) is a source term. The distance can be computed by solving this PDE and finding the time at which the concentration reaches a certain threshold.\n\n#### Voronoi Distances\nVoronoi distances are based on the Voronoi diagram, where each point in space is assigned to its nearest seed (source) point. Mathematically, given a set of seeds \\( S = \\{ s_1, s_2, ..., s_n \\} \\), the Voronoi cell for each seed \\( s_i \\) is defined as:\n\\[ V(s_i) = \\{ x : d(x, s_i) \\leq d(x, s_j), \\forall j \neq i \\}, \\]\nwhere \\( d(x, y) \\) denotes the Euclidean distance between points \\( x \\) and \\( y \\).\n\n#### Harmonic with Stiffness Distances\nHarmonic distances can be modified to account for stiffness variations in the domain by solving a weighted Laplace equation where the weights are determined by the local stiffness. Mathematically, this involves solving:\n\\[\n-\\Delta (k(x) u(x)) = 0,\n\\]\nwhere \\( k(x) \\) is the stiffness function.\n\n## Parameters and Data\nThe significant Data fields exposed by the component include:\n- `d_showMapIndex`: Frame DOF index on which display values. Type: unsigned int.\n- `d_showDistanceMap`: Show the distance for each point of the target point set. Type: bool.\n- `d_showGoalDistanceMap`: Show the distance for each point of the target point set. Type: bool.\n- `d_showTextScaleFactor`: Scale to apply on the text. Type: double.\n- `d_showGradientMap`: Show gradients for each point of the target point set. Type: bool.\n- `d_showGradientsScaleFactor`: Scale for the gradients displayed. Type: double.\n- `d_offset`: Translation offset between the topology and the point set. Type: Coord.\n- `d_distanceType`: Type of distance to compute for inserted frames. Type: sofa::helper::OptionsGroup.\n- `d_initTarget`: Initialize the target MechanicalObject from the grid. Type: bool.\n- `d_initTargetStep`: Initialize the target MechanicalObject from the grid using this step. Type: int.\n- `d_harmonicMaxValue`: Max value used to initialize the harmonic distance grid. Type: double."
}