turtlebasket
/
openGJK
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Enhance documentation in Readme and Header

fixes-turtlebasket
Mattia Montanari 2023-02-13 14:11:28 +01:00
parent 9d9e8e4d26
commit d9a9bf2a4b
2 changed files with 53 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@ -21,15 +21,15 @@
< FOR A PARTICULAR PURPOSE. See GNU General Public License for details. --> < FOR A PARTICULAR PURPOSE. See GNU General Public License for details. -->
# Get started # Getting started
If you have some basic tools installed (git, compiler and cmake) clone this repo: On Linux, Mac or Windows, if you have a basic C/C++ toolchain installed (git, compiler and cmake) clone this repo:
``` ```
git clone https://github.com/MattiaMontanari/openGJK.git git clone https://github.com/MattiaMontanari/openGJK.git
``` ```
followed by these commands: Then use these commands to build and run an example:
``` ```
cmake -E make_directory build cmake -E make_directory build
@ -44,8 +44,17 @@ If you get no errors, the successfull output is:
However, if you do get an error - any error - please file a bug! Support requests are welcome too. However, if you do get an error - any error - please file a bug! Support requests are welcome too.
# Beyond getting started # Use OpenGJK in your project
With the commands above you have built a demo example tha invokes the openGJK library. The library is statically linked and the distance between two bodies is computed and returned. The best source to learn how to use OpenGJK are the examples. They are listed [here](https://www.mattiamontanari.com/opengjk/docs/examples/) for C, C#, Go, Matlab and Python. I aim to publish few more for Julia and Unity.
To learn how to use this library in your project the best place to start is the demo. Look at `main.c` and the other examples. In `examples/c/CMakeLists.txt` you can find how simple is to link using CMake. Take a look at the `examples` folder in this repo and have fun. File a request if you wish to see more!
# Contribute
You are very welcome to:
- Create pull requests of any kind
- Let me know if you are using this library and find it usefule
- Open issues with request for support because they will help you and many others
- Cite this repository ([a sweet GitHub feature](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#about-citation-files)) or my paper: Montanari, M. et at, *Improving the GJK Algorithm for Faster and More Reliable Distance Queries Between Convex Objects* (2017). ACM Trans. Graph.

51
include/openGJK/openGJK.h
View File

@ -20,31 +20,52 @@
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS // // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS //
// FOR A PARTICULAR PURPOSE. See GNU General Public License for details. // // FOR A PARTICULAR PURPOSE. See GNU General Public License for details. //
/**
* @file openGJK.h
* @author Mattia Montanari
* @date 1 Jan 2022
* @brief Main interface of OpenGJK containing quick reference and API documentation.
*
* More extensive explanation of what the header
* @see http://google.com
*/
#ifndef OPENGJK_H__ #ifndef OPENGJK_H__
#define OPENGJK_H__ #define OPENGJK_H__
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C"
{
#endif #endif
/// @brief Use double as default precision /*! @brief Precision of floating-point numbers.
*
* Default is set to 64-bit (Double). Change this to quickly play around with 16- and 32-bit. */
#define gkFloat double #define gkFloat double
/// @brief Structure of a body /*! @brief Data structure for convex polytopes.
typedef struct gkPolytope_ { *
int numpoints; // Number of points defining the body * Polytopes are three-dimensional shapes and the GJK algorithm works directly on their convex-hull. However the convex-hull is never computed explicity, instead each GJK-iteraion employs a support function that has a cost linearly dependen on the number of points defining the polytope. */
gkFloat s[3]; // Support mapping computed last typedef struct gkPolytope_
gkFloat **coord; // Points' coordinates {
} gkPolytope; int numpoints; /*!< Number of points defining the polytope. */
gkFloat s[3]; /*!< Furthest point retunred by the support function and updated at each GJK-iteration. For the first itearion this value is a guess - and this guess not irrelevant. */
gkFloat **coord; /*!< Coordinates of the points of the polytope. This is owned by user who manages and garbage-collects the memory for these coordinates. */
} gkPolytope;
/// @brief Structure of the simplex /*! @brief Data structure for simplex.
typedef struct gkSimplex_ { *
int nvrtx; // Number of simplex's vertices * The simplex is updated at each GJK-iteration. For the first itearion this value is a guess - and this guess not irrelevant. */
gkFloat vrtx[4][3]; // Coordinates of simplex's vertices typedef struct gkSimplex_
} gkSimplex; {
int nvrtx; /*!< Number of points defining the simplex. */
gkFloat vrtx[4][3]; /*!< Coordinates of the points of the simplex. */
} gkSimplex;
/// @brief Uses the GJK algorithm to compute the minimum distance between two bodies /*! @brief Invoke the GJK algorithm to compute the minimum distance between two polytopes.
gkFloat compute_minimum_distance(const gkPolytope p_, const gkPolytope q_, gkSimplex *s_); *
* The simplex has to be initialised prior the call to this function. */
gkFloat compute_minimum_distance(const gkPolytope p_, const gkPolytope q_, gkSimplex *s_);
#ifdef __cplusplus #ifdef __cplusplus
} }