Enhance documentation in Readme and Header
Mattia Montanari
parent
9d9e8e4d26
commit
d9a9bf2a4b
21
README.md
21
README.md
|
|
@ -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.
|
||||
|
|
@ -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__
|
||||
|
|
|
|||
Loading…
Reference in New Issue