linkforge-core 1.4.0__py3-none-any.whl

linkforge/core/__init__.py

@@ -0,0 +1,301 @@
+"""LinkForge Core Library.
+
+The platform-independent heart of the LinkForge project, providing a
+unified Intermediate Representation (IR) for robotics. This core library
+handles the "Robotics Intelligence" isolated from design tools.
+
+As the "LLVM for Robotics," LinkForge Core provides the essential IR and tools
+for parsing, generating, and validating robot descriptions across formats.
+"""
+
+from __future__ import annotations
+
+# Versioning
+__version__ = "1.4.0"  # x-release-please-version
+
+# Sub-Package Exposure
+# (Ensures lf.models, lf.parsers, etc. are accessible via dot-notation)
+from . import (
+    composer,
+    constants,
+    exceptions,
+    generators,
+    models,
+    parsers,
+    physics,
+    validation,
+)
+
+# Base Architecture: Interfaces and Resolvers
+from .base import (
+    FileSystemResolver,
+    IResourceResolver,
+    NetworkResolver,
+    RobotGenerator,
+    RobotParser,
+)
+
+# Composer API: The LinkForge way to build robots
+from .composer import (
+    LinkBuilder,
+    RobotBuilder,
+    box,
+    cylinder,
+    mesh,
+    sphere,
+)
+
+# Core Infrastructure: Constants and Exceptions
+from .constants import (
+    DEFAULT_GRAVITY,
+    DEFAULT_LINK_MASS,
+    EPSILON,
+    PI,
+)
+from .exceptions import (
+    LinkForgeError,
+    RobotGeneratorError,
+    RobotMathError,
+    RobotModelError,
+    RobotParserError,
+    RobotParserIOError,
+    RobotPhysicsError,
+    RobotSecurityError,
+    RobotValidationError,
+    RobotXacroError,
+    RobotXacroExpressionError,
+    RobotXacroRecursionError,
+    ValidationErrorCode,
+    XacroDetectedError,
+)
+
+# Generators and Functional I/O
+from .generators import (
+    RobotXMLGenerator,
+    SRDFGenerator,
+    URDFGenerator,
+    XACROGenerator,
+)
+from .io import (
+    read_srdf,
+    read_urdf,
+    read_xacro,
+    validate_robot,
+    write_srdf,
+    write_urdf,
+    write_xacro,
+)
+from .logging_config import get_logger, setup_logging
+
+# IR Models: Entities, Sensors and Hardware
+from .models import (
+    Box,
+    CameraInfo,
+    Chain,
+    Collision,
+    CollisionPair,
+    Color,
+    ContactInfo,
+    Cylinder,
+    EndEffector,
+    ForceTorqueInfo,
+    GazeboElement,
+    GazeboPlugin,
+    Geometry,
+    GeometryType,
+    GPSInfo,
+    GroupState,
+    IMUInfo,
+    Inertial,
+    InertiaTensor,
+    Joint,
+    JointCalibration,
+    JointDynamics,
+    JointLimits,
+    JointMimic,
+    JointProperty,
+    JointSafetyController,
+    JointType,
+    KinematicGraph,
+    LidarInfo,
+    Link,
+    LinkPhysics,
+    LinkSphereApproximation,
+    Material,
+    Mesh,
+    PassiveJoint,
+    PlanningGroup,
+    Robot,
+    Ros2Control,
+    Ros2ControlJoint,
+    Ros2ControlSensor,
+    SemanticRobotDescription,
+    Sensor,
+    SensorNoise,
+    SensorType,
+    Sphere,
+    SrdfSphere,
+    Transform,
+    Transmission,
+    TransmissionActuator,
+    TransmissionJoint,
+    TransmissionType,
+    Vector3,
+    VirtualJoint,
+    Visual,
+)
+
+# Parsers and Resolvers
+from .parsers import (
+    RobotXMLParser,
+    SRDFParser,
+    URDFParser,
+    XACROParser,
+    XacroResolver,
+    clear_xacro_cache,
+)
+
+# Processing and Validation: Physics and Checks
+from .physics import (
+    calculate_inertia,
+    validate_mesh_topology,
+)
+from .validation import (
+    RobotValidator,
+    Severity,
+    ValidationCheck,
+    ValidationIssue,
+    ValidationResult,
+)
+
+__all__ = [
+    # Sub-Packages
+    "composer",
+    "constants",
+    "exceptions",
+    "generators",
+    "models",
+    "parsers",
+    "physics",
+    "validation",
+    # Functional API
+    "read_urdf",
+    "write_urdf",
+    "read_xacro",
+    "write_xacro",
+    "read_srdf",
+    "write_srdf",
+    "validate_robot",
+    # Core Models
+    "Robot",
+    "Link",
+    "Joint",
+    "Visual",
+    "Collision",
+    "Inertial",
+    "InertiaTensor",
+    "KinematicGraph",
+    "LinkPhysics",
+    "Transform",
+    "Vector3",
+    "Geometry",
+    "GeometryType",
+    "Material",
+    "Color",
+    "Box",
+    "Cylinder",
+    "Sphere",
+    "Mesh",
+    # Sensors & Hardware
+    "Sensor",
+    "SensorType",
+    "SensorNoise",
+    "LidarInfo",
+    "CameraInfo",
+    "IMUInfo",
+    "GPSInfo",
+    "ContactInfo",
+    "ForceTorqueInfo",
+    "Transmission",
+    "TransmissionType",
+    "TransmissionJoint",
+    "TransmissionActuator",
+    "Ros2Control",
+    "Ros2ControlJoint",
+    "Ros2ControlSensor",
+    "GazeboPlugin",
+    "GazeboElement",
+    # Semantic API
+    "SemanticRobotDescription",
+    "PlanningGroup",
+    "Chain",
+    "GroupState",
+    "EndEffector",
+    "PassiveJoint",
+    "VirtualJoint",
+    "CollisionPair",
+    "LinkSphereApproximation",
+    "SrdfSphere",
+    "JointProperty",
+    # Properties & Dynamics
+    "JointLimits",
+    "JointDynamics",
+    "JointMimic",
+    "JointSafetyController",
+    "JointCalibration",
+    "JointType",
+    # File Parsers and Generators
+    "URDFParser",
+    "XACROParser",
+    "SRDFParser",
+    "RobotXMLParser",
+    "XacroResolver",
+    "clear_xacro_cache",
+    "URDFGenerator",
+    "XACROGenerator",
+    "SRDFGenerator",
+    "RobotXMLGenerator",
+    "RobotParser",
+    "RobotGenerator",
+    "IResourceResolver",
+    "FileSystemResolver",
+    "NetworkResolver",
+    # Composer API
+    "RobotBuilder",
+    "LinkBuilder",
+    "box",
+    "cylinder",
+    "sphere",
+    "mesh",
+    # Validation & Physics
+    "RobotValidator",
+    "ValidationResult",
+    "ValidationIssue",
+    "Severity",
+    "ValidationErrorCode",
+    "ValidationCheck",
+    "calculate_inertia",
+    "validate_mesh_topology",
+    # Exceptions
+    "LinkForgeError",
+    "RobotModelError",
+    "RobotParserError",
+    "RobotParserIOError",
+    "RobotGeneratorError",
+    "RobotValidationError",
+    "RobotPhysicsError",
+    "RobotMathError",
+    "RobotSecurityError",
+    "RobotXacroError",
+    "RobotXacroRecursionError",
+    "RobotXacroExpressionError",
+    "XacroDetectedError",
+    # Constants
+    "PI",
+    "EPSILON",
+    "DEFAULT_GRAVITY",
+    "DEFAULT_LINK_MASS",
+    # Logging
+    "get_logger",
+    "setup_logging",
+]

linkforge/core/_utils/__init__.py

@@ -0,0 +1 @@
+"""Core utility functions for the LinkForge project."""

linkforge/core/_utils/dict_utils.py

@@ -0,0 +1,122 @@
+"""Dictionary utility functions for LinkForge."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar, overload
+
+K = TypeVar("K")
+V = TypeVar("V")
+T = TypeVar("T")
+
+
+class AttrDict(dict[str, Any]):
+    """Dictionary providing attribute-access for nested fields (e.g., config.mass).
+    Used for XACRO property resolution where YAML-loaded data uses dot notation.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the attribute dictionary and recursively wrap nested data.
+
+        Args:
+            *args: Positional arguments passed to the dict constructor.
+            **kwargs: Keyword arguments passed to the dict constructor.
+        """
+        super().__init__(*args, **kwargs)
+        for key, value in self.items():
+            self[key] = self._wrap(value)
+
+    @classmethod
+    def _wrap(cls, value: Any) -> Any:
+        """Recursively wrap dictionaries and lists.
+
+        Args:
+            value: The value to potentially wrap in an AttrDict.
+
+        Returns:
+            The wrapped value (AttrDict, list of wrapped values, or the original).
+        """
+        if isinstance(value, dict):
+            return cls(value)
+        if isinstance(value, list):
+            return [cls._wrap(v) for v in value]
+        return value
+
+    def __getattr__(self, name: str) -> Any:
+        """Access dictionary keys as attributes.
+
+        Args:
+            name: Key name to access.
+
+        Returns:
+            Value associated with the key.
+
+        Raises:
+            AttributeError: If key is not found.
+        """
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Set dictionary keys as attributes.
+
+        Args:
+            name: Key name to set.
+            value: Value to associate with the key.
+        """
+        self[name] = value
+
+    def __delattr__(self, name: str) -> None:
+        """Delete dictionary keys as attributes.
+
+        Args:
+            name: Key name to delete.
+
+        Raises:
+            AttributeError: If key is not found.
+        """
+        try:
+            del self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+@overload
+def filter_items_by_name(items: dict[K, V], search_term: str | None) -> dict[K, V]: ...
+
+
+@overload
+def filter_items_by_name(items: list[T], search_term: str | None) -> list[T]: ...
+
+
+def filter_items_by_name(
+    items: dict[Any, Any] | list[Any],
+    search_term: str | None,
+) -> dict[Any, Any] | list[Any]:
+    """Filter items by non case-sensitive substring matching on their names.
+
+    For dictionaries: filters by keys (dictionary keys treated as names).
+    For lists: filters by the '.name' attribute of objects.
+
+    Args:
+        items: Dictionary (name->object) or list of objects to be filtered
+        search_term: Search string to match against item names
+          (non case-sensitive)
+
+    Returns:
+        Filtered items in the same format as input. If search_term is empty
+          or None, returns all items.
+    """
+    if search_term is None:
+        return items
+
+    if isinstance(search_term, str) and search_term.strip() == "":
+        return items
+
+    search_lower = search_term.lower()
+
+    if isinstance(items, dict):
+        return {name: obj for name, obj in items.items() if search_lower in name.lower()}
+
+    return [obj for obj in items if hasattr(obj, "name") and search_lower in obj.name.lower()]

linkforge/core/_utils/math_utils.py

@@ -0,0 +1,75 @@
+"""Mathematical utility functions."""
+
+from __future__ import annotations
+
+import math
+
+from ..constants import (
+    EPSILON,
+)
+
+
+def clean_float(value: float, epsilon: float = EPSILON) -> float:
+    """Clean up floating point values to avoid -0.0 and very small numbers.
+
+    Args:
+        value: Float value to clean
+        epsilon: Threshold below which values become 0.0
+
+    Returns:
+        Cleaned float value
+    """
+    if abs(value) < epsilon:
+        return 0.0
+    return value
+
+
+def format_float(value: float, precision: int = 6) -> str:
+    """Format float with reasonable precision, removing trailing zeros.
+
+    Args:
+        value: Float value to format
+        precision: Maximum number of decimal places
+
+    Returns:
+        Formatted string
+    """
+    # Clean up small values and -0.0 first
+    cleaned = clean_float(value)
+
+    # Format with specified precision
+    formatted = f"{cleaned:.{precision}f}"
+    # Remove trailing zeros and decimal point if not needed
+    formatted = formatted.rstrip("0").rstrip(".")
+    return formatted if formatted != "-0" else "0"
+
+
+def normalize_vector(x: float, y: float, z: float) -> tuple[float, float, float]:
+    """Normalize a 3D vector to unit length.
+
+    Args:
+        x, y, z: Vector components
+
+    Returns:
+        Normalized components (x, y, z)
+    """
+    magnitude = math.sqrt(x**2 + y**2 + z**2)
+    if magnitude < EPSILON:
+        return (0.0, 0.0, 0.0)
+    return (x / magnitude, y / magnitude, z / magnitude)
+
+
+def format_vector(x: float, y: float, z: float, precision: int = 6) -> str:
+    """Format 3D vector with reasonable precision.
+
+    Converts three float components into a space-separated string suitable
+    for URDF attributes like xyz, rpy, size, etc.
+
+    Args:
+        x, y, z: Vector components
+        precision: Floating point precision
+
+    Returns:
+        Space-separated string (e.g., \"1.0 2.0 3.0\")
+    """
+    return f"{format_float(x, precision)} {format_float(y, precision)} {format_float(z, precision)}"

linkforge/core/_utils/path_utils.py

@@ -0,0 +1,169 @@
+"""Path and resource resolution utilities for LinkForge."""
+
+import os
+import re
+from pathlib import Path
+
+
+def resolve_package_path(
+    uri: str, start_dir: Path, additional_search_paths: list[Path] | None = None
+) -> Path | None:
+    """Resolve package:// URI by searching ROS_PACKAGE_PATH or upward in the tree.
+
+    This enables LinkForge to work both in standard ROS environments and in
+    standalone Blender workspaces without ROS installed.
+
+    Args:
+        uri: URI starting with package:// or package:/
+        start_dir: Starting directory for upward search (usually URDF/XACRO directory)
+        additional_search_paths: Optional list of fallback directories to check first.
+
+    Returns:
+        Path to the resolved resource or None
+    """
+    if "package://" in uri:
+        path_remainder = uri.replace("package://", "")
+    elif "package:/" in uri:
+        path_remainder = uri.replace("package:/", "")
+    elif uri.startswith("package:"):
+        path_remainder = uri.replace("package:", "")
+    else:
+        return None
+
+    if not path_remainder:
+        return None
+
+    parts = path_remainder.split("/")
+    package_name = parts[0]
+    relative_path = "/".join(parts[1:])
+
+    # Check provided additional search paths first (highest priority for overrides)
+    if additional_search_paths:
+        for p in additional_search_paths:
+            pkg_base = Path(p)
+            pkg_path = pkg_base / package_name
+            if pkg_path.exists():
+                return pkg_path / relative_path
+
+            # Also check if we ARE inside the package base already
+            if pkg_base.name == package_name:
+                return pkg_base / relative_path
+
+    # Check ROS_PACKAGE_PATH (ROS Mode)
+    ros_path = os.environ.get("ROS_PACKAGE_PATH")
+    if ros_path:
+        for path in ros_path.split(os.pathsep):
+            pkg_base = Path(path)
+            # Some paths in ROS_PACKAGE_PATH might be empty or invalid
+            if not path.strip():
+                continue
+
+            pkg_path = pkg_base / package_name
+            if pkg_path.exists():
+                return pkg_path / relative_path
+
+            # Also check if we ARE inside the package base already (e.g. if path is the pkg itself)
+            if pkg_base.name == package_name:
+                return pkg_base / relative_path
+
+    # Fallback to upward search (Standalone Mode)
+    # This searches for a folder matching the package name or a package.xml
+    curr = start_dir.resolve()
+    if curr.is_file():
+        curr = curr.parent
+
+    # Search up to 10 levels or root
+    for _ in range(10):
+        # Case A: Current folder name matches package name
+        if curr.name == package_name:
+            return curr / relative_path
+
+        # Case B: Current folder contains package.xml
+        pkg_xml = curr / "package.xml"
+        if pkg_xml.exists() and _extract_package_name(pkg_xml) == package_name:
+            return curr / relative_path
+
+        if curr.parent == curr:
+            break
+        curr = curr.parent
+
+    return None
+
+
+def _extract_package_name(xml_path: Path) -> str | None:
+    """Extract <name> from package.xml using regex for performance."""
+    try:
+        # Lightweight scan of the beginning of the file
+        with open(xml_path, encoding="utf-8") as f:
+            content = f.read(1024)
+            match = re.search(r"<name>(.*?)</name>", content)
+            return match.group(1).strip() if match else None
+    except Exception:
+        return None
+
+
+def normalize_uri_to_path(uri: str) -> Path:
+    """Normalize a resource URI (specifically file://) to a local filesystem Path.
+
+    Handles Windows-style file:// URIs (e.g. file:///C:/) by stripping the
+    leading slash if a drive letter is detected. This ensures portability across
+    Posix and Windows environments.
+
+    Args:
+        uri: The URI to normalize (e.g. file:///path/mesh.stl).
+
+    Returns:
+        A Path object representing the local path.
+    """
+    if uri.startswith("file://"):
+        # Strip scheme (file://)
+        scheme = "file://"
+        path_str = uri[len(scheme) :]
+        # Windows handling: /C:/ -> C:/ (strip leading slash before drive letter)
+        if path_str.startswith("/") and len(path_str) > 2 and path_str[2] == ":":
+            path_str = path_str[1:]
+        return Path(path_str)
+
+    return Path(uri)
+
+
+def get_export_path(resource: str, relative_to: Path | None = None) -> str:
+    """Prepare a resource string for export in URDF/XACRO.
+
+    Ensures that URIs (package://, file://) are preserved correctly and not
+    mangled by standard Path normalization. If a base directory is provided,
+    local paths and file:// URIs are converted to relative paths where possible.
+
+    Args:
+        resource: The resource URI or path string.
+        relative_to: Optional base directory to make paths relative to.
+
+    Returns:
+        The string to be used in the 'filename' attribute.
+    """
+    # Preserve package:// URIs (never make relative)
+    if resource.startswith("package://") or resource.startswith("package:/"):
+        return resource
+
+    # Handle file:// URIs
+    if resource.startswith("file://"):
+        path = normalize_uri_to_path(resource)
+        if relative_to and path.is_absolute():
+            try:
+                # Use .absolute() on relative_to just in case it's not
+                rel = path.relative_to(relative_to.absolute())
+                return str(rel)
+            except ValueError:
+                pass
+        return resource
+
+    # Handle standard paths
+    path = Path(resource)
+    if relative_to and path.is_absolute():
+        try:
+            rel = path.relative_to(relative_to.absolute())
+            return str(rel)
+        except ValueError:
+            pass
+
+    return resource