# Abstract Robot Overview

To define and manage semantic information about robots CoraPlex uses the `AbstractRobot` class of the semantic
digital twin. Specific instances of the `AbstractRobot` class are part of the Context that is passed to the Plan on
creation.

The `AbstractRobot` class defines a semantic, high-level model of a robot as it appears in a world description. Rather
than focusing on actuation details or low-level control, it organizes the robot's physical and functional structure into
coherent parts such as kinematic chains, end effectors, sensors, and the torso. This abstraction lets downstream
components reason about what the robot is, what it has, and how its parts relate, without needing to know how individual
joints or links are implemented.

## The Problem It Solves

Robot software often mixes structural knowledge (which bodies and joints form an arm, where the gripper's tool frame is,
what cameras are available) with control or task logic. That coupling complicates reuse and makes it hard to write generic
algorithms that operate across different platforms. `AbstractRobot` solves this by providing a uniform, semantic view of
a robot that is reconstructible from a `World` description. The result is a clean separation: semantic structure and
capabilities are captured once, while planners, controllers, and task logic can query that structure in a device-agnostic way.

## Core Concepts and Terminology

A robot is a semantic annotation with a `root` body typically representing its base. From this root, the robot is
composed of structured semantic annotations of its parts (all defined in
`semantic_digital_twin.robots.robot_parts`):

* A `KinematicChain` is a contiguous sequence of kinematic structure entities from a `root` body to a `tip` body.
* An `EndEffector` is the abstract base for end effectors and always defines a `tool_frame` as well as a
  `front_facing_orientation` and the derived `front_facing_axis` used for tasks such as approach planning. Concrete
  grippers such as `PR2RightGripper` and `HSRBGripper` extend `EndEffector` (together with the `HasTwoFingers`
  mixin and one or more `Finger` parts).
* A `Sensor` is any perceptual device; `Camera` is a concrete sensor that adds a forward-facing axis, a field of
  view, and typical operating height bounds.
* A `Torso` is a special kinematic chain that connects the base to other chains, and a `Neck` is a specialized
  kinematic chain that connects the head and its sensors.

## How Parts Fit Together

Composition uses **specialized structures**: each robot defines only the parts it actually has, wired together with
mixins and generics, and the parts are reached as nested attributes rather than through `add_*` methods. For example,
the PR2 exposes its arms as `pr2.mobile_base.torso.arms`, and an arm declares its gripper through a mixin such as
`HasEndEffector[PR2RightGripper]`. Sub-parts are instantiated automatically from the generic type hints, and the
framework handles the order in which semantic annotations are added to the world, so robot structures are valid by
construction. Calling `validate()` confirms that all fields are plausibly filled and that the robot can be
synchronized without issues.

To query a robot's parts regardless of its specific structure, `AbstractRobot` provides accessor methods:
`get_end_effectors()`, `get_arms()`, `get_sensors()`, `get_torso()`, `get_left_arm_if_specified()`,
`get_right_arm_if_specified()` and `get_default_camera()`.

## Interaction with the World and Motion Control

Because `AbstractRobot` is rooted in the world model, it can expose cross-cutting capabilities in a uniform way. The
`controlled_connections` property returns the robot's connections that are controlled by a controller. The `drive`
property returns the robot's `WheeledDrive` connection (`Optional[WheeledDrive]`) if the base is connected that way,
allowing higher-level code to discover how to command base motion without hard-coding link names.

For safety and performance tuning, the robot provides `tighten_dof_velocity_limits_of_1dof_connections` and
`tighten_dof_velocity_limits_proportionally` to constrain the velocity limits of its one-degree-of-freedom active
connections.

## Construction and Extensibility

Robots are usually created via the `from_world` class method, which constructs the semantic structure by looking up
bodies and connections in a `World` (`from_branch_in_world` is available when several identical robots share one
world). To implement a new robot, follow three rules:

1. **Map concepts**: create a class for every distinct part of the robot defined in `robot_parts.py`.
2. **Define the hierarchy**: use mixins and generics to declare direct parent-child relationships (for example
   `PR2RightArm(HasEndEffector[PR2RightGripper])`).
3. **Implement the abstract methods**: most importantly `get_ros_file_path` and `_get_root_body_name`.

## Concrete Examples: PR2 and HSRB

The `PR2` subclass illustrates a dual-arm mobile manipulator whose base `root` is `base_footprint`. Each arm is a
kinematic chain carrying a two-fingered gripper, and the head is a `Neck` carrying a `Camera` with a field of view
and plausible operating heights. The `HSRB` subclass models a single-arm service robot whose arm chain carries both a
gripper and a hand-mounted `Camera`, demonstrating how one chain can act as both a manipulator and a sensor chain. As
with PR2, the HSRB is built entirely by `from_world` using URDF-consistent link names so that it matches the parsed
world model.

## Key takeaways

- `AbstractRobot` is a semantic, world-backed description of a robot's structure and capabilities.
- Parts are composed from `KinematicChain`, `EndEffector`, `Sensor` and `Torso` using specialized structures
  (mixins and generics), and reached as nested attributes.
- Accessor methods such as `get_arms()` and `get_default_camera()` query parts in a robot-agnostic way.
- The robot is reconstructed from a `World` via `from_world`; new robots are added by subclassing and implementing
  `get_ros_file_path` and `_get_root_body_name`.