README.md

---
title: Aminatron
emoji: A
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
python_version: 3.12
pinned: false
license: mit
---

# Aminatron

Aminatron is a multi-object detection model.

It detects several objects on one image and returns object class, confidence, bounding box and an annotated image.

## Folders

```text
aminatron/
  photos/              default input photos
  model/aminatron.pt   main Aminatron model
  runs/predict/        output images with boxes
  coco_yolo/           prepared COCO dataset
  open_images_coco_ext_yolo/ prepared COCO + Open Images dataset
```

`model/aminatron.pt` is the main model everywhere. No `yolo11s.pt` or `yolo11m.pt` files are needed after `aminatron.pt` is created.

## Install

```bash
cd /Users/aminmammadov/aiwork/models/aminatron
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Create Aminatron Model

Create `model/aminatron.pt` from YOLO11m once:

```bash
python train.py --save-as-aminatron
```

This uses `yolo11m.pt` as source and saves it as:

```text
model/aminatron.pt
```

## Run On Laptop

Put images into:

```text
aminatron/photos/
```

Run:

```bash
python predict.py
```

Run on one custom image:

```bash
python predict.py path/to/image.jpg
```

Results are saved to:

```text
runs/predict/
```

## Prepare COCO

Prepare a smaller COCO subset:

```bash
python train.py --prepare-only --max-train 5000 --max-val 1000 --overwrite
```

Prepare full COCO:

```bash
python train.py --prepare-only --max-train 0 --max-val 0 --overwrite
```

`0` means no limit.

## Fine-Tune Aminatron

Fine-tune the existing `model/aminatron.pt`:

```bash
python train.py --epochs 10
```

Continue training later:

```bash
python train.py --epochs 5
```

Both commands use `model/aminatron.pt` by default and save the best result back to `model/aminatron.pt`.

## Add Open Images V7 Classes Without Forgetting COCO

Open Images V7 is useful for adding more objects like fruits, toys and animals. Do not train on Open Images alone if you want to keep old COCO classes. Prepare COCO first, then prepare a mixed COCO + Open Images dataset.

Prepare COCO if `coco_yolo/data.yaml` does not exist:

```bash
python train.py --prepare-only --max-train 5000 --max-val 1000 --overwrite
```

Install the Open Images preparation dependency locally:

```bash
pip install -r requirements-open-images.txt
```

FiftyOne upgrades `Pillow` above the version required by Gradio. That is okay for dataset preparation/training. Before running the web app again, run `pip install -r requirements.txt` to restore the app dependencies.

Prepare a small starter subset:

```bash
python prepare_open_images.py --max-train 2000 --max-val 500 --overwrite
```

Prepare a tiny test subset first if you only want to check that the pipeline works:

```bash
python prepare_open_images.py --max-train 50 --max-val 20 --overwrite
```

Prepare only specific classes:

```bash
python prepare_open_images.py --classes Apple Banana Orange Toy Doll "Teddy bear" Ball Cat Dog Person --max-train 3000 --max-val 700 --overwrite
```

The result is saved to:

```text
open_images_coco_ext_yolo/data.yaml
```

This mixed dataset uses:

```text
coco_yolo/images/train + open_images_coco_ext_yolo/images/train
coco_yolo/images/val   + open_images_coco_ext_yolo/images/val
```

Class ids are COCO-compatible. Matching Open Images classes are mapped into existing COCO ids, for example `Person -> person`, `Dog -> dog`, `Apple -> apple`, `Teddy bear -> teddy bear`. Truly new classes are added after the 80 COCO classes.

Because your previous test run produced an 18-class `aminatron.pt`, restore the COCO base before additive training:

```bash
python train.py --save-as-aminatron
```

Train Aminatron on COCO + Open Images together:

```bash
python train.py --data-dir open_images_coco_ext_yolo --no-auto-prepare --epochs 10
```

`--no-auto-prepare` is intentional: it prevents `train.py` from accidentally preparing plain COCO if `open_images_coco_ext_yolo/data.yaml` is missing.

Important: old model files are backed up automatically to `model/backups/` before `model/aminatron.pt` is overwritten.

## Web Demo

```bash
python app.py
```

## Hugging Face Space Email Review

The Space can email the original uploaded image and the processed result image to:

```text
mammadov.amin2000@gmail.com
```

For this to work, add these Hugging Face Space Secrets:

```text
RESEND_API_KEY=your_resend_api_key
EMAIL_TO=mammadov.amin2000@gmail.com
EMAIL_FROM=Aminatron <onboarding@resend.dev>
```

Recommended setup:

1. Create a Resend account with `mammadov.amin2000@gmail.com`.
2. Create an API key at https://resend.com/api-keys.
3. Add `RESEND_API_KEY` to Hugging Face Space Secrets.
4. Keep `EMAIL_TO=mammadov.amin2000@gmail.com`.

If you use Resend without a verified custom domain, keep:

```text
EMAIL_FROM=Aminatron <onboarding@resend.dev>
```

This is better for Hugging Face Spaces than Gmail SMTP because SMTP ports can be unreachable from the Space container.

Fallback Gmail SMTP secrets, only if SMTP works in your environment:

```text
SMTP_USER=your_gmail_address@gmail.com
SMTP_PASSWORD=your_gmail_app_password
EMAIL_TO=mammadov.amin2000@gmail.com
```

For Gmail, `SMTP_PASSWORD` must be a Gmail App Password, not your normal Gmail password.

You can also use this secret name instead of `SMTP_PASSWORD`:

```text
GMAIL_APP_PASSWORD=your_gmail_app_password
```

Gmail setup:

1. Enable 2-Step Verification in your Google account.
2. Create an App Password for Mail.
3. Put that app password into `SMTP_PASSWORD` or `GMAIL_APP_PASSWORD`.

Optional secrets:

```text
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
```

If SMTP secrets are missing, the Space still works, but photos are not emailed.

## Most Needed Commands

```bash
cd /Users/aminmammadov/aiwork/models/aminatron
source .venv/bin/activate
python train.py --save-as-aminatron
python predict.py
python train.py --prepare-only --max-train 5000 --max-val 1000 --overwrite
pip install -r requirements-open-images.txt
python prepare_open_images.py --max-train 2000 --max-val 500 --overwrite
python train.py --save-as-aminatron
python train.py --data-dir open_images_coco_ext_yolo --no-auto-prepare --epochs 10
python train.py --epochs 10
python train.py --epochs 5
python app.py
```