Using and training EvolveX

Overview

EvolveX detects loitering and fighting in CCTV streams and raises alerts with snapshot evidence. It is written from scratch on NumPy and the Python standard library. It uses no pretrained models: both models are trained only on footage you label yourself in EvolveX Studio.

Generations. A Gen is a major version: Gen1 = 1.x.y, Gen2 = 2.0.0. Minor versions add features or retrained models; patch versions fix and tune. Every saved model file records the version that made it. See Generations.

Who uses what

Website visitors use neither. The monitor is for the people watching a site's cameras; Studio is for the people who train the models.

Install

You need Python 3 with NumPy, and the ffmpeg binary.

pip install numpy
sudo apt install ffmpeg
cp config.example.json config.json    # add your cameras
cp .env.example .env                  # login, database, R2 and email settings
python -m suspect.main --version

• GPU (NVIDIA Jetson): install CuPy in its own virtual environment and point training.gpu_python in config.json at it. Training is about 6× faster.
• Server: the monitor and Studio run as Docker containers. Set EVX_USER and EVX_PASSWORD whenever they are reachable from the internet.
• Storage: local files by default; PostgreSQL and Cloudflare R2 when DATABASE_URL and R2_* are set.

Using the model

Start the monitor with python -m suspect.main --config config.json and open http://localhost:8080. Until you promote trained models, it finds people with its motion detector and scores fights with a motion-energy heuristic.

1. Add cameras

List them under cameras in config.json. Names must be unique.

2. Choose the detector

Set processing.detector to "cnn" to use EVX-Det. It falls back to "motion" if the model file is missing. det_conf (default 0.3) is its score threshold.

3. Draw loitering zones

loiter_zones are polygons in 0–1 coordinates of the frame; the default is the whole frame.

4. Tune behaviour per camera

5. Receive alerts

Each alert is written to evidence/alerts.jsonl with an annotated PNG snapshot. It can also be sent to a webhook_url and emailed with the snapshot (ALERT_EMAIL_TO and SMTP_*; test with python -m suspect.notify).

Using the models from Python

from suspect.nn.evxdet import load_evx_det
from suspect.nn.model import load_fight_model

det = load_evx_det("models/evx_person.npz")
for x0, y0, x1, y1, score in det.detect(rgb, motion, conf=0.3):
    ...   # rgb: (H,W,3) uint8, motion: (H,W) uint8

fight = load_fight_model("models/evx_fight.npz")

The motion input must come from BackgroundModel.motion_u8(), computed exactly as the monitor computes it.

Training

Start Studio with python -m suspect.studio and open http://localhost:8090. A model only knows the scenes it was trained on, so label footage from every camera you deploy on.

1. Collect. Upload videos or record from a configured camera. Cover different times of day; people walking, standing and queueing; and fight look-alikes such as running, hugging and play.
2. Prepare. Each video is decoded at the monitor's width and frame rate, keeping every 5th frame for labelling. If you change processing.width or fps, re-prepare and retrain.
3. Label people. Drag a box around every person on each kept frame and press Enter. Press E for a frame with nobody in it. Press S for suggested boxes, then check them.
4. Label fights. Press [ where a fight starts and ] where it ends, then tick Fight labelling complete. Only ticked videos train the fight classifier.
5. Split. auto gives the first 70 % of a video to training, the next 15 % to validation and the last 15 % to test. With several videos, give each whole video to one split.
6. Train. Train the person detector first, then the fight classifier. The best epoch is kept: the person detector by (AP50 + F1) / 2, the fight classifier by F1.
7. Test. Run the test split. Person: AP at IoU 0.5 and precision, recall and F1 by threshold. Fight: accuracy, precision, recall, F1, AUC and the confusion matrix.
8. Promote. Promote a run that beats production. The old model is archived and models/registry.json records the change. Restart the monitor.
9. Evolve. Pre-label new footage with the production model, correct it, retrain, test and promote.

Command line

python -m suspect.training import clip.mp4
python -m suspect.training prepare --step 5
python -m suspect.training status
python -m suspect.training train person --epochs 60 --batch 16
python -m suspect.training train fight --epochs 30
python -m suspect.training test person-20260929-101500
python -m suspect.training promote person-20260929-101500

# GPU on the Jetson
SUSPECT_BACKEND=cupy ~/.venvs/suspect/bin/python -m suspect.training train person

Training parameters

Override any of them with --key value on the command line, or in Studio's form.

Each run is saved in training/runs/<kind>-<timestamp>/. On a server CPU, expect about 0.2 s per labelled frame per epoch; start with a few hundred frames.

Releasing a Gen

Each Gen has a permanent entry on the Generations page and a test report. python tools/gen_report.py --gen N writes the production models' test results, training-data counts and SHA-256 checksums into it. The model files are published as a GitHub release with a Zenodo DOI. The full checklist is docs/RELEASE.md in the repository.

Troubleshooting

Citing EvolveX

Cite the generation you used. Each Gen's BibTeX, and its DOI once minted, is on the Generations page. List your paper on Publications.

@software{evolvex_gen1,
  title   = {EvolveX Gen1: Evolving Vigilance for Behavioural Exceptions},
  author  = {Alobaedy, Mustafa},
  year    = {2026},
  url     = {https://evolvex.my}
}

EvolveX is licensed under the PolyForm Noncommercial License 1.0.0.