From f2871569f529413e55251dc794398ebf58bcd5e5 Mon Sep 17 00:00:00 2001 From: Mattia Montanari Date: Thu, 10 Jun 2021 23:41:30 +0200 Subject: [PATCH] Update README.md --- README.md | 231 ++---------------------------------------------------- 1 file changed, 6 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 7889209..d7b50d3 100644 --- a/README.md +++ b/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 ..`. 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.