📝 [Update] tutorial, split cfg, data, model, task

docs/1_tutorials/0_allIn1.rst

@@ -0,0 +1,204 @@
+All In 1
+========
+
+:file:`yolo.lazy` is a packaged file that includes :guilabel:`training`, :guilabel:`validation`, and :guilabel:`inference` tasks.
+For detailed function documentation, thercheck out the IPython notebooks to learn how to import and use these function
+the following section will break down operation inside of lazy, also supporting directly import/call the function.
+
+[TOC], setup, build, dataset, train, validation, inference
+To train the model, you can run:
+
+Train Model
+----------
+
+
+- batch size check / cuda
+- training time / check
+- build model / check
+- dataset / check
+
+.. code-block:: bash
+
+    python yolo/lazy.py task=train
+
+You can customize the training process by overriding the following common arguments:
+
+- ``name``: :guilabel:`str`
+  The experiment name.
+
+- ``model``: :guilabel:`str`
+  Model backbone, options include [model_zoo] v9-c, v7, v9-e, etc.
+
+- ``cpu_num``: :guilabel:`int`
+  Number of CPU workers (num_workers).
+
+- ``out_path``: :guilabel:`Path`
+  The output path for saving models and logs.
+
+- ``weight``: :guilabel:`Path | bool | None`
+  The path to pre-trained weights, False for training from scratch, None for default weights.
+
+- ``use_wandb``: :guilabel:`bool`
+  Whether to use Weights and Biases for experiment tracking.
+
+- ``use_TensorBoard``: :guilabel:`bool`
+  Whether to use TensorBoard for logging.
+
+- ``image_size``: :guilabel:`int | [int, int]`
+  The input image size.
+
+- ``+quiet``: :guilabel:`bool`
+  Optional, disable all output.
+
+- ``task.epoch``: :guilabel:`int`
+  Total number of training epochs.
+
+- ``task.data.batch_size``: :guilabel:`int`
+  The size of each batch (auto-batch sizing [WIP]).
+
+Examples
+~~~~~~~~
+
+To train a model with a specific batch size and image size, you can run:
+
+.. code-block:: bash
+
+    python yolo/lazy.py task=train task.data.batch_size=12 image_size=1280
+
+Multi-GPU Training with DDP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For multi-GPU training, we use Distributed Data Parallel (DDP) for efficient and scalable training.
+DDP enable training model with mutliple GPU, even the GPUs aren't on the same machine. For more details, you can refer to the `DDP tutorial <https://pytorch.org/tutorials/intermediate/ddp_tutorial.html>`_.
+
+To train on multiple GPUs, replace the ``python`` command with ``torchrun --nproc_per_node=[GPU_NUM]``. The ``nproc_per_node`` argument specifies the number of GPUs to use.
+
+
+.. tabs::
+
+   .. tab:: bash
+    .. code-block:: bash
+
+        torchrun --nproc_per_node=2 yolo/lazy.py task=train device=[0,1]
+
+   .. tab:: zsh
+    .. code-block:: bash
+
+        torchrun --nproc_per_node=2 yolo/lazy.py task=train device=\[0,1\]
+
+
+Training on a Custom Dataset
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use the auto-download module, we suggest users construct the dataset config in the following format.
+If the config files include `auto_download`, the model will automatically download the dataset when creating the dataloader.
+
+Here is an example dataset config file:
+
+.. literalinclude:: ../../yolo/config/dataset/dev.yaml
+  :language: YAML
+
+Both of the following formats are acceptable:
+
+- ``path``: :guilabel:`str`
+  The path to the dataset.
+
+- ``train, validation``: :guilabel:`str`
+  The training and validation directory names under `/images`. If using txt as ground truth, these should also be the names under `/labels/`.
+
+- ``class_num``: :guilabel:`int`
+  The number of dataset classes.
+
+- ``class_list``: :guilabel:`List[str]`
+  Optional, the list of class names, used only for visualizing the bounding box classes.
+
+- ``auto_download``: :guilabel:`dict`
+  Optional, whether to auto-download the dataset.
+
+The dataset should include labels or annotations, preferably in JSON format for compatibility with pycocotools during inference:
+
+.. code-block:: text
+
+    DataSetName/
+    ├── annotations
+    │   ├── train_json_name.json
+    │   └── val_json_name.json
+    ├── labels/
+    │   ├── train/
+    │   │   ├── AnyLabelName.txt
+    │   │   └── ...
+    │   └── validation/
+    │       └── ...
+    └── images/
+        ├── train/
+        │   ├── AnyImageNameN.{png,jpg,jpeg}
+        │   └── ...
+        └── validation/
+            └── ...
+
+
+Validation Model
+----------------
+
+During training, this block will be auto-executed. You may also run this task manually to generate a JSON file representing the predictions for a given validation dataset. If the validation set includes JSON annotations, it will run pycocotools for evaluation.
+
+We recommend setting ``task.data.shuffle`` to False and turning off ``task.data.data_augment``.
+
+You can customize the validation process by overriding the following arguments:
+
+- ``task.nms.min_confidence``: :guilabel:`str`
+  The minimum confidence of model prediction.
+
+- ``task.nms.min_iou``: :guilabel:`str`
+  The minimum IoU threshold for NMS (Non-Maximum Suppression).
+
+Examples
+~~~~~~~~
+
+.. tabs::
+
+   .. tab:: git-cloned
+      .. code-block:: bash
+
+         python yolo/lazy.py task=validation task.nms.min_iou=0.9
+
+   .. tab:: PyPI
+      .. code-block:: bash
+
+         yolo task=validation task.nms.min_iou=0.9
+
+
+Model Inference
+---------------
+
+.. note::
+   The ``dataset`` parameter shouldn't be overridden because the model requires the ``class_num`` of the dataset. If the classes have names, please provide the ``class_list``.
+
+You can customize the inference process by overriding the following arguments:
+
+- ``task.fast_inference``: :guilabel:`str`
+  Optional. Values can be `onnx`, `trt`, `deploy`, or `None`. `deploy` will detach the model auxiliary head.
+
+- ``task.data.source``: :guilabel:`str | Path | int`
+  This argument will be auto-resolved and could be a webcam ID, image folder path, video/image path.
+
+- ``task.nms.min_confidence``: :guilabel:`str`
+  The minimum confidence of model prediction.
+
+- ``task.nms.min_iou``: :guilabel:`str`
+  The minimum IoU threshold for NMS (Non-Maximum Suppression).
+
+Examples
+~~~~~~~~
+
+.. tabs::
+
+   .. tab:: git-cloned
+      .. code-block:: bash
+
+         python yolo/lazy.py model=v9-m task.nms.min_confidence=0.1 task.data.source=0 task.fast_inference=onnx
+
+   .. tab:: PyPI
+      .. code-block:: bash
+
+         yolo model=v9-m task.nms.min_confidence=0.1 task.data.source=0 task.fast_inference=onnx

docs/1_tutorials/0_train.rst

@@ -1,10 +0,0 @@
-.. _Train:
-
-Train
-=====
-
-Train on COCO2017
------------------
-
-Train on Cusom Dataset
------------------

docs/1_tutorials/1_setup.rst

@@ -0,0 +1,35 @@
+Setup Config
+============
+
+To set up your configuration, you will need to generate a configuration class based on :class:`~yolo.config.config.Config`, which can be achieved using `hydra <https://hydra.cc/>`_.
+The configuration will include all the necessary settings for your ``task``, including general configuration, ``dataset`` information, and task-specific information (``train``, ``inference``, ``validation``).
+
+Next, create the progress logger to handle the output and progress bar. This class is based on `rich <https://github.com/Textualize/rich>`_'s progress bar and customizes the logger (print function) using `loguru <https://loguru.readthedocs.io/>`_.
+
+.. tabs::
+
+   .. tab:: decorator
+      .. code-block:: python
+
+         import hydra
+         from yolo import ProgressLogger
+         from yolo.config.config import Config
+
+         @hydra.main(config_path="config", config_name="config", version_base=None)
+         def main(cfg: Config):
+             progress = ProgressLogger(cfg, exp_name=cfg.name)
+             pass
+
+   .. tab:: initialize & compose
+      .. code-block:: python
+
+         from hydra import compose, initialize
+         from yolo import ProgressLogger
+         from yolo.config.config import Config
+
+         with initialize(config_path="config", version_base=None):
+             cfg = compose(config_name="config", overrides=["task=train", "model=v9-c"])
+
+         progress = ProgressLogger(cfg, exp_name=cfg.name)
+
+TODO: add a config over view

docs/1_tutorials/1_validation.rst

@@ -1,9 +0,0 @@
-Validation
-==========
-
-
-Validation on COCO2017
-----------------------
-
-Validation on Custom Dataset
-----------------------------

docs/1_tutorials/2_buildmodel.rst

@@ -0,0 +1,62 @@
+Build Model
+===========
+
+In YOLOv7, the prediction will be ``Anchor``, and in YOLOv9, it will predict ``Vector``. The converter will turn the bounding box to the vector.
+
+The overall model flowchart is as follows:
+
+.. mermaid::
+
+    flowchart LR
+    Input-->Model;
+    Model--Class-->NMS;
+    Model--Anc/Vec-->Converter;
+    Converter--Box-->NMS;
+    NMS-->Output;
+
+Load Model
+~~~~~~~~~~
+
+Using `create_model`, it will automatically create the :class:`~yolo.model.yolo.YOLO` model and load the provided weights.
+
+Arguments:
+
+- **model**: :class:`~yolo.config.config.ModelConfig`
+  The model configuration.
+- **class_num**: :guilabel:`int`
+  The number of classes in the dataset, used for the YOLO's prediction head.
+- **weight_path**: :guilabel:`Path | bool`
+  The path to the model weights.
+    - If `False`, weights are not loaded.
+    - If :guilabel:`True | None`, default weights are loaded.
+    - If a `Path`, the model weights are loaded from the specified path.
+
+.. code-block:: python
+
+    model = create_model(cfg.model, class_num=cfg.dataset.class_num, weight_path=cfg.weight)
+    model = model.to(device)
+
+Deploy Model
+~~~~~~~~~~~~
+
+In the deployment version, we will remove the auxiliary branch of the model for fast inference. If the config includes ONNX and TensorRT, it will load/compile the model to ONNX or TensorRT format after removing the auxiliary branch.
+
+.. code-block:: python
+
+    model = FastModelLoader(cfg).load_model(device)
+
+Autoload Converter
+~~~~~~~~~~~~~~~~~~
+
+Autoload the converter based on the model type (v7 or v9).
+
+Arguments:
+
+- **Model Name**: :guilabel:`str`
+  Used for choosing ``Vec2Box`` or ``Anc2Box``.
+- **Anchor Config**: The anchor configuration, used to generate the anchor grid.
+- **model**, **image_size**: Used for auto-detecting the anchor grid.
+
+.. code-block:: python
+
+    converter = create_converter(cfg.model.name, model, cfg.model.anchor, cfg.image_size, device)

docs/1_tutorials/2_inference.rst

@@ -1,9 +0,0 @@
-Inference
-==========
-
-
-Inference Video
----------------
-
-Inference Image
----------------

docs/1_tutorials/3_dataset.rst

@@ -0,0 +1,77 @@
+Create Dataset
+==============
+
+In this section, we will prepare the dataset and create a dataloader.
+
+Overall, the dataloader can be created by:
+
+.. code-block:: python
+
+   from yolo import create_dataloader
+   dataloader = create_dataloader(cfg.task.data, cfg.dataset, cfg.task.task, use_ddp)
+
+For inference, the dataset will be handled by :class:`~yolo.tools.data_loader.StreamDataLoader`, while for training and validation, it will be handled by :class:`~yolo.tools.data_loader.YoloDataLoader`.
+
+The input arguments are:
+
+- **DataConfig**: :class:`~yolo.config.config.DataConfig`, the relevant configuration for the dataloader.
+- **DatasetConfig**: :class:`~yolo.config.config.DatasetConfig`, the relevant configuration for the dataset.
+- **task_name**: :guilabel:`str`, the task name, which can be `inference`, `validation`, or `train`.
+- **use_ddp**: :guilabel:`bool`, whether to use DDP (Distributed Data Parallel). Default is `False`.
+
+Train and Validation
+----------------------------
+
+Dataloader Return Type
+~~~~~~~~~~~~~~~~~~~~~
+
+For each iteration, the return type includes:
+
+- **batch_size**: the size of each batch, used to calculate batch average loss.
+- **images**: the input images.
+- **targets**: the ground truth of the images according to the task.
+
+Auto Download Dataset
+~~~~~~~~~~~~~~~~~~~~~
+
+The dataset will be auto-downloaded if the user provides the `auto_download` configuration. For example, if the configuration is as follows:
+
+
+.. literalinclude:: ../../yolo/config/dataset/mock.yaml
+  :language: YAML
+
+
+First, it will download and unzip the dataset from `{prefix}/{postfix}`, and verify that the dataset has `{file_num}` files.
+
+Once the dataset is verified, it will generate `{train, validation}.cache` in Tensor format, which accelerates the dataset preparation speed.
+
+Inference
+-----------------
+
+In streaming mode, the model will infer the most recent frame and draw the bounding boxes by default, given the save flag to save the image. In other modes, it will save the predictions to `runs/inference/{exp_name}/outputs/` by default.
+
+Dataloader Return Type
+~~~~~~~~~~~~~~~~~~~~~
+
+For each iteration, the return type of `StreamDataLoader` includes:
+
+- **images**: tensor, the size of each batch, used to calculate batch average loss.
+- **rev_tensor**: tensor, reverse tensor for reverting the bounding boxes and images to the input shape.
+- **origin_frame**: tensor, the original input image.
+
+Input Type
+~~~~~~~~~~
+
+- **Stream Input**:
+
+  - **webcam**: :guilabel:`int`, ID of the webcam, for example, 0, 1.
+  - **rtmp**: :guilabel:`str`, RTMP address.
+
+- **Single Source**:
+
+  - **image**: :guilabel:`Path`, path to image files (`jpeg`, `jpg`, `png`, `tiff`).
+  - **video**: :guilabel:`Path`, path to video files (`mp4`).
+
+- **Folder**:
+
+  - **folder of images**: :guilabel:`Path`, the relative or absolute path to the folder containing images.

docs/1_tutorials/4_train.rst

@@ -0,0 +1,55 @@
+Train & Validation
+==================
+
+Training Model
+----------------
+
+To train a model, the :class:`~yolo.tools.solver.ModelTrainer` can help manage the training process. Initialize the :class:`~yolo.tools.solver.ModelTrainer` and use the :func:`~yolo.tools.solver.ModelTrainer.solve` function to start the training.
+
+Before starting the training, don't forget to start the progress logger to enable logging the process status. This will also enable `Weights & Biases (wandb) <https://wandb.ai/site>`_ or TensorBoard if configured.
+
+.. code-block:: python
+
+  from yolo import ModelTrainer
+  solver = ModelTrainer(cfg, model, converter, progress, device, use_ddp)
+  progress.start()
+  solver.solve(dataloader)
+
+Training Diagram
+~~~~~~~~~~~~~~~~
+
+The following diagram illustrates the training process:
+
+.. mermaid::
+
+  flowchart LR
+    subgraph TS["trainer.solve"]
+      subgraph TE["train one epoch"]
+        subgraph "train one batch"
+          backpropagation-->TF[forward]
+          TF-->backpropagation
+        end
+      end
+      subgraph validator.solve
+          VC["calculate mAP"]-->VF[forward]
+          VF[forward]-->VC
+      end
+    end
+    TE-->validator.solve
+    validator.solve-->TE
+
+Validation Model
+----------------
+
+To validate the model performance, we follow a similar approach as the training process using :class:`~yolo.tools.solver.ModelValidator`.
+
+.. code-block:: python
+
+   from yolo import ModelValidator
+   solver = ModelValidator(cfg, model, converter, progress, device, use_ddp)
+   progress.start()
+   solver.solve(dataloader)
+
+The :class:`~yolo.tools.solver.ModelValidator` class helps manage the validation process, ensuring that the model's performance is evaluated accurately.
+
+.. note:: The original training process already includes the validation phase. Call this separately if you want to run the validation again after the training is completed.

docs/1_tutorials/5_inference.rst

@@ -0,0 +1,20 @@
+Inference
+==========
+
+
+Inference Video
+---------------
+
+Inference Image
+---------------
+task: inference
+
+fast_inference:  # onnx, trt, deploy or Empty
+data:
+    source: demo/images/inference/image.png
+    image_size: ${image_size}
+    data_augment: {}
+nms:
+  min_confidence: 0.5
+  min_iou: 0.5
+# save_predict: True

docs/conf.py

@@ -20,6 +20,7 @@ sys.path.insert(0, os.path.abspath(".."))
 
 extensions = [
     "sphinx_rtd_theme",
+    "sphinx_tabs.tabs",
     "sphinxcontrib.mermaid",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
@@ -35,7 +36,9 @@ myst_enable_extensions = [
     "deflist",
 ]
 html_theme = "sphinx_rtd_theme"
-
+html_theme_options = {
+    "sticky_navigation": False,
+}
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/index.rst

@@ -33,9 +33,12 @@ Explore our documentation:
    :maxdepth: 1
    :caption: Tutorials
 
-   1_tutorials/0_train
-   1_tutorials/1_validation
-   1_tutorials/2_inference
+   1_tutorials/0_allIn1
+   1_tutorials/1_setup
+   1_tutorials/2_buildmodel
+   1_tutorials/3_dataset
+   1_tutorials/4_train
+   1_tutorials/5_inference
 
 
 .. toctree::