spaxel/notes/bf-3aij-pattern.md

Blob Object Literal Search Pattern

Definition

A blob-shaped object literal is a data structure representing a detected person/presence in 3D space with positional and confidence information. Blobs are the core tracking entity in the Spaxel system, representing real-time detected people from fusion engine results.

Key Characteristics

Core Fields (Required)

• id - Unique numeric identifier for the blob
• x, y, z - 3D world-space position (metres)
• confidence/weight - Detection confidence score [0-1]

Extended Fields (Optional)

• vx, vy, vz - Velocity components (m/s)
• posture - Body posture state (standing/walking/seated/lying)
• person_id/person - Associated person identity
• person_label/personName - Display name for identified person
• person_color/assignedColor - Hex color for dashboard rendering
• trails - Historical position trail array
• identity_resolved - Boolean flag for identity confirmation
• ble_device - Associated BLE device reference

Language-Specific Patterns

JavaScript (TypeScript) Pattern

// Minimal blob structure
{ id: number, x: number, y: number, z: number, confidence?: number }

// Extended blob (dashboard state)
{ id: number, x: number, y: number, z: number, confidence: number, 
  vx?: number, vy?: number, vz?: number, posture?: string, 
  person?: string, ble_device?: string, trails?: Array, 
  personName?: string, assignedColor?: string, identityResolved?: boolean }

// Example from quick-actions.test.js
const blob = { id: 123, x: 2, y: 0, z: 3, personName: undefined, assignedColor: undefined, identityResolved: undefined };

Go Pattern

// Minimal fusion.Blob struct literal
fusion.Blob{X: float64, Y: float64, Z: float64, Confidence: float64}

// Extended tracker.Blob struct literal
tracker.Blob{
    ID: int,
    X: float64, Y: float64, Z: float64,
    VX: float64, VY: float64, VZ: float64,
    Weight: float64,
    Posture: Posture,
    // ... identity fields
}

// TrackedBlob struct literal (automation package)
automation.TrackedBlob{
    ID: int, X: float64, Y: float64, Z: float64,
    VX: float64, VY: float64, VZ: float64,
    Confidence: float64,
}

Grep/Ripgrep Patterns

JavaScript/TypeScript Files

# Find minimal blob literals (id + position fields)
rg '\{[^}]*id:\s*\d+[^}]*x:\s*[\d.]+[^}]*y:\s*[\d.]+[^}]*z:\s*[\d.]+[^}]*\}' --type js

# Find blob objects with id, x, y, z fields (any order)
rg '(?i)\{[^}]*\bid:\s*\w+[^}]*\bx:\s*[\d.]+[^}]*\by:\s*[\d.]+[^}]*\bz:\s*[\d.]+[^}]*\}' --type js

# Find blob objects with person/identity fields
rg '\{[^}]*\bid:\s*\w+[^}]*\bperson(Name|Label)?:' --type js

# Find blob state assignments
rg 'blobs\[.*\]\s*=\s*\{' --type js

Go Files

# Find fusion.Blob struct literals
rg 'fusion\.Blob\{[^}]*X:\s*[\d.]+[^}]*Y:\s*[\d.]+[^}]*Z:\s*[\d.]+[^}]*\}' --type go

# Find tracker.Blob struct literals
rg 'tracker\.Blob\{' --type go

# Find TrackedBlob struct literals
rg '(TrackedBlob|automation\.TrackedBlob)\{' --type go

# Find blob result patterns (simulator)
rg 'BlobResult\{' --type go

Cross-Language Pattern

# Find any object with id + x + y + z fields (both JS and Go)
rg '(?i)\{[^}]*\bid:\s*\w+[^}]*\bx:\s*[\d.]+[^}]*\by:\s*[\d.]+[^}]*\bz:\s*[\d.]+[^}]*\}' 

# Find blob creation in tests
rg 'blob.*=.*\{.*id:.*x:.*y:.*z:' -i

Example Matches

JavaScript Examples

// Quick actions test (minimal)
const blob = { id: 123, x: 2, y: 0, z: 3 };

// State initialization (extended)
appState.blobs[id] = {
    id: id,
    personName: undefined,
    assignedColor: undefined,
    identityResolved: undefined
};

// With person data
const blob = { id: 123, person: 'Alice', x: 2, y: 0, z: 3 };

Go Examples

// Fusion blob (minimal)
Blob{X: 2, Y: 1, Z: 2, Confidence: 0.85}

// Tracker blob creation
b := &Blob{
    ID:       t.nextID,
    X:        meas[0],
    Z:        meas[1],
    Weight:   meas[2],
    LastSeen: now,
}

// Automation TrackedBlob conversion
autoBlobs[i] = automation.TrackedBlob{
    ID:         b.ID,
    X:          b.X,
    Y:          b.Y,
    Z:          b.Z,
    VX:         b.VX,
    VY:         b.VY,
    VZ:         b.VZ,
    Confidence: b.Weight,
}

Search Strategy Recommendations

1. Start with the minimal pattern (id + x + y + z) to catch all blob-like objects
2. Filter by context to distinguish blobs from similar 3D position objects (nodes, zones, etc.)
3. Use language-specific patterns when focusing on specific code areas
4. Check surrounding code for blob-specific operations (updateBlob, getBlob, blob state management)

Related Structures (Not Blobs)

• Node objects: Use mac instead of id for identification
• Zone objects: Include dimensions (w, d, h) and zone_type
• Link objects: Include node_mac, peer_mac, delta_rms
• Events: Include timestamp_ms, type, severity

Usage Notes

• Blob objects are created by the fusion engine and consumed by the tracker
• JavaScript blobs are state objects in the dashboard's central state management
• Go blobs are struct literals passed between fusion, tracking, and automation packages
• Search patterns should account for both object literal creation and state assignment patterns