How it works
A guided CLI workflow: choose detection or comparison, pick your model folder, then let the engine process your dataset or validation set.
Choose Process Images (Detection) to run object
detection on your dataset, or Compare Models to benchmark every
.pt file in a folder against validation data.
Select the model folder (e.g. cars or
receipts) containing your trained weights and a classes.txt
file. Classes load automatically—no manual YAML editing for detection runs.
Detection: pick a specific model file, process
all images in dataset/, and write results under output/.
Comparison: the system finds all models, builds a comparer dataset,
evaluates each on validation data, and saves model_comparison.csv.
Two main features
One entry point (python main.py), two powerful paths
depending on whether you need labeled images or performance metrics.
Select a model file such as best1.pt. The
engine loads weights and classes, runs YOLO on every image in dataset/, and
writes annotated images, YOLO label files, and optional output video.
Automatically discovers every model in the selected folder, creates a comparer validation structure, evaluates each checkpoint, and exports a CSV with Precision, Recall, mAP50, and mAP50-95 for easy analysis.
Features
Everything from the Supervised AI Learner README—dynamic model folders, structured output, and standard YOLO artifacts.
Choose from multiple model folders and individual
.pt files without hard-coding paths in the codebase.
Process images with your selected YOLO model and draw detections with confidence scores, color-coded by class.
Compare performance of multiple trained models on the same validation data and rank them with standard detection metrics.
All results land in a consistent output/
tree—saved images, labels, video, and comparison reports.
Stitch detection frames into output_video.mp4
so you can review batch runs visually.
Reads classes.txt from each model folder and
configures detection classes automatically.
Generates standard YOLO annotation files with normalized coordinates ready for training pipelines.
Screens · Main interface
The interactive CLI is your control center—pick detection or model
comparison, browse folders under models/, and select the exact weight file before
processing starts.
Run
python main.py and follow numbered prompts. The menu lists every model folder and
.pt checkpoint so you never edit paths by hand.
Screens · Precision and accuracy
Accuracy charts summarize how reliably your checkpoint finds objects on validation data—use them alongside raw label files to decide whether a model is ready for production.
Visual metrics make it easier to spot
under-performing classes or inconsistent detections without opening every image manually.
Pair this view with the exported labels in output/labels/ for a full picture.
Screens · Model comparison
The Compare Models workflow evaluates each .pt file in a
folder against validation data and exports a spreadsheet you can sort, filter, and share.
When you train several versions—
best1.pt, best2.pt, best3.pt—the comparer ranks them
with industry-standard metrics so you pick the winner without rerunning manual tests.
Output format
Every run writes predictable files under output/—ready
for review, retraining, or spreadsheet analysis.
Saved in output/saved/ with detected objects,
confidence scores, and class colors applied.
Standard format in output/labels/:
<class_id> <x_center> <y_center> <width> <height>
with normalized 0–1 coordinates, plus classes.txt.
output/model_comparison.csv lists Precision,
Recall, mAP50, and mAP50-95 per model—open in Excel or pandas.
Dynamic features
Reads classes.txt from the model folder and
wires detection classes without manual edits.
Creates data.yaml automatically for model
comparison using classes and validation paths from your selected folder.
Validates models, class files, and dataset folders before processing with clear messages when something is missing.
Requirements
Python 3.13.2 recommended. Install Ultralytics YOLO, OpenCV, and pandas for comparison runs.
pip install ultralytics opencv-python pandas pyyamlOpen source · MIT License · Python CLI
Clone the repo, set up a virtual environment, organize your models and
dataset, then run python main.py.
python -m venv venv then activate:
venv\Scripts\activate on Windows or source venv/bin/activate on
macOS/Linux.
Run pip install ultralytics opencv-python pandas
pyyaml inside your activated environment.
Place trained weights under models/<folder>/
with classes.txt. Put images (and optional labels) in dataset/.
With (venv) active, run python main.py
and follow the interactive menu for detection or comparison.
MIT License · Built with Ultralytics YOLO · github.com/XeroDays/Supervised_learner