Quickstart: train, predict and export a detector

This page fine-tunes an object detector on your own images, then predicts with it, evaluates it and exports it. Every step is shown both as a command and in Python.

You need:

Mayaku installed (pip install mayaku, see Installation).
A dataset in COCO format with a training split and a validation split.

1. Lay out the data

Mayaku reads COCO JSON annotations directly. A typical layout, the one Roboflow's "COCO" export produces:

Text only

data/
├── train/
│   ├── _annotations.coco.json
│   ├── img_0001.jpg
│   └── ...
├── valid/
│   ├── _annotations.coco.json
│   └── ...
└── test/            (optional)
    ├── _annotations.coco.json
    └── ...

Each file_name in the JSON is resolved relative to the image directory you pass. Any layout works as long as that holds. The required JSON fields are listed in Datasets.

2. Check the data (optional)

Python

import mayaku

report = mayaku.health_check("data/train/_annotations.coco.json", "data/train")
print(report)

The report gives image, box and class counts, the input size training would use, object-size fractions, class balance, and warnings such as images without annotations. See Datasets.

3. Train

Command line:

Bash

mayaku train --weights mayaku-n-det \
  --annotations data/train/_annotations.coco.json --images data/train \
  --val-annotations data/valid/_annotations.coco.json --val-images data/valid

Python:

Python

from mayaku import train

result = train(
    weights="mayaku-n-det",
    train_annotations="data/train/_annotations.coco.json",
    train_images="data/train",
    val_annotations="data/valid/_annotations.coco.json",
    val_images="data/valid",
)
print(result["final_weights"])   # runs/mayaku-n-det/train/best.pt
print(result["metrics"]["AP"])   # COCO AP@[.50:.95] on the validation split

What happens:

mayaku-n-det is the nano detector pretrained by Datamarkin. It downloads to ./mayaku-n-det.pth the first time, and later runs reuse that file.
The class count and the input size (the "canvas") come from your training annotations. The class layer is re-initialized for your classes.
Training runs 100 epochs, the fine-tune default for datasets of 10 images or more, and evaluates on the validation split after every epoch.
The checkpoint with the best validation AP is saved as best.pt and scored once more at the end.

For a 300-image dataset of 4:3 photos with 3 classes, the log starts like this:

Text only

[mayaku.train] auto-config input.canvas_hw: None -> [672, 896]
[mayaku.train] auto-config model.num_classes: None -> 3
[mayaku.train] auto-config train.assigner_warmup: 5 -> 0
[mayaku.train] auto-config train.aug.mosaic: 1.0 -> 0.1
[mayaku.train] auto-config train.epochs: 125 -> 100
[mayaku.train] auto-config train.final_frac: 0.16 -> 0.2
[mayaku.train] tier n, 3 classes, canvas 672x896, 100 epochs, batch 16 on cuda -> runs/mayaku-n-det/train

Each auto-config line is a setting Mayaku derived from your data because you didn't set it yourself. See Training.

When training finishes, the command prints final weights: runs/mayaku-n-det/train/best.pt.

To pick a size other than nano, use mayaku-s-det, mayaku-m-det or mayaku-l-det. See Models. For every training option, see Training.

4. Predict

Command line (prints JSON):

Bash

mayaku predict runs/mayaku-n-det/train/best.pt photo.jpg

Python:

Python

from mayaku import from_pretrained

predictor = from_pretrained("runs/mayaku-n-det/train/best.pt")
det = predictor("photo.jpg")

for box, score, label in zip(det.boxes.tolist(), det.scores.tolist(), det.labels.tolist()):
    print(predictor.class_names[label], round(score, 3), box)   # box is [x1, y1, x2, y2] in pixels

The checkpoint holds the class names, input size and thresholds, so no config file is needed. See Prediction.

5. Evaluate on the test split

Bash

mayaku eval runs/mayaku-n-det/train/best.pt \
  --annotations data/test/_annotations.coco.json --images data/test

Python

from mayaku import evaluate

metrics = evaluate("runs/mayaku-n-det/train/best.pt",
                   annotations="data/test/_annotations.coco.json", images="data/test")
print(metrics["AP"], metrics["AP50"])

See Evaluation for every metric key.

6. Export

Bash

pip install "mayaku[onnx]" onnxruntime
mayaku export onnx runs/mayaku-n-det/train/best.pt --output model.onnx

The exported file runs through the same from_pretrained and mayaku predict:

Bash

mayaku predict model.onnx photo.jpg

Core ML, OpenVINO and TensorRT work the same way. See Export and deployment.