#!/usr/bin/env node

/**

* ADR-075: CSI Subcarrier Correlation Graph Visualizer

*

* ASCII visualization of the subcarrier correlation graph used by the

* min-cut person counter. Shows per-person subcarrier clusters, graph

* connectivity, and correlation heatmap in real-time.

*

* Usage:

* # Live from ESP32 nodes via UDP

* node scripts/csi-graph-visualizer.js --port 5006

*

* # Replay from recorded CSI data

* node scripts/csi-graph-visualizer.js --replay data/recordings/pretrain-1775182186.csi.jsonl

*

* # Show correlation heatmap only

* node scripts/csi-graph-visualizer.js --replay FILE --mode heatmap

*

* ADR: docs/adr/ADR-075-mincut-person-separation.md

*/

'use strict';

const dgram = require('dgram');

const fs = require('fs');

const readline = require('readline');

const { parseArgs } = require('util');

// ---------------------------------------------------------------------------

// CLI

// ---------------------------------------------------------------------------

const { values: args } = parseArgs({

options: {

port: { type: 'string', short: 'p', default: '5006' },

replay: { type: 'string', short: 'r' },

interval: { type: 'string', short: 'i', default: '2000' },

window: { type: 'string', short: 'w', default: '2000' },

mode: { type: 'string', short: 'm', default: 'all' },

node: { type: 'string', short: 'n', default: '0' },

'corr-threshold': { type: 'string', default: '0.3' },

'cut-threshold': { type: 'string', default: '2.0' },

'var-floor': { type: 'string', default: '0.5' },

width: { type: 'string', default: '80' },

},

strict: true,

});

const PORT = parseInt(args.port, 10);

const INTERVAL_MS = parseInt(args.interval, 10);

const WINDOW_MS = parseInt(args.window, 10);

const CORR_THRESHOLD = parseFloat(args['corr-threshold']);

const CUT_THRESHOLD = parseFloat(args['cut-threshold']);

const VAR_FLOOR = parseFloat(args['var-floor']);

const MODE = args.mode; // 'all', 'heatmap', 'clusters', 'spectrum'

const TARGET_NODE = parseInt(args.node, 10);

const WIDTH = parseInt(args.width, 10);

const CSI_MAGIC = 0xC5110001;

const HEADER_SIZE = 20;

// Color palette for person clusters (ANSI 256)

const PERSON_COLORS = [

'\x1b[31m', // red

'\x1b[32m', // green

'\x1b[34m', // blue

'\x1b[33m', // yellow

'\x1b[35m', // magenta

'\x1b[36m', // cyan

'\x1b[91m', // bright red

'\x1b[92m', // bright green

];

const RESET = '\x1b[0m';

const DIM = '\x1b[2m';

const BOLD = '\x1b[1m';

// Heatmap characters (11 levels of intensity)

const HEAT = [' ', '\u2591', '\u2591', '\u2592', '\u2592', '\u2593', '\u2593', '\u2588', '\u2588', '\u2588', '\u2588'];

// Bar chart characters

const BARS = ['\u2581', '\u2582', '\u2583', '\u2584', '\u2585', '\u2586', '\u2587', '\u2588'];

// ---------------------------------------------------------------------------

// Sliding window (same as mincut-person-counter.js)

// ---------------------------------------------------------------------------

class SubcarrierWindow {

constructor(maxAgeMs) {

this.maxAgeMs = maxAgeMs;

this.frames = [];

this.nSubcarriers = 0;

}

push(timestamp, amplitudes) {

this.nSubcarriers = amplitudes.length;

this.frames.push({ timestamp, amplitudes: Float64Array.from(amplitudes) });

const cutoff = timestamp - this.maxAgeMs;

while (this.frames.length > 0 && this.frames[0].timestamp < cutoff) {

this.frames.shift();

}

}

get length() { return this.frames.length; }

correlationMatrix() {

const nFrames = this.frames.length;

const nSc = this.nSubcarriers;

if (nFrames < 5 || nSc === 0) return null;

const mean = new Float64Array(nSc);

const std = new Float64Array(nSc);

for (let f = 0; f < nFrames; f++) {

const amp = this.frames[f].amplitudes;

for (let i = 0; i < nSc; i++) mean[i] += amp[i];

}

for (let i = 0; i < nSc; i++) mean[i] /= nFrames;

for (let f = 0; f < nFrames; f++) {

const amp = this.frames[f].amplitudes;

for (let i = 0; i < nSc; i++) {

const d = amp[i] - mean[i];

std[i] += d * d;

}

}

for (let i = 0; i < nSc; i++) std[i] = Math.sqrt(std[i] / (nFrames - 1));

const activeIndices = [];

for (let i = 0; i < nSc; i++) {

if (std[i] > VAR_FLOOR) activeIndices.push(i);

}

const n = activeIndices.length;

if (n < 2) return { matrix: null, n: 0, activeIndices, mean, std };

const matrix = new Float64Array(n * n);

for (let ai = 0; ai < n; ai++) {

matrix[ai * n + ai] = 1.0;

const si = activeIndices[ai];

for (let aj = ai + 1; aj < n; aj++) {

const sj = activeIndices[aj];

let cov = 0;

for (let f = 0; f < nFrames; f++) {

const amp = this.frames[f].amplitudes;

cov += (amp[si] - mean[si]) * (amp[sj] - mean[sj]);

}

cov /= (nFrames - 1);

const denom = std[si] * std[sj];

const r = denom > 1e-10 ? cov / denom : 0;

matrix[ai * n + aj] = r;

matrix[aj * n + ai] = r;

}

}

return { matrix, n, activeIndices, mean, std };

}

/** Get latest amplitudes */

latestAmplitudes() {

if (this.frames.length === 0) return null;

return this.frames[this.frames.length - 1].amplitudes;

}

}

// ---------------------------------------------------------------------------

// Graph + Stoer-Wagner (minimal copy from mincut-person-counter.js)

// ---------------------------------------------------------------------------

class WeightedGraph {

constructor(n) {

this.n = n;

this.adj = new Array(n);

for (let i = 0; i < n; i++) this.adj[i] = new Map();

this.edgeCount = 0;

}

addEdge(u, v, w) {

if (u === v) return;

if (!this.adj[u].has(v)) this.edgeCount++;

this.adj[u].set(v, w);

this.adj[v].set(u, w);

}

static fromCorrelation(matrix, n, threshold) {

const g = new WeightedGraph(n);

for (let i = 0; i < n; i++) {

for (let j = i + 1; j < n; j++) {

const r = Math.abs(matrix[i * n + j]);

if (r > threshold) g.addEdge(i, j, r);

}

}

return g;

}

connectedComponents() {

const visited = new Uint8Array(this.n);

const components = [];

for (let start = 0; start < this.n; start++) {

if (visited[start]) continue;

const comp = [];

const queue = [start];

visited[start] = 1;

while (queue.length > 0) {

const u = queue.shift();

comp.push(u);

for (const [v] of this.adj[u]) {

if (!visited[v]) { visited[v] = 1; queue.push(v); }

}

}

components.push(comp);

}

return components;

}

subgraph(vertices) {

const newIdx = new Map();

vertices.forEach((v, i) => newIdx.set(v, i));

const sub = new WeightedGraph(vertices.length);

for (const u of vertices) {

for (const [v, w] of this.adj[u]) {

if (newIdx.has(v) && u < v) sub.addEdge(newIdx.get(u), newIdx.get(v), w);

}

}

return { graph: sub, mapping: vertices };

}

}

function stoerWagner(graph) {

const n = graph.n;

if (n <= 1) return { minCutValue: Infinity, partition: [Array.from({length: n}, (_, i) => i), []] };

const adj = new Array(n);

for (let i = 0; i < n; i++) adj[i] = new Map(graph.adj[i]);

const groups = new Array(n);

for (let i = 0; i < n; i++) groups[i] = [i];

let activeVertices = Array.from({length: n}, (_, i) => i);

let bestCut = Infinity;

let bestPartitionSide = null;

while (activeVertices.length > 1) {

const key = new Float64Array(n);

const inA = new Uint8Array(n);

let s = -1, t = -1;

for (let iter = 0; iter < activeVertices.length; iter++) {

let best = -1, bestKey = -Infinity;

for (const v of activeVertices) {

if (!inA[v] && key[v] > bestKey) { bestKey = key[v]; best = v; }

}

if (best === -1) {

for (const v of activeVertices) { if (!inA[v]) { best = v; break; } }

}

s = t; t = best; inA[best] = 1;

if (adj[best]) {

for (const [nb, w] of adj[best]) {

if (activeVertices.includes(nb) && !inA[nb]) key[nb] += w;

}

}

}

let cutOfPhase = 0;

if (adj[t]) {

for (const [nb, w] of adj[t]) {

if (activeVertices.includes(nb) && nb !== t) cutOfPhase += w;

}

}

if (s === -1 || t === -1) break;

if (cutOfPhase < bestCut) { bestCut = cutOfPhase; bestPartitionSide = [...groups[t]]; }

if (adj[t]) {

for (const [nb, w] of adj[t]) {

if (nb === s) continue;

const ex = adj[s].get(nb) || 0;

adj[s].set(nb, ex + w);

adj[nb].delete(t);

adj[nb].set(s, ex + w);

}

}

adj[s].delete(t);

groups[s] = groups[s].concat(groups[t]);

groups[t] = [];

activeVertices = activeVertices.filter(v => v !== t);

}

if (!bestPartitionSide || bestPartitionSide.length === 0) {

return { minCutValue: Infinity, partition: [Array.from({length: n}, (_, i) => i), []] };

}

const sideSet = new Set(bestPartitionSide);

const sideA = [], sideB = [];

for (let i = 0; i < n; i++) { (sideSet.has(i) ? sideA : sideB).push(i); }

return { minCutValue: bestCut, partition: [sideA, sideB] };

}

function separatePersons(graph, cutThreshold, maxPersons) {

const components = graph.connectedComponents();

const personGroups = [];

for (const comp of components) {

if (comp.length < 2) continue;

_split(graph, comp, cutThreshold, maxPersons, personGroups);

}

return personGroups;

}

function _split(graph, vertices, cutThreshold, maxPersons, result) {

if (vertices.length < 2 || result.length >= maxPersons) {

if (vertices.length >= 2) result.push(vertices);

return;

}

const { graph: sub, mapping } = graph.subgraph(vertices);

const { minCutValue, partition } = stoerWagner(sub);

if (minCutValue >= cutThreshold || partition[0].length === 0 || partition[1].length === 0) {

result.push(vertices);

return;

}

_split(graph, partition[0].map(i => mapping[i]), cutThreshold, maxPersons, result);

_split(graph, partition[1].map(i => mapping[i]), cutThreshold, maxPersons, result);

}

// ---------------------------------------------------------------------------

// Visualization renderers

// ---------------------------------------------------------------------------

/**

* Render correlation heatmap (downsampled to fit terminal width).

* Rows and columns = active subcarrier indices.

*/

function renderHeatmap(corr, width) {

if (!corr || !corr.matrix) return [' (insufficient data for heatmap)'];

const { matrix, n, activeIndices } = corr;

const lines = [];

lines.push(`${BOLD}Correlation Heatmap${RESET} (${n} active subcarriers, threshold=${CORR_THRESHOLD})`);

// Downsample if needed

const maxCols = Math.min(n, width - 8);

const step = Math.max(1, Math.ceil(n / maxCols));

const displayN = Math.ceil(n / step);

// Header row: subcarrier indices

let header = ' ';

for (let j = 0; j < displayN; j++) {

const sc = activeIndices[j * step];

header += (sc < 10 ? `${sc} ` : `${sc}`).slice(0, 2);

}

lines.push(DIM + header + RESET);

for (let i = 0; i < displayN; i++) {

const sc = activeIndices[i * step];

let row = ` ${String(sc).padStart(3)} `;

for (let j = 0; j < displayN; j++) {

const ii = i * step, jj = j * step;

const val = Math.abs(matrix[ii * n + jj]);

const level = Math.min(10, Math.floor(val * 10));

if (val > CORR_THRESHOLD) {

row += `\x1b[33m${HEAT[level]}${RESET} `;

} else {

row += `${DIM}${HEAT[level]}${RESET} `;

}

}

lines.push(row);

}

return lines;

}

/**

* Render subcarrier spectrum bar with person cluster coloring.

*/

function renderSpectrum(window, personGroups, activeIndices) {

const amp = window.latestAmplitudes();

if (!amp) return [' (no data)'];

const lines = [];

const nSc = window.nSubcarriers;

// Build subcarrier-to-person mapping

const scToPerson = new Int8Array(nSc).fill(-1);

if (personGroups && activeIndices) {

for (let p = 0; p < personGroups.length; p++) {

for (const graphIdx of personGroups[p]) {

if (graphIdx < activeIndices.length) {

scToPerson[activeIndices[graphIdx]] = p;

}

}

}

}

// Find max amplitude for normalization

let maxAmp = 0;

for (let i = 0; i < nSc; i++) {

if (amp[i] > maxAmp) maxAmp = amp[i];

}

if (maxAmp === 0) maxAmp = 1;

lines.push(`${BOLD}Spectrum${RESET} (${nSc} subcarriers, colored by person cluster)`);

// Render bar

let bar = ' ';

for (let i = 0; i < nSc; i++) {

const level = Math.floor((amp[i] / maxAmp) * 7.99);

const ch = BARS[Math.max(0, Math.min(7, level))];

const personIdx = scToPerson[i];

if (personIdx >= 0 && personIdx < PERSON_COLORS.length) {

bar += PERSON_COLORS[personIdx] + ch + RESET;

} else {

bar += DIM + ch + RESET;

}

}

lines.push(bar);

// Legend

let legend = ' ';

for (let i = 0; i < nSc; i++) {

const p = scToPerson[i];

if (p >= 0 && p < PERSON_COLORS.length) {

legend += PERSON_COLORS[p] + (p + 1) + RESET;

} else {

legend += DIM + '.' + RESET;

}

}

lines.push(legend);

return lines;

}

/**

* Render cluster summary with per-person statistics.

*/

function renderClusters(personGroups, activeIndices, corr) {

if (!personGroups || personGroups.length === 0) {

return [' No person clusters detected'];

}

const lines = [];

lines.push(`${BOLD}Person Clusters${RESET} (${personGroups.length} detected)`);

for (let p = 0; p < personGroups.length; p++) {

const group = personGroups[p];

const color = p < PERSON_COLORS.length ? PERSON_COLORS[p] : '';

// Map back to subcarrier indices

const scIds = group.map(i => activeIndices[i]);

const scStr = scIds.length <= 16

? scIds.join(', ')

: scIds.slice(0, 14).join(', ') + `, ...+${scIds.length - 14}`;

// Compute intra-cluster average correlation

let avgCorr = 0, count = 0;

if (corr && corr.matrix) {

for (let i = 0; i < group.length; i++) {

for (let j = i + 1; j < group.length; j++) {

avgCorr += Math.abs(corr.matrix[group[i] * corr.n + group[j]]);

count++;

}

}

if (count > 0) avgCorr /= count;

}

lines.push(` ${color}Person ${p + 1}${RESET}: ${group.length} subcarriers, avg intra-corr=${avgCorr.toFixed(3)}`);

lines.push(` ${DIM}SC: [${scStr}]${RESET}`);

}

return lines;

}

/**

* Render graph connectivity summary.

*/

function renderGraphStats(graph, corr) {

if (!graph) return [' (no graph)'];

const lines = [];

const components = graph.connectedComponents();

const density = graph.n > 1 ? (2 * graph.edgeCount) / (graph.n * (graph.n - 1)) : 0;

lines.push(`${BOLD}Graph${RESET}: ${graph.n} nodes, ${graph.edgeCount} edges, density=${density.toFixed(3)}, components=${components.length}`);

// Degree distribution summary

const degrees = new Array(graph.n);

let minDeg = Infinity, maxDeg = 0, sumDeg = 0;

for (let i = 0; i < graph.n; i++) {

degrees[i] = graph.adj[i].size;

if (degrees[i] < minDeg) minDeg = degrees[i];

if (degrees[i] > maxDeg) maxDeg = degrees[i];

sumDeg += degrees[i];

}

const avgDeg = graph.n > 0 ? sumDeg / graph.n : 0;

lines.push(` Degree: min=${minDeg} max=${maxDeg} avg=${avgDeg.toFixed(1)}`);

return lines;

}

// ---------------------------------------------------------------------------

// Full render

// ---------------------------------------------------------------------------

function render(window, nodeId) {

const corr = window.correlationMatrix();

const lines = [];

const ts = new Date().toISOString().slice(11, 19);

lines.push(`${BOLD}ADR-075 CSI Graph Visualizer${RESET} [${ts}] Node ${nodeId} | ${window.length} frames`);

lines.push('═'.repeat(WIDTH));

let graph = null;

let personGroups = null;

let activeIndices = corr ? corr.activeIndices : [];

if (corr && corr.matrix && corr.n >= 2) {

graph = WeightedGraph.fromCorrelation(corr.matrix, corr.n, CORR_THRESHOLD);

personGroups = separatePersons(graph, CUT_THRESHOLD, 8);

}

const personCount = personGroups ? personGroups.length : 0;

lines.push(`${BOLD}Persons: ${personCount}${RESET} | Active subcarriers: ${activeIndices.length}/${window.nSubcarriers}`);

lines.push('');

if (MODE === 'all' || MODE === 'spectrum') {

lines.push(...renderSpectrum(window, personGroups, activeIndices));

lines.push('');

}

if (MODE === 'all' || MODE === 'clusters') {

lines.push(...renderClusters(personGroups, activeIndices, corr));

lines.push('');

}

if (MODE === 'all' || MODE === 'heatmap') {

lines.push(...renderHeatmap(corr, WIDTH));

lines.push('');

}

if (graph) {

lines.push(...renderGraphStats(graph, corr));

}

lines.push('═'.repeat(WIDTH));

lines.push(`${DIM}Thresholds: corr=${CORR_THRESHOLD} cut=${CUT_THRESHOLD} var-floor=${VAR_FLOOR}${RESET}`);

return lines.join('\n');

}

// ---------------------------------------------------------------------------

// Packet parsing

// ---------------------------------------------------------------------------

function parseIqHex(iqHex, nSubcarriers) {

const bytes = Buffer.from(iqHex, 'hex');

const amplitudes = new Float64Array(nSubcarriers);

for (let sc = 0; sc < nSubcarriers; sc++) {

const offset = 2 + sc * 2;

if (offset + 1 >= bytes.length) break;

let I = bytes[offset]; let Q = bytes[offset + 1];

if (I > 127) I -= 256;

if (Q > 127) Q -= 256;

amplitudes[sc] = Math.sqrt(I * I + Q * Q);

}

return amplitudes;

}

function parseUdpPacket(buf) {

if (buf.length < HEADER_SIZE) return null;

const magic = buf.readUInt32LE(0);

if (magic !== CSI_MAGIC) return null;

const nodeId = buf.readUInt8(4);

const nSubcarriers = buf.readUInt16LE(6);

const amplitudes = new Float64Array(nSubcarriers);

for (let sc = 0; sc < nSubcarriers; sc++) {

const offset = HEADER_SIZE + sc * 2;

if (offset + 1 >= buf.length) break;

const I = buf.readInt8(offset);

const Q = buf.readInt8(offset + 1);

amplitudes[sc] = Math.sqrt(I * I + Q * Q);

}

return { nodeId, nSubcarriers, amplitudes, timestamp: Date.now() };

}

// ---------------------------------------------------------------------------

// Main: live mode

// ---------------------------------------------------------------------------

function startLive() {

const windows = new Map();

const server = dgram.createSocket('udp4');

server.on('message', (buf) => {

const frame = parseUdpPacket(buf);

if (!frame) return;

if (!windows.has(frame.nodeId)) {

windows.set(frame.nodeId, new SubcarrierWindow(WINDOW_MS));

}

windows.get(frame.nodeId).push(frame.timestamp, frame.amplitudes);

});

setInterval(() => {

process.stdout.write('\x1b[2J\x1b[H');

for (const [nodeId, window] of windows) {

if (TARGET_NODE !== 0 && nodeId !== TARGET_NODE) continue;

console.log(render(window, nodeId));

console.log();

}

if (windows.size === 0) {

console.log('Waiting for CSI frames on UDP port ' + PORT + '...');

}

}, INTERVAL_MS);

server.bind(PORT, () => {

console.log(`CSI Graph Visualizer listening on UDP port ${PORT}`);

});

}

// ---------------------------------------------------------------------------

// Main: replay mode

// ---------------------------------------------------------------------------

async function startReplay(filePath) {

if (!fs.existsSync(filePath)) {

console.error(`File not found: ${filePath}`);

process.exit(1);

}

const windows = new Map();

const rl = readline.createInterface({

input: fs.createReadStream(filePath),

crlfDelay: Infinity,

});

let lastRenderTs = 0;

let frameCount = 0;

for await (const line of rl) {

if (!line.trim()) continue;

let record;

try { record = JSON.parse(line); } catch { continue; }

if (record.type !== 'raw_csi' || !record.iq_hex) continue;

const nSc = record.subcarriers || 64;

const amplitudes = parseIqHex(record.iq_hex, nSc);

const nodeId = record.node_id;

const tsMs = record.timestamp * 1000;

if (!windows.has(nodeId)) {

windows.set(nodeId, new SubcarrierWindow(WINDOW_MS));

}

windows.get(nodeId).push(tsMs, amplitudes);

frameCount++;

if (lastRenderTs === 0) lastRenderTs = tsMs;

if (tsMs - lastRenderTs >= INTERVAL_MS) {

process.stdout.write('\x1b[2J\x1b[H');

for (const [nid, window] of windows) {

if (TARGET_NODE !== 0 && nid !== TARGET_NODE) continue;

console.log(render(window, nid));

console.log();

}

lastRenderTs = tsMs;

// Small delay for visual effect during replay

await new Promise(r => setTimeout(r, 100));

}

}

// Final render

console.log();

console.log('═'.repeat(WIDTH));

console.log(`${BOLD}Replay complete${RESET}: ${frameCount} frames`);

for (const [nodeId, window] of windows) {

if (TARGET_NODE !== 0 && nodeId !== TARGET_NODE) continue;

console.log();

console.log(render(window, nodeId));

}

}

// ---------------------------------------------------------------------------

// Entry point

// ---------------------------------------------------------------------------

if (args.replay) {

startReplay(args.replay);

} else {

startLive();

}