refactor: modernize Blender-to-Core translation pipeline and stabilize integration tests

- Implemented a Registry-based Translator pattern (ITranslator) for specialized component handling.
- Decoupled physical, mechanical, and control layers into dedicated Translators (Link, Joint, Sensor, Transmission, Ros2Control).
- Purged legacy shims, diagnostic prints, and dead code from the adapter layer.
- Fixed a critical 'MagicMock' leakage issue in integration tests by correcting property access in Ros2ControlTranslator.
- Standardized ROS 2 control property mapping to use 'hardware_plugin' per the core model specification.
- Achieved 100% test coverage for the new architecture with 58 unit tests and 16 integration tests.
- Sanitized imports and applied professional formatting across the adapter and test suites.

Signed-off-by: arounamounchili <patouossa.mounchili@gmail.com>

Author: arounamounchili

CONTRIBUTING.md

@@ -214,8 +214,8 @@ def test_link_creation():
     """Test creating a link with valid parameters."""
     link = Link(
         name="test_link",
-        initial_visuals=[],
-        initial_collisions=[],
+        visuals=[],
+        collisions=[],
         inertial=Inertial(mass=1.0, inertia=InertiaTensor.zero())
     )
     assert link.name == "test_link"

core/src/linkforge_core/composer/link_builder.py

@@ -476,43 +476,34 @@ def calibration(self, rising: float | None = None, falling: float | None = None)
         return self
 
     def physics(self, **kwargs: Any) -> LinkBuilder:
-        """Set simulation and contact physics properties for this link.
+        """Set surface and contact physics properties for this link.
 
-        Supports both typed LinkPhysics fields and raw gazebo_params.
+        Supports both typed LinkPhysics fields and raw engine-specific parameters.
 
         Common arguments:
             self_collide (bool): Enable self-collision.
             gravity (bool): Enable gravity.
-            mu1, mu2 (float): Friction coefficients.
+            mu, mu2 (float): Friction coefficients.
             kp, kd (float): Contact stiffness and damping.
 
         Returns:
             The LinkBuilder instance.
         """
         self._check_not_committed()
 
-        # Update both typed model and raw gazebo_params for backward compatibility
         phys_fields = {f.name for f in LinkPhysics.__dataclass_fields__.values()}
-
-        # Mapping for Blender/ODE specific names to Core Physics fields
-        mapped_kwargs = kwargs.copy()
-        if "mu1" in kwargs and "mu" not in kwargs:
-            mapped_kwargs["mu"] = kwargs["mu1"]
-
-        phys_updates = {k: v for k, v in mapped_kwargs.items() if k in phys_fields}
+        phys_updates = {k: v for k, v in kwargs.items() if k in phys_fields}
 
         if phys_updates:
             self._link.physics = replace(self._link.physics, **phys_updates)
 
-        # Always update gazebo_params so generators/tests relying on it continue to work
-        self._link.gazebo_params.update(kwargs)
+        # Store non-physics fields in gazebo_params
+        remaining_kwargs = {k: v for k, v in kwargs.items() if k not in phys_fields}
+        if remaining_kwargs:
+            self._link.gazebo_params.update(remaining_kwargs)
 
         return self
 
-    def simulation(self, **kwargs: Any) -> LinkBuilder:
-        """Deprecated: Use physics() instead."""
-        return self.physics(**kwargs)
-
     def _configure_joint(
         self,
         name: str | None = None,
@@ -902,8 +893,8 @@ def _finalize_link(self, inertial: Inertial | None) -> None:
         l_state = self._link
         link = Link(
             name=self._link_name,
-            initial_visuals=l_state.visuals,
-            initial_collisions=l_state.collisions,
+            visuals=l_state.visuals,
+            collisions=l_state.collisions,
             inertial=inertial,
             physics=l_state.physics,
         )

core/src/linkforge_core/constants.py

@@ -6,7 +6,7 @@
 # ----------------------------
 
 # Default static friction coefficient (Coulomb)
-DEFAULT_FRICTION_MU1 = 1.0
+DEFAULT_FRICTION_MU = 1.0
 
 # Default dynamic friction coefficient (Coulomb)
 DEFAULT_FRICTION_MU2 = 1.0

core/src/linkforge_core/generators/urdf_generator.py

@@ -13,6 +13,7 @@
 ]
 
 import xml.etree.ElementTree as ET
+from collections import defaultdict
 from pathlib import Path
 from typing import Any
 
@@ -22,7 +23,7 @@
 from ..models.gazebo import GazeboElement, GazeboPlugin
 from ..models.geometry import Transform
 from ..models.joint import Joint, JointType
-from ..models.link import Collision, Link, Visual
+from ..models.link import Collision, Link, LinkPhysics, Visual
 from ..models.material import Material
 from ..models.robot import Robot
 from ..models.ros2_control import Ros2Control
@@ -773,19 +774,13 @@ def _add_gazebo_element(self, parent: ET.Element, gazebo_elem: GazeboElement) ->
             xml_add_text(gz_elem, "material", gazebo_elem.material)
 
         # Add boolean properties
-        self._add_optional_bool_element(gz_elem, "selfCollide", gazebo_elem.self_collide)
         self._add_optional_bool_element(gz_elem, "static", gazebo_elem.static)
-        self._add_optional_bool_element(gz_elem, "gravity", gazebo_elem.gravity)
         self._add_optional_bool_element(gz_elem, "provideFeedback", gazebo_elem.provide_feedback)
         self._add_optional_bool_element(
             gz_elem, "implicitSpringDamper", gazebo_elem.implicit_spring_damper
         )
 
         # Add numeric properties
-        self._add_optional_numeric_element(gz_elem, "mu1", gazebo_elem.mu1)
-        self._add_optional_numeric_element(gz_elem, "mu2", gazebo_elem.mu2)
-        self._add_optional_numeric_element(gz_elem, "kp", gazebo_elem.kp)
-        self._add_optional_numeric_element(gz_elem, "kd", gazebo_elem.kd)
         self._add_optional_numeric_element(gz_elem, "stopCfm", gazebo_elem.stop_cfm)
         self._add_optional_numeric_element(gz_elem, "stopErp", gazebo_elem.stop_erp)
 
@@ -885,12 +880,75 @@ def add_gazebo(self, parent: ET.Element, robot: Robot) -> None:
             parent: Parent XML element (robot)
             robot: Robot model
         """
-        if robot.gazebo_elements:
+        if robot.links or robot.gazebo_elements:
             parent.append(ET.Comment(" Gazebo "))
-        # Sort gazebo elements by reference for deterministic output
-        # Empty reference (global) comes first
-        for gazebo_elem in sorted(robot.gazebo_elements, key=lambda g: g.reference or ""):
-            self._add_gazebo_element(parent, gazebo_elem)
+
+        grouped_elements: dict[str | None, list[GazeboElement]] = defaultdict(list)
+        for gz in robot.gazebo_elements:
+            grouped_elements[gz.reference].append(gz)
+
+        # 1. Handle Link-level Gazebo tags (Physics + Extensions)
+        for link in sorted(robot.links, key=lambda lnk: lnk.name):
+            # Create a single tag for this link
+            gz_tag = ET.SubElement(parent, "gazebo", reference=link.name)
+
+            # Add Physics (Universal Truth)
+            self._fill_link_physics(gz_tag, link.physics)
+
+            # Add any explicit Gazebo elements for this link
+            if link.name in grouped_elements:
+                for elem in grouped_elements[link.name]:
+                    self._fill_gazebo_element(gz_tag, elem)
+                # Mark as handled
+                del grouped_elements[link.name]
+
+        # 2. Handle Robot-level (reference=None) and other Gazebo tags
+        # Sort by reference for deterministic output
+        for ref in sorted(grouped_elements.keys(), key=lambda r: r or ""):
+            attrib = {"reference": ref} if ref else {}
+            gz_tag = ET.SubElement(parent, "gazebo", attrib)
+            for elem in grouped_elements[ref]:
+                self._fill_gazebo_element(gz_tag, elem)
+
+    def _fill_link_physics(self, gz_elem: ET.Element, phys: LinkPhysics) -> None:
+        """Fill an existing gazebo element with physics properties."""
+        # Boolean properties
+        ET.SubElement(gz_elem, "selfCollide").text = "true" if phys.self_collide else "false"
+        ET.SubElement(gz_elem, "gravity").text = "true" if phys.gravity else "false"
+
+        # Friction parameters
+        ET.SubElement(gz_elem, "mu1").text = format_float(phys.mu)
+        ET.SubElement(gz_elem, "mu2").text = format_float(phys.mu2)
+
+        # Contact parameters
+        ET.SubElement(gz_elem, "kp").text = format_float(phys.kp)
+        ET.SubElement(gz_elem, "kd").text = format_float(phys.kd)
+
+    def _fill_gazebo_element(self, gz_elem: ET.Element, gazebo_elem: GazeboElement) -> None:
+        """Fill an existing gazebo element with properties from a GazeboElement model."""
+        # Add material if specified
+        if gazebo_elem.material is not None:
+            xml_add_text(gz_elem, "material", gazebo_elem.material)
+
+        # Add boolean properties
+        self._add_optional_bool_element(gz_elem, "static", gazebo_elem.static)
+        self._add_optional_bool_element(gz_elem, "provideFeedback", gazebo_elem.provide_feedback)
+        self._add_optional_bool_element(
+            gz_elem, "implicitSpringDamper", gazebo_elem.implicit_spring_damper
+        )
+
+        # Add numeric properties
+        self._add_optional_numeric_element(gz_elem, "stopCfm", gazebo_elem.stop_cfm)
+        self._add_optional_numeric_element(gz_elem, "stopErp", gazebo_elem.stop_erp)
+
+        # Add custom properties (sort by key for deterministic output)
+        for key in sorted(gazebo_elem.properties.keys()):
+            prop_elem = ET.SubElement(gz_elem, key)
+            prop_elem.text = gazebo_elem.properties[key]
+
+        # Add plugins (sort by name for deterministic output)
+        for plugin in sorted(gazebo_elem.plugins, key=lambda p: p.name):
+            self._add_gazebo_plugin_element(gz_elem, plugin)
 
     def add_sensors(self, parent: ET.Element, robot: Robot) -> None:
         """Add Sensors section to parent element.

core/src/linkforge_core/models/gazebo.py

@@ -19,24 +19,16 @@ class GazeboElement:
     properties: dict[str, str] = field(default_factory=dict)
     plugins: list[GazeboPlugin] = field(default_factory=list)
 
-    # Common properties for links
+    # Common properties for links (platform-specific)
     material: str | None = None  # Gazebo material (e.g., "Gazebo/Red")
-    self_collide: bool | None = None
     static: bool | None = None
-    gravity: bool | None = None
 
-    # Common properties for joints
+    # Common properties for joints (platform-specific)
     stop_cfm: float | None = None  # Constraint force mixing for joint stops
     stop_erp: float | None = None  # Error reduction parameter for joint stops
     provide_feedback: bool | None = None  # Enable force-torque feedback
     implicit_spring_damper: bool | None = None
 
-    # Friction parameters
-    mu1: float | None = None  # Friction coefficient in first friction direction
-    mu2: float | None = None  # Friction coefficient in second friction direction
-    kp: float | None = None  # Contact stiffness
-    kd: float | None = None  # Contact damping
-
     def __post_init__(self) -> None:
         """Validate Gazebo element."""
         # If reference is specified, it must be non-empty

core/src/linkforge_core/models/link.py

@@ -2,13 +2,12 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
-from dataclasses import InitVar, dataclass, field, replace
+from dataclasses import dataclass, field, replace
 
 from ..constants import (
     DEFAULT_CONTACT_KD,
     DEFAULT_CONTACT_KP,
-    DEFAULT_FRICTION_MU1,
+    DEFAULT_FRICTION_MU,
     DEFAULT_FRICTION_MU2,
     DEFAULT_GRAVITY,
     DEFAULT_SELF_COLLIDE,
@@ -99,11 +98,17 @@ def __post_init__(self) -> None:
 
 @dataclass(frozen=True)
 class LinkPhysics:
-    """Advanced physics settings for simulation engines (Gazebo/GZ)."""
+    """Surface and contact physics properties for a link.
+
+    These parameters govern how the link interacts with other objects in a
+    physics simulator (e.g., Gazebo, MuJoCo, PyBullet). While naming follows
+    common conventions, generators are responsible for mapping these to
+    engine-specific equivalents.
+    """
 
     self_collide: bool = DEFAULT_SELF_COLLIDE
     gravity: bool = DEFAULT_GRAVITY
-    mu: float = DEFAULT_FRICTION_MU1
+    mu: float = DEFAULT_FRICTION_MU
     mu2: float = DEFAULT_FRICTION_MU2
     kp: float = DEFAULT_CONTACT_KP
     kd: float = DEFAULT_CONTACT_KD
@@ -150,19 +155,12 @@ class Link:
     """
 
     name: str
-    initial_visuals: InitVar[Sequence[Visual] | None] = None
-    initial_collisions: InitVar[Sequence[Collision] | None] = None
     inertial: Inertial | None = None
     physics: LinkPhysics = field(default_factory=LinkPhysics)
+    visuals: list[Visual] = field(default_factory=list)
+    collisions: list[Collision] = field(default_factory=list)
 
-    _visuals: list[Visual] = field(default_factory=list, init=False)
-    _collisions: list[Collision] = field(default_factory=list, init=False)
-
-    def __post_init__(
-        self,
-        initial_visuals: Sequence[Visual] | None = None,
-        initial_collisions: Sequence[Collision] | None = None,
-    ) -> None:
+    def __post_init__(self) -> None:
         """Validate link."""
         if not self.name:
             raise RobotValidationError(
@@ -178,28 +176,19 @@ def __post_init__(
                 value=self.name,
             )
 
-        if initial_visuals:
-            self._visuals.extend(initial_visuals)
-        if initial_collisions:
-            self._collisions.extend(initial_collisions)
-
-    @property
-    def visuals(self) -> list[Visual]:
-        """Get visual representations."""
-        return list(self._visuals)
-
-    @property
-    def collisions(self) -> list[Collision]:
-        """Get collision representations."""
-        return list(self._collisions)
+        # Ensure visuals and collisions are lists (in case they were passed as other sequences)
+        if not isinstance(self.visuals, list):
+            self.visuals = list(self.visuals)
+        if not isinstance(self.collisions, list):
+            self.collisions = list(self.collisions)
 
     def add_visual(self, visual: Visual) -> None:
         """Add a visual representation."""
-        self._visuals.append(visual)
+        self.visuals.append(visual)
 
     def add_collision(self, collision: Collision) -> None:
         """Add a collision representation."""
-        self._collisions.append(collision)
+        self.collisions.append(collision)
 
     @property
     def mass(self) -> float:
@@ -220,7 +209,7 @@ def with_prefix(self, prefix: str) -> Link:
         """Create a new link with a prefixed name and sub-elements."""
         return Link(
             name=f"{prefix}{self.name}",
-            initial_visuals=[v.with_prefix(prefix) for v in self._visuals],
-            initial_collisions=[c.with_prefix(prefix) for c in self._collisions],
-            inertial=self.inertial,
+            visuals=[v.with_prefix(prefix) for v in self.visuals],
+            collisions=[c.with_prefix(prefix) for c in self.collisions],
+            physics=self.physics,
         )