.. highlight:: shell

============
Installation
============


Latest version
--------------

rigid-body-motion can be installed via ``pip``:

.. code-block:: console

    $ pip install rigid-body-motion

or via ``conda``:

.. code-block:: console

    $ conda install -c phausamann -c conda-forge rigid-body-motion


Optional dependencies
---------------------

Optional dependencies can be installed via ``pip`` or ``conda`` (just replace
``pip install`` with ``conda install``).

Transformations can be sped up significantly by installing the numba library:

.. code-block:: console

    $ pip install numba

rigid-body-motion supports xarray data types:

.. code-block:: console

    $ pip install xarray

Loading the example datasets requires the pooch and netCDF4 libraries:

.. code-block:: console

    $ pip install pooch netcdf4

Plotting functions require matplotlib:

.. code-block:: console

    $ pip install matplotlib

ROS integration
---------------

The package also integrates with ROS_, which can be installed quite
conveniently via ``conda`` thanks to the amazing work by the people from
RoboStack_. This even works on Windows and macOS! The necessary dependencies
are:

.. code-block:: console

    $ conda install -c conda-forge -c robostack ros-noetic-rospy ros-noetic-tf ros-noetic-tf2-ros ros-noetic-tf2-geometry-msgs ros-noetic-geometry-msgs ros-noetic-visualization-msgs python-orocos-kdl boost=1.74

Note that these packages are only available for Python 3.6 and 3.8.

.. _ROS: https://www.ros.org/
.. _RoboStack: https://github.com/RoboStack

In order to use RViz for visualization you need to install that as well:

.. code-block:: console

    $ conda install -c conda-forge -c robostack ros-noetic-rviz

Since ROS can communicate across conda environments, we would however recommend
installing RViz in a dedicated environment:

.. code-block:: console

    $ conda create -n ros -c conda-forge -c robostack ros-noetic-rviz

After installing, you can spin up a ``roscore``:

.. code-block:: console

    $ conda activate ros
    $ roscore

and, from a second terminal, launch RViz:

.. code-block:: console

    $ conda activate ros
    $ rviz

Troubleshooting
~~~~~~~~~~~~~~~

In order to make sure all ROS dependencies have been set up correctly, run:

.. code-block:: console

    $ python -m rigid_body_motion.ros.check_install

If this is not successful, you need to fix some of your dependencies. The
following outlines solutions for common issues:

1. Problem: boost version

   .. code-block:: console

       ImportError: libboost_thread.so.1.74.0: cannot open shared object file:
       No such file or directory

   Solution: install correct boost version

   .. code-block:: console

       $ conda install -c conda-forge boost=1.74

   Replace ``1.74`` with whatever version the traceback tells you is missing.

Example environments
--------------------

We recommend using rigid_body_motion in a dedicated conda environment.
For the examples in the user guide, we provide an
:download:`environment file<_static/envs/example-env.yml>`
that you can download and set up with:

.. code-block:: console

    $ conda env create -f example-env.yml

There's also an example environment that includes the necessary ROS packages
(:download:`here<_static/envs/example-env-ros.yml>`) that you can set up with:

.. code-block:: console

    $ conda env create -f example-env-ros.yml

If you download the examples as Jupyter notebooks, it is sufficient to have
the Jupyter notebook server installed in your base environment alongside
``nb_conda``:

.. code-block:: console

    $ conda install -n base nb_conda

Now you can open any of the example notebooks, go to *Kernel > Change kernel*
and select *Python [conda env:rbm-examples]*
(or *Python [conda env:rbm-examples-ros]*).

Pre-release version
-------------------

The latest pre-release can be installed from the GitHub master branch:

.. code-block:: console

    $ pip install git+https://github.com/phausamann/rigid-body-motion.git