📝 [Update] README document

README.md

@@ -1,5 +1,4 @@
-# YOLOv9-MIT
-An MIT license rewrite of YOLOv9
+# YOLO: Official Implementation of YOLOv{7, 9}
 
 ![WIP](https://img.shields.io/badge/status-WIP-orange)
 > [!IMPORTANT]
@@ -7,66 +6,72 @@ An MIT license rewrite of YOLOv9
 > 
 > Use of this code is at your own risk and discretion. It is advisable to consult with the project owner before deploying or integrating into any critical systems.
 
-## Contributing
+Welcome to the official implementation of the YOLOv7 and YOLOv9. This repository will contains the complete codebase, pre-trained models, and detailed instructions for training and deploying YOLOv9.
 
-While the project's structure is still being finalized, we ask that potential contributors wait for these foundational decisions to be made. We greatly appreciate your patience and are excited to welcome contributions from the community once we are ready. Alternatively, you are welcome to propose functions that should be implemented based on the original YOLO version or suggest other enhancements! 
+## TL;DR
+- Official YOLOv9 model implementation.
+- Features real-time detection with state-of-the-art accuracy.
+<!-- - Includes pre-trained models and training scripts. -->
+- Quick train: `python examples/example_train.py`
 
-If you are interested in contributing, please keep an eye on project updates or contact us directly at [[email protected]](mailto:[email protected]) for more information.
+## Introduction
+- [**YOLOv9**: Learning What You Want to Learn Using Programmable Gradient Information](https://arxiv.org/abs/2402.13616)
+- [**YOLOv7**: Trainable bag-of-freebies sets new state-of-the-art for real-time object detectors](https://arxiv.org/abs/2207.02696)
 
-# Installing Dependencies
-```
+## Installation
+To get started with YOLOv9, clone this repository and install the required dependencies:
+```shell
+git clone [email protected]:WongKinYiu/yolov9mit.git
+cd yolov9mit
 pip install -r requirements.txt
 ```
 
-# Training the Model
-To start training the model, use the following command:
-```bash
-$python examples/example_train.py
+<!-- 
 ```
-Ensure that you are in the root directory of the project when you run this command.
+pip install git+https://github.com/WongKinYiu/yolov9mit.git
+``` 
+-->
+
+<!-- ### Quick Start
+Run YOLOv9 on a pre-trained model with:
+
+```shell
+python examples/example_train.py hyper.data.batch_size=8
+``` -->
+
+<!-- ## Model Zoo[WIP]
+Find pre-trained models with benchmarks on various datasets in the [Model Zoo](docs/MODELS). -->
 
-The training script will automatically utilize the configuration files from the `yolo/config/` directory as specified by the Hydra configuration framework. This setup allows easy management and adjustment of training parameters without modifying the code.
+## Training
+For training YOLOv9 on your dataset:
 
-To override any configuration parameters directly from the command line, you can specify them after the script. For example, to change the batch size, you can run:
+Modify the configuration file data/config.yaml to point to your dataset.
+Run the training script:
 
-```bash
-$python examples/example_train.py hyper.data.batch_size=8
+```shell
+python examples/example_train.py hyper.data.batch_size=8 model=v9-c
 ```
 
+More customization details, or ways to modify the model can be found [HOWTO](docs/HOWTO).
 
+## Evaluation [WIP]
+Evaluate the model performance using:
 
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=WongKinYiu/yolov9mit&type=Date)](https://star-history.com/#WongKinYiu/yolov9mit&Date)
-
-## To-Do Lists
-- [ ] Project Setup
-    - [X] requirements
-    - [x] LICENSE
-    - [ ] README
-    - [x] pytests
-    - [ ] setup.py/pip install
-    - [x] log format
-    - [ ] hugging face
-- [ ] Data proccess
-    - [ ] Dataset
-        - [x] Download script
-        - [ ] Auto Download
-        - [ ] xywh, xxyy, xcyc
-    - [x] Dataloder
-        - [x] Data arugment
-- [ ] Model
-    - [ ] load model
-        - [ ] from yaml
-        - [ ] from github
-    - [x] trainer
-        - [x] train_one_iter
-        - [x] train_one_epoch
-    - [ ] DDP
-    - [x] EMA, OTA
-- [ ] Loss
-- [ ] Run
-    - [ ] train
-    - [ ] test
-    - [ ] demo
-- [x] Configuration
+```shell
+python examples/examples_evaluate.py weights=v9-c.pt
+```
+
+## Contributing
+Contributions to the YOLOv9 project are welcome! See [CONTRIBUTING](docs/CONTRIBUTING.md) for how to help out.
+
+## Citations
+```
+@misc{wang2024yolov9,
+      title={YOLOv9: Learning What You Want to Learn Using Programmable Gradient Information}, 
+      author={Chien-Yao Wang and I-Hau Yeh and Hong-Yuan Mark Liao},
+      year={2024},
+      eprint={2402.13616},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV}
+}
+```

docs/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to YOLO
+
+Thank you for your interest in contributing to this project! We value your contributions and want to make the process as easy and enjoyable as possible. Below you will find the guidelines for contributing.
+
+## Quick Links
+- [Main README](../README.md)
+- [License](../LICENSE)
+- [Issue Tracker](https://github.com/WongKinYiu/yolov9mit/issues)
+- [Pull Requests](https://github.com/WongKinYiu/yolov9mit/pulls)
+
+## Testing and Formatting
+We strive to maintain a high standard of quality in our codebase:
+- **Testing:** We use `pytest` for testing. Please add tests for new code you create.
+- **Formatting:** Our code follows a consistent style enforced by `isort` for imports sorting and `black` for code formatting. Run these tools to format your code before submitting a pull request.
+
+## GitHub Actions
+We utilize GitHub Actions for continuous integration. When you submit a pull request, automated tests and formatting checks will run. Ensure that these checks pass for your pull request to be accepted.
+
+## How to Contribute
+
+### Proposing Enhancements
+For feature requests or improvements, open an issue with:
+- A clear title and description.
+- Explain why this enhancement would be useful.
+- Considerations or potential implementation details.
+
+## Pull Request Checklist
+Before sending your pull request, always check the following:
+- The code follows the [Python style guide](https://www.python.org/dev/peps/pep-0008/).
+- Code and files are well organized.
+- All tests pass.
+- New code is covered by tests.
+- We would be very happy if [gitmoji😆](https://www.npmjs.com/package/gitmoji-cli) could be used to assist the commit message💬!
+
+## Code Review Process
+Once you submit a PR, maintainers will review your work, suggest changes if necessary, and merge it once it’s approved.
+
+---
+
+Your contributions are greatly appreciated and vital to the project's success!
+
+Please feel free to contact [[email protected]](mailto:[email protected])!
+
+

docs/HOWTO.md

@@ -0,0 +1,90 @@
+# How To modified YOLO
+
+To facilitate easy customization of the YOLO model, we've structured the codebase to allow for changes through configuration files and minimal code adjustments. This guide will walk you through the steps to customize various components of the model including the architecture, blocks, data loaders, and loss functions.
+
+## Custom Model Architecture
+
+You can change the model architecture simply by modifying the YAML configuration file. Here's how:
+
+1. **Modify Architecture in Config:**
+   
+   Navigate to your model's configuration file (typically formate like `yolo/config/model/v9-c.yaml`).
+   - Adjust the architecture settings under the `architecture` section. Ensure that every module you reference exists in `module.py`, or refer to the next section on how to add new modules.
+
+    ```yaml
+    model:
+      foo:
+        - ADown:
+            args: {out_channels: 256}
+        - RepNCSPELAN:
+            source: -2
+            args: {out_channels: 512, part_channels: 256}
+            tags: B4
+      bar:
+        - Concat:
+            source: [-2, B4]
+    ```
+
+   `tags`: Use this to labels any module you want, and could be the module source.
+
+   `source`: Set this to the index of the module output you wish to use as input; default is `-1` which refers to the last module's output. Capable tags, relative position, absolute position
+
+   `args`: A dictionary used to initialize parameters for convolutional or bottleneck layers.
+
+   `output`: Whether to serve as the output of the model.
+
+## Custom Block
+
+To add or modify a block in the model:
+
+1. **Create a New Module:**
+
+   Define a new class in `module.py` that inherits from `nn.Module`.
+   
+   The constructor should accept `in_channels` as a parameter. Make sure to calculate `out_channels` based on your model's requirements or configure it through the YAML file using `args`.
+
+    ```python
+    class CustomBlock(nn.Module):
+        def __init__(self, in_channels, out_channels, **kwargs):
+            super().__init__()
+            self.module = # conv, bool, ...
+        def forward(self, x):
+            return self.module(x) 
+    ```
+
+2. **Reference in Config:**
+   ```yaml
+    ...
+    - CustomBlock:
+        args: {out_channels: int, etc: ...}
+        ...
+    ...
+   ```
+
+
+## Custom Data Augmentation
+
+Custom transformations should be designed to accept an image and its bounding boxes, and return them after applying the desired changes. Here’s how you can define such a transformation:
+
+
+1. **Define Dataset:**
+
+    Your class must have a `__call__` method that takes a PIL image and its corresponding bounding boxes as input, and returns them after processing.
+
+
+   ```python
+    class CustomTransform:
+        def __init__(self, prob=0.5):
+            self.prob = prob
+
+        def __call__(self, image, boxes):
+            return image, boxes
+   ```
+2. **Update CustomTransform in Config:**
+
+    Specify your custom transformation in a YAML config `yolo/config/data/augment.yaml`. For examples:
+    ```yaml
+    Mosaic: 1
+    # ... (Other Transform)
+    CustomTransform: 0.5
+    ```

docs/MODELS.md

@@ -0,0 +1,31 @@
+# YOLO Model Zoo
+
+Welcome to the YOLOv9 Model Zoo! Here, you will find a variety of pre-trained models tailored to different use cases and performance needs. Each model comes with detailed information about its training regime, performance metrics, and usage instructions.
+
+## Standard Models
+
+These models are trained on common datasets like COCO and provide a balance between speed and accuracy.
+
+
+| Model | Test Size | AP<sup>val</sup> | AP<sub>50</sub><sup>val</sup> | AP<sub>75</sub><sup>val</sup> | Param. | FLOPs |
+| :-- | :-: | :-: | :-: | :-: | :-: | :-: |
+| [**YOLOv9-T**]() | 640 | **38.3%** | **53.1%** | **41.3%** | **2.0M** | **7.7G** |
+| [**YOLOv9-S**]() | 640 | **46.8%** | **63.4%** | **50.7%** | **7.1M** | **26.4G** |
+| [**YOLOv9-M**]() | 640 | **51.4%** | **68.1%** | **56.1%** | **20.0M** | **76.3G** |
+| [**YOLOv9-C**]() | 640 | **53.0%** | **70.2%** | **57.8%** | **25.3M** | **102.1G** |
+| [**YOLOv9-E**]() | 640 | **55.6%** | **72.8%** | **60.6%** | **57.3M** | **189.0G** |
+|  |  |  |  |  |  |  |
+| [**YOLOv7**]() | 640 | **51.4%** | **69.7%** | **55.9%** |
+| [**YOLOv7-X**]() | 640 | **53.1%** | **71.2%** | **57.8%** |
+| [**YOLOv7-W6**]() | 1280 | **54.9%** | **72.6%** | **60.1%** |
+| [**YOLOv7-E6**]() | 1280 | **56.0%** | **73.5%** | **61.2%** |
+| [**YOLOv7-D6**]() | 1280 | **56.6%** | **74.0%** | **61.8%** |
+| [**YOLOv7-E6E**]() | 1280 | **56.8%** | **74.4%** | **62.1%** |
+
+## Download and Usage Instructions
+
+To use these models, download them from the links provided and use the following command to run detection:
+
+```bash
+$yolo detect weights=path/to/model.pt img=640 conf=0.25 source=your_image.jpg
+```