docs(bf-3aij): define blob object literal search pattern
- Document blob object structure in JavaScript and Go - Create grep/ripgrep patterns for finding blob literals - Provide example matches from codebase - Document key characteristics: id, position, confidence fields - Add search patterns for both JS dashboard and Go backend This provides the foundation for identifying blob-shaped object literals across the spaxel codebase for future search/refactoring work.
This commit is contained in:
jedarden
parent
111eb2719b
commit
079c631134
1 changed files with 177 additions and 0 deletions
177
notes/bf-3aij-pattern.md
Normal file
177
notes/bf-3aij-pattern.md
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
# 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```go
|
||||
// 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
|
||||
Loading…
Add table
Reference in a new issue