neurovisionx 0.1.0

Unified CNN library for image classification and anchor-free object detection with Adaptive Feature Pyramid Attention (AFPA).

NeuroVisionX

A unified PyTorch library for image classification and anchor-free object detection, built around a single shared backbone and a custom attention module: AFPA (Adaptive Feature Pyramid Attention).

---

Why NeuroVisionX

Most beginner-friendly libraries make you choose: a simple classifier or a heavy, hard-to-configure detector (YOLO/SSD-style with anchor boxes and many hyperparameters).

NeuroVisionX gives you both, from one backbone:

• One backbone, two heads. Train a classifier, a detector, or both, without duplicating feature extraction code.
• AFPA attention block. Lightweight channel+spatial attention with a learnable residual gate, so it starts as identity and "switches on" only when useful — more stable than dropping raw attention into a network from scratch.
• Anchor-free detection head. Predicts object centers, sizes, and sub-pixel offsets directly (CenterNet/FCOS-style) — no anchor box tuning.
• One Trainer class for both tasks, with sensible defaults.
• Minimal dependencies: torch, torchvision, pillow. Nothing exotic.

Installation

pip install neurovisionx

For local development:

git clone https://github.com/sricodings/neurovisionx.git
cd neurovisionx
pip install -e ".[dev]"

Quick start

Classification

import neurovisionx as nv
from torch.utils.data import DataLoader

train_ds = nv.ImageFolderDataset("data/train", image_size=224)
train_loader = DataLoader(train_ds, batch_size=32, shuffle=True)

model = nv.NeuroVisionXNet(num_classes=len(train_ds.classes), mode="classify")
trainer = nv.Trainer(model, train_loader, task="classify")
trainer.fit(epochs=20)

Object detection

import neurovisionx as nv
from torch.utils.data import DataLoader

train_ds = nv.DetectionDataset("data/images", "data/annotations.json", image_size=512)
train_loader = DataLoader(train_ds, batch_size=8, shuffle=True,
                           collate_fn=nv.dataset.detection_collate_fn)

model = nv.NeuroVisionXNet(num_classes=5, mode="detect")
trainer = nv.Trainer(model, train_loader, task="detect")
trainer.fit(epochs=30)

detections = model.detect(image_tensor, score_thresh=0.4)

Annotation format (annotations.json) — simple COCO-lite JSON:

[
  {"image": "img1.jpg", "boxes": [[34, 12, 200, 180]], "labels": [0]},
  {"image": "img2.jpg", "boxes": [[10, 10, 50, 50], [60, 60, 120, 140]], "labels": [2, 4]}
]

Architecture overview

Input image
    │
    ▼
 Stem conv
    │
    ▼
 Stage 1 (downsample + AFPA) ─────────────┐
    │                                     │
    ▼                                     │
 Stage 2 (downsample + AFPA)  -> C3       │  multi-scale
    │                                     │  feature maps
    ▼                                     │
 Stage 3 (downsample + AFPA)  -> C4 ──┐   │
    │                                 │   │
    ▼                                 │   │
 Stage 4 (downsample + AFPA)  -> C5   │   │
    │                                 │   │
    ├──> Classifier head (GAP + FC)   │   │
    │                                 ▼   │
    └──> 1x1 conv + upsample ──> fuse with C4
                                       │
                                       ▼
                            Anchor-free detection head
                          (heatmap, size, offset maps)

Repository layout

neurovisionx/
├── neurovisionx/
│   ├── __init__.py        # public API
│   ├── layers.py           # ConvBNAct, AFPABlock (the novel attention module)
│   ├── backbone.py         # multi-stage CNN backbone
│   ├── detection_head.py   # anchor-free detection head
│   ├── model.py             # NeuroVisionXNet (combines backbone + heads)
│   ├── dataset.py           # ImageFolderDataset, DetectionDataset
│   ├── trainer.py           # Trainer (training loop, losses)
│   └── utils.py             # IoU, NMS, heatmap decoding, visualization
├── examples/
│   ├── train_classifier.py
│   └── train_detector.py
├── tests/
├── docs/
│   └── PUBLISHING_GUIDE.md
├── pyproject.toml
├── LICENSE
└── README.md

Roadmap (suggested, fill in as you build)

• Pretrained backbone weights (ImageNet-style pretraining)
• ONNX export for deployment
• Mixed-precision training support
• Data augmentation pipeline (mosaic, mixup, random crop)
• Benchmark results vs ResNet/YOLO baselines on COCO subset
• Sphinx-generated documentation site

Contributing

Pull requests are welcome. Please open an issue first to discuss major changes. Run pytest and black . before submitting.

Citing

If you use NeuroVisionX in research, please cite:

@software{neurovisionx2026,
  author = {YOUR NAME},
  title = {NeuroVisionX: Unified Classification and Anchor-Free Detection with Adaptive Feature Pyramid Attention},
  year = {2026},
  url = {https://github.com/YOUR_USERNAME/neurovisionx}
}

License

MIT License — see LICENSE.