231 lines
9.3 KiB
Markdown
231 lines
9.3 KiB
Markdown
|
|
openGJK {#mainpage}
|
|
=======
|
|
|
|
The openGJK library uses the Gilbert-Johnson-Keerthi (GJK) algorithm to
|
|
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
|
|
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
|
|
Using openGJK is very simple. This guide will help you getting
|
|
started compiling and using openGJK.
|
|
|
|
### 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
|
|
------------------------------------------------------------------------
|