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
|
||||
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.
|
||||
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/).
|
||||
|
||||
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.
|
||||
The best code is in dev branch - Enjoy!
|
||||
|
||||
## 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
|
||||
------------------------------------------------------------------------
|
||||
> openGJK, Copyright (c) 2018-2021
|
||||
>
|
||||
> Department of Engineering Science. University of Oxford, UK.
|
||||
|
|
|
|||
Loading…
Reference in New Issue