Getting Started

Download from Github


To get a head-start and avoid installing all the dependences, a Docker image (based on Ubuntu 16.04 LTS) was created. A Docker image is a stripped-to-the-bare-bones Linux image. Just install Docker in your machine (it is multiplatform, i.e., Linux, Windows, and Mac), download and run the OpenGA image (instructions below). As a result, it is going to create a container (which is similar to a virtual machine) inside your host system with all the necessary elements: tools, libraries, and source code.

IMPORTANT: at this moment, only the standard GAAFs are able to be run with the Docker image. The pose-estimation GAAFs (which are called using Matlab) are included in the GitHub repository files (soon the Python-based scripts will be also available).

Step-by-step to use the OpenGA image:

  1. Download the GitHub files containing all the source codes and scripts, or clone the respository: 
    $ git clone https://github.com/wilderlopes/OpenGA.git

  2. Install Docker.
    The procedure varies by operating system. Go here for Linux and here for Windows or Mac OS.

  3. It is time to download the OpenGA Docker image. There are three ways of doing it:
    • Method A: Pull it from Docker Hub (easiest and recommended): 
      $ docker pull wilderlopes/openga
    • Method B: Download the OpenGA Docker image from here (2.4 GB .tar file). After the download, you can load it into your docker like so 
      $ docker load < openga.tar
    • Method C: Alternatively, you can build the image in your host system using the Dockerfile provided with the GitHub repository. See how to do it here.

  4. Whatever is the alternative chosen above, you should now have the OpenGA Docker image available. To check it, run the following command (Linux users): 
    $ docker images
    You should expect an output similar to 
    REPOSITORY           TAG                 IMAGE ID            CREATED             SIZE
wilderlopes/openga   latest              beb957393d05        About an hour ago   2.45GB

  5. It is time to run the image. Go inside the folder you downloaded (cloned) from the GitHub 
    $ cd OpenGA
    You will find the file "start.sh". Run it like 
    $ ./start.sh
    This file runs the Docker image, creating a container. You will find yourself inside the container, in the directory '/home/openga' (notice that the prompt changes, showing the container ID -- it will be a different one for you). A welcome message is printed: 
    root@2095a07347a0:/home/openga# Welcome to OpenGA! Please have a look on the README file or access www.openga.org.
  6. Let's run a simulation to check if everything works as expected. Navigate to the python scripts directory: 
    root@2095a07347a0:/home/openga# cd scripts/GAAFs_standard/python/
    There you find the python script 'gaafs.py', which you can run as 
    root@2095a07347a0:/home/openga/scripts/GAAFs_standard/python# python gaafs.py
    It will run 100 realizations, each with 1000 iterations, of the GA-LMS (standard) in a system identification task. The estimated and optimal multivectors are printed on the terminal, and MSE and EMSE learning curves are saved in the file 'learningCurvesGA-LMS.pdf' inside the working path. At the moment, the only way to change the coefficients of the plant to be identified (optimal weights) is modifying the source codes and rebuilding the binaries.
    You can open the file 'learningCurvesGA-LMS.pdf' from your host computer (the container does not have a pdf reader). Go to 
    $ cd OpenGA/scripts/GAAFs_standard/python
    There you will find the same 'learningCurvesGA-LMS.pdf' which you can open with your pdf reader.
If you are in trouble, fell free to contact us.

Tutorials

Some plain-text tutorials for different applications.

  1. Running the GA-LMS (standard) in a system identification task

  2. Running the GA-LMS (pose estimation) in a 3D point cloud registration task

    3. The files to run the GAAFs for pose estimation are located in the GitHub repository: 
    openga/scripts/GAAFs_poseEstimation/

    There you can also find a video showing the performance of the GA-LMS estimating the relative rotation between two point clouds.
    • Matlab example [Coming soon]
    • Python example [Coming soon]

Scientific Literature

The following selected publications and websites provide a starting point for those who are willing to conduct research on/with Geometric Algebra.