Metadata-Version: 2.1
Name: gaikpy
Version: 0.3.4.2
Summary: Calculates and visualises forward and (full-pose) inverse kinematic realised with a genetic algorithm (ga) for URDF models
Home-page: https://github.com/knowledgetechnologyuhh/gaikpy
Author: Erik Strahl
Author-email: strahl@informatik.uni-hamburg.de
License: UNKNOWN
Platform: Posix; Linux; MacOS X; Windows
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
Requires-Dist: Sphinx
Requires-Dist: m2r2
Requires-Dist: sphinxcontrib-napoleon
Requires-Dist: numpy
Requires-Dist: scipy (==1.4.1)
Requires-Dist: sympy
Requires-Dist: math3d
Requires-Dist: matplotlib
Requires-Dist: transforms3d
Requires-Dist: urdfpy
Requires-Dist: ikpy (==3.0.1)

# Introduction

![Nico using ik](https://github.com/knowledgetechnologyuhh/gaikpy/blob/main/nico_ik.jpg?raw=true "NICO ik")

gaikpy is a pure python approach to solve the inverse kinematics for every URDF modelled robot.

gaikpy solves the inverse kinematics for every URDF based robot model using a genetic algorithm approach. No pretraining is needed. gaikpy is completely realised in python. gaikpy has already integrated the [NICO robot](https://www.inf.uni-hamburg.de/en/inst/ab/wtm/research/neurobotics/nico.html), but you can easily extend this with every robot with a URDF model at hand. Just take the URDF and define your chain ( containing the joints you want to use) , calculate the ik and maybe visualize it. 

If you use the library in an academic context, you can cite it by citing the paper below. We analysed the ik in a hybrid manipulation context for the NICO robot ( the measured calculation times in the paper are already outdated, gaikpy is much faster now ).

Neuro-Genetic Visuomotor Architecture for Robotic Grasping   
Matthias Kerzel, Josua Spisak, Erik Strahl, Stefan Wermter
Artificial Neural Networks and Machine Learning – ICANN 2020, pages 533-545 - 2020.

https://www2.informatik.uni-hamburg.de/wtm/publications/2020/KSSW20/ICANN_2020__Neuro_Genetic_Visuomotor_Framework_Preprint.pdf

# History and credits

The Neuro Inspired COmpanion ( or [NICO](https://www.inf.uni-hamburg.de/en/inst/ab/wtm/research/neurobotics/nico.html) ) is the robot we developed at the [Knowledge Technology group](https://www.inf.uni-hamburg.de/en/inst/ab/wtm/about.html) at the [University of Hamburg](https://www.uni-hamburg.de/en.html) to fullfill our [research needs](https://www2.informatik.uni-hamburg.de/wtm/publications/2017/KSMNHW17/NICO_RO-MAN_2017-PREPRINT-2017.pdf). 

Our philosophy is to have a full python based interface for the NICO ( besides our ROS based interface ), so we searched first for an existing python based ik library. We found [ikpy](https://github.com/Phylliade/ikpy), which is a great software, but was at least at time we started not able to solve the full-pose ik ( but only the position ) for our NICO robot. 

As we favour the idea of bioinspired algoritms in our group and one of our former students has [developed a genetic based ik approach in C#](https://ieeexplore.ieee.org/document/7866587), we took parts of this concept and adapted this to our python approach, which you see here with gaikpy.


![Nico using ik](https://github.com/knowledgetechnologyuhh/gaikpy/blob/main/nico_opt.gif?raw=true "NICO ik")

# Installation

## From the pypi repository

+ create a python environment

    python3 -m venv env
+ activate the environement

    source ./env/bin/activate
+ get gaikpy and the depening packages

    pip install gaikpy
+ run the demo

    demo.py

## Using the souce code from github

+ Clone the repository with git clone

    git clone https://github.com/knowledgetechnologyuhh/gaikpy.git
+ Change to the directory

    cd gaikpy
+ Create a python environment

    python3 -m venv env
+ Activate your environment 

    source ./env/bin/activate
+ Install

    python setup.py develop 

or 

    python setup.py install
+ Run the test

    python setup.py test
You should have no errors ( warnings are fine, the included libraries might throw some)
+ Run the demo

    python demo.py


# Build the docs

+ cd gaikpy/docs
+ make html
+ browse at gaikpy/docs/build/html

# Usage

Use the gaikpy to solve the full pose ik for you. 

The pip package and the github rep contain both the NICO urdf model, so that you use it instantly.

The demo.py program uses the NICO model and calculates the ik for some test values.

Take a look at demo.py and adapt it to you usecase or robot:

Start with your imports

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-

    import gaikpy
    from gaikpy import chain
    from gaikpy import robot
    from gaikpy import chain_definitions
    import time
    import pickle
    import os


We need a URDF, which is the ROS, but as well in other context, model representation of a robot
Here we take take NICO model that is included in the package

    nico_path = gaikpy.get_nico_urdf_path()+"/complete_modified_bounds.urdf"

We have to define a chain containing the URDF and a list of joint / link combinations with all joints 
taking part in he movement. Below is a definiion o the right NICO arm

    rightchain = chain.Chain.from_urdf_file(
                # The path to he URDF
                nico_path , 
                # The chain: We start with a link and the first joint up to the last joint involved
                base_elements=["torso:11", "r_shoulder_z", "right_shoulder:11", 
                "r_shoulder_y", "right_collarbone:11", "r_arm_x", "right_upper_arm:11", "r_elbow_y", 
                "right_lower_arm:11", "r_wrist_z","right_wrist:11", "r_wrist_x", 
                "right_palm:11", "r_ringfingers_x"],
                # Not all the joints listed have to take part in the movement
                # This is a mask blending out joints inbetween the chain 
                # (here we do not want to involve the finger joints) 
                active_joints_mask=[False, True, True, True, True, True, True, False, False, False])


For visualization we built he a full robot model
again using the URDF

    nico_right_chain=chain_definitions.nico_right_chain_active
    nico=robot.robot(nico_path,nico_right_chain)

We use some poses, where we can be sure, that they are mechanically 
reachable (cause we have used forward kinematics to generate the dataset, see this in the examples about generating movement examples)

    with open(gaikpy.get_nico_data_path()+'/nico_right_20_new.p', 'rb') as f:
                sample_set = pickle.load(f)

Go through all the samples in file
This contains pairs of poses in Eukledian and in the joint space 
Of cours we use only the Eukledian ones in this example

    for sample in sample_set:

        # joi is the data in joint space for the robot (not used)
        # sfwr is the pose in Euklidan space
        (joi,sfwr)=sample
        print ("Original pose: \n" + str(sfwr))

        # Show a target pointer in the scene, so that we know, which pose NICOs hand shoul take 
        nico.update_target(sfwr)

Calculate the IK, get the robots joint values

        ik_kor = rightchain.inverse_kinematics(sfwr, method="ga_simple",include_orientation=True,
                            numGenerations=1000,max_iter=100000,dist_acc=0.01,or_acc=0.1,
                            multiproc=True,orientation_weight=-1)

        # Change the joint data to the full joint representation
        joi=rightchain.active_from_full(ik_kor)

        # Get the Eukledian pose using orward kinematics
        fwr=rightchain.forward_kinematics(ik_kor,full_kinematics=False)

        #Let us compare the results
        print ("gaikpy result: \n" + str(fwr))

Update the pose on the visualised NICO

        nico.update_robot_pose(joi)

        #Wait a time to display the result
        time.sleep(0.3)


# Use other robots

Using other robots is very easy, if you have a URDF model of the robot at hand. Just take the URDF model and list the joints and links of your active chain until the end effector. Just adapt the demo.py or the NICO example ./examples/visualise_NICO.py to see how it works.
We will integrate other robots by default in the future. 

# License

GNU GENERAL PUBLIC LICENSE Version 3

