spaxel/notes/bf-4bhd.md

Blob Creation Code Paths - Analysis Report

Task: Find all blob creation code paths

Summary

This report documents all locations where blob objects are created or constructed in the spaxel codebase. There are FOUR distinct Blob types across different packages:

1. tracking.Blob - 2D floor tracker (X, Z coordinates)
2. tracker.Blob - 3D tracker with identity support (X, Y, Z coordinates + posture)
3. fusion.Blob - Simple fusion result (X, Y, Z + confidence)
4. automation.TrackedBlob - Automation engine blob representation

---

Blob Type Definitions

1. tracking.Blob (mothership/internal/tracking/tracker.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
    ukf      *UKF
    
    // Identity fields
    PersonID           string
    PersonLabel        string
    PersonColor        string
    PersonName         string
    AssignedColor      string
    IdentityResolved   bool
    IdentityConfidence float64
    IdentitySource     string
    IdentityLastSeen   time.Time
    Posture            Posture
}

2. tracker.Blob (mothership/internal/tracker/tracker.go)

type Blob struct {
    ID         int
    X, Y, Z    float64 // world-space position, metres
    VX, VY, VZ float64 // velocity, m/s
    Weight     float64 // detection confidence [0..1]
    Posture    Posture
    LastSeen   time.Time
    Trail      [][3]float64
    
    // Identity fields
    PersonID           string
    PersonLabel        string
    PersonColor        string
    IdentityConfidence float64
    IdentitySource     string
    IdentityLastSeen   time.Time
    ukf *UKF
}

3. fusion.Blob (mothership/internal/fusion/fusion.go)

type Blob struct {
    X, Y, Z    float64 // world-space position (metres)
    Confidence float64 // normalised [0..1]
}

4. automation.TrackedBlob (mothership/internal/automation/engine.go)

type TrackedBlob struct {
    ID         int
    X, Y, Z    float64
    VX, VY, VZ float64
    Confidence float64
}

5. signal.TrackedBlob (mothership/internal/signal/processor.go)

type TrackedBlob struct {
    ID         int
    X, Y, Z    float64
    VX, VY, VZ float64
    Weight     float64
    
    // Identity fields
    PersonID           string
    PersonLabel        string
    PersonColor        string
    IdentityConfidence float64
    IdentitySource     string
    Posture            string
}

---

Blob Creation Sites

Pattern 1: Direct struct construction with &Blob{}

1.1 tracking/tracker.go:163 - New blob from measurement

b := &Blob{
    ID:       t.nextID,
    X:        meas[0],
    Z:        meas[1],
    Weight:   meas[2],
    LastSeen: now,
    Trail:    [][2]float64{{meas[0], meas[1]}},
    ukf:      NewUKF(meas[0], meas[1]),
    // Initialize identity fields with default values
    PersonName:       "",
    AssignedColor:    "",
    IdentityResolved: false,
}

• Context: Tracker.Update() when unmatched measurements create new tracks
• Pattern: Pointer construction, initializes ID, position, weight, trail, UKF filter

1.2 tracker/tracker.go:162 - New 3D blob from measurement

b := &Blob{
    ID: t.nextID,
    X:  m[0], Y: m[1], Z: m[2],
    Weight:   m[3],
    LastSeen: now,
    Trail:    [][3]float64{{m[0], m[1], m[2]}},
    Posture:  PostureUnknown,
    ukf:      NewUKF(m[0], m[1], m[2]),
}

• Context: Tracker.Update() when unmatched measurements create new 3D tracks
• Pattern: Similar to 1.1 but with Y coordinate and Posture field

---

Pattern 2: Value-type construction with Blob{}

2.1 fusion/fusion.go:260 - Blob from peak detection

blobs[i] = Blob{X: p[0], Y: p[1], Z: p[2], Confidence: p[3]}

• Context: Engine.Fuse() converting fusion grid peaks to blobs
• Pattern: Value-type construction from 4-element peak array [x, y, z, confidence]

---

Pattern 3: Slice allocation and copying

3.1 tracking/tracker.go:206-208 - Return snapshot (deep copy)

out := make([]Blob, len(t.blobs))
for i, b := range t.blobs {
    out[i] = *b
    trail := make([][2]float64, len(b.Trail))
    copy(trail, b.Trail)
    out[i].Trail = trail
}

• Context: Tracker.Update() returning immutable snapshot
• Pattern: Dereference pointer, deep-copy trail slice

3.2 tracker/tracker.go:193-195 - Return 3D snapshot (deep copy)

out := make([]Blob, len(t.blobs))
for i, b := range t.blobs {
    out[i] = *b
    trail := make([][3]float64, len(b.Trail))
    copy(trail, b.Trail)
    out[i].Trail = trail
    out[i].ukf = nil
}

• Context: Tracker.Update() returning immutable snapshot
• Pattern: Similar to 3.1 but clears ukf field for caller safety

3.3 tracker/identity.go:214-216 - Get all blobs copy

result := make([]Blob, len(tm.blobs))
copy(result, tm.blobs)

• Context: TrackManager.GetAllBlobs() returning all blobs
• Pattern: Slice copy operation

---

Pattern 4: automation.TrackedBlob construction

4.1 cmd/mothership/main.go:2213 - Automation blob conversion

autoBlobs[i] = automation.TrackedBlob{
    // fields populated
}

• Context: Converting blobs to automation engine format
• Pattern: Cross-package type conversion

---

Pattern 5: signal.TrackedBlob construction

5.1 cmd/mothership/main.go:5384 - Fusion result to tracked blob

b := sigproc.TrackedBlob{
    ID:     id,
    X:      pk.X,
    Y:      pk.Y,
    Z:      pk.Z,
    Weight: pk.Confidence,
}

• Context: blobTracker.track() converting fusion peaks to tracked blobs
• Pattern: Type conversion from fusion.Blob to signal.TrackedBlob

---

Pattern 6: Test data construction

6.1 fusion/fusion_test.go:631 - Test fixture

Blobs: []Blob{{X: 2, Y: 1, Z: 2, Confidence: 0.85}}

• Context: Test data creation
• Pattern: Inline slice literal with struct literals

6.2 fusion/fusion_test.go:680 - Test fixture

Blobs: []Blob{{X: 2, Y: 1, Z: 2, Confidence: 0.80}}

6.3 fusion/fusion_test.go:700 - Test fixture

result := &Result{Blobs: []Blob{{X: 1, Y: 1, Z: 1, Confidence: 0.5}}}

---

Files That Update Blob Fields

Identity assignment (tracker/identity.go)

applyIdentity() - Lines 167-182

func (tm *TrackManager) applyIdentity(blob *Blob, info *IdentityInfo, now time.Time) {
    blob.PersonID = info.PersonID
    blob.PersonLabel = info.PersonLabel
    blob.PersonColor = info.PersonColor
    blob.PersonName = info.PersonName
    blob.AssignedColor = info.AssignedColor
    blob.IdentityResolved = info.IdentityResolved
    blob.IdentityConfidence = info.IdentityConfidence
    blob.IdentityLastSeen = now
    
    if info.IdentitySource != "" {
        blob.IdentitySource = info.IdentitySource
    } else {
        blob.IdentitySource = "ble_triangulation"
    }
}

• Context: Applying BLE identity match to blob
• Pattern: Field mutation on existing blob pointer

clearIdentity() - Lines 185-194

func (tm *TrackManager) clearIdentity(blob *Blob) {
    blob.PersonID = ""
    blob.PersonLabel = ""
    blob.PersonColor = ""
    blob.PersonName = ""
    blob.AssignedColor = ""
    blob.IdentityResolved = false
    blob.IdentityConfidence = 0
    blob.IdentitySource = ""
}

• Context: Clearing identity when match expires
• Pattern: Resetting identity fields to defaults

---

Key Findings

Files Requiring Updates for Blob Structure Changes

1. mothership/internal/tracking/tracker.go (line 163)

   • Constructor for new 2D blobs

2. mothership/internal/tracker/tracker.go (line 162)

   • Constructor for new 3D blobs with posture

3. mothership/internal/fusion/fusion.go (line 260)

   • Constructor for fusion result blobs

4. mothership/cmd/mothership/main.go (lines 2213, 5384)

   • Type conversion constructors for automation and signal packages

5. mothership/internal/tracker/identity.go (lines 167-194)

   • Identity field assignment and clearing

Creation Patterns by Type

Blob Type	Construction Method	Typical Context
tracking.Blob	&Blob{}	New track from measurement
tracker.Blob	&Blob{}	New 3D track from measurement
fusion.Blob	Blob{}	Peak detection result
automation.TrackedBlob	TrackedBlob{}	Automation trigger evaluation
signal.TrackedBlob	TrackedBlob{}	Fusion to tracking pipeline

Identity Fields Affected

When updating blob identity fields, these files need changes:

• Constructors: tracker.go (2 locations) - initialize new fields
• Identity matching: identity.go - applyIdentity() and clearIdentity()
• Type conversions: main.go - automation and signal TrackedBlob conversions

---

Recommendations

1. For adding new identity fields: Update all 5 creation sites
2. For changing blob structure: Update type definitions and all constructors
3. For identity field logic: Focus on tracker/identity.go
4. For testing: Update fusion_test.go fixtures when structure changes

---

Acceptance Criteria Status

• All blob creation sites are identified and listed
• Each site is documented with file path and line number
• Creation pattern is noted (constructor, literal, factory, etc.)
• Report is ready for the next bead to use

Total blob creation sites found: 8 primary + 3 field mutation sites