# CameraCfg API Reference

Complete API reference for `CameraCfg` configuration class.

## Class Definition

```python
from genesislab.engine.scene import CameraCfg

@configclass
class CameraCfg:
    """Camera configuration for scene rendering and recording."""
```

## Parameters

### Resolution

#### `res: tuple[int, int]`
- **Type**: `tuple[int, int]`
- **Default**: `(1280, 720)`
- **Description**: Camera resolution (width, height)
- **Example**:
  ```python
  res=(1920, 1080)  # Full HD
  res=(1280, 720)   # HD
  res=(640, 480)    # SD
  ```

### Position & Orientation

#### `pos: tuple[float, float, float]`
- **Type**: `tuple[float, float, float]`
- **Default**: `(3.5, 0.0, 2.5)`
- **Description**: Camera position (x, y, z)
  - If `entity_name=None`: world frame position
  - If `entity_name` set: offset from entity in local frame
- **Example**:
  ```python
  pos=(5.0, 0.0, 3.0)     # World: 5m forward, 3m up
  pos=(-3.0, 0.0, 2.5)    # Local: 3m behind, 2.5m up
  ```

#### `lookat: tuple[float, float, float]`
- **Type**: `tuple[float, float, float]`
- **Default**: `(0.0, 0.0, 0.5)`
- **Description**: Camera look-at target (x, y, z)
  - If `entity_name=None`: world frame target
  - If `entity_name` set: target direction in local frame
- **Example**:
  ```python
  lookat=(0.0, 0.0, 0.5)  # World: look at origin
  lookat=(1.0, 0.0, 0.0)  # Local: look forward (+X)
  ```

#### `up: tuple[float, float, float]`
- **Type**: `tuple[float, float, float]`
- **Default**: `(0.0, 0.0, 1.0)`
- **Description**: Camera up direction (x, y, z)
- **Note**: Usually keep default (Z-up)

#### `fov: float`
- **Type**: `float`
- **Default**: `40.0`
- **Range**: `(0, 180)`
- **Description**: Vertical field of view in degrees
- **Example**:
  ```python
  fov=30.0   # Narrow (telephoto)
  fov=45.0   # Normal
  fov=75.0   # Wide (first person)
  fov=90.0   # Very wide
  ```

### Tracking

#### `track_mode: Optional[str]`
- **Type**: `Optional[Literal["static", "chase", "follow", "side", "top", "first_person"]]`
- **Default**: `None`
- **Description**: Camera tracking mode preset
- **Values**:
  - `None`: Manual configuration
  - `"static"`: Static camera (world frame)
  - `"chase"`: Chase camera (behind and above) ⭐
  - `"follow"`: Follow camera (over-the-shoulder)
  - `"side"`: Side view
  - `"top"`: Top-down view
  - `"first_person"`: First-person view
- **Example**:
  ```python
  track_mode="chase"  # Use chase preset
  track_mode=None     # Manual configuration
  ```

#### `entity_name: Optional[str]`
- **Type**: `Optional[str]`
- **Default**: `None`
- **Description**: Entity name to attach camera to
  - `None`: Static camera in world frame
  - `"robot"`: Attach to robot entity
- **Example**:
  ```python
  entity_name="robot"     # Follow robot
  entity_name="robot_0"   # Follow specific robot
  entity_name=None        # Static camera
  ```

#### `link_name: Optional[str]`
- **Type**: `Optional[str]`
- **Default**: `None`
- **Description**: Link name to attach camera to (if entity_name is set)
  - `None`: Attach to entity root
  - Link name: Attach to specific link
- **Common values**: `"pelvis"`, `"base_link"`, `"head"`, `"torso"`
- **Example**:
  ```python
  link_name="pelvis"  # Attach to pelvis
  link_name="head"    # Attach to head
  link_name=None      # Attach to root
  ```

### Backend

#### `backend: str`
- **Type**: `Literal["rasterizer", "raytracer", "batch_renderer"]`
- **Default**: `"rasterizer"`
- **Description**: Camera rendering backend
- **Values**:
  - `"rasterizer"`: Fast, real-time (default)
  - `"raytracer"`: High-quality, slow
  - `"batch_renderer"`: Very fast for multi-env RL
- **Example**:
  ```python
  backend="rasterizer"      # Default, fast
  backend="raytracer"       # High quality
  backend="batch_renderer"  # Multi-env RL
  ```

### Display

#### `show_in_gui: bool`
- **Type**: `bool`
- **Default**: `False`
- **Description**: Whether to show camera window in viewer GUI
- **Note**: Only works when `viewer=True`
- **Example**:
  ```python
  show_in_gui=True   # Show camera window
  show_in_gui=False  # No GUI window
  ```

## Methods

### `__post_init__()`
Validates configuration and applies track_mode presets.

**Validation**:
- `res` must be 2-tuple with positive values
- `fov` must be in range (0, 180)

**Track mode application**:
- If `track_mode` is set, applies preset values for `pos`, `lookat`, `fov`, `link_name`

## Usage Examples

### Basic Static Camera

```python
from genesislab.engine.scene import CameraCfg

camera = CameraCfg(
    res=(1920, 1080),
    pos=(5.0, 0.0, 3.0),
    lookat=(0.0, 0.0, 0.5),
    fov=45.0,
)
```

### Chase Tracking (Preset)

```python
camera = CameraCfg(
    track_mode="chase",
    entity_name="robot",
    res=(1920, 1080),
)
```

### Custom Entity Attachment

```python
camera = CameraCfg(
    entity_name="robot",
    link_name="pelvis",
    pos=(-3.0, 0.0, 2.5),  # Behind and above
    lookat=(1.0, 0.0, 0.5),  # Look forward
    fov=50.0,
    backend="rasterizer",
)
```

### First Person View

```python
camera = CameraCfg(
    track_mode="first_person",
    entity_name="robot",
    res=(1280, 720),
)
# Equivalent to:
# camera = CameraCfg(
#     entity_name="robot",
#     link_name="pelvis",
#     pos=(0.0, 0.0, 0.2),
#     lookat=(1.0, 0.0, 0.0),
#     fov=75.0,
# )
```

### Override Preset

```python
camera = CameraCfg(
    track_mode="chase",       # Use chase preset
    entity_name="robot",
    pos=(-4.0, 0.5, 3.0),    # Override position
    fov=55.0,                 # Override FOV
)
```

## Track Mode Presets

Complete preset configurations:

### Static
```python
{
    "pos": (5.0, 0.0, 3.0),
    "lookat": (0.0, 0.0, 0.5),
    "entity_name": None,  # Force static
    "fov": 45.0,
}
```

### Chase
```python
{
    "pos": (-3.5, 0.0, 2.5),   # Behind and above
    "lookat": (1.0, 0.0, 0.5),  # Look forward
    "fov": 50.0,
}
```

### Follow
```python
{
    "pos": (-2.0, 0.5, 1.8),    # Behind, slight side
    "lookat": (1.0, 0.0, 0.8),  # Look forward, up
    "fov": 45.0,
}
```

### Side
```python
{
    "pos": (0.0, -3.0, 1.5),    # Right side
    "lookat": (0.0, 0.5, 0.8),  # Look inward
    "fov": 45.0,
}
```

### Top
```python
{
    "pos": (0.0, 0.0, 5.0),      # Above
    "lookat": (0.5, 0.0, -1.0),  # Look down
    "fov": 60.0,
}
```

### First Person
```python
{
    "pos": (0.0, 0.0, 0.2),     # Slightly above link
    "lookat": (1.0, 0.0, 0.0),  # Look forward
    "link_name": "pelvis",
    "fov": 75.0,
}
```

## Integration with SceneCfg

```python
from genesislab.engine.scene import SceneCfg, CameraCfg

scene_cfg = SceneCfg(
    viewer=False,
    camera=CameraCfg(
        track_mode="chase",
        entity_name="robot",
    ),
)
```

## See Also

- [RecordingCfg API](recording_cfg.md) - Recording configuration
- [SceneCfg Extensions](scene_cfg.md) - Scene configuration
- [Tracking Guide](../user_guide/camera/tracking.md) - Robot tracking guide
- [Configuration Guide](../user_guide/camera/configuration.md) - Detailed configuration