body_pos: Doxygen documentation

namespace soil_simulator

Functions

void CalcBodyPos(SimOut *sim_out, std::vector<float> pos, std::vector<float> ori, Grid grid, Bucket *bucket, SimParam sim_param, float tol)

This function determines all the cells where the bucket is located.

The bucket position is calculated based on its reference pose stored in the Bucket class, as well as the provided position (pos) and orientation (ori). pos and ori are used to apply the appropriate translation and rotation to the bucket relative to its reference pose. The centre of rotation is assumed to be the bucket origin. The orientation is provided using the quaternion definition.

Parameters:

  • sim_out – Class that stores simulation outputs.

  • pos – Cartesian coordinates of the bucket origin. [m]

  • ori – Orientation of the bucket. [Quaternion]

  • grid – Class that stores information related to the simulation grid.

  • bucket – Class that stores information related to the bucket object.

  • sim_param – Class that stores information related to the simulation.

  • tol – Small number used to handle numerical approximation errors.

void CalcBodyPos(SimOut *sim_out, std::vector<float> pos, std::vector<float> ori, Grid grid, Blade *blade, SimParam sim_param, float tol)

This function determines all the cells where the blade is located.

The blade position is calculated based on its reference pose stored in the Blade class, as well as the provided position (pos) and orientation (ori). pos and ori are used to apply the appropriate translation and rotation to the blade relative to its reference pose. The centre of rotation is assumed to be the blade origin. The orientation is provided using the quaternion definition.

Parameters:

  • sim_out – Class that stores simulation outputs.

  • pos – Cartesian coordinates of the blade origin. [m]

  • ori – Orientation of the blade. [Quaternion]

  • grid – Class that stores information related to the simulation grid.

  • blade – Class that stores information related to the blade object.

  • sim_param – Class that stores information related to the simulation.

  • tol – Small number used to handle numerical approximation errors.

std::vector<std::vector<int>> CalcRectanglePos(std::vector<float> a, std::vector<float> b, std::vector<float> c, std::vector<float> d, Grid grid, float tol)

This function determines the cells where a rectangle surface is located.

The rectangle is defined by providing the Cartesian coordinates of its four vertices in the proper order.

To optimize performance, the function iterates over a portion of the horizontal grid where the rectangle is located. For each cell, the function calculates the height of the plane formed by the rectangle at the top right corner of the cell. If the cell is within the rectangle area, the calculated height is added to the results for the four neighbouring cells.

This method works because when a plane intersects with a rectangular cell, the minimum and maximum height of the plane within the cell occurs at one of the cell corners. By iterating through all the cells, the function ensures that all the corners of each cell are investigated.

However, this approach does not work when the rectangle is perpendicular to the XY plane. To handle this case, the function uses the CalcLinePos function to include the cells that lie on the four edges of the rectangle.

Note:

  • The iteration is performed over the top right corner of each cell, but any other corner could have been chosen without affecting the results.

  • Not all cells are provided, since, at a given XY position, only the cells with the minimum and maximum height are important.

  • When the rectangle follows a cell border, the exact location of the rectangle becomes ambiguous. It is assumed that the caller resolves this ambiguity.

Parameters:

  • a – Cartesian coordinates of one vertex of the rectangle. [m]

  • b – Cartesian coordinates of one vertex of the rectangle. [m]

  • c – Cartesian coordinates of one vertex of the rectangle. [m]

  • d – Cartesian coordinates of one vertex of the rectangle. [m]

  • grid – Class that stores information related to the simulation grid.

  • tol – Small number used to handle numerical approximation errors.

Returns:

Collection of cells indices where the rectangle is located. Result is not sorted and duplicates may be present.

std::tuple<std::vector<std::vector<float>>, std::vector<std::vector<float>>, std::vector<std::vector<bool>>, int> DecomposeVectorRectangle(std::vector<float> ab_ind, std::vector<float> ad_ind, std::vector<float> a_ind, int area_min_x, int area_min_y, int area_length_x, int area_length_y, float tol)

This function performs a vector decomposition on a portion of the horizontal plane where a rectangle ABCD is located.

The position of the rectangle is defined by its edges AB and AD, while the specified area extends over [area_min_x, area_min_x + area_length_x] on the X direction and [area_min_y, area_min_y + area_length_y] on the Y direction.

For each cell in the specified area, the function decomposes it into the basis formed by the vectors AB and AD. Let O be the name of a cell, it can then be decomposed as

AO = c_ab * AB + c_ad * AD.

This decomposition leads to a system of 2 equations with 2 unknowns (c_ab and c_ad)

AO[1] = c_ab * AB[1] + c_ad * AD[1] {1},
AO[2] = c_ab * AB[2] + c_ad * AD[2] {2}.

One may note that AB[1] * {2} - AB[2] * {1} implies that

AB[1] * AO[2] - AB[2] * AO[1] = c_ad * AD[2] * AB[1] - c_ad * AD[1] * AB[2]

that can be further rewritten as

c_ad = (AB[1] * AO[2] - AB[2] * AO[1]) / (AD[2] * AB[1] - AD[1] * AB[2]).

Similarly, AD[1] * {2} - AD[2] * {1} implies that

c_ab = -(AD[1] * AO[2] - AD[2] * AO[1]) / (AD[2] * AB[1] - AD[1] * AB[2]).

This decomposition allows us to determine whether the cell O is inside the rectangle area, since this requires c_ab and c_ad to be between 0 and 1.

Note: By convention, the decomposition is done at the top right corner of each cell.

Parameters:

  • ab_ind – Indices representing the edge AB of the rectangle.

  • ad_ind – Indices representing the edge AD of the rectangle.

  • a_ind – Indices of the vertex A from which the edges AB and AD start.

  • area_min_x – Minimum index in the X direction of the specified area.

  • area_min_y – Minimum index in the Y direction of the specified area.

  • area_length_x – Number of grid elements in the X direction of the specified area.

  • area_length_y – Number of grid elements in the Y direction of the specified area.

  • tol – Small number used to handle numerical approximation errors.

Returns:

A tuple composed of a vector of vector giving the vector decomposition in terms of the AB component, a vector of vector giving the vector decomposition in terms of the AD component, a vector of vector indicating whether the cell is inside the rectangle area, and the number of cells inside the rectangle area.

std::vector<std::vector<int>> CalcTrianglePos(std::vector<float> a, std::vector<float> b, std::vector<float> c, Grid grid, float tol)

This function determines the cells where a triangle surface is located.

The triangle is defined by providing the Cartesian coordinates of its three vertices in the proper order.

To optimize performance, the function iterates over a portion of the horizontal grid where the triangle is located. For each cell, the function calculates the height of the plane formed by the triangle at the top right corner of the cell. If the cell is within the triangle area, the calculated height is added to the results for the four neighbouring cells.

This method works because when a plane intersects with a rectangular cell, the minimum and maximum height of the plane within the cell occurs at one of the cell corners. By iterating through all the cells, the function ensures that all the corners of each cell are investigated.

However, this approach does not work when the triangle is perpendicular to the XY plane. To handle this case, the function uses the CalcLinePos function to include the cells that lie on the three edges of the triangle.

Note:

  • The iteration is performed over the top right corner of each cell, but any other corner could have been chosen without affecting the results.

  • Not all cells are provided, since, at a given XY position, only the cells with the minimum and maximum height are important.

  • When the triangle follows a cell border, the exact location of the triangle becomes ambiguous. It is assumed that the caller resolves this ambiguity.

Parameters:

  • a – Cartesian coordinates of one vertex of the triangle. [m]

  • b – Cartesian coordinates of one vertex of the triangle. [m]

  • c – Cartesian coordinates of one vertex of the triangle. [m]

  • grid – Class that stores information related to the simulation grid.

  • tol – Small number used to handle numerical approximation errors.

Returns:

Collection of cells indices where the triangle is located. Result is not sorted and duplicates may be present.

std::tuple<std::vector<std::vector<float>>, std::vector<std::vector<float>>, std::vector<std::vector<bool>>, int> DecomposeVectorTriangle(std::vector<float> ab_ind, std::vector<float> ac_ind, std::vector<float> a_ind, int area_min_x, int area_min_y, int area_length_x, int area_length_y, float tol)

This function performs a vector decomposition on a portion of the horizontal plane where a tritangle ABC is located.

The position of the triangle is defined by its edges AB and AC, while the specified area extends over [area_min_x, area_min_x + area_length_x] on the X direction and [area_min_y, area_min_y + area_length_y] on the Y direction.

For each cell in the specified area, the function decomposes it into the basis formed by the vectors AB and AC. Let O be the name of a cell, it can then be decomposed as

AO = c_ab * AB + c_ac * AC.

This decomposition leads to a system of 2 equations with 2 unknowns (c_ab and c_ac)

AO[1] = c_ab * AB[1] + c_ac * AC[1] {1},
AO[2] = c_ab * AB[2] + c_ac * AC[2] {2}.

One may note that AB[1] * {2} - AB[2] * {1} implies that

AB[1] * AO[2] - AB[2] * AO[1] = c_ac * AC[2] * AB[1] - c_ac * AC[1] * AB[2]

that can be further rewritten as

c_ac = (AB[1] * AO[2] - AB[2] * AO[1]) / (AC[2] * AB[1] - AC[1] * AB[2]).

Similarly, AC[1] * {2} - AC[2] * {1} implies that

c_ab = -(AC[1] * AO[2] - AC[2] * AO[1]) / (AC[2] * AB[1] - AC[1] * AB[2]).

This decomposition allows us to determine whether the cell O is inside the triangle area, since this requires c_ab and c_ac to be between 0 and 1, and the sum of c_ab and c_ac to be lower than 1.

Note: By convention, the decomposition is done at the top right corner of each cell.

Parameters:

  • ab_ind – Indices representing the edge AB of the triangle.

  • ac_ind – Indices representing the edge AC of the triangle.

  • a_ind – Indices of the vertex A from which the edges AB and AC start.

  • area_min_x – Minimum index in the X direction of the specified area.

  • area_min_y – Minimum index in the Y direction of the specified area.

  • area_length_x – Number of grid elements in the X direction of the specified area.

  • area_length_y – Number of grid elements in the Y direction of the specified area.

  • tol – Small number used to handle numerical approximation errors.

Returns:

A tuple composed of a vector of vector giving the vector decomposition in terms of the AB component, a vector of vector giving the vector decomposition in terms of the AC component, a vector of vector indicating whether the cell is inside the triangle area, and the number of cells inside the triangle area.

std::vector<std::vector<int>> CalcLinePos(std::vector<float> a, std::vector<float> b, Grid grid)

This function determines all the cells that lie on a straight line between two Cartesian coordinates.

The algorithm implemented in this function comes from the article: “A Fast Voxel Traversal Algorithm for Ray Tracing” by J. Amanatides and A. Woo.

The floating-point values are rounded to obtain the cell indices in the X, Y, Z directions. As the centre of each cell is considered to be on the centre of the top surface, round should be used for getting the cell indices in the X and Y direction, while ceil should be used for the Z direction.

Note: When the line follows a cell border, the exact location of the line becomes ambiguous. It is assumed that the caller resolves this ambiguity.

Parameters:

  • a – Cartesian coordinates of the first extremity of the line. [m]

  • b – Cartesian coordinates of the second extremity of the line. [m]

  • grid – Class that stores information related to the simulation grid.

Returns:

Collection of cells indices where the line is located.

void UpdateBody(std::vector<std::vector<int>> area_pos, SimOut *sim_out, Grid grid, float tol)

This function updates the body position in body following the cells composing area_pos.

For each XY position, the first cell found in area_pos corresponds to the minimum height of the body, while the last one provides the maximum height. As a result, this function must be called separately for each body wall and area_pos must be sorted.

Parameters:

  • area_pos – A collection of cell indices specifying where a body wall is located.

  • sim_out – Class that stores simulation outputs.

  • grid – Class that stores information related to the simulation grid.

  • tol – Small number used to handle numerical approximation errors.

void IncludeNewBodyPos(SimOut *sim_out, int ii, int jj, float min_h, float max_h, float tol)

This function updates the body position in body at the coordinates (ii, jj).

The minimum and maximum heights of the body at that position are given by min_h and max_h, respectively. If the given position overlaps with an existing position, then the existing position is updated as the union of the two positions. Otherwise, a new position is added to body_.

Parameters:

  • sim_out – Class that stores simulation outputs.

  • ii – Index of the considered position in the X direction.

  • jj – Index of the considered position in the Y direction.

  • min_h – Minimum height of the body. [m]

  • max_h – Maximum height of the body. [m]

  • tol – Small number used to handle numerical approximation errors.