Merge branch 'develop' into merge-master-into-develop

Author: passalis

Dockerfile

@@ -1,11 +1,11 @@
 FROM ubuntu:20.04
 
-ARG branch
+ARG branch=master
 
 # Install dependencies
 RUN apt-get update && \
-    apt-get --yes install git sudo
-RUN DEBIAN_FRONTEND="noninteractive" apt-get -y install tzdata
+    apt-get --yes install git sudo && \
+    DEBIAN_FRONTEND="noninteractive" apt-get -y install tzdata
 
 # Add Tini
 ENV TINI_VERSION v0.19.0
@@ -16,12 +16,14 @@ ENTRYPOINT ["/tini", "--"]
 # Clone the repo and install the toolkit
 RUN git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr -b $branch
 WORKDIR "/opendr"
-RUN ./bin/install.sh
+RUN ./bin/install.sh && \ 
+    rm -rf /root/.cache/* && \
+    apt-get clean
 
 # Create script for starting Jupyter Notebook
-RUN /bin/bash -c "source ./bin/activate.sh; pip3 install jupyter"
-RUN echo "#!/bin/bash\n source ./bin/activate.sh\n ./venv/bin/jupyter notebook --port=8888 --no-browser --ip 0.0.0.0 --allow-root" > start.sh
-RUN chmod +x start.sh
+RUN /bin/bash -c "source ./bin/activate.sh; pip3 install jupyter" && \
+    echo "#!/bin/bash\n source ./bin/activate.sh\n ./venv/bin/jupyter notebook --port=8888 --no-browser --ip 0.0.0.0 --allow-root" > start.sh && \
+    chmod +x start.sh
 
 # Start Jupyter Notebook inside OpenDR
 CMD ["./start.sh"]

Dockerfile-cuda

@@ -1,19 +1,15 @@
 FROM nvidia/cuda:11.2.0-cudnn8-devel-ubuntu20.04
 
-ARG branch
+ARG branch=develop
 
 # Fix NVIDIA CUDA Linux repository key rotation
 ENV APT_KEY_DONT_WARN_ON_DANGEROUS_USAGE=1
 RUN apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu$(cat /etc/os-release | grep VERSION_ID | awk '{print substr($0,13,5)}' | awk -F'.' '{print $1$2}')/x86_64/3bf863cc.pub
 
-ARG branch
-
-ARG branch
-
 # Install dependencies
 RUN apt-get update && \
-    apt-get --yes install git sudo apt-utils
-RUN DEBIAN_FRONTEND="noninteractive" apt-get -y install tzdata
+    apt-get --yes install git sudo apt-utils && \
+    DEBIAN_FRONTEND="noninteractive" apt-get -y install tzdata
 
 # Add Tini
 ENV TINI_VERSION v0.19.0
@@ -27,12 +23,14 @@ RUN sudo apt-get --yes install build-essential
 ENV OPENDR_DEVICE gpu
 RUN git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr -b $branch
 WORKDIR "/opendr"
-RUN ./bin/install.sh
+RUN ./bin/install.sh && \
+    rm -rf /root/.cache/* && \
+    apt-get clean
 
 # Create script for starting Jupyter Notebook
-RUN /bin/bash -c "source ./bin/activate.sh; pip3 install jupyter"
-RUN echo "#!/bin/bash\n source ./bin/activate.sh\n ./venv/bin/jupyter notebook --port=8888 --no-browser --ip 0.0.0.0 --allow-root" > start.sh
-RUN chmod +x start.sh
+RUN /bin/bash -c "source ./bin/activate.sh; pip3 install jupyter" && \
+    echo "#!/bin/bash\n source ./bin/activate.sh\n ./venv/bin/jupyter notebook --port=8888 --no-browser --ip 0.0.0.0 --allow-root" > start.sh && \ 
+    chmod +x start.sh
 
 # Start Jupyter Notebook inside OpenDR
 CMD ["./start.sh"]

README.md

@@ -11,6 +11,7 @@ ______________________________________________________________________
   <a href="docs/reference/installation.md">Installation</a> •
   <a href="#using-opendr-toolkit">Using OpenDR toolkit</a> •
   <a href="projects">Examples</a> •
+  <a href="docs/reference/customize.md">Customization</a> •
   <a href="#roadmap">Roadmap</a> •
   <a href="CHANGELOG.md">Changelog</a> •
   <a href="LICENSE">License</a>
@@ -59,10 +60,10 @@ Please follow the instructions provided in the [wiki](https://github.com/tasoste
 ## How to cite us
 If you use OpenDR for your research, please cite the following paper that introduces OpenDR architecture and design:
 <pre>
-@article{opendr2022,
+@inproceedings{opendr2022,
   title={OpenDR: An Open Toolkit for Enabling High Performance, Low Footprint Deep Learning for Robotics},
   author={Passalis, Nikolaos and Pedrazzi, Stefania and Babuska, Robert and Burgard, Wolfram and Dias, Daniel and Ferro, Francesco and Gabbouj, Moncef and Green, Ole and Iosifidis, Alexandros and Kayacan, Erdal and Kober, Jens and Michel, Olivier and Nikolaidis, Nikos and Nousi, Paraskevi and Pieters, Roel and Tzelepi, Maria and Valada, Abhinav and Tefas, Anastasios},
-  journal={arXiv preprint arXiv:2203.00403},
+    booktitle = {Proceedings of the 2022 IEEE/RSJ International Conference on Intelligent Robots and Systems (to appear)},
   year={2022}
 }
 </pre>

docs/reference/customize.md

@@ -0,0 +1,58 @@
+# Customizing the toolkit
+
+OpenDR is fully open-source and can be readily customized to meet the needs of several different application areas, since the source code for all the developed tools is provided.
+Several ready-to-use examples, which are expected to cover a wide range of different needs, are provided.
+For example, users can readily use the existing [ROS nodes](projects/opendr_ws), e.g., by including the required triggers or by combining several nodes into one to build custom nodes that will fit their needs. 
+Furthermore, note that several tools can be combined within a ROS node, as showcased in [face recognition ROS node](projects/opendr_ws/src/perception/scripts/face_recognition.py). 
+You can use these nodes as a template for customizing the toolkit to your own needs.
+The rest of this document includes instructions for:
+1. Building docker images using the provided docker files. 
+
+
+## Building custom docker images
+The default docker images can be too large for some applications.
+OpenDR provides the dockerfiles for customizing the images to your own needs, e.g., using OpenDR in custom third-party images.
+Therefore, you can build the docker images locally using the [Dockerfile](/Dockerfile) ([Dockerfile-cuda](/Dockerfile-cuda) for cuda) provided in the root folder of the toolkit.
+
+### Building the CPU image
+For the CPU image, execute the following commands:
+```bash
+git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr
+cd opendr
+sudo docker build -t opendr/opendr-toolkit:cpu .
+```
+
+### Building the CUDA image
+For the cuda-enabled image, first edit `/etc/docker/daemon.json` in order to set the default docker runtime:
+```
+{
+    "runtimes": {
+        "nvidia": {
+            "path": "nvidia-container-runtime",
+            "runtimeArgs": []
+        }
+    },
+    "default-runtime": "nvidia"
+}
+```
+
+Restart docker afterwards:
+```
+sudo systemctl restart docker.service
+```
+Then you can build the supplied dockerfile:
+```bash
+git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr
+cd opendr
+sudo docker build -t opendr/opendr-toolkit:cuda -f Dockerfile-cuda .
+```
+
+### Running the custom images
+In order to run them, the commands are respectively:
+```bash
+sudo docker run -p 8888:8888 opendr/opendr-toolkit:cpu
+```
+and
+```
+sudo docker run --gpus all -p 8888:8888 opendr/opendr-toolkit:cuda
+```

docs/reference/fall-detection.md

@@ -5,9 +5,18 @@ The *fall_detection* module contains the *FallDetectorLearner* class, which inhe
 ### Class FallDetectorLearner
 Bases: `engine.learners.Learner`
 
-The *FallDetectorLearner* class contains the implementation of a naive fall detector algorithm.
+The *FallDetectorLearner* class contains the implementation of a rule-based fall detector algorithm.
 It can be used to perform fall detection on images (inference) using a pose estimator.
 
+This rule-based method can provide **cheap and fast** fall detection capabilities when pose estimation
+is already being used. Its inference time cost is ~0.1% of pose estimation, adding negligible overhead.
+
+However, it **has known limitations** due to its nature. Working with 2D poses means that depending on the 
+orientation of the person, it cannot detect most fallen poses that face the camera. 
+Another example of known false-positive detection occurs when a person is sitting with their knees 
+detectable, but ankles obscured or undetectable, this however is critical for detecting a fallen person
+whose ankles are not visible.
+
 The [FallDetectorLearner](/src/opendr/perception/fall_detection/fall_detector_learner.py) class has the
 following public methods:
 

docs/reference/installation.md

@@ -1,68 +1,29 @@
 # Installing OpenDR toolkit
 
 OpenDR can be installed in the following ways:
-1. By cloning this repository (CPU/GPU support)
-2. Using *pip* (CPU/GPU support)
-3. Using *docker* (CPU/GPU support)
+1. Using *pip* (CPU/GPU support)
+2. Using *docker* (CPU/GPU support)
+3. By cloning this repository (CPU/GPU support, for advanced users only)
 
 The following table summarizes the installation options based on your system architecture and OS:
 
-| Installation Method | CPU/GPU  | OS                    |
-|---------------------|----------|-----------------------|
-| Clone & Install     | Both     | Ubuntu 20.04 (x86-64) |
-| pip                 | Both     | Ubuntu 20.04 (x86-64) |
-| docker              | Both     | Linux / Windows       |
+| Installation Method   | OS                    |
+|-----------------------|-----------------------|
+| Clone & Install       | Ubuntu 20.04 (x86-64) |
+| pip                   | Ubuntu 20.04 (x86-64) |
+| docker                | Linux / Windows       |
 
+Note that pip installation includes only the Python API of the toolkit. 
+If you need to use all the functionalities of the toolkit (e.g., ROS nodes, etc.), then you need either to use the pre-compiled docker images or to follow the installation instructions for cloning and building the toolkit.
 
-# Installing by cloning OpenDR repository (Ubuntu 20.04, x86, architecture)
-
-This is the recommended way of installing the whole toolkit, since it allows for fully exploiting all the provided functionalities.
-To install the toolkit, please first make sure that you have `git` available on your system.
-```bash
-sudo apt install git
-```
-Then, clone the toolkit:
-```bash
-git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr
-```
-You are then ready to install the toolkit:
-```bash
-cd opendr
-./bin/install.sh
-```
-The installation script automatically installs all the required dependencies.
-Note that this might take a while (~10-20min depending on your machine and network connection), while the script also makes system-wide changes.
-Using dockerfiles is strongly advised (please see below), unless you know what you are doing.
-Please also make sure that you have enough RAM available for the installation (about 4GB of free RAM is needed for the full installation/compilation).
-
-
-If you want to install GPU-related dependencies, then you can appropriately set the `OPENDR_DEVICE` variable.
-The toolkit defaults to using CPU.
-Therefore, if you want to use GPU, please set this variable accordingly *before* running the installation script:
-```bash
-export OPENDR_DEVICE=gpu
-```
-The installation script creates a *virtualenv*, where the toolkit is installed.
-To activate OpenDR environment you can just source the `activate.sh`:
+The toolkit is developed and tested on *Ubuntu 20.04 (x86-64)*. 
+Please make sure that you have the most recent version of all tools by running
 ```bash
-source ./bin/activate.sh
+sudo apt upgrade
 ```
-Then, you are ready to use the toolkit!
-
-**NOTE:** `OPENDR_DEVICE` does not alter the inference/training device at *runtime*. 
-It only affects the dependency installation.
-You can use OpenDR API to change the inference device.
-
-You can also verify the installation by using the supplied Python and C unit tests:
-```bash
-make unittest
-make ctests
-```
-
-If you plan to use GPU-enabled functionalities, then you are advised to install [CUDA 11.2](https://developer.nvidia.com/cuda-11.2.0-download-archive), along with [CuDNN](https://developer.nvidia.com/cudnn).
-
-**HINT:** All tests probe for the `TEST_DEVICE` enviromental variable when running.
-If this enviromental variable is set during testing, it allows for easily running all tests on a different device (e.g., setting `TEST_DEVICE=cuda:0` runs all tests on the first GPU of the system).
+before installing the toolkit and then follow the installation instructions in the relevant section.
+All the required dependencies will be automatically installed (or explicit instructions are provided).
+Other platforms apart from Ubuntu 20.04, e.g., Windows, other Linux distributions, etc., are currently supported through docker images.
 
 # Installing using *pip*
 
@@ -179,45 +140,54 @@ In this case, do not forget to enable the virtual environment with:
 ```bash
 source bin/activate.sh
 ```
-## Build the docker images yourself _(optional)_
-Alternatively you can also build the docker images locally using the [Dockerfile](/Dockerfile) ([Dockerfile-cuda](/Dockerfile-cuda) for cuda) provided in the root folder of the toolkit.
 
-For the CPU image, execute the following commands:
+# Installing by cloning OpenDR repository (Ubuntu 20.04, x86, architecture)
+
+This is the recommended way of installing the whole toolkit, since it allows for fully exploiting all the provided functionalities.
+To install the toolkit, please first make sure that you have `git` available on your system.
+```bash
+sudo apt install git
+```
+Then, clone the toolkit:
 ```bash
 git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr
+```
+You are then ready to install the toolkit:
+```bash
 cd opendr
-sudo docker build -t opendr/opendr-toolkit:cpu .
+./bin/install.sh
 ```
+The installation script automatically installs all the required dependencies.
+Note that this might take a while (~10-20min depending on your machine and network connection), while the script also makes system-wide changes.
+Using dockerfiles is strongly advised (please see below), unless you know what you are doing.
+Please also make sure that you have enough RAM available for the installation (about 4GB of free RAM is needed for the full installation/compilation).
 
-For the cuda-enabled image, first edit `/etc/docker/daemon.json` in order to set the default docker runtime:
-```
-{
-    "runtimes": {
-        "nvidia": {
-            "path": "nvidia-container-runtime",
-            "runtimeArgs": []
-        }
-    },
-    "default-runtime": "nvidia"
-}
-```
 
-Restart docker afterwards:
-```
-sudo systemctl restart docker.service
+If you want to install GPU-related dependencies, then you can appropriately set the `OPENDR_DEVICE` variable.
+The toolkit defaults to using CPU.
+Therefore, if you want to use GPU, please set this variable accordingly *before* running the installation script:
+```bash
+export OPENDR_DEVICE=gpu
 ```
-Then you can build the supplied dockerfile:
+The installation script creates a *virtualenv*, where the toolkit is installed.
+To activate OpenDR environment you can just source the `activate.sh`:
 ```bash
-git clone --depth 1 --recurse-submodules -j8 https://github.com/opendr-eu/opendr
-cd opendr
-sudo docker build -t opendr/opendr-toolkit:cuda -f Dockerfile-cuda .
+source ./bin/activate.sh
 ```
+Then, you are ready to use the toolkit!
+
+**NOTE:** `OPENDR_DEVICE` does not alter the inference/training device at *runtime*. 
+It only affects the dependency installation.
+You can use OpenDR API to change the inference device.
 
-In order to run them, the commands are respectively:
+You can also verify the installation by using the supplied Python and C unit tests:
 ```bash
-sudo docker run --gpus all -p 8888:8888 opendr/opendr-toolkit:cpu
-```
-and
-```
-sudo docker run --gpus all -p 8888:8888 opendr/opendr-toolkit:cuda
+make unittest
+make ctests
 ```
+
+If you plan to use GPU-enabled functionalities, then you are advised to install [CUDA 11.2](https://developer.nvidia.com/cuda-11.2.0-download-archive), along with [CuDNN](https://developer.nvidia.com/cudnn).
+
+**HINT:** All tests probe for the `TEST_DEVICE` enviromental variable when running.
+If this enviromental variable is set during testing, it allows for easily running all tests on a different device (e.g., setting `TEST_DEVICE=cuda:0` runs all tests on the first GPU of the system).
+

docs/reference/rosbridge.md

@@ -59,25 +59,28 @@ ROSBridge.from_ros_pose(self,
                         ros_pose)
 ```
 
-Converts a ROS pose into an OpenDR pose.
+Converts an OpenDRPose2D message into an OpenDR Pose.
 
 Parameters:
 
-- **message**: *ros_bridge.msg.Pose*\
-  ROS pose to be converted into an OpenDR pose.
+- **ros_pose**: *ros_bridge.msg.OpenDRPose2D*\
+  ROS pose to be converted into an OpenDR Pose.
 
 #### `ROSBridge.to_ros_pose`
 
 ```python
 ROSBridge.to_ros_pose(self,
-                      ros_pose)
+                      pose)
 ```
-Converts an OpenDR pose into a ROS pose.
+Converts an OpenDR Pose into a OpenDRPose2D msg that can carry the same information, i.e. a list of keypoints, 
+the pose detection confidence and the pose id.
+Each keypoint is represented as an OpenDRPose2DKeypoint with x, y pixel position on input image with (0, 0) 
+being the top-left corner.
 
 Parameters:
 
-- **message**: *engine.target.Pose*\
-  OpenDR pose to be converted to ROS pose.
+- **pose**: *engine.target.Pose*\
+  OpenDR Pose to be converted to ROS OpenDRPose2D.
 
 
 #### `ROSBridge.to_ros_category`