workshop-11-03-2025-detect-mmdetect.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "fb5f8d81",
   "metadata": {},
   "source": [
    "# Workshop: Training Object Detection Models with MMDetection\n",
    "\n",
    "In this workshop, we will learn how to train several state-of-the-art object detection models using [MMDetection](https://github.com/open-mmlab/mmdetection), a PyTorch-based detection toolbox. The models we cover include:\n",
    "\n",
    "- **YOLOv3**\n",
    "- **SSD**\n",
    "- **RetinaNet**\n",
    "- **Faster R-CNN**\n",
    "\n",
    "Before starting, please ensure that:\n",
    "\n",
    "1. You have a CUDA-enabled GPU.\n",
    "2. Your dataset (e.g. COCO) is correctly prepared and the paths in the configuration files are updated accordingly.\n",
    "3. Your Python environment meets the MMDetection requirements (compatible PyTorch, MMCV, etc.)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4fd541f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Clone the MMDetection repository (if not already cloned)\n",
    "# !git clone https://github.com/open-mmlab/mmdetection.git\n",
    "# %cd mmdetection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3d383daf",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install MMDetection and its dependencies\n",
    "# Adjust the MMCV version and CUDA/torch links as necessary for your environment\n",
    "# !pip install mmcv-full==1.7.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html\n",
    "# !pip install -e ."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "122d1bf6-8ae4-4491-8b42-857b3ec0619a",
   "metadata": {},
   "outputs": [],
   "source": [
    "! pip install -U mmcv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "961c48e2-13e6-49e3-9e92-2ce7a754daf5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# ! pip install mmengine"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc01ac40-c9bd-44a3-9549-d6b00fe3913a",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install -U mim"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4ddd7955-7f36-4d26-b150-a15b464b1a93",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install -U openmim\n",
    "!mim install mmengine\n",
    "!mim install \"mmcv>=2.0.0\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eea34ff3",
   "metadata": {},
   "source": [
    "## Environment Setup\n",
    "\n",
    "Before training, please ensure that the dataset paths and other parameters in the configuration files are correct. If you use a custom dataset, update the data section accordingly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fecc325c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mmcv\n",
    "from mmdet.apis import train_detector\n",
    "from mmdet.datasets import build_dataset\n",
    "from mmdet.models import build_detector\n",
    "\n",
    "def train_model(config_file, work_dir, resume_from=None):\n",
    "    \"\"\"\n",
    "    Train an object detection model using MMDetection.\n",
    "    \n",
    "    Parameters:\n",
    "      config_file (str): Path to the MMDetection config file.\n",
    "      work_dir (str): Directory where checkpoints and logs will be saved.\n",
    "      resume_from (str, optional): Checkpoint path to resume training.\n",
    "    \"\"\"\n",
    "    # Load configuration\n",
    "    cfg = mmcv.Config.fromfile(config_file)\n",
    "    cfg.work_dir = work_dir\n",
    "    \n",
    "    if resume_from is not None:\n",
    "        cfg.resume_from = resume_from\n",
    "        \n",
    "    # Adjust runtime parameters if needed (adjust batch size/workers according to your GPU)\n",
    "    cfg.data.samples_per_gpu = 2\n",
    "    cfg.data.workers_per_gpu = 2\n",
    "    \n",
    "    # Build the training dataset\n",
    "    datasets = [build_dataset(cfg.data.train)]\n",
    "    \n",
    "    # Build the detector model\n",
    "    model = build_detector(cfg.model, train_cfg=cfg.get('train_cfg'), test_cfg=cfg.get('test_cfg'))\n",
    "    model.init_weights()\n",
    "    \n",
    "    # Start training (set distributed=False for single-GPU training)\n",
    "    train_detector(model, datasets, cfg, distributed=False, validate=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5407157",
   "metadata": {},
   "source": [
    "## Training YOLOv3\n",
    "\n",
    "We now begin by training the YOLOv3 model. The configuration file for YOLOv3 is located in the `configs/yolov3` folder. Make sure that the dataset paths inside the config file match your setup."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31366bb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train YOLOv3 model\n",
    "train_model(\n",
    "    config_file='configs/yolov3/yolov3_d53_mstrain-608_273e_coco.py',\n",
    "    work_dir='./work_dirs/yolov3'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c723e11",
   "metadata": {},
   "source": [
    "## Training SSD\n",
    "\n",
    "Next, we train the SSD model. Its configuration file is found in the `configs/ssd` directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4038e94",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train SSD model\n",
    "train_model(\n",
    "    config_file='configs/ssd/ssd300_coco.py',\n",
    "    work_dir='./work_dirs/ssd'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f222ba94",
   "metadata": {},
   "source": [
    "## Training RetinaNet\n",
    "\n",
    "Now, we train the RetinaNet model using its configuration file from the `configs/retinanet` folder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "23590b91",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train RetinaNet model\n",
    "train_model(\n",
    "    config_file='configs/retinanet/retinanet_r50_fpn_1x_coco.py',\n",
    "    work_dir='./work_dirs/retinanet'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd635d29",
   "metadata": {},
   "source": [
    "## Training Faster R-CNN\n",
    "\n",
    "Finally, we train the Faster R-CNN model. Its configuration is located in the `configs/faster_rcnn` folder. Verify the dataset settings if you are using a custom dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "018ffc1a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train Faster R-CNN model\n",
    "train_model(\n",
    "    config_file='configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py',\n",
    "    work_dir='./work_dirs/faster_rcnn'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5323a3e",
   "metadata": {},
   "source": [
    "## Evaluation and Next Steps\n",
    "\n",
    "After training, you can evaluate your model using MMDetection's test script. For example, to evaluate the YOLOv3 model, you can run the following command (make sure to replace `<checkpoint_file>` with the actual path to your checkpoint):\n",
    "\n",
    "```bash\n",
    "python tools/test.py configs/yolov3/yolov3_d53_mstrain-608_273e_coco.py ./work_dirs/yolov3/latest.pth --out results.pkl\n",
    "```\n",
    "\n",
    "You can also visualize detection results using MMDetection's built-in visualization tools. For more information, consult the [MMDetection documentation](https://mmdetection.readthedocs.io/)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c11ea1dc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example: Evaluate a trained YOLOv3 model\n",
    "# (Uncomment and replace <checkpoint_file> with the path to your checkpoint if you wish to run evaluation.)\n",
    "# !python tools/test.py configs/yolov3/yolov3_d53_mstrain-608_273e_coco.py ./work_dirs/yolov3/latest.pth --out results.pkl"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8a8f66f",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "This notebook demonstrated how to set up your environment and train several object detection models using MMDetection. Customize the configuration files as needed for your dataset and hardware. Experiment with different models or training schedules to achieve the best performance for your task.\n",
    "\n",
    "Happy training!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5fa7216c-f074-44e8-a54f-6cd44acfa412",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}