Skip to content

Commit 6331896

Browse files
jonasrenaultjonasrenault
authored
21 add models (#24)
* update pages url with custom domain * update to v2.0.0 (#23) * remove references to yolov8 * add docs for imagenet dataset * add more to datasets docs * add training results to models doc * add links to orion models * add more docs on models * add models to readme * fix typos
1 parent c93b2d6 commit 6331896

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+736
-13
lines changed

‎README.md‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,18 @@
88

99
## Documentation
1010

11-
**The documentation for Orion is available [here](https://jonasrenault.github.io/orion/).**
11+
**Checkout Orion's [documentation](http://jrenault.fr/orion/) for help.**
12+
13+
## Models
14+
15+
Orion provides [YOLO12](https://docs.ultralytics.com/models/yolo12/) models fine-tuned on a [custom dataset](http://jrenault.fr/orion/datasets) of military vehicles with [4 classes](http://jrenault.fr/orion/classes).
16+
17+
| Model | size<br><sup>(pixels) | params<br><sup>(M) |
18+
| ------------------------------------------------------------------------------------ | --------------------- | -------------------- |
19+
| [orion12n](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12n.pt) | 640 | 2.6 |
20+
| [orion12s](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12s.pt) | 640 | 9.3 |
21+
| [orion12m](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12m.pt) | 640 | 20.2 |
22+
| [orion12l](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12l.pt) | 640 | 26.4 |
1223

1324
## Installation
1425

@@ -42,15 +53,41 @@ When you install Orion in a virtual environment, it creates a CLI script called
4253
orion --help
4354
```
4455

45-
to see the various commands available (or take a look at the [documentation](https://jonasrenault.github.io/orion/) for examples).
56+
to see the various commands available (or take a look at the [documentation](http://jrenault.fr/orion/) for examples).
57+
58+
#### Detect military vehicles in images
59+
60+
The `predict` command will use one of orion's models to detect military vehicles in images. For example, if you downloaded the [orion12m.pt](#models) model file into your current directory, and want to use it to detect military vehicles in an image, run
61+
62+
```bash
63+
orion predict ./orion12m.pt resources/test/afvs.jpg -s
64+
```
65+
66+
The `predict` command with the `-s` option will save the annotated image:
67+
68+
<div align="center">
69+
<img src="docs/imgs/afvs.jpg" width="640"/>
70+
</div>
71+
72+
#### Track military vehicles in videos
73+
74+
The `track` command will use one of orion's models to track military vehicles in videos. For example, if you downloaded the [orion12m.pt](#models) model file into your current directory, and want to use it to track military vehicles in a video, run
75+
76+
```bash
77+
orion track ./orion12m.pt resources/test/mev1.mp4
78+
```
79+
80+
<div align="center">
81+
<img src="docs/imgs/mev_tracking.gif" width="640"/>
82+
</div>
4683

4784
## Contents
4885

4986
- The [orion](./orion/) directory contains the source code used to fetch and format datasets for fine-tuning a YOLO12 model for object detection.
5087
- The [resources](./resources/) directory contains video samples for vehicle detection task.
5188
- The [notebooks](./notebooks/) directory contains exemple notebooks on how to
5289
1. [Prepare](./notebooks/01_Prepare.ipynb) a custom dataset of images annotated for automatic target recognition of military vehicles.
53-
2. [Train](./notebooks/02_Train.ipynb) fine-tune a YOLO12 model using the prepared dataset.
90+
2. [Train](./notebooks/02_Train.ipynb) a YOLO12 model using the prepared dataset.
5491
3. [Evaluate](./notebooks/03_Evaluate.ipynb) a fine-tuned model on a realistic test dataset.
5592

5693
## Run the notebooks

‎docs/classes.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Classes
2+
3+
Orion uses four broad classes of military vehicles that our model can discriminate:
4+
5+
1. **Armoured Fighting Vehicle (AFV)**
6+
2. **Armoured Personnel Carrier (APC)**
7+
3. **Military Engineering Vehicle (MEV)**
8+
4. **Light Armoured Vehicle (LAV)**
9+
10+
## Class repartition
11+
12+
![Class repartition](imgs/labels.jpg)
13+
14+
The AFV class is overrepresented in Orion's [dataset](./datasets.md) since most open source image datasets only label military vehicles as tanks.

‎docs/datasets.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Datasets
2+
3+
Orion uses images from open source object-detection datasets to create a dataset of military vehicles and format it correctly for [YOLO](https://github.com/ultralytics/ultralytics) training. This page describes the various datasets used by Orion.
4+
5+
## ImageNet
6+
7+
The first dataset Orion uses is `ImageNet21k`. The `ImageNet21k` dataset is available from the [image-net website](https://image-net.org/download-images.php). You need to register and be granted access to download the images. We use the Winter 21 version since it gives the option of downloading the images for a single synset (a class) and we're only interested in images of specific classes (military vehicles).
8+
9+
* The processed version of ImageNet21k is available on the [ImageNet21k repository](https://github.com/Alibaba-MIIL/ImageNet21K).
10+
* The class ids and names are available in [this issue](https://github.com/google-research/big_transfer/issues/7#issuecomment-640048775).
11+
12+
Orion provides a `search` function to search ImageNet class names for a given query.
13+
14+
```python
15+
def search(
16+
keywords: list[str],
17+
dir: Path = settings.ORION_HOME_DIR / "imagenet",
18+
):
19+
"""
20+
Search image net classes matching the given keywords.
21+
22+
Args:
23+
keywords (list[str]): List of keywords to search for.
24+
dir (Path, optional): directory where files will be downloaded.
25+
Defaults to ORION_HOME_DIR / "imagenet".
26+
"""
27+
```
28+
29+
!!! note
30+
The `search` function will download the list of class names and ids in the dataset `dir` if they are not already present.
31+
32+
Orion also provides a convenience `download` function to download images and annotations for a specific class id.
33+
34+
```python
35+
def download(
36+
ids: list[str],
37+
dir: Path = settings.ORION_HOME_DIR / "imagenet",
38+
):
39+
"""
40+
Download ImageNet images and annotations for the given class ids.
41+
42+
Args:
43+
ids (list[str]): the class ids to download.
44+
dir (Path, optional): the dataset directory.
45+
Defaults to settings.ORION_HOME_DIR / "imagenet".
46+
"""
47+
```
48+
49+
!!! note
50+
The `download` function will only download images for classes that actually have object detection annotations (a lot of classes in the ImageNet21k dataset do not have annotations).
51+
52+
!!! info
53+
Orion uses **378 annotated images** from the ImageNet dataset, coming from the `n04389033` class (tank, army tank, armored combat vehicle, armoured combat vehicle), which are all mapped to the `AFV` class.`
54+
55+
## OpenImage
56+
57+
The second dataset Orion uses is [Open Images](https://storage.googleapis.com/openimages/web/index.html) which contains images with `Tank` detection labels. Images from OpenImages are downloaded and managed with [fiftyone](https://docs.voxel51.com/integrations/open_images.html).
58+
59+
!!! info
60+
Orion uses **1246 annotated images** from the OpenImage dataset which are all mapped to the `AFV` class.
61+
62+
## Russian Military annotated dataset
63+
64+
Another dataset Orion uses is the [Russian Military vehicles](https://universe.roboflow.com/capstoneproject/russian-military-annotated) annotated dataset provided by Tuomo Hiippala from Digital Geography Lab on Roboflow. It contains 1042 annotated images of russing military vehicles with 10 classes which we map to either the `AFC` or the `APC` class.
65+
66+
```python
67+
LABEL_MAPPING = {
68+
"bm-21": "AFV",
69+
"t-80": "AFV",
70+
"t-64": "AFV",
71+
"t-72": "AFV",
72+
"bmp-1": "AFV",
73+
"bmp-2": "AFV",
74+
"bmd-2": "AFV",
75+
"btr-70": "APC",
76+
"btr-80": "APC",
77+
"mt-lb": "APC",
78+
}
79+
```
80+
81+
Orion provides a `download` function to download the images and annotations from this dataset and structure the directory to be imported into a `fiftyone` dataset.
82+
83+
```python
84+
def download(dir: Path = settings.ORION_HOME_DIR / "roboflow"):
85+
"""
86+
Downlad images and annotations from the russian military annotated dataset
87+
on roboflow and format them to be imported into a fo.Dataset.
88+
89+
Args:
90+
dir (Path, optional): the dataset dir.
91+
Defaults to settings.ORION_HOME_DIR / "roboflow".
92+
"""
93+
```
94+
95+
!!! info
96+
Orion uses **1042 annotated images** from the Russian Military vehicles dataset which are mapped to the `AFV` or `APC` class.
97+
98+
## Google Images
99+
100+
To improve our training dataset, we also scraped images of military vehicles from Google Image and annotated them by hand. This sample dataset is available for download from Orion's github repository and contains 669 images of vehicles from all four classes (`AFV`, `APC`, `MEV` and `LAV`).
101+
102+
!!! info
103+
Orion uses **669 annotated images** scraped from Google Images for all four classes.
104+
105+
## The Search 2
106+
107+
The [The Search_2](https://figshare.com/articles/dataset/The_Search_2_dataset/1041463) consist of 44 high-resolution digital color images of different complex natural scenes, with each scene (image) containing a single military vehicle that serves as a search target. This dataset is not used by Orion for training; it is used instead for evaluating the models on **realistic long range automatic target recognition (ATR) samples**.
108+
109+
## Command-line
110+
111+
Orion provides a CLI command to download and setup a dataset of annotated military vehicles for training and development of automatic target recognition models. The `prepare` command will download images from the [ImageNet](#imagenet), [OpenImages](#openimage), [Russian military](#russian-military-annotated-dataset) and [Google Images](#google-images) sources and combine them into a single dataset on disk.
112+
113+
The `prepare` command takes as an option the directory where all the source images will be downloaded and where the full combined dataset will be saved (by default, `~/.cache/orion`).
114+
115+
```bash
116+
orion prepare --help
117+
118+
Usage: orion prepare [OPTIONS]
119+
120+
Prepare a dataset of annotated military vehicle images.
121+
122+
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────╮
123+
│ --dir -d DIRECTORY Orion home directory. [default: ~/.cache/orion] │
124+
│ --ids TEXT List of class ids to download. [default: n04389033] │
125+
│ --help Show this message and exit. │
126+
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────╯
127+
```

‎docs/imgs/afvs.jpg‎

197 KB
Loading

‎docs/imgs/labels.jpg‎

224 KB
Loading

‎docs/imgs/mev_tracking.gif‎

6.31 MB
Loading

‎docs/models.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Models
2+
3+
Orion provides [YOLO12](https://docs.ultralytics.com/models/yolo12/) models fine-tuned on a [custom dataset](datasets.md) of military vehicles with [4 classes](classes.md).
4+
5+
| Model | size<br><sup>(pixels) | params<br><sup>(M) |
6+
| ------------------------------------------------------------------------------------ | --------------------- | -------------------- |
7+
| [orion12n](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12n.pt) | 640 | 2.6 |
8+
| [orion12s](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12s.pt) | 640 | 9.3 |
9+
| [orion12m](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12m.pt) | 640 | 20.2 |
10+
| [orion12l](https://github.com/jonasrenault/orion/releases/download/v2.0.0/orion12l.pt) | 640 | 26.4 |
11+
12+
## Training results
13+
14+
### Orion12n
15+
16+
![Orion12n training results](trains/orion12n/results.png)
17+
18+
### Orion12s
19+
20+
![Orion12s training results](trains/orion12s/results.png)
21+
22+
### Orion12m
23+
24+
![Orion12m training results](trains/orion12m/results.png)
25+
26+
### Orion12l
27+
28+
![Orion12l training results](trains/orion12l/results.png)
29+
30+
## Usage
31+
32+
To use one of Orion's models, download it from the [links above](#models) and then use one of Orion's CLI commands:
33+
34+
### Detect military vehicles in images
35+
36+
The `predict` command will use the model to detect military vehicles in images.
37+
38+
```bash
39+
orion predict --help
40+
41+
Usage: orion predict [OPTIONS] MODEL_PATH DATA
42+
43+
Run predictions on a set of images using the given model.
44+
45+
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
46+
│ * model_path PATH model path. [required] │
47+
│ * data PATH data to make predictions on. [required] │
48+
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
49+
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
50+
│ --save -s save annotated images. │
51+
│ --save-txt --no-save-txt save detection results in a txt file. [default: save-txt] │
52+
│ --save-conf --no-save-conf save confidence score for each detection. [default: save-conf] │
53+
│ --output -o DIRECTORY save directory. [default: Path.cwd() /runs/predict] │
54+
│ --help Show this message and exit. │
55+
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
56+
```
57+
58+
For example, if you downloaded the [orion12m.pt](#models) model file into your current directory, and want to use it to detect military vehicles in an image, run
59+
60+
```bash
61+
orion predict ./orion12m.pt resources/test/afvs.jpg -s
62+
```
63+
64+
!!! tip
65+
The `predict` command with the `-s` option will save the annotated image.
66+
67+
![Annotated AFVs](imgs/afvs.jpg)
68+
69+
### Track military vehicles in videos
70+
71+
The `track` command will use the model to track military vehicles in videos.
72+
73+
```bash
74+
orion track --help
75+
76+
Usage: orion track [OPTIONS] MODEL_PATH DATA
77+
78+
Track tanks in a video using a YOLO model and specified tracker.
79+
80+
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
81+
│ * model_path PATH model path. [required] │
82+
│ * data PATH input video. [required] │
83+
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
84+
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
85+
│ --conf -c FLOAT confidence threshold for detections. [default: 0.5] │
86+
│ --tracker -t TEXT tracker configuration file. [default: botsort.yaml] │
87+
│ --output -o DIRECTORY save directory. [default: Path.cwd() /runs/track] │
88+
│ --help Show this message and exit. │
89+
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
90+
```
91+
92+
For example, if you downloaded the [orion12m.pt](#models) model file into your current directory, and want to use it to track military vehicles in a video, run
93+
94+
```bash
95+
orion track ./orion12m.pt resources/test/mev1.mp4
96+
```
97+
98+
![MEV tracking](imgs/mev_tracking.gif)

‎docs/trains/orion12l/BoxF1_curve.png‎

203 KB
Loading

‎docs/trains/orion12l/BoxPR_curve.png‎

125 KB
Loading

‎docs/trains/orion12l/BoxP_curve.png‎

181 KB
Loading

0 commit comments

Comments
 (0)