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

View File

@ -21,15 +21,15 @@
< 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
```
followed by these commands:
Then use these commands to build and run an example:
```
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.
# 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.

View File

@ -8,7 +8,7 @@
// |_| //
// //
// Copyright 2022 Mattia Montanari, University of Oxford //
// //
// //
// This program is free software: you can redistribute it and/or modify it under //
// the terms of the GNU General Public License as published by the Free Software //
// Foundation, either version 3 of the License. You should have received a copy //
@ -20,34 +20,55 @@
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS //
// 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__
#define OPENGJK_H__
#ifdef __cplusplus
extern "C" {
extern "C"
{
#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
/// @brief Structure of a body
typedef struct gkPolytope_ {
int numpoints; // Number of points defining the body
gkFloat s[3]; // Support mapping computed last
gkFloat **coord; // Points' coordinates
} gkPolytope;
/*! @brief Data structure for convex polytopes.
*
* 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. */
typedef struct 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
typedef struct gkSimplex_ {
int nvrtx; // Number of simplex's vertices
gkFloat vrtx[4][3]; // Coordinates of simplex's vertices
} gkSimplex;
/*! @brief Data structure for simplex.
*
* The simplex is updated at each GJK-iteration. For the first itearion this value is a guess - and this guess not irrelevant. */
typedef struct 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
gkFloat compute_minimum_distance(const gkPolytope p_, const gkPolytope q_, gkSimplex *s_);
/*! @brief Invoke the GJK algorithm to compute the minimum distance between two polytopes.
*
* 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
}
#endif
#endif // OPENGJK_H__
#endif // OPENGJK_H__