NeuralSignal

NeuralSignal is a full-stack project for radio signal quality assessment using deep learning. It includes:

• A FastAPI backend for model inference, IQ-to-spectrogram conversion, synthetic IQ generation, and Grad-CAM visualization.
• A React + Vite frontend for uploading IQ/image inputs and viewing predictions interactively.

The quality classes are:

• Poor
• Average
• Good

Project Structure

DL_CNN/
|- app/
|  |- backend/
|  |  |- main.py
|  |  |- model_utils.py
|  |  |- requirements.txt
|  |  `- *.pth (fallback model checkpoints)
|  `- frontend/
|     |- src/
|     |- package.json
|     `- vite.config.ts
|- search_results/
|  `- best_checkpoints/   (preferred model checkpoints)
`- README.md

Features

• Predict quality from IQ samples (/predict/iq)
• Predict quality from spectrogram images (/predict/image)
• Convert IQ to spectrogram PNG (/convert/iq)
• Generate random quality-controlled IQ + spectrogram (/generate/random-spectrogram)
• Produce Grad-CAM heatmaps from IQ input (/gradcam/iq)

Backend Setup (FastAPI)

1) Install dependencies

cd app/backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2) Run API server

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend runs at http://localhost:8000.

3) Model loading behavior

For each model, backend first tries:

• search_results/best_checkpoints/<preferred_file>.pth

If not found, it falls back to:

• app/backend/<fallback_file>.pth

Supported model names:

• BaselineCNN
• ResNet18
• EfficientNet-B0

Frontend Setup (React + Vite)

1) Install dependencies

cd app/frontend
npm install

2) Start development server

npm run dev

Frontend runs at Vite default URL (usually http://localhost:5173).

The UI calls backend using API_BASE = "http://localhost:8000" in app/frontend/src/App.tsx.

IQ Input Format

IQ data must be equivalent to shape (1024, 2):

• 1024 rows
• Each row is [I, Q]

Accepted input styles:

• JSON array ([[i0, q0], [i1, q1], ...])
• CSV/space-separated numeric values
• Flat input with exactly 2048 scalar values (reshaped internally to 1024x2)

API Quick Reference

• GET /
  • Health check and loaded model info.
• POST /predict/iq
  • Multipart form: file + optional model_name.
• POST /predict/image
  • Multipart form: grayscale/normal image + optional model_name.
• POST /convert/iq
  • Multipart form IQ file; returns image/png.
• GET /generate/random-spectrogram
  • Query params: quality, model_name, enforce_prediction, max_attempts, seed.
• POST /gradcam/iq
  • Multipart form IQ file + optional model_name; returns spectrogram/cam/overlay images as base64 data URLs.

Example Requests

Predict from IQ file

curl -X POST "http://localhost:8000/predict/iq" \
  -F "model_name=ResNet18" \
  -F "file=@sample_iq.json"

Convert IQ to spectrogram image

curl -X POST "http://localhost:8000/convert/iq" \
  -F "file=@sample_iq.json" \
  --output spectrogram.png

Notes

• app/backend/venv and app/frontend/node_modules are local environments and should not be committed.
• Large model/data artifacts (.pth, .hdf5) are typically local-only unless you intentionally version them.