--[BE] Fix issues with bindings exposed by pybind11-stubgen (#2430)

* --add missing attributes bindings
* --better docstring
* --improve Configuration setters' binds and add initializers' binds
* --add LightLayoutAttributes bindings
* --improve setter and add initializer masks
raw setters and initializers should not be used for attributes, since they may corrupt a required field.
* --add SemanticAttributes bindings
* --address some sensor binding stub errors
* --pull configuration bindings out of simbindings into their own file
* --add missing enums and docstrings
* --rearrange/cleanup
* --update magnum bindings to catch missing include
* --Separate scene node definition and extension to address circular dep
* --Temporarily remove link access binding since link lacks bindings
* --Separate Render-related binds for creation and def for circular refs
* --address LightPositionModel enum in LightInfo ctor

src/esp/bindings/AttributesManagersBindings.cpp

@@ -11,6 +11,7 @@
 #include "esp/metadata/attributes/AbstractObjectAttributes.h"
 #include "esp/metadata/attributes/LightLayoutAttributes.h"
 #include "esp/metadata/attributes/ObjectAttributes.h"
+#include "esp/metadata/attributes/SemanticAttributes.h"
 #include "esp/metadata/attributes/StageAttributes.h"
 
 #include "esp/metadata/managers/AOAttributesManager.h"
@@ -416,8 +417,8 @@ void initAttributesManagersBindings(py::module& m) {
 
   // ==== Light Layout Attributes Template manager ====
   declareBaseAttributesManager<LightLayoutAttributes,
-                               ManagedObjectAccess::Copy>(m, "LightLayout",
-                                                          "BaseLightLayout");
+                               ManagedObjectAccess::Copy>(
+      m, "LightLayoutAttributes", "BaseLightLayout");
   // NOLINTNEXTLINE(bugprone-unused-raii)
   py::class_<
       LightLayoutAttributesManager,
@@ -497,17 +498,6 @@ void initAttributesManagersBindings(py::module& m) {
            R"(Returns the handle for a random synthesized(primitive asset)-based
           template chosen from the existing ObjectAttributes templates being managed.)");
 
-  // ==== Stage Attributes Template manager ====
-  declareBaseAttributesManager<StageAttributes, ManagedObjectAccess::Copy>(
-      m, "StageAttributes", "BaseStage");
-  // NOLINTNEXTLINE(bugprone-unused-raii)
-  py::class_<StageAttributesManager,
-             AttributesManager<StageAttributes, ManagedObjectAccess::Copy>,
-             StageAttributesManager::ptr>(
-      m, "StageAttributesManager",
-      R"(Manages StageAttributes which define metadata for stages (i.e. static background mesh such
-      as architectural elements) pre-instantiation. Can import .stage_config.json files.)");
-
   // ==== Physics World/Manager Template manager ====
 
   declareBaseAttributesManager<PhysicsManagerAttributes,
@@ -544,6 +534,17 @@ void initAttributesManagersBindings(py::module& m) {
       R"(Manages SemanticAttributes which define semantic mappings and files applicable to a scene instance,
       such as semantic screen descriptor files and semantic regions. Can import .semantic_config.json files.)");
 
+  // ==== Stage Attributes Template manager ====
+  declareBaseAttributesManager<StageAttributes, ManagedObjectAccess::Copy>(
+      m, "StageAttributes", "BaseStage");
+  // NOLINTNEXTLINE(bugprone-unused-raii)
+  py::class_<StageAttributesManager,
+             AttributesManager<StageAttributes, ManagedObjectAccess::Copy>,
+             StageAttributesManager::ptr>(
+      m, "StageAttributesManager",
+      R"(Manages StageAttributes which define metadata for stages (i.e. static background mesh such
+      as architectural elements) pre-instantiation. Can import .stage_config.json files.)");
+
 }  // initAttributesManagersBindings
 }  // namespace managers
 }  // namespace metadata

src/esp/bindings/Bindings.cpp

@@ -9,6 +9,7 @@
 #include "esp/core/Configuration.h"
 #include "esp/core/Esp.h"
 #include "esp/core/RigidState.h"
+#include "esp/gfx/Renderer.h"
 
 namespace py = pybind11;
 using py::literals::operator""_a;
@@ -58,24 +59,36 @@ PYBIND11_MODULE(habitat_sim_bindings, m) {
 
   py::bind_map<std::map<std::string, std::string>>(m, "MapStringString");
 
-  // NOTE(msb) These need to be run in dependency order.
-  // TODO(msb) gfx, scene, and sensor should not cross-depend
-  // TODO(msb) sim and sensor should not cross-depend
   esp::initEspBindings(m);
   esp::core::config::initConfigBindings(m);
   esp::core::initCoreBindings(m);
   esp::geo::initGeoBindings(m);
-  esp::scene::initSceneBindings(m);
-  esp::gfx::initGfxBindings(m);
-  esp::gfx::replay::initGfxReplayBindings(m);
+
+  // To address circular references, we build certain class binding before
+  // other bindings that reference it, and then complete its definition that
+  // includes references to those classes.
+  auto pySceneNode = esp::scene::createSceneNodeBind(m);
+  auto pyRenderCamera = esp::gfx::createRenderCameraBind(m);
+  auto pyRenderer = esp::gfx::createRendererBind(m);
+  esp::gfx::initRenderTargetBind(m);
+  // Sensor depends on SceneNode, RenderCamera and RenderTarget bindings
   esp::sensor::initSensorBindings(m);
+  esp::gfx::initGfxBindings(m, pyRenderCamera);
+
+  esp::gfx::replay::initGfxReplayBindings(m);
+  // We pass the created scene node class binding to the initialization function
+  // to complete its definition
+  esp::scene::initSceneBindings(m, pySceneNode);
   esp::nav::initShortestPathBindings(m);
+  esp::sim::initSimConfigBindings(m);
   esp::metadata::initAttributesBindings(m);
-  esp::metadata::initMetadataMediatorBindings(m);
   esp::metadata::managers::initAttributesManagersBindings(m);
+  esp::metadata::initMetadataMediatorBindings(m);
   // These depend on SceneNode bindings
   esp::physics::initPhysicsBindings(m);
   esp::physics::initPhysicsObjectBindings(m);
   esp::physics::initPhysicsWrapperManagerBindings(m);
   esp::sim::initSimBindings(m);
+  // Renderer relies on simulator class bindings
+  esp::gfx::finalInitRenderer(pyRenderer);
 }

src/esp/bindings/Bindings.h

@@ -5,6 +5,7 @@
 #ifndef ESP_BINDINGS_BINDINGS_H_
 #define ESP_BINDINGS_BINDINGS_H_
 
+#include <Magnum/SceneGraph/PythonBindings.h>
 #include <pybind11/pybind11.h>
 #include "esp/bindings/OpaqueTypes.h"
 
@@ -33,10 +34,51 @@ void initGeoBindings(pybind11::module& m);
 
 namespace gfx {
 
+/**
+ * @brief Create pybind class for RenderCamera, and partially define bindings.
+ * Bindings should be completed in @ref initGfxBindings, once dependent
+ * bindings have been created (i.e. SceneNode)
+ */
+pybind11::class_<RenderCamera,
+                 Magnum::SceneGraph::PyFeature<RenderCamera>,
+                 Magnum::SceneGraph::Camera3D,
+                 Magnum::SceneGraph::PyFeatureHolder<RenderCamera>>
+createRenderCameraBind(pybind11::module& m);
+
+class Renderer;
+
+/**
+ * @brief Create pybind class for Renderer, and partially define bindings.
+ * Bindings should be completed in @ref initGfxBindings, once dependent
+ * bindings have been created (i.e. SceneNode)
+ */
+pybind11::class_<esp::gfx::Renderer, std::shared_ptr<Renderer>>
+createRendererBind(pybind11::module& m);
+
+/**
+ * @brief Finalize Renderer bindings definitions after sim bindings class
+ * defined.
+ */
+void finalInitRenderer(
+    pybind11::class_<Renderer, std::shared_ptr<Renderer>>& renderer);
+
+/**
+ * @brief Specify bindings for RenderTarget. Done separately so that it can be
+ * performed before Sensor bindings are defined, which depend on it.
+ */
+void initRenderTargetBind(pybind11::module& m);
+
 /**
  * @brief Specify bindings for constructs in esp::gfx namespace
  */
-void initGfxBindings(pybind11::module& m);
+void initGfxBindings(
+    pybind11::module& m,
+    pybind11::class_<RenderCamera,
+                     Magnum::SceneGraph::PyFeature<RenderCamera>,
+                     Magnum::SceneGraph::Camera3D,
+                     Magnum::SceneGraph::PyFeatureHolder<RenderCamera>>&
+        renderCamera);
+
 namespace replay {
 /**
  * @brief Specify bindings for constructs in esp::gfx::replay namespace
@@ -96,6 +138,16 @@ void initPhysicsWrapperManagerBindings(pybind11::module& m);
 }  // namespace physics
 
 namespace scene {
+
+pybind11::class_<
+    esp::scene::SceneNode,
+    Magnum::SceneGraph::PyObject<esp::scene::SceneNode>,
+    Magnum::SceneGraph::Object<
+        Magnum::SceneGraph::BasicTranslationRotationScalingTransformation3D<
+            float>>,
+    Magnum::SceneGraph::PyObjectHolder<esp::scene::SceneNode>>
+createSceneNodeBind(pybind11::module& m);
+
 /**
  * @brief Specify bindings for @ref esp::scene::SceneNode , @ref esp::scene::SceneGraph ,
  * @ref esp::scene::SceneManager , @ref esp::scene::SemanticCategory ,
@@ -104,7 +156,16 @@ namespace scene {
  * @ref esp::scene::SemanticLevel , @ref esp::scene::SemanticScene , and
  * @ref esp::scene::ObjectControls
  */
-void initSceneBindings(pybind11::module& m);
+void initSceneBindings(
+    pybind11::module& m,
+    pybind11::class_<
+        esp::scene::SceneNode,
+        Magnum::SceneGraph::PyObject<esp::scene::SceneNode>,
+        Magnum::SceneGraph::Object<
+            Magnum::SceneGraph::BasicTranslationRotationScalingTransformation3D<
+                float>>,
+        Magnum::SceneGraph::PyObjectHolder<esp::scene::SceneNode>>&
+        pySceneNode);
 }  // namespace scene
 
 namespace sensor {
@@ -116,10 +177,14 @@ void initSensorBindings(pybind11::module& m);
 
 namespace sim {
 /**
- * @brief Specify bindings for @ref esp::sim::SimulatorConfiguration , @ref esp::sim::Simulator ,
- * @ref esp::sim::ReplayRendererConfiguration , @ref esp::sim::AbstractReplayRenderer ,
+ * @brief Specify bindings for @ref esp::sim::Simulator and @ref esp::sim::AbstractReplayRenderer ,
  */
 void initSimBindings(pybind11::module& m);
+/**
+ * @brief Specify bindings for @ref esp::sim::SimulatorConfiguration and
+ * @ref esp::sim::ReplayRendererConfiguration
+ */
+void initSimConfigBindings(pybind11::module& m);
 }  // namespace sim
 
 }  // namespace esp