v1.2.0: Improved camera API, housekeeping, and FlyGym-live game support

What's Changed

Important

API-breaking Changes:

• Improved camera API.

Other Changes:

• Add FlyGym live video game support
• Switch to Poetry for package management
• Various minor improvements

Full Changelog: v1.1.0...v1.2.0

v1.1.0: Updates with minor API breaking changes

What's Changed

Important

API-breaking Changes:

• Removed legacy spawn orientation preprocessing: Previously, pi/2 was subtracted from the user-specified spawn orientation on the x-y plane. This was to make the behavior consistent with a legacy version of NeuroMechFly. This behavior is no longer desired; from this version onwards, the spawn orientation is used as is.
• Changed flip detection method: Previously, flips are reported when all legs reliably lose contact with the ground. Now, we simply check if the z component of the "up" cardinal vector is negative. Additionally, the detect_flip parameter of Fly is now deprecated; flips are always detect and reported.

Other Changes:

• Added cardinal direction sensing (vectors describing +x, +y, +z of the fly) to the observation space.
• Strictly fixed the required MuJoCo version to 3.2.3, and dm_control version to 1.0.23. This is to prevent API-breaking changes in future versions of these libraries from affecting FlyGym. FlyGym maintainers will periodically check for compatibility with newer versions of these libraries.
• Allowed different sets of DoFs to be monitored vs. actuated. Previously, the two sets are always the same.

Housekeeping: From this version onwards, we will use EffVer as the versioning policy. The version number will communicate how much effort we expect a user will need to spend to adopt the new version. While we previously tried to adhere to the stricter SemVer, we found that it was not effective because many core dependencies of FlyGym (e.g., MuJoCo, NumPy, and Python itself) do not use SemVer.

Full Changelog: v1.0.1...v1.1.0

v1.0.1: Minor bug fixes

Fixed minor bugs related to the set of DoFs in the predefined poses, and to rendering at extremely high frequencies. Fixed outdated class names and links in the docs. In addition, contact sensor placements used by the hybrid turning controller are now added to the preprogrammed module. Slightly simplified visual calibration.

What's Changed

• Site formatting change by @sibocw in #198
• Purge pip cache more often to avoid occasional hashing issue by @sibocw in #199
• Minor update to the website by @sibocw in #200
• Merge website updates since v1.0.0 release into the dev branch for v1.0.1-pre.1 by @sibocw in #202
• Fix missing DoFs in preset poses by @sibocw in #204
• Fix very low playspeed rendering by @sibocw in #205
• add default contact sensors by @sibocw in #206
• Update out-of-date import paths in RST files and note books by @sibocw in #208
• Simplify visual calibration function by @sibocw in #209

Full Changelog: v1.0.0...v1.0.1

v1.0.0: First stable release

In spring 2024, NeuroMechFly was used, for the second time, in a course titled Controlling behavior in animals and robots at EPFL. At the same time, we revised the NeuroMechFly v2 manuscript. In these processes, we significantly improved the FlyGym package, added new functionalities, and incorporated changes as we received feedback from the students. These enhancements are released as FlyGym version 1.0.0. This release is not backward compatible; please refer to the tutorials and API references for more information. The main changes are:

• Major API changes:
  • The NeuroMechFly class is split into Fly, a class that represents the fly, and Simulation, a class that represents the simulation, which can potentially contain multiple flies.
  • The Parameters class is deprecated. Parameters related to the fly (such as joint parameters, actuated DoFs, etc.) should be set directly on the Fly object. Parameters related to the simulation (such as the time step, the render cameras, etc.) should be set directly on the Simulation object.
  • A new Camera class is introduced. A simulation can contain multiple cameras.
• New examples:
  • Path integration based on ascending mechanosensory feedback.
  • Head stabilization based on ascending mechanosensory feedback.
  • Navigating a complex plume, simulated separately in a fluid mechanics simulator.
  • Following another fly using a realistic, connectome-constrained neural network that processes visual inputs.

What's Changed (automatically generated)

• Fix vision update mask by @sibocw in #115
• HybridTurningNMF: clear CPG's intrinsic freqs and amps during reset by @stepanove in #117
• New steps by @stimpfli in #118
• Vision-related changes: generalize conversion from ommatidia readings to human readable format by @sibocw in #121
• Bux fix: .reset() doesn't return "vision_updated" in info by @sibocw in #124
• Fix typos in tutorials by @tkclam in #123
• Typo fixes and minor style improvements, with some minor API-breaking variable renamings for the next major release by @tkclam in #126
• Rename peak_intensity to peak_odor_intensity by @tkclam in #127
• Revert "Rename peak_intensity to peak_odor_intensity" by @tkclam in #128
• add python 3.12 as a supported version by @tkclam in #131
• Use updated hybrid controller in head stabilization / vision-related tasks by @sibocw in #135
• Unify head stabilization, connectome-constrained vision model, and updated hybrid controller for complex terrain. by @sibocw in #134
• Merge moving-bars into dev-v1.0.0 by @tkclam in #140
• Implement path integration by @sibocw in #141
• WIP merge recent updates/refactors into path-integrator by @sibocw in #142
• Adhesion-related fix for hybrid controller (avoiding physics errors) by @sibocw in #143
• Fix head stabilization by @tkclam in #144
• Head stabilization complex terrain & improved visual tracking algorithm by @sibocw in #139
• WIP - Add neck camera by @sibocw in #146
• Visualization: stabilizing the neck camera and plotting the neck control signal by @sibocw in #152
• Fly-following-fly: S-shaped path to semicircle by @sibocw in #147
• Complex plume simulation & tracking by @sibocw in #151
• Path integration: allow different contact force thresholds for different legs, filter contact force signal by @sibocw in #145
• Fly following: using multiple Tx neurons for object detection by @sibocw in #153
• Head stabilization over complex terrain & fly-to-fly following using head stabilization by @sibocw in #150
• Fix actuators by @stimpfli in #160
• Add temporary pointers to new examples on website by @sibocw in #162
• Odor tests by @tkclam in #164
• Fix: add "all" option to get_collision_geometries by @sibocw in #165
• Update old tests by @tkclam in #167
• Vision tests by @tkclam in #166
• Add unit tests for flygym/examples by @sibocw in #163
• Refactor examples into separate submodules by @sibocw in #161
• Prerelease v1.0.0-pre.1 by @sibocw in #168
• Fix dependency for sphinx site building by @sibocw in #169
• Unit tests for complex plume by @sibocw in #171
• Refactor documentation by @sibocw in #172
• Gallery in website by @stimpfli in #173
• Add path integration tutorial by @sibocw in #174
• Add tutorial for head stabilization by @sibocw in #175
• Add complex plume tracking tutorial by @sibocw in #177
• Make RST pages for tutorials by @sibocw in #178
• Release: v1.0.0-pre.2 by @sibocw in #180
• Fix neck joint drifting bug by @sibocw in #183
• Add advanced vision tutorial by @tkclam in #176
• Release: v1.0.0-pre.3 by @sibocw in #181
• Fix following camera by @sibocw in #187
• add controller comparison by @tkclam in #190
• Fix bug in parallelized closed-loop plume tracking by @sibocw in #193
• Add walking controller comparison by @sibocw in #192
• Add CI checks for Windows and macOS by @sibocw in #194
• add dockerfile and CI to test it by @sibocw in #195
• Merge release v1.0.0 by @sibocw in #196

New Contributors

• @stepanove made their first contribution in #117

Full Changelog: v0.2.5...v1.0.0

v1.0.0-pre.3

• Added HybridTurningFly
• Changed RealisticVisionController to RealisticVisionFly
• Minor bug fixes
• Minor refactoring
• Updated tutorials
• Updated Sphinx website

v1.0.0-pre.2: Add further tutorials

• Added new tutorials and notebooks for:
  • Path integration
  • Head stabilization
  • Complex plume tracking
• Minor refactoring in the process of writing the tutorials above. But some of these are not backward compatible due to renaming
• Added hybrid controller notebook to the website
• Various CI changes:
  • Fixed rendering on GitHub runners so that the vision module and rendering utilities can be tested via CI
  • Upload built website as artifact in the doc workflow
• Added a gallery on the website
• Various minor updates on the website

Still pending for v1.0.0:

• Tutorial for connectome-constrained vision and multi-fly simulation
• Update change log (a mini migration guide?)
• Multi-version sphinx website
• Tutorials can be further edited

v1.0.0-pre.1: Prerelease of v1 API

We will release a new major version of flygym with several important updates:

• Improved base kinematics for walking
• Path integration
• Head stabilization
• Complex plume tracking
• Connectome-constrained vision model

This is a prerelease. The formal release will come in the next 1-2 weeks.

v0.2.5: Support MuJoCo 3.x.x

• Modify model file to support MuJoCo 3.1.1
• Remove support for Python 3.7 (too old; not supported by MuJoCo 3.x.x)
• Remove support for Python 3.12 (too new; not supported by Numba)

v0.2.4: Fix MuJoCo version to 2.3.x

See #101

v0.2.3: Bug fixes; improved ball position

• Fixed bug related to now deprecated automatic adhesion control
• Modified ball placement in the tethered environment