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" 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).
4. Only for the C# interface on Unix you will need mono 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.

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 . 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 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

                   [email protected]