# Components

Reusable components for robots, sensors, terrains, and actuators.

```{toctree}
:maxdepth: 2

robots
sensors
terrains
actuators
camera/index
```

## Overview

Components are reusable, configurable building blocks for robot learning tasks:

- **Robots**: Pre-configured robot models and URDF/MJCF loaders
- **Sensors**: Camera, LiDAR, IMU, and other sensor implementations
- **Terrains**: Procedural and custom terrain generation
- **Actuators**: Motor models and PD controllers

## Robots

### Supported Robots

**Quadrupeds**:
- Unitree Go2, A1, B2
- ANYmal-D
- Aliengo

**Humanoids**:
- Unitree H1, G1
- Custom humanoid URDFs

**Others**:
- Wheeled robots
- Manipulators
- Custom URDF/MJCF models

### Robot Configuration

```python
@configclass
class RobotCfg:
    # Model
    urdf_path: str = "path/to/robot.urdf"
    asset_name: str = "go2"
    
    # Physics
    default_joint_pos: dict[str, float] = field(default_factory=dict)
    default_joint_stiffness: float = 25.0
    default_joint_damping: float = 0.5
    
    # Control
    action_scale: float = 0.25
    decimation: int = 4  # Control frequency = sim_freq / decimation
```

## Sensors

### Sensor Types

**Proprioceptive**:
- Joint encoders (position, velocity)
- IMU (angular velocity, linear acceleration, orientation)
- Force/torque sensors

**Exteroceptive**:
- RGB cameras
- Depth cameras
- Segmentation cameras
- LiDAR (2D, 3D point clouds)
- Contact sensors

### Fake vs Genesis Sensors

**Fake Sensors** (Fast, for training):
```python
@configclass
class FakeIMUCfg(SensorBaseCfg):
    sensor_type: str = "fake"
    update_period: float = 0.01  # 100 Hz
    noise: NoiseCfg | None = GaussianNoiseCfg(mean=0.0, std=0.01)
```

**Genesis Sensors** (High-fidelity, for evaluation):
```python
@configclass
class CameraSensorCfg(SensorBaseCfg):
    sensor_type: str = "genesis"
    width: int = 640
    height: int = 480
    fov: float = 90.0
    near: float = 0.1
    far: float = 100.0
```

## Terrains

### Terrain Types

**Flat**:
```python
@configclass
class FlatTerrainCfg(TerrainBaseCfg):
    terrain_type: str = "flat"
    size: tuple[float, float] = (100.0, 100.0)
```

**Rough** (Procedurally Generated):
```python
@configclass
class RoughTerrainCfg(TerrainBaseCfg):
    terrain_type: str = "rough"
    size: tuple[float, float] = (100.0, 100.0)
    horizontal_scale: float = 0.1
    vertical_scale: float = 0.005
    border_size: float = 5.0
    
    # Curriculum
    curriculum: bool = True
    num_levels: int = 10
    
    # Sub-terrains
    terrain_proportions: dict[str, float] = field(default_factory=lambda: {
        "flat": 0.2,
        "rough": 0.2,
        "stairs": 0.2,
        "slopes": 0.2,
        "stepping_stones": 0.2
    })
```

**Mesh** (Custom):
```python
@configclass
class MeshTerrainCfg(TerrainBaseCfg):
    terrain_type: str = "mesh"
    mesh_path: str = "path/to/terrain.obj"
    scale: float = 1.0
```

### Terrain Curriculum

```python
@configclass
class TerrainCurriculumCfg:
    # Enable curriculum
    enabled: bool = True
    
    # Difficulty levels
    num_levels: int = 10
    start_level: int = 0
    
    # Progression criteria
    success_rate_threshold: float = 0.8
    min_episodes_per_level: int = 100
```

## Actuators

### PD Controller

```python
@configclass
class PDControllerCfg(ActuatorBaseCfg):
    actuator_type: str = "pd"
    
    # PD gains
    stiffness: float | dict[str, float] = 25.0
    damping: float | dict[str, float] = 0.5
    
    # Limits
    effort_limit: float | dict[str, float] = 23.5  # Nm
    velocity_limit: float | dict[str, float] = 30.0  # rad/s
```

### Motor Model

```python
@configclass
class MotorModelCfg(ActuatorBaseCfg):
    actuator_type: str = "motor"
    
    # Motor characteristics
    peak_torque: float = 30.0  # Nm
    peak_velocity: float = 50.0  # rad/s
    
    # Dynamics
    motor_inertia: float = 0.001  # kg⋅m²
    gear_ratio: float = 6.0
```

## Usage Examples

### Creating a Robot

```python
# Pre-configured robot
from genesislab.components.robots import Go2RobotCfg

robot_cfg = Go2RobotCfg()

# Custom robot
@configclass
class MyRobotCfg(RobotCfg):
    urdf_path: str = "path/to/my_robot.urdf"
    default_joint_pos: dict[str, float] = field(default_factory=lambda: {
        "joint1": 0.0,
        "joint2": 0.5,
        # ...
    })
```

### Creating a Sensor

```python
# Fake IMU for fast training
from genesislab.components.sensors import FakeIMUCfg

imu_cfg = FakeIMUCfg(
    update_period=0.01,
    noise=GaussianNoiseCfg(mean=0.0, std=0.01)
)

# Genesis camera for vision
from genesislab.components.sensors import CameraSensorCfg

camera_cfg = CameraSensorCfg(
    width=640,
    height=480,
    fov=90.0,
    position=(0.3, 0.0, 0.1),  # Relative to robot base
    orientation=(0.0, 0.0, 0.0)  # Roll, pitch, yaw
)
```

### Creating a Terrain

```python
# Flat terrain
from genesislab.components.terrains import FlatTerrainCfg

terrain_cfg = FlatTerrainCfg(
    size=(100.0, 100.0)
)

# Rough terrain with curriculum
from genesislab.components.terrains import RoughTerrainCfg

terrain_cfg = RoughTerrainCfg(
    curriculum=True,
    num_levels=10,
    terrain_proportions={
        "flat": 0.2,
        "rough": 0.3,
        "stairs": 0.3,
        "slopes": 0.2
    }
)
```

## Component Registry

Components can be registered for easy access:

```python
from genesislab.components import ROBOT_REGISTRY

# Register custom robot
@ROBOT_REGISTRY.register("my_robot")
@configclass
class MyRobotCfg(RobotCfg):
    urdf_path: str = "path/to/robot.urdf"
    # ...

# Use registered robot
robot_cfg = ROBOT_REGISTRY.get("my_robot")()
```

## Next Steps

- See [robot configurations](robots.md)
- See [sensor configurations](sensors.md)
- See [terrain configurations](terrains.md)
- Check [tutorials](../../user_guide/tutorials/index.md)