Vortex Core Detection

A machine learning pipeline that detects vortex cores in fluid dynamics image datasets using YOLOv5 for object detection, computer vision for feature extraction, and an ensemble of AdaBoost, Random Forest, and XGBoost classifiers wrapped in a hard-voting ensemble model.

---

Overview

This project tackles vortex core detection as a two-stage problem:

1. Object Detection — YOLOv5 is used to locate vortex candidates in images, extracting contour-level features from each detected region.
2. Classification — The extracted features are fed into an ensemble classifier to determine whether each candidate is a true vortex core or not.

The final classifier is a hard-voting VotingClassifier combining:

• AdaBoostClassifier
• RandomForestClassifier
• XGBClassifier

The entire pipeline was deployed on a Google Cloud VM with an HTML frontend.

---

Pipeline

Image Dataset
      ↓
YOLOv5 Object Detection
      ↓
Feature Extraction (contourArea, areaPercDiff, aspectRatio, momentLocDiff)
      ↓
Data Wrangling + EDA  (feature_engineering.py)
      ↓
Ensemble Training: AdaBoost + Random Forest + XGBoost  (training for ensemble.py)
      ↓
Voting Classifier (Hard Vote)  →  Saved as .pkl
      ↓
Prediction on new data  (test.py)

---

Features

• 4 engineered features extracted from image contours: contourArea, areaPercDiff, aspectRatio, momentLocDiff
• Comprehensive EDA with 9 plot types: Count, Density, Pair, Box, Point, Strip, Violin, Joint, Heatmap
• Hyperparameter tuning via GridSearchCV across all three classifiers simultaneously
• Feature importance plots saved for each individual classifier
• Confusion matrix heatmap and classification report CSV exported automatically
• Validation curve plotting for estimator count vs. accuracy
• Model persistence — trained VotingClassifier saved as Voting Classifier.pkl via joblib

---

Tech Stack

Layer	Technology
Object Detection	YOLOv5
Data Processing	pandas, numpy
EDA & Visualisation	seaborn, matplotlib, plotly
ML Models	scikit-learn (AdaBoost, RandomForest, VotingClassifier), XGBoost
Hyperparameter Tuning	GridSearchCV
Model Serialisation	joblib
Deployment	Google Cloud VM + HTML frontend
Notebooks	Jupyter (.ipynb)

---

Project Structure

Vortex-Core-Detection/
├── data/
│   └── train.csv                   # Feature dataset extracted from vortex images
├── src/
│   ├── feature_engineering.py      # EDA and visualisation (9 plot types)
│   ├── training for ensemble.py    # Model training, tuning, evaluation & saving
│   ├── test.py                     # Load saved model and run predictions
│   ├── Feature_Engineering.ipynb   # Notebook version of feature engineering
│   ├── Train.ipynb                 # Notebook version of training pipeline
│   └── Test.ipynb                  # Notebook version of testing pipeline
└── README.md

---

Dataset Features

The classifier uses 4 features extracted from image contours:

Feature	Description
contourArea	Area of the detected contour region
areaPercDiff	Percentage difference in area between candidate and reference
aspectRatio	Width-to-height ratio of the bounding box
momentLocDiff	Difference in centroid location using image moments

Label: vortex (1) vs non-vortex (0)

---

Setup

1. Clone the repo

git clone https://github.com/AyushMaria/Vortex-Core-Detection.git
cd Vortex-Core-Detection

2. Install dependencies

pip install numpy pandas scikit-learn xgboost matplotlib seaborn plotly joblib

3. Prepare your data

Place your feature CSV in data/train.csv. It must include the columns:

ID, localX, localY, contourArea, areaPercDiff, aspectRatio, momentLocDiff, label

---

Usage

Step 1 — EDA & Feature Engineering

cd src
python feature_engineering.py

Generates 9 visualisation plots saved to images/.

Step 2 — Train the Ensemble

python "training for ensemble.py"

This will:

• Split data into train/test (70/30)
• Train AdaBoost, Random Forest, and XGBoost individually
• Combine them into a hard-voting VotingClassifier
• Save feature importance plots to images/
• Save the classification report to reports/report.csv
• Save the model as Voting Classifier.pkl

Step 3 — Run Predictions

python test.py

Loads Voting Classifier.pkl and runs predictions on the test dataset.

---

Module Reference

feature_engineering.py

Function	Description
plot_trends(df)	Generates all 9 EDA plots and saves them to images/
main()	Loads train.csv, preprocesses data, calls plot_trends()

training for ensemble.py

Function	Description
hyperparameter_tune(X_train, y_train)	GridSearchCV across AdaBoost, RF, and XGBoost params
train_classifiers(X_train, X_test, y_train, y_test)	Trains all models, creates voting ensemble, saves .pkl
classification_report(y_test, y_pred)	Exports classification report to reports/report.csv
validation_curve(model, X, y)	Plots validation curve vs. number of estimators
confusion_matrix(y_test, y_pred)	Saves confusion matrix heatmap to images/
feature_importance(clf)	Saves bar chart of feature importances to images/

test.py

Function	Description
predict(df)	Loads saved VotingClassifier.pkl and returns predictions

---

Outputs

After running the full pipeline, you will find:

images/
  countplot.png
  densityplot.png
  pairplot1.png / pairplot2.png / pairplot3.png
  boxplot.png
  pointplot.png
  violinplot.png
  jointplot.png
  stripplot.png
  heatmap.png
  feature_importance.png

reports/
  report.csv

Voting Classifier.pkl

---

License

MIT