RL--based Learner for Active Face Recognition (opendr-eu#473)

* Active_fr * Active_fr * Active_fr * Fixes and ReadME * Fixes * Fixes and ReadME * Delete src/opendr/perception/active_perception/active_face_recognition/tester.py removed extra file * Fixes and ReadME * Attempted merge fix for continual * Removed some prints * Face images for database creation * Eval fix * Fixed suggestions by Kostas. Ignored num_steps for eval() but fixed num_episodes logic. Implemented suggestions on ReadME * Added demo under projects * Added demo under projects and corresponding README * Blank lines on demos * Blank lines on demos * Update docs/reference/active_face_recognition.md Co-authored-by: Kostas Tsampazis <[email protected]> * Fixed Webots version on protos files, minor fixes on README * Fixed Webots version on protos files, minor fixes on README --------- Co-authored-by: Kostas Tsampazis <[email protected]>
lucamarchionni · Nov 14, 2023 · 2a7d11d · 2a7d11d
1 parent 184eba9
commit 2a7d11d
Show file tree

Hide file tree

Showing 187 changed files with 10,528 additions and 0 deletions.
diff --git a/docs/reference/active_face_recognition.md b/docs/reference/active_face_recognition.md
@@ -0,0 +1,199 @@
+# active_face_recognition module
+
+The *active_face_recognition* module contains the *ActiveFaceRecognitionLearner* class, which inherits from the abstract 
+class *LearnerRL*.
+
+### Class ActiveFaceRecognitionLearner
+Bases: `engine.learners.LearnerRL`
+
+The *ActiveFaceRecognitionLearner* is an agent that can be used to train a quadrotor robot equipped with an RGB camera 
+to maximize the confidence of OpenDR's FaceRecognition module.
+
+The [ActiveFaceRecognitionLearner](../../src/opendr/perception/active_perception/active_face_recognition/active_face_recognition_learner.py) class has the 
+following public methods:
+
+#### `ActiveFaceRecognitionLearner` constructor
+
+Constructor parameters:
+- **lr**: *float, default=3e-4*\
+  The initial learning rate to be used during training.
+- **iters**: *int, default=5e6*\
+  The number of steps the training should run for.
+- **batch_size**: *int, default=64*\
+  The batch size during training.
+- **checkpoint_after_iter**: *int, default=0*\
+  After how many training steps a checkpoint should be saved.
+- **checkpoint_load_iter**: *int, default=0*\
+  Checkpoint to load.
+- **temp_path**: *str, default=''*\
+  Path where the algorithm stores log files and saves checkpoints.
+- **device**: *{'cpu', 'cuda'}, default='cuda'*\
+  The device to be used.
+- **n_steps**: *int, default=6400*\
+  Number of steps to run environment per update.
+- **gamma**: *float, default=0.9*\
+  Discount factor for future rewards.
+- **clip_range**: *float, default=0.1*\
+  Clip policy updates.
+- **target_kl**: *float, default=0.1*\
+  KL Divergence update threshold.
+
+#### `ActiveFaceRecognitionLearner.fit`
+```python
+ActiveFaceRecognitionLearner.fit(self, logging_path, verbose)
+```
+
+Train the agent on the environment.
+
+Parameters:
+
+- **logging_path**: *str, default='./'*\
+  Path for logging and checkpointing.
+- **verbose**: *bool, default=True*\
+  Enable verbosity.
+
+
+#### `ActiveFaceRecognitionLearner.eval`
+```python
+ActiveFaceRecognitionLearner.eval(self, num_episodes, deterministic)
+```
+Evaluate the agent on the specified environment.
+
+Parameters:
+
+- **num_episodes**: *int, default=10*\
+  Number of evaluation episodes to run.
+- **deterministic**: *bool, default=False*\
+  Use deterministic actions from the policy.
+
+
+#### `ActiveFaceRecognitionLearner.infer`
+```python
+ActiveFaceRecognitionLearner.infer(self, observation, deterministic)
+```
+Performs inference on a single observation.
+
+Parameters:
+
+- **observation**: *engine.Image, default=None*\
+  Single observation.
+- **deterministic**: *bool, default=False*\
+  Use deterministic actions from the policy
+
+#### `ActiveFaceRecognitionLearner.save`
+```python
+ActiveFaceRecognitionLearner.save(self, path)
+```
+Saves the model in the path provided.
+
+Parameters:
+
+- **path**: *str*\
+  Path to save the model, including the filename.
+
+
+#### `ActiveFaceRecognitionLearner.load`
+```python
+ActiveFaceRecognitionLearner.load(self, path)
+```
+Loads a model from the path provided.
+
+Parameters:
+
+- **path**: *str*\
+  Path of the model to be loaded.
+
+
+
+#### `ActiveFaceRecognitionLearner.download`
+```python
+ActiveFaceRecognitionLearner.download(self, path)
+```
+Downloads a pretrained model to the path provided.
+
+Parameters:
+
+- **path**: *str*\
+  Path to download model.
+
+### Running the environment
+
+The environment is provided with a [world](../../src/opendr/perception/active_perception/active_face_recognition/simulation/worlds/active_face_recognition.wbt)
+that needs to be opened with Webots version 2023b in order to demonstrate the active face recognition learner.
+
+Once the world is opened and the simulation is running, you can run a script utilizing ActiveFaceRecognitionLearner \
+by setting WEBOTS_HOME environment variable:
+
+`export WEBOTS_HOME=/usr/local/webots`
+
+and then run the desired script, e.g. demo.py by:
+
+`$WEBOTS_HOME/webots-controller /path/to/script/demo.py`
+
+
+### Examples
+
+Training in Webots environment:
+
+```python
+from opendr.perception.active_perception.active_face_recognition import ActiveFaceRecognitionLearner
+
+learner = ActiveFaceRecognitionLearner(n_steps=1024)
+learner.fit(logging_path='./active_face_recognition_tmp')
+```
+
+
+Evaluating a pretrained model:
+
+```python
+from opendr.perception.active_perception.active_face_recognition import ActiveFaceRecognitionLearner
+
+learner = ActiveFaceRecognitionLearner()
+path = './'
+learner.download(path)
+learner.load("./active_fr.zip")
+rewards = learner.eval(num_episodes=10, deterministic=False)
+
+print(rewards)
+```
+
+
+Running inference on a pretrained model:
+
+```python
+from opendr.perception.active_perception.active_face_recognition import ActiveFaceRecognitionLearner
+
+learner = ActiveFaceRecognitionLearner()
+path = './'
+learner.download(path)
+learner.load("./active_fr.zip")
+
+obs = learner.env.reset()
+while True:
+    action, _ = learner.infer(obs)
+    obs, reward, done, info = learner.env.step(action)
+    if done:
+        obs = learner.env.reset()
+```
+
+
+### Performance Evaluation
+
+TABLE 1: Speed (FPS) for inference on various platforms.
+
+|                 | TX2    | XavierNX | RTX 2070 Super |
+| --------------- |--------|----------|----------------|
+| FPS Evaluation  | 425.27 | 512.48   | 683.25         |
+
+TABLE 2: Platform compatibility evaluation.
+
+| Platform                                     | Test results |
+|----------------------------------------------| ------------ |
+| x86 - Ubuntu 20.04 (bare installation - CPU) | Pass         |
+| x86 - Ubuntu 20.04 (bare installation - GPU) | Pass         |
+| x86 - Ubuntu 20.04 (pip installation)        | Pass         |
+| x86 - Ubuntu 20.04 (CPU docker)              | Pass         |
+| x86 - Ubuntu 20.04 (GPU docker)              | Pass         |
+| NVIDIA Jetson TX2                            | Pass         |
+| NVIDIA Jetson Xavier NX                      | Pass         |
+
diff --git a/projects/python/perception/active_perception/active_face_recognition/README.md b/projects/python/perception/active_perception/active_face_recognition/README.md
@@ -0,0 +1,10 @@
+# ActiveFaceRecognition Demos
+
+This folder contains sample applications that demonstrate various parts of the functionality provided by the ActiveFaceRecognition algorithms provided by OpenDR.
+
+More specifically, the following applications are provided:
+
+1. demos/fit_demo.py: A tool that demonstrates how to perform training using ActiveFaceRecognition
+2. demos/eval_demo.py: A tool that demonstrates how to perform evaluation using ActiveFaceRecognition
+
+Please use the `--device cpu` flag for the demos if you are running them on a machine without a CUDA-enabled GPU.
diff --git a/projects/python/perception/active_perception/active_face_recognition/demos/eval_demo.py b/projects/python/perception/active_perception/active_face_recognition/demos/eval_demo.py
@@ -0,0 +1,20 @@
+# Copyright 2020-2023 OpenDR European Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from opendr.perception.active_perception.active_face_recognition import ActiveFaceRecognitionLearner
+
+learner = ActiveFaceRecognitionLearner()
+learner.download('./')
+learner.load('./active_fr.zip')
+rewards = learner.eval(num_episodes=5)
+print(rewards)
diff --git a/projects/python/perception/active_perception/active_face_recognition/demos/fit_demo.py b/projects/python/perception/active_perception/active_face_recognition/demos/fit_demo.py
@@ -0,0 +1,18 @@
+# Copyright 2020-2023 OpenDR European Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from opendr.perception.active_perception.active_face_recognition import ActiveFaceRecognitionLearner
+
+learner = ActiveFaceRecognitionLearner(iters=500, n_steps=100)
+learner.fit(logging_path='../testing')
+learner.save('./best/')
diff --git a/src/opendr/perception/active_perception/active_face_recognition/__init__.py b/src/opendr/perception/active_perception/active_face_recognition/__init__.py
@@ -0,0 +1,4 @@
+from opendr.perception.active_perception.active_face_recognition.active_face_recognition_learner \
+    import ActiveFaceRecognitionLearner
+
+__all__ = ['ActiveFaceRecognitionLearner']