refactor: complete architectural hardening and code quality audit

- Centralized all magic literals in core and blender platforms.
- Reorganized constants for improved logical flow and maintainability.
- Resolved import instabilities in URDF/SRDF parsers.
- Rephrased legacy comments into professional compatibility notices.
- Fixed numerical precision regressions in joint tests.
- Verified with full test suite, linting, and type checking.

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

Author: arounamounchili

core/src/linkforge_core/composer/link_builder.py

@@ -15,6 +15,14 @@
 from dataclasses import dataclass, field, replace
 from typing import TYPE_CHECKING, Any
 
+from ..constants import (
+    DEFAULT_CAMERA_FOV,
+    DEFAULT_CAMERA_HEIGHT,
+    DEFAULT_CAMERA_WIDTH,
+    DEFAULT_LIDAR_RANGE_MAX,
+    DEFAULT_LIDAR_RANGE_MIN,
+    DEFAULT_LIDAR_SAMPLES,
+)
 from ..exceptions import RobotValidationError, ValidationErrorCode
 from ..models.gazebo import GazeboElement
 from ..models.geometry import Geometry, Transform, Vector3
@@ -604,9 +612,9 @@ def ros2_control(
     def camera(
         self,
         name: str,
-        fov: float = 1.047,
-        width: int = 640,
-        height: int = 480,
+        fov: float = DEFAULT_CAMERA_FOV,
+        width: int = DEFAULT_CAMERA_WIDTH,
+        height: int = DEFAULT_CAMERA_HEIGHT,
         xyz: tuple[float, float, float] = (0, 0, 0),
         rpy: tuple[float, float, float] = (0, 0, 0),
     ) -> LinkBuilder:
@@ -636,9 +644,9 @@ def camera(
     def lidar(
         self,
         name: str,
-        range_min: float = 0.1,
-        range_max: float = 10.0,
-        samples: int = 640,
+        range_min: float = DEFAULT_LIDAR_RANGE_MIN,
+        range_max: float = DEFAULT_LIDAR_RANGE_MAX,
+        samples: int = DEFAULT_LIDAR_SAMPLES,
         xyz: tuple[float, float, float] = (0, 0, 0),
         rpy: tuple[float, float, float] = (0, 0, 0),
     ) -> LinkBuilder:

core/src/linkforge_core/constants.py

@@ -3,42 +3,16 @@
 This module provides industry-standard baselines used during robot model
 definition and validation. Constants are categorized into:
 
-- **Physics Defaults**: Standard friction, stiffness, and damping coefficients.
-- **Namespaces**: Official URIs and prefixes for XML/XACRO processing.
-- **Numerical Stability**: Guardrails (mass, inertia, epsilon) for simulation.
-- **Validation**: Thresholds for mesh topology and file size.
+1.  **Infrastructure**: XML/XACRO namespaces and structural prefixes.
+2.  **Numerical Stability**: Fundamental precision and solver guardrails.
+3.  **Validation**: Physical and geometric sanity thresholds.
+4.  **Physics & Dynamics**: Global simulation and component behaviors.
+5.  **Component Defaults**: Standard baselines for Links, Joints, and Sensors.
 """
 
 from __future__ import annotations
 
-# Physics Defaults (Simulation)
-# ----------------------------
-
-# Default static friction coefficient (Coulomb)
-DEFAULT_FRICTION_MU = 1.0
-
-# Default dynamic friction coefficient (Coulomb)
-DEFAULT_FRICTION_MU2 = 1.0
-
-# Default contact stiffness (N/m)
-# 1e12 is the industry standard for 'hard' contact in Gazebo/GZ
-DEFAULT_CONTACT_KP = 1e12
-
-# Default contact damping (N s/m)
-DEFAULT_CONTACT_KD = 1.0
-
-# Default gravity inclusion
-DEFAULT_GRAVITY = True
-
-# Default self-collision inclusion
-DEFAULT_SELF_COLLIDE = False
-
-# Default Joint Axis (Z-axis is standard for many robotics defaults)
-DEFAULT_AXIS_XYZ = (0.0, 0.0, 1.0)
-DEFAULT_AXIS_XYZ_STR = "0 0 1"
-
-
-# XML and XACRO Namespaces
+# 1. XML and XACRO Infrastructure
 # ----------------------------
 
 # Official XACRO namespace URIs
@@ -52,7 +26,27 @@
 XACRO_PREFIX = "xacro:"
 
 
-# Validation Limits (Sanity Checks)
+# 2. Numerical Stability (Foundation)
+# ----------------------------
+
+# General small value for floating point comparisons
+EPSILON = 1e-9
+
+# Stability epsilon for Sylvester's criterion and inertia checks
+SYLVESTER_TOLERANCE_EPSILON = 1e-9
+
+# Minimum mass in kg to prevent singular matrices in dynamics solvers
+MIN_REASONABLE_MASS = 1e-6
+
+# Minimum inertia diagonal value to prevent zero-inertia crashes
+MIN_REASONABLE_INERTIA = 1e-9
+
+# Thresholds for inertia calculation fallback and stability
+MIN_MASS_STABILITY_THRESHOLD = 0.01  # kg
+MIN_INERTIA_STABILITY_VALUE = 1e-6  # kg·m²
+
+
+# 3. Validation Limits (Guardrails)
 # ----------------------------
 
 # Maximum absolute value allowed for floats in robot models
@@ -68,46 +62,77 @@
 # Maximum depth for XML tree parsing to prevent Billion Laughs / recursion issues
 MAX_XML_DEPTH = 2000
 
-
-# Numerical Stability (Guardrails)
-# ----------------------------
-
-# Small value for floating point comparisons
-EPSILON = 1e-9
-
-# Minimum mass in kg to prevent singular matrices in dynamics solvers
-MIN_REASONABLE_MASS = 1e-6
-
-# Minimum inertia diagonal value to prevent zero-inertia crashes
-MIN_REASONABLE_INERTIA = 1e-9
-
-# Thresholds for inertia calculation fallback and stability
-MIN_MASS_STABILITY_THRESHOLD = 0.01  # kg
-MIN_INERTIA_STABILITY_VALUE = 1e-6  # kg·m²
-
-# Geometric thresholds
+# Geometric and Mesh thresholds
 DEGENERATE_VOL_THRESHOLD = 1e-12  # m³
 NEGATIVE_INERTIA_THRESHOLD = -1e-06
-SYLVESTER_TOLERANCE_EPSILON = 1e-9
-
-# Mesh Validation Thresholds
 MESH_PROXIMITY_THRESHOLD = 6
 MESH_SLIVER_THRESHOLD = 1000.0
 MIN_MESH_AREA = 1e-15
 
 
-# Joint Dynamics Defaults
+# 4. Global Physics Defaults
 # ----------------------------
 
-# Default joint damping (N s / m or N m s / rad)
-DEFAULT_JOINT_DAMPING = 0.0
+# Default static/dynamic friction coefficient (Coulomb)
+DEFAULT_FRICTION_MU = 1.0
+DEFAULT_FRICTION_MU2 = 1.0
 
-# Default joint friction (N or N m)
-DEFAULT_JOINT_FRICTION = 0.0
+# Default contact stiffness (N/m) and damping (N s/m)
+# 1e12 is the industry standard for 'hard' contact in Gazebo/GZ
+DEFAULT_CONTACT_KP = 1e12
+DEFAULT_CONTACT_KD = 1.0
+
+# Simulation toggles
+DEFAULT_GRAVITY = True
+DEFAULT_SELF_COLLIDE = False
 
-# Visualization Defaults (Core)
+
+# 5. Component Defaults
 # ----------------------------
-DEFAULT_COLOR_RGBA_STR = "0.7 0.7 0.7 1.0"
+
+# --- Link Defaults ---
+DEFAULT_LINK_MASS = 1.0
+DEFAULT_MATERIAL_RGBA = (0.7, 0.7, 0.7, 1.0)
+DEFAULT_MATERIAL_RGBA_STR = "0.7 0.7 0.7 1.0"
 DEFAULT_MESH_SCALE_STR = "1 1 1"
 DEFAULT_GEOMETRY_RADIUS = 0.1
 DEFAULT_GEOMETRY_LENGTH = 0.5
+
+# --- Joint Defaults ---
+# Default axis (Z-axis is standard for many robotics defaults)
+DEFAULT_AXIS_XYZ = (0.0, 0.0, 1.0)
+DEFAULT_AXIS_XYZ_STR = "0 0 1"
+
+# Joint Dynamics
+DEFAULT_JOINT_DAMPING = 0.0
+DEFAULT_JOINT_FRICTION = 0.0
+DEFAULT_JOINT_EFFORT = 10.0
+DEFAULT_JOINT_VELOCITY = 1.0
+
+# --- Sensor Defaults ---
+# Common
+DEFAULT_UPDATE_RATE = 30.0
+DEFAULT_SENSOR_TYPE = "CAMERA"
+DEFAULT_SENSOR_ALWAYS_ON = True
+DEFAULT_SENSOR_VISUALIZE = False
+
+# Camera
+DEFAULT_CAMERA_FOV = 1.047  # Radians (~60 degrees)
+DEFAULT_CAMERA_WIDTH = 640
+DEFAULT_CAMERA_HEIGHT = 480
+DEFAULT_CAMERA_FORMAT = "R8G8B8"
+DEFAULT_CAMERA_NEAR = 0.1
+DEFAULT_CAMERA_FAR = 100.0
+
+# LIDAR Horizontal Parameters
+DEFAULT_LIDAR_SAMPLES = 640
+DEFAULT_LIDAR_RANGE_MIN = 0.1
+DEFAULT_LIDAR_RANGE_MAX = 10.0
+DEFAULT_LIDAR_RANGE_RESOLUTION = 0.01
+DEFAULT_LIDAR_MIN_ANGLE = -1.570796  # -90 degrees
+DEFAULT_LIDAR_MAX_ANGLE = 1.570796  # +90 degrees
+
+# LIDAR Vertical Parameters
+DEFAULT_LIDAR_VERTICAL_SAMPLES = 1
+DEFAULT_LIDAR_VERTICAL_MIN_ANGLE = 0.0
+DEFAULT_LIDAR_VERTICAL_MAX_ANGLE = 0.0

core/src/linkforge_core/models/joint.py

@@ -20,6 +20,7 @@
     DEFAULT_JOINT_DAMPING,
     DEFAULT_JOINT_FRICTION,
     EPSILON,
+    SYLVESTER_TOLERANCE_EPSILON,
 )
 from ..exceptions import RobotValidationError, ValidationErrorCode
 from ..utils.string_utils import is_valid_name
@@ -259,7 +260,7 @@ def __post_init__(self) -> None:
                 )
 
             # Enforce normalized axis in model
-            if abs(axis_magnitude - 1.0) > 1e-6:
+            if abs(axis_magnitude - 1.0) > SYLVESTER_TOLERANCE_EPSILON:
                 raise RobotValidationError(
                     ValidationErrorCode.INVALID_VALUE,
                     "Joint axis must be a unit vector",

core/src/linkforge_core/models/material.py

@@ -12,6 +12,7 @@
 
 from dataclasses import dataclass, replace
 
+from ..constants import DEFAULT_MATERIAL_RGBA
 from ..exceptions import RobotValidationError, ValidationErrorCode
 
 
@@ -47,8 +48,8 @@ def black(cls) -> Color:
 
     @classmethod
     def grey(cls) -> Color:
-        """Standard grey color (0.5, 0.5, 0.5, 1.0)."""
-        return cls(0.5, 0.5, 0.5, 1.0)
+        """Standard grey color from constants."""
+        return cls(*DEFAULT_MATERIAL_RGBA)
 
     def to_tuple(self) -> tuple[float, float, float, float]:
         """Convert to RGBA tuple."""

core/src/linkforge_core/models/sensor.py

@@ -17,7 +17,21 @@
 from dataclasses import dataclass, field, replace
 from enum import Enum
 
-from ..constants import EPSILON
+from ..constants import (
+    DEFAULT_CAMERA_FAR,
+    DEFAULT_CAMERA_FORMAT,
+    DEFAULT_CAMERA_FOV,
+    DEFAULT_CAMERA_HEIGHT,
+    DEFAULT_CAMERA_NEAR,
+    DEFAULT_CAMERA_WIDTH,
+    DEFAULT_LIDAR_MAX_ANGLE,
+    DEFAULT_LIDAR_MIN_ANGLE,
+    DEFAULT_LIDAR_RANGE_MAX,
+    DEFAULT_LIDAR_RANGE_MIN,
+    DEFAULT_LIDAR_SAMPLES,
+    DEFAULT_UPDATE_RATE,
+    EPSILON,
+)
 from ..exceptions import RobotValidationError, ValidationErrorCode
 from .gazebo import GazeboPlugin
 from .geometry import Transform
@@ -50,12 +64,12 @@ class SensorNoise:
 class CameraInfo:
     """Camera-specific sensor information."""
 
-    horizontal_fov: float = 1.047  # Radians (~60°)
-    width: int = 640
-    height: int = 480
-    format: str = "R8G8B8"  # Pixel format
-    near_clip: float = 0.1
-    far_clip: float = 100.0
+    horizontal_fov: float = DEFAULT_CAMERA_FOV
+    width: int = DEFAULT_CAMERA_WIDTH
+    height: int = DEFAULT_CAMERA_HEIGHT
+    format: str = DEFAULT_CAMERA_FORMAT
+    near_clip: float = DEFAULT_CAMERA_NEAR
+    far_clip: float = DEFAULT_CAMERA_FAR
     noise: SensorNoise | None = None
 
     def __post_init__(self) -> None:
@@ -98,10 +112,10 @@ class LidarInfo:
     """LIDAR/laser scanner sensor information."""
 
     # Horizontal scan parameters
-    horizontal_samples: int = 640
+    horizontal_samples: int = DEFAULT_LIDAR_SAMPLES
     horizontal_resolution: float = 1.0
-    horizontal_min_angle: float = -1.570796  # -π/2 radians (-90°)
-    horizontal_max_angle: float = 1.570796  # π/2 radians (90°)
+    horizontal_min_angle: float = DEFAULT_LIDAR_MIN_ANGLE
+    horizontal_max_angle: float = DEFAULT_LIDAR_MAX_ANGLE
 
     # Vertical scan parameters (for 3D LIDAR)
     vertical_samples: int = 1
@@ -110,8 +124,8 @@ class LidarInfo:
     vertical_max_angle: float = 0.0
 
     # Range parameters
-    range_min: float = 0.1  # m
-    range_max: float = 10.0  # m
+    range_min: float = DEFAULT_LIDAR_RANGE_MIN
+    range_max: float = DEFAULT_LIDAR_RANGE_MAX
     range_resolution: float = 0.01  # m
 
     # Noise
@@ -250,7 +264,7 @@ class Sensor:
     name: str
     type: SensorType
     link_name: str  # Link this sensor is attached to
-    update_rate: float = 30.0  # Hz
+    update_rate: float = DEFAULT_UPDATE_RATE  # Hz
     always_on: bool = True
     visualize: bool = False
 

core/src/linkforge_core/parsers/srdf_parser.py

@@ -12,7 +12,7 @@
 from typing import Any, TypeVar
 
 from ..base import IResourceResolver
-from ..constants import XACRO_URIS
+from ..constants import MAX_FILE_SIZE, MAX_XML_DEPTH, XACRO_URIS
 from ..exceptions import (
     RobotParserError,
     RobotParserIOError,
@@ -34,12 +34,11 @@
     VirtualJoint,
 )
 from ..utils.xml_utils import (
-    MAX_XML_DEPTH,
     get_xml_namespace,
     parse_float,
     strip_xml_namespace,
 )
-from .xml_base import MAX_FILE_SIZE, RobotXMLParser
+from .xml_base import RobotXMLParser
 
 # Define a TypeVar for generic collection parsing
 T = TypeVar("T")