Merge pull request #180 from NeLy-EPFL/dev-v1.0.0-pre.2

Release: v1.0.0-pre.2

Author: sibocw

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,5 @@
 ### Description
 [describe your changes here]
 
-### Types of changes
-
-- [ ] Bugfix
-- [ ] New feature
-- [ ] Refactor / Code style update (no logical changes)
-- [ ] Build / CI changes
-- [ ] Documentation Update
-- [ ] Other (explain)
-
 ### Does this address any currently open issues?
 [list open issues here]

.github/workflows/documentation.yaml

@@ -34,4 +34,4 @@ jobs:
           if-no-files-found: error
           retention-days: 1
           compression-level: 6
-          overwrite: false
+          overwrite: false

README.md

@@ -4,7 +4,7 @@
 
 [**Documentation**](https://neuromechfly.org/) | [**Preprint**](https://www.biorxiv.org/content/10.1101/2023.09.18.556649) | [**Discussion Board**](https://github.com/NeLy-EPFL/flygym/discussions)
 
-![Python: 3.7–3.12](https://img.shields.io/badge/python-3.7%E2%80%933.12-blue)
+![Python: 3.9–3.12](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)
 [![License: MPL 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/NeLy-EPFL/flygym/blob/main/LICENSE)
 [![PyPI version](https://badge.fury.io/py/flygym.svg)](https://badge.fury.io/py/flygym)
 ![Repo Size](https://img.shields.io/github/repo-size/NeLy-EPFL/flygym)
@@ -31,7 +31,7 @@ In brief:
 pip install "flygym"
 ```
 
-See [our website](https://neuromechfly.org/installation.html) for details, especially if you plan to install FlyGym in the developer mode (i.e. if you plan to make changes to the code). Dependencies are specified in [`setup.py`](https://github.com/NeLy-EPFL/flygym/blob/main/setup.py) and will be installed automatically upon installation using pip. Installation should take no more than a few minutes. NeuroMechFly has been tested on Linux (Ubuntu 22.04.3) and macOS (13.5.2). All commits are tested automatically using the latest Ubuntu version on Python versions 3.7 through 3.12 (see [CI workflow](https://github.com/NeLy-EPFL/flygym/blob/main/.github/workflows/tests.yaml) for exact test specification). The PyPI version of the current release of FlyGym is indicated on the shield at the top of this page. No special or paid software is required to use FlyGym.
+See [our website](https://neuromechfly.org/installation.html) for details, especially if you plan to install FlyGym in the developer mode (i.e. if you plan to make changes to the code). Dependencies are specified in [`setup.py`](https://github.com/NeLy-EPFL/flygym/blob/main/setup.py) and will be installed automatically upon installation using pip. Installation should take no more than a few minutes. NeuroMechFly has been tested on Linux (Ubuntu 22.04.3) and macOS (13.5.2). All commits are tested automatically using the latest Ubuntu version on Python versions 3.9 through 3.12 (see [CI workflow](https://github.com/NeLy-EPFL/flygym/blob/main/.github/workflows/tests.yaml) for exact test specification). The PyPI version of the current release of FlyGym is indicated on the shield at the top of this page. No special or paid software is required to use FlyGym.
 
 ## Demos
 See [our website](https://neuromechfly.org/tutorials/index.html) for tutorials, including expected outputs. For code blocks that take more than a few seconds to run, the running time (on a 2020 MacBook Pro with M1 processor running macOS 13.5.2) is indicated, typically in the form of a progress bar.

doc/source/api_ref/camera.rst

@@ -0,0 +1,41 @@
+Camera
+======
+
+The ``Camera`` class defines how images should be rendered from a camera in the world model. Note that the ``Camera`` class does not by itself add a camera to the MuJoCo model — the camera must have already existed and can be referenced by its name. The camera can be added in two ways:
+
+1. By adding a camera to the MuJoCo model file. Refer to the `section on camera <https://mujoco.readthedocs.io/en/stable/XMLreference.html#body-camera>`_ in the MuJoCo XML reference for more information. As an example, the following XML code adds a tracking camera to the MuJoCo model:
+
+.. code-block:: xml
+
+    <worldbody>
+        <!-- ... other things ... -->
+        <camera name="camera_top" class="nmf" mode="track" ipd="0.068" pos="0 0 8" euler="0 0 0"/>
+    </worldbody>
+
+2. By calling ``.worldbody.add()`` on the root element of the MuJoCo model programmatically in Python. Practically, this can be done by extending an existing FlyGym Arena class and adding the camera in the ``__init__`` method. For example, the following code adds a stationary bird's eye camera to the MuJoCo model:
+
+.. code-block:: python3
+
+    from flygym.arena import BaseArena
+
+    class MyArena(BaseArena):
+        def __init__(self):
+            super().__init__()
+            self.birdeye_cam = self.root_element.worldbody.add(
+                "camera",
+                name="birdseye_cam",
+                mode="fixed",
+                pos=(20, 0, 20),
+                euler=(0, 0, 0),
+                fovy=60,
+            )
+            # ... other things ...
+
+Once the camera is added to the MuJoCo model, it can be referenced by its name to initialize the ``Camera`` object with additional parameters assigned to it. These can include: rendering rate in frames-per-second (FPS), window size, play speed, etc. Furthermore, the ``Camera`` class has useful methods such as ``.save_video``, ``.reset``, etc. Logics such as rotating the camera in tilted terrain are also implemented in the ``Camera`` class. The ``.render`` method is the main point of entry for fetching images from the camera.
+
+The full API reference of the ``Camera`` class is as follows:
+
+.. autoclass:: flygym.camera.Camera
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/api_ref/examples/locomotion.rst

@@ -1,6 +1,15 @@
 Locomotion
 ==========
 
+Preprogrammed steps
+-------------------
+
+.. autoclass:: flygym.examples.locomotion.PreprogrammedSteps
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
+
 CPG controller
 --------------
 

doc/source/api_ref/examples/olfaction.rst

@@ -1,5 +1,5 @@
-Olfaction
-=========
+Advanced Olfaction
+==================
 
 Arenas
 ------

doc/source/api_ref/examples/vision.rst

@@ -1,5 +1,5 @@
-Vision
-======
+Advanced Vision
+===============
 
 Arenas
 ------

doc/source/api_ref/fly.rst

@@ -0,0 +1,7 @@
+Fly
+===
+
+An object of the ``Fly`` class is an instance of a simulated fly. There can be multiple flies in a `Simulation <simulation.html>`_. The ``Fly`` object contains parameters related to the fly but not the whole simulation: for example, the set of actuated joints, spawn position, joint actuator parameters (stiffness, damping, etc.), and initial pose.
+
+.. autoclass:: flygym.Fly
+    :members:

doc/source/api_ref/index.rst

@@ -7,12 +7,14 @@ This section of the documentation provides the complete API reference for the Fl
 .. toctree::
    :maxdepth: 2
 
-   parameters
-   simulation
+   fly
    arena
+   camera
+   simulation
    state
    vision
    olfaction
    utils
    preprogrammed
-   examples/index
+   examples/index
+   legacy

doc/source/api_ref/legacy.rst

@@ -0,0 +1,11 @@
+Legacy API
+==========
+
+.. warning::
+
+    This API, inherited from the 0.x.x versions, is deprecated and will be removed in a future release. Please use the new API (the rest of the documentation) instead.
+
+.. automodule:: flygym.core
+    :members:
+    :undoc-members:
+    :show-inheritance: