Getting Started

There are two ways of getting started with OpenGA:

  1. [Jupyter Notebooks]

    Simply download the files from GitHub (or clone the repository) and run the examples. There are examples for Python and MATLAB. Note that those are provided as Jupyter notebooks, which should be previously installed in your computer (see here how to do it). Also, some extra packages need to be installed (see list in the GitHub page).

  2. [Docker Image] (Recommended) ---> Download image (497 MB)

    Python notebooks are great. However, as pointed out on the README file in the GitHub repository, before running the tutorials one still needs to install the dependencies (libraries and packages). Thus, to get a head-start on using OpenGA, a Docker image (based on Ubuntu 14.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 are included in the GitHub repository files.

    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 - Download the OpenGA Docker image from here. It is a .tar file with 497 MB in size. Alternatively, you can build the image in your host system using the Dockerfile provided with the GitHub files. See how to do it here.

    4 - Load the OpenGA docker image:

    $ docker load < openga.tar

    5 - Now you should 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
    openga              latest              cd321034fc07        2 hours ago         495.2 MB

    6 - 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.
    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). Navigate to the directory containing the files you downloaded from GitHub (in this case 'OpenGA') and do like this
    $ 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.