# Unreal Camera Setup with AnySurface Parameters

This guide explains how to configure a `CineCameraActor` in Unreal Engine using camera parameters (XYZ, rotations, fx, fy, cx, cy) provided by **AnySurface**, using **Blueprints only**.

---

## 1. What AnySurface Provides
The platform will send:
- **Position:** `X, Y, Z` (camera center in world units)
- **Rotation:** `Yaw, Pitch, Roll` (3 Euler angles in degrees or radians)
- **Intrinsics:**
  - `fx, fy` (focal lengths in pixels)
  - `cx, cy` (principal point in pixels)
- **Image Size:** `ImageWidth`, `ImageHeight` (in pixels)

These values describe a **physical camera** (position/orientation) and its **lens properties** (intrinsics).

---

## 2. Unreal’s Camera Model
Unreal’s `CineCameraActor` expects:
- **World Transform:** Location (X,Y,Z) + Rotation (Pitch,Yaw,Roll).
- **Filmback (Sensor Size):** Sensor Width & Height (in millimeters).
- **Lens Settings:** Focal Length (mm).
- **Film Offsets:** Horizontal/Vertical offsets (mm) for principal point shifts.

We must **convert from pixels → millimeters** and map the principal point.

---

## 3. Conversion Formulas

### 3.1 Focal Length (mm)
```
FocalLength = (fx * SensorWidth) / ImageWidth
```
(Use `fy` similarly if aspect ratio differs.)

### 3.2 Principal Point Offsets
```
OffsetX = ((cx / ImageWidth) - 0.5) * SensorWidth
OffsetY = (0.5 - (cy / ImageHeight)) * SensorHeight
```
(OffsetY flips because Unreal’s origin is at the top-left.)

---

## 4. Blueprint Implementation

### Step-by-Step Graph
1. **Create Variables**  
   - `fx, fy, cx, cy, ImageWidth, ImageHeight, X, Y, Z, Pitch, Yaw, Roll`.
   - Set **SensorWidth** and **SensorHeight** constants (e.g., 36mm x 24mm if full-frame).

2. **Math Nodes**  
   - Compute `FocalLength`, `OffsetX`, and `OffsetY` using the formulas above (using `Divide`, `Subtract`, `Multiply` nodes).

3. **Set Camera Intrinsics**  
   - **Set Current Focal Length** → `FocalLength`.
   - **Set Filmback Sensor Width/Height** → `SensorWidth`, `SensorHeight`.
   - **Set Filmback Horizontal Offset** → `OffsetX`.
   - **Set Filmback Vertical Offset** → `OffsetY`.

4. **Set Camera Pose (Extrinsics)**  
   - **SetActorLocation** → `(X, Y, Z)` (convert units if needed; Unreal default is cm).
   - **SetActorRotation** → `(Pitch, Yaw, Roll)`.

5. **Execution**  
   - Run these steps on **BeginPlay** or whenever AnySurface sends updated values (e.g., via a custom event or tick).

---

## 5. Artist Workflow
- Open Unreal Editor.
- Place a **CineCameraActor**.
- Create a **Blueprint Actor** called `AnySurfaceCameraDriver`.
- Inside it, create variables (`fx`, `fy`, `cx`, `cy`, `X`, `Y`, `Z`, etc.).
- Build the math graph (copy/paste formulas).
- Drag the `CineCameraActor` into the Blueprint as a **Camera Reference**.
- On **BeginPlay**, call the above steps to configure the camera.

---

## 6. Key Notes for Artists
- **Units:** AnySurface provides XYZ in **meters**; Unreal uses **centimeters**. Multiply by 100 before `SetActorLocation`.
- **Rotation:** Ensure the handedness matches. If rotations appear flipped, invert Pitch or Roll.
- **Preview:** The `CineCameraActor` viewport will now match the real camera’s projection (fx, fy, cx, cy).