Update README.md
Mattia Montanari
GitHub
parent
8d53d5142e
commit
f2871569f5
231
README.md
231
README.md
|
|
@ -1,230 +1,11 @@
|
||||||
|
|
||||||
openGJK {#mainpage}
|
Hello!
|
||||||
=======
|
=======
|
||||||
|
|
||||||
The openGJK library uses the Gilbert-Johnson-Keerthi (GJK) algorithm to
|
I'll never have enough time for this project, but contributes are welcome! Please check out [docs and more details here](https://www.mattiamontanari.com/opengjk/).
|
||||||
compute the minimum distance between convex polytopes. The
|
|
||||||
implementation follows the description presented in
|
|
||||||
"[Improving the GJK Algorithm for Faster and More Reliable Distance
|
|
||||||
Queries Between Convex Objects. ACM Trans. on Graph. 2017](https://dl.acm.org/citation.cfm?id=3083724)" and has been tested
|
|
||||||
on Unix and Windows systems for C, C# and Matlab programs.
|
|
||||||
|
|
||||||
This library offers researchers a tool that works
|
The best code is in dev branch - Enjoy!
|
||||||
out of the box: you can import it in your program and use it to measure
|
|
||||||
the distance between two convex polytopes in 3D. All it needs are the
|
|
||||||
coordinates of the vertices describing the two bodies.
|
|
||||||
This library is not optimised for production, but it does provide a comprehensive and robust implementation. It is sufficiently fast for
|
|
||||||
most applications, and you can also build from here to suite your own
|
|
||||||
application. For instance, openGJK is not for incremental and is not
|
|
||||||
for NURBS, but it offers a good starting point for such specific
|
|
||||||
applications.
|
|
||||||
|
|
||||||
## Getting Started
|
> openGJK, Copyright (c) 2018-2021
|
||||||
Using openGJK is very simple. This guide will help you getting
|
>
|
||||||
started compiling and using openGJK.
|
> Department of Engineering Science. University of Oxford, UK.
|
||||||
|
|
||||||
### When should I use openGJK?
|
|
||||||
|
|
||||||
OpenGJK is designed with accuracy and robustness in mind and is
|
|
||||||
suitable for engineering simulations. Good use of this library
|
|
||||||
include the finite element method (FEM) and discrete element method (DEM).
|
|
||||||
|
|
||||||
Basically, openGJK can measure the distance between **any convex polytope**. For example:
|
|
||||||
- line segments
|
|
||||||
- triangles
|
|
||||||
- tetrahedrons
|
|
||||||
- cubes.
|
|
||||||
|
|
||||||
### Installing the openGJK library
|
|
||||||
|
|
||||||
#### Prerequisites
|
|
||||||
|
|
||||||
1. A compiler (gnu or Microsoft Visual Studio for C)
|
|
||||||
2. CMake version 3.5 or above
|
|
||||||
3. Only for the Matlab interface you will need to build mex files (find out the requisites from [Mathworks documentation](https://uk.mathworks.com/help/matlab/matlab_external/what-you-need-to-build-mex-files.html)).
|
|
||||||
4. Only for the C# interface on Unix you will need [mono](http://www.mono-project.com/) and Microsoft Visual Studio toolchain for C# on Windows.
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
|
|
||||||
There are CMake files for compiling openGJK in the usual
|
|
||||||
way:
|
|
||||||
1. Create a new folder in the folder containing this readme file.
|
|
||||||
2. Move into that folder and type `cmake -G <duild-system> ..`. For example,
|
|
||||||
on Windows you can type `cmake -G "Visual Studio 15 2017 Win64" ..`, on Unix `cmake -G "Unix Makefiles" ..`.
|
|
||||||
3. Use the files generated by Cmake to build the library. Whether you compile
|
|
||||||
with `make` or an IDE, you will build a shared library and an executable
|
|
||||||
for the C example. For Matlab and C# applications, see sections below.
|
|
||||||
|
|
||||||
To install the library you should copy the header file openGJK.h and the binaries in a folder accessible in the search path by all users (on Unix this would normally be /usr/local).
|
|
||||||
|
|
||||||
### Automated documentation
|
|
||||||
The folder `doc` contains a Doxygen file for generating the documentation of the whole
|
|
||||||
library. To build the documentation cd into `doc` and call Doxygen from the command line simply by typing `doxygen`. If correctly installed, Doxygen will create html documentation with graphs illustrating the call stack of the functions of the library.
|
|
||||||
|
|
||||||
## API user reference
|
|
||||||
|
|
||||||
```double gjk( struct bodyA, struct bodyB, struct simplex)```
|
|
||||||
|
|
||||||
### Parameters
|
|
||||||
* **bodyA** The first body.
|
|
||||||
* **bodyB** The second body.
|
|
||||||
* **simplex** The simplex used the GJK algorithm at the first iteration.
|
|
||||||
|
|
||||||
### Returns
|
|
||||||
* **double** the minimum distance between bodyA and bodyB.
|
|
||||||
|
|
||||||
### Description
|
|
||||||
The function `gjk` computes the minimum Euclidean distance between two bodies using the
|
|
||||||
GJK algorithm. Note that the simplex used at the first iteration may be initialised by the user, but this is not necessary.
|
|
||||||
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
openGJK comes in two flavours: *accurate* and *fast* (default). You can
|
|
||||||
change before compiling by editing the main 'lib\CMakeLists.txt' file
|
|
||||||
(in the folder `lib`). Set the option `VERSION_ACCURATE` to `ON` and
|
|
||||||
run CMake. You can verify what version is being compiled from the terminal,
|
|
||||||
if you do not see "Version: Accurate" when calling CMake, you have to clean
|
|
||||||
the CMake cache.
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
This section presents three examples on how to use openGJK with C, C# and Matlab.
|
|
||||||
All the examples have been tested both Linux and Windows; the former used `make` and `gcc`,
|
|
||||||
the latter using `Visual studio 2017` and its compiler. Only x64 systems have been tested.
|
|
||||||
|
|
||||||
### C
|
|
||||||
This example illustrates how to include openGJK in an existing C
|
|
||||||
program.
|
|
||||||
|
|
||||||
All files for the example are in the `example1_c` folder. The executable built with
|
|
||||||
CMake reads the coordinates of two polytopes from the input files,
|
|
||||||
respectively userP.dat and userQ.dat, and computes the minimum distance
|
|
||||||
between them.
|
|
||||||
|
|
||||||
Notice that the input files must be in the folder from which the executable
|
|
||||||
is launched, otherwise an error is returned.
|
|
||||||
|
|
||||||
You can edit the coordinates in the input file to test different
|
|
||||||
polytopes; just remember to edit also the first number in the files
|
|
||||||
that corresponds to the numbers of vertices that the program will read.
|
|
||||||
|
|
||||||
### Matlab
|
|
||||||
This example illustrates how to invoke openGJK as a regular built-in
|
|
||||||
Matlab function.
|
|
||||||
|
|
||||||
Open Matlab and cd into the `example2_mex` folder. By running the
|
|
||||||
script `runme.m`, Matlab will first compile a mex file (telling you
|
|
||||||
about the name of the mex file generated) and will call the script
|
|
||||||
`main.m`. This invokes openGJK within Matlab and illustrates the
|
|
||||||
result.
|
|
||||||
|
|
||||||
The mex file may be copied and called from any other Matlab project.
|
|
||||||
|
|
||||||
### C# #
|
|
||||||
This example illustrates how to invoke openGJK in an applications written in C#.
|
|
||||||
The only file required is in the `example3_csharp` folder. This can be compiled in Unix
|
|
||||||
with mono, or in Windows using Visual Studio. Notice that, however, the openGJK library
|
|
||||||
is compiled for a specific architecture (usually x64), and this breaks the portability
|
|
||||||
of the .NET application compiled in this example.
|
|
||||||
|
|
||||||
Below are the steps for compiling the C# application on Windows and Linux. Both
|
|
||||||
procedures assume the dynamic library of openGJK has been already compiled.
|
|
||||||
|
|
||||||
#### Compile on Windows
|
|
||||||
1. Move into the folder `example3_csharp` and create a new folder `example3`.
|
|
||||||
2. Copy into this folder the openGJK library or make it available in any directory.
|
|
||||||
3. Open Visual Studio and create a new project. As project type select **Console App (.NET Framework)**.
|
|
||||||
4. Add to this project the `main.cs` file
|
|
||||||
5. Set x64 as the target platform, compile the application and run it.
|
|
||||||
|
|
||||||
|
|
||||||
#### Compile on Linux
|
|
||||||
1. Move into the folder `example3_csharp` and create a new folder `example3`.
|
|
||||||
2. Copy into this folder the openGJK library or install is so that is available in any directory.
|
|
||||||
3. Move into that new folder and open a terminal.
|
|
||||||
4. Type `mcs -out:example3demo -d:UNIX ../main.cs`
|
|
||||||
5. Run the example by typing `mono example3demo`
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Repository content
|
|
||||||
This repository contains the following files and folders:
|
|
||||||
|
|
||||||
```
|
|
||||||
│ CMakeLists.txt
|
|
||||||
│ README.md
|
|
||||||
│
|
|
||||||
├───doc
|
|
||||||
│ openGJKcustomfooter.html
|
|
||||||
│ openGJKcustomheader.html
|
|
||||||
│ openGJKcustomstyle.css
|
|
||||||
│ Doxyfile
|
|
||||||
│ oxfordLogo.jpg
|
|
||||||
│
|
|
||||||
├───example1_c
|
|
||||||
│ CMakeLists.txt
|
|
||||||
│ main.c
|
|
||||||
│ userP.dat
|
|
||||||
│ userQ.dat
|
|
||||||
│
|
|
||||||
├───example2_mex
|
|
||||||
│ main.m
|
|
||||||
│ runme.m
|
|
||||||
│
|
|
||||||
├───example3_csharp
|
|
||||||
│ main.cs
|
|
||||||
│
|
|
||||||
└───lib
|
|
||||||
│ CMakeLists.txt
|
|
||||||
│
|
|
||||||
├───ext
|
|
||||||
│ predicates.c
|
|
||||||
│ predicates.h
|
|
||||||
│
|
|
||||||
├───include
|
|
||||||
│ └───openGJK
|
|
||||||
│ openGJK.h
|
|
||||||
│
|
|
||||||
└───src
|
|
||||||
openGJK.c
|
|
||||||
```
|
|
||||||
|
|
||||||
## Where to go next?
|
|
||||||
|
|
||||||
A clear presentation of the GJK algorithm can be found in the
|
|
||||||
book by **Van der Bergen** *Collision Detection in Interactive 3D
|
|
||||||
Environments*, edited by Elsevier.
|
|
||||||
|
|
||||||
More details about the GJK algorithm can be found in the original paper
|
|
||||||
from Gilbert, Johnson and Keerthi [A fast procedure for computing the distance between complex objects in three-dimensional space](http://ieeexplore.ieee.org/document/2083/?arnumber=2083).
|
|
||||||
|
|
||||||
OpenGJK implements the GJK algorithm as described in: [Improving the GJK Algorithm for Faster and More Reliable Distance
|
|
||||||
Queries Between Convex Objects. ACM Trans. on Graph. 2017 ](https://dl.acm.org/citation.cfm?id=3083724). Refer to this papar for further details on the method.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Licence
|
|
||||||
|
|
||||||
This open-source edition of openGJK is released under the terms of
|
|
||||||
[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) License.
|
|
||||||
This means that any software created with this library you must comply
|
|
||||||
with the terms of this licence. If you are seeking another licence please
|
|
||||||
contact the author at the address at the end of this file.
|
|
||||||
|
|
||||||
openGJK may use the geometric predicates from *Routines for Arbitrary
|
|
||||||
Precision Floating-point Arithmetic*, by Jonathan Richard Shewchuk,
|
|
||||||
whose source code is included in the file predicates.c of this
|
|
||||||
repository for convenience.
|
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
|
||||||
openGJK, Copyright (c) 2018
|
|
||||||
|
|
||||||
Impact Engineering Laboratory
|
|
||||||
Department of Engineering Science
|
|
||||||
University of Oxford
|
|
||||||
Parks Road, Oxford, OX1 3PJ
|
|
||||||
|
|
||||||
mattia.montanari@eng.ox.ac.uk
|
|
||||||
------------------------------------------------------------------------
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue