# Blob Data Structure Documentation

## Overview
This document describes the blob/person data structure used in the Spaxel 3D dashboard frontend.

## Backend Blob Structure (Go)

**Location:** `/home/coding/spaxel/mothership/internal/tracking/tracker.go` (lines 20-40)

```go
type Blob struct {
    ID       int
    X        float64 // metres, room X
    Z        float64 // metres, room Z
    VX       float64 // m/s
    VZ       float64 // m/s
    Weight   float64 // localisation confidence [0..1]
    LastSeen time.Time
    Trail    [][2]float64 // recent positions (newest last)
    ukf      *UKF

    // Identity fields (populated by BLE-to-blob matching)
    PersonID           string    `json:"person_id,omitempty"`
    PersonLabel        string    `json:"person_label,omitempty"`
    PersonColor        string    `json:"person_color,omitempty"`
    IdentityConfidence float64   `json:"identity_confidence,omitempty"`
    IdentitySource     string    `json:"identity_source,omitempty"`
    IdentityLastSeen   time.Time `json:"-"`
    Posture            Posture   `json:"posture,omitempty"`
}
```

### Posture Enum
```go
type Posture string

const (
    PostureUnknown  Posture = "unknown"
    PostureStanding Posture = "standing"
    PostureWalking  = "walking"
    PostureSeated   = "seated"
    PostureLying    Posture = "lying"
)
```

## Frontend Blob Structure (JavaScript)

**Location:** Implicitly defined through usage in `/home/coding/spaxel/dashboard/js/viz3d.js`

The frontend blob object has the following properties:

### Core Position & Motion
- `id` (number) - Blob unique identifier
- `x` (number) - X position in meters (room coordinate system)
- `z` (number) - Z position in meters (room coordinate system)
- `y` (number) - Y/height position (optional, typically 0 for floor level)
- `vx` (number) - X velocity in m/s (optional, defaults to 0)
- `vz` (number) - Z velocity in m/s (optional, defaults to 0)
- `vy` (number) - Y velocity (optional, used in replay mode)

### Trail & History
- `trail` (Array of [number, number]) - Array of [x, z] position tuples representing recent positions (max 60 points)

### Identity Fields (from BLE matching)
- `person_id` (string) - UUID from BLE registry
- `person_label` (string) - Display name for the person
- `person_color` (string) - Hex color code for UI (e.g., "#4fc3f7")
- `person_name` (string) - Alternative person name field (used in quick-actions.js)

### Quality & Classification
- `weight` (number) - Localization confidence [0..1]
- `posture` (string) - Estimated body posture: "standing", "walking", "seated", "lying", "unknown"

## Files That Use Blob Data

### Primary Files

1. **`/home/coding/spaxel/dashboard/js/viz3d.js`**
   - `applyLocUpdate(blobs)` (line 765) - Main function that processes blob updates
   - Creates 3D humanoid representations for each blob
   - Updates positions, velocities, and animations
   - Manages blob lifecycle (creation/deletion)
   - Functions:
     - `_createBlobObj(id)` - Creates blob visualization
     - `_updateTrail(obj, trailData)` - Updates position trail
     - `_updatePillar(obj, x, z, height)` - Updates vertical reference pillar
     - `updateReplayBlobs(blobs, timestamp_ms)` - Handles replay blob data

2. **`/home/coding/spaxel/dashboard/js/ambient_renderer.js`**
   - `updateState(state)` (line 138) - Receives blob data for ambient mode
   - Interpolates blob positions for smooth 2D rendering
   - Properties accessed: `blob.id`, `blob.x`, `blob.y`, `blob.z`

3. **`/home/coding/spaxel/dashboard/js/quick-actions.js`**
   - Spatial quick actions for blob interactions
   - Actions include: identify person, follow, show history, mark incorrect, explain, mark unknown
   - Properties accessed: `blob.id`, `blob.personName`, `blob.person`

4. **`/home/coding/spaxel/dashboard/js/app.js`**
   - WebSocket message handler for blob updates
   - Forwards blob data to Viz3D and ambient renderer

### Supporting Files

5. **`/home/coding/spaxel/dashboard/js/explainability.js`**
   - Blob explanation feature ("Why is this here?")
   - Uses blob_id for fetching explanations

6. **`/home/coding/spaxel/dashboard/js/feedback.js`**
   - Blob detection feedback collection
   - Event type: `BLOB_DETECTION`

## Blob Data Flow

```
Backend (Go) mothership/tracker.go
         ↓ WebSocket
Frontend app.js (WebSocket handler)
         ↓
┌────────────────┬─────────────────┐
│   viz3d.js     │ ambient_renderer │
│ (3D rendering) │   (2D ambient)   │
└────────────────┴─────────────────┘
         ↓
   quick-actions.js (user interactions)
```

## Usage Pattern Example

From `viz3d.js` line 768-790:
```javascript
blobs.forEach(b => {
    seen.add(b.id);
    let obj = _blobs3D.get(b.id);
    if (!obj) {
        obj = _createBlobObj(b.id);
        obj.createdAt = now;
        _blobs3D.set(b.id, obj);
    }

    obj.group.position.set(b.x, 0, b.z);
    obj.lastPosition = { x: b.x, z: b.z };
    obj.lastVelocity = { vx: b.vx || 0, vz: b.vz || 0 };

    const speed = Math.sqrt(b.vx*b.vx + b.vz*b.vz);
    _setPosture(obj.humanoid, speed > 0.25 ? 'walking' : 'standing');
    if (speed > 0.25) {
        obj.humanoid.actions.walking.timeScale = Math.min(speed * 1.8, 2.5);
        obj.group.rotation.y = Math.atan2(b.vx, b.vz);
    }

    _updateTrail(obj, b.trail);
    if (_room) _updatePillar(obj, b.x, b.z, _room.height);
});
```

## Key Modification Points

To modify the blob data structure, these are the primary files to update:

1. **Backend:** `/home/coding/spaxel/mothership/internal/tracking/tracker.go` (lines 20-40)
   - Modify the `Blob` struct definition
   - Ensure JSON tags are correct for serialization

2. **Frontend:** `/home/coding/spaxel/dashboard/js/viz3d.js`
   - Line 765-795: `applyLocUpdate()` - Update property access patterns
   - Line 3623-3638: `updateReplayBlobs()` - Update replay blob structure mapping
   - Line 699-733: `_createBlobObj()` - Update blob visualization initialization

3. **Frontend:** `/home/coding/spaxel/dashboard/js/quick-actions.js`
   - Update blob property access in action functions

4. **Frontend:** `/home/coding/spaxel/dashboard/js/ambient_renderer.js`
   - Line 138-178: `updateState()` - Update property access for ambient mode

## Trail Structure

The `trail` field contains an array of `[x, z]` coordinate tuples:
- Maximum length: 60 points (TrailMaxLen constant in Go backend)
- Newest positions are last in the array
- Used for rendering the path history behind each blob
- Y-coordinate is fixed at floor level (0.02m) for trail rendering

## Summary

The blob data structure is defined on the backend in Go and implicitly on the frontend through JavaScript object property access. The primary frontend files that consume and manipulate blob data are:
- `viz3d.js` (3D visualization)
- `ambient_renderer.js` (2D ambient mode)
- `quick-actions.js` (spatial actions)

For modifications to the blob structure, update the backend Go struct first, then update property access patterns in all three frontend files.