Merge pull request #319 from JdeRobot/docs-update

Updating Docs

Author: dpascualhe

README.md

@@ -9,14 +9,15 @@
 
 *DetectionMetrics* is a toolkit designed to unify and streamline the evaluation of perception models across different frameworks and datasets. Looking for our published ***DetectionMetrics v1***? Check out all the [relevant links](#v1) below.
 
-Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the flexibility of our previous release, *DetectionMetrics* has been redesigned with an expanded focus on image and LiDAR segmentation. As we move forward, *v2* will be the actively maintained version, featuring continued updates and enhancements to keep pace with evolving AI and computer vision technologies.
+Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the flexibility of our previous release, *DetectionMetrics* has been redesigned with an expanded focus on image and LiDAR segmentation, and now includes **image object detection** capabilities. As we move forward, *v2* will be the actively maintained version, featuring continued updates and enhancements to keep pace with evolving AI and computer vision technologies.
 
 <table style='font-size:100%; margin: auto;'>
   <tr>
     <th>&#128187; <a href="https://github.com/JdeRobot/DetectionMetrics">Code</a></th>
     <th>&#128295; <a href="https://jderobot.github.io/DetectionMetrics/v2/installation">Installation</a></th>
     <th>&#129513; <a href="https://jderobot.github.io/DetectionMetrics/v2/compatibility">Compatibility</a></th>
     <th>&#128214; <a href="https://jderobot.github.io/DetectionMetrics/py_docs/_build/html/index.html">Docs</a></th>
+    <th>&#128187; <a href="https://jderobot.github.io/DetectionMetrics/v2/gui">GUI</a></th>
   </tr>
 </table>
 
@@ -45,8 +46,8 @@ Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the f
   <tr>
     <td>Object detection</td>
     <td>Image</td>
-    <td>Check <a href="https://jderobot.github.io/DetectionMetrics/v1"><i>DetectionMetrics v1</i></a></td>
-    <td>Check <a href="https://jderobot.github.io/DetectionMetrics/v1"><i>DetectionMetrics v1</i></a></td>
+    <td>COCO, custom formats</td>
+    <td>PyTorch</td>
   </tr>
 </tbody>
 </table>
@@ -94,16 +95,44 @@ Install your deep learning framework of preference in your environment. We have
 If you are using LiDAR, Open3D currently requires `torch==2.2*`.
 
 # Usage
-As of now, *DetectionMetrics* can either be used as a Python library or as a command-line application.
+DetectionMetrics can be used in three ways: through the **interactive GUI** (detection only), as a **Python library**, or via the **command-line interface** (segmentation and detection).
 
-### Library
+## Interactive GUI
+The easiest way to get started with DetectionMetrics is through the GUI (detection tasks only):
+
+```bash
+# From the project root directory
+streamlit run app.py
+```
+
+The GUI provides:
+- **Dataset Viewer**: Browse and visualize your datasets
+- **Inference**: Run real-time inference on images
+- **Evaluator**: Perform comprehensive model evaluation
+
+For detailed GUI documentation, see our [GUI guide](https://jderobot.github.io/DetectionMetrics/v2/gui).
+
+## Library
 
 🧑‍🏫️ [Image Segmentation Tutorial](https://github.com/JdeRobot/DetectionMetrics/blob/master/examples/tutorial_image_segmentation.ipynb)
 
+🧑‍🏫️ [Image Detection Tutorial](https://github.com/JdeRobot/DetectionMetrics/blob/master/examples/tutorial_image_detection.ipynb)
+
 You can check the `examples` directory for further inspiration. If you are using *poetry*, you can run the scripts provided either by activating the created environment using `poetry shell` or directly running `poetry run python examples/<some_python_script.py>`.
 
-### Command-line interface
-DetectionMetrics currently provides a CLI with two commands, `dm_evaluate` and `dm_batch`. Thanks to the configuration in the `pyproject.toml` file, we can simply run `poetry install` from the root directory and use them without explicitly invoking the Python files. More details are provided in [DetectionMetrics website](https://jderobot.github.io/DetectionMetrics/v2/usage/#command-line-interface).
+## Command-line interface
+DetectionMetrics provides a CLI with two commands, `dm_evaluate` and `dm_batch`. Thanks to the configuration in the `pyproject.toml` file, we can simply run `poetry install` from the root directory and use them without explicitly invoking the Python files. More details are provided in [DetectionMetrics website](https://jderobot.github.io/DetectionMetrics/v2/usage/#command-line-interface).
+
+### Example Usage
+**Segmentation:**
+```bash
+dm_evaluate segmentation image --model_format torch --model /path/to/model.pt --model_ontology /path/to/ontology.json --model_cfg /path/to/cfg.json --dataset_format rellis3d --dataset_dir /path/to/dataset --dataset_ontology /path/to/ontology.json --out_fname /path/to/results.csv
+```
+
+**Detection:**
+```bash
+dm_evaluate detection image --model_format torch --model /path/to/model.pt --model_ontology /path/to/ontology.json --model_cfg /path/to/cfg.json --dataset_format coco --dataset_dir /path/to/coco/dataset --out_fname /path/to/results.csv
+```
 
 <h1 id="v1">DetectionMetrics v1</h1>
 

detectionmetrics/cli/__init__.py

@@ -83,6 +83,10 @@ def get_dataset(
         if labels_dir is None:
             raise ValueError("--labels_dir is required for 'rugd' format")
 
+    elif dataset_format == "coco":
+        if dataset_dir is None:
+            raise ValueError("--dataset_dir is required for 'coco' format")
+
     else:
         raise ValueError(f"Dataset format not supported: {dataset_format}")
 
@@ -116,6 +120,19 @@ def get_dataset(
             "labels_dir": labels_dir,
             "ontology_fname": ontology,
         }
+    elif dataset_format == "coco":
+        # For COCO, we need to construct the annotation file path and image directory
+        # Assuming standard COCO structure: dataset_dir/annotations/instances_split.json and dataset_dir/images/split/
+        if len(split) > 1:
+            raise ValueError("COCO format currently supports only one split at a time")
+        split_name = split[0]
+        annotation_file = f"{dataset_dir}/annotations/instances_{split_name}2017.json"
+        image_dir = f"{dataset_dir}/images/{split_name}2017"
+        dataset_args = {
+            "annotation_file": annotation_file,
+            "image_dir": image_dir,
+            "split": split_name,
+        }
     else:
         raise ValueError(f"Dataset format not supported: {dataset_format}")
 

detectionmetrics/cli/evaluate.py

@@ -17,7 +17,7 @@ def parse_split(ctx, param, value):
 
 
 @click.command(name="evaluate", help="Evaluate model on dataset")
-@click.argument("task", type=click.Choice(["segmentation"], case_sensitive=False))
+@click.argument("task", type=click.Choice(["segmentation", "detection"], case_sensitive=False))
 @click.argument(
     "input_type", type=click.Choice(["image", "lidar"], case_sensitive=False)
 )
@@ -53,7 +53,7 @@ def parse_split(ctx, param, value):
 @click.option(
     "--dataset_format",
     type=click.Choice(
-        ["gaia", "rellis3d", "goose", "generic", "rugd"], case_sensitive=False
+        ["gaia", "rellis3d", "goose", "generic", "rugd", "coco"], case_sensitive=False
     ),
     show_default=True,
     default="gaia",
@@ -67,7 +67,7 @@ def parse_split(ctx, param, value):
 @click.option(
     "--dataset_dir",
     type=click.Path(exists=True, file_okay=False, dir_okay=True),
-    help="Dataset directory (used for 'Rellis3D' and 'Wildscenes' formats)",
+    help="Dataset directory (used for 'Rellis3D', 'Wildscenes', and 'COCO' formats)",
 )
 @click.option(
     "--split_dir",

detectionmetrics/models/__init__.py

@@ -11,6 +11,13 @@
 except ImportError:
     print("Torch not available")
 
+try:
+    from detectionmetrics.models.torch_detection import TorchImageDetectionModel
+
+    REGISTRY["torch_image_detection"] = TorchImageDetectionModel
+except ImportError:
+    print("Torch detection not available")
+
 try:
     from detectionmetrics.models.tensorflow import TensorflowImageSegmentationModel
 

docs/_config.yml

@@ -277,6 +277,9 @@ compress_html:
 
 # Collections
 collections:
+  pages:
+    output: true
+    permalink: /:path/
   portfolio:
     output: true
     permalink: /:collection/:path/

docs/_data/navigation.yml

@@ -67,12 +67,16 @@ main_v2:
       url: /v2/compatibility/#image-semantic-segmentation
     - title: "LiDAR semantic segmentation"
       url: /v2/compatibility/#lidar-semantic-segmentation
-    - title: "Object detection"
-      url: /v2/compatibility/#object-detection
+    - title: "Image object detection"
+      url: /v2/compatibility/#image-object-detection
   - title: Usage
     url: /v2/usage
     children:
+      - title: "Interactive GUI"
+        url: /v2/usage/#interactive-gui
       - title: "Library"
         url: /v2/usage/#library
       - title: "Command-line interface"
-        url: /v2/usage/#command-line-interface
+        url: /v2/usage/#command-line-interface
+  - title: GUI
+    url: /v2/gui

docs/_pages/home.md

@@ -15,14 +15,15 @@ excerpt:
 # What is DetectionMetrics?
 *DetectionMetrics* is a toolkit designed to unify and streamline the evaluation of perception models across different frameworks and datasets. Looking for our published ***DetectionMetrics v1***? Check out all the [relevant links](#v1) below.
 
-Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the flexibility of our previous release, *DetectionMetrics* has been redesigned with an expanded focus expanded focus on image and LiDAR segmentation. As we move forward, *v2* will be the actively maintained version, featuring continued updates and enhancements to keep pace with evolving AI and computer vision technologies.
+Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the flexibility of our previous release, *DetectionMetrics* has been redesigned with an expanded focus on image and LiDAR segmentation, and now includes **image object detection** capabilities with an interactive GUI. As we move forward, *v2* will be the actively maintained version, featuring continued updates and enhancements to keep pace with evolving AI and computer vision technologies.
 
 <table class='centered-table'>
     <tr>
         <th>&#128187; <a href="https://github.com/JdeRobot/DetectionMetrics">Code</a></th>
-        <th>&#128295; <a href="https://jderobot.github.io/DetectionMetrics/v2/installation">Installation</a></th>
-        <th>&#129513; <a href="https://jderobot.github.io/DetectionMetrics/v2/compatibility">Compatibility</a></th>
-        <th>&#128214; <a href="https://jderobot.github.io/DetectionMetrics/py_docs/_build/html/index.html">Docs</a></th>
+        <th>&#128295; <a href="/v2/installation/">Installation</a></th>
+        <th>&#129513; <a href="/v2/compatibility/">Compatibility</a></th>
+        <th>&#128214; <a href="/py_docs/_build/html/index.html">Docs</a></th>
+        <th>&#128421; <a href="/v2/gui/">GUI</a></th>
     </tr>
 </table>
 
@@ -53,8 +54,8 @@ Now, we're excited to introduce ***DetectionMetrics v2***! While retaining the f
   <tr>
     <td>Object detection</td>
     <td>Image</td>
-    <td>Check <a href="https://jderobot.github.io/DetectionMetrics/v1"><i>DetectionMetrics v1</i></a></td>
-    <td>Check <a href="https://jderobot.github.io/DetectionMetrics/v1"><i>DetectionMetrics v1</i></a></td>
+    <td>COCO</td>
+    <td>PyTorch</td>
   </tr>
 </tbody>
 </table>

docs/_pages/v2/compatibility.md

@@ -91,5 +91,41 @@ sidebar:
 - Computational cost:
     - Number of parameters, average inference time, model size
 
-## Object detection
-Coming soon.
+## Image object detection
+- Datasets:
+    - **[COCO](https://cocodataset.org/)**: Standard COCO format with JSON annotations and image directory structure
+- Models:
+    - **PyTorch ([TorchScript](https://pytorch.org/docs/stable/jit.html) compiled format and native modules)**:
+        - Input shape: `(batch, channels, height, width)`
+        - Output shape: `(batch, num_detections, 6)` where each detection contains `[x1, y1, x2, y2, confidence, class_id]`
+        - JSON configuration file format:
+
+        ```json
+        {
+            "normalization": {
+                "mean": [<r>, <g>, <b>],
+                "std": [<r>, <g>, <b>]
+            },
+            "resize": {  # optional
+                "width": <px>,
+                "height": <px>
+            },
+            "confidence_threshold": <float>,
+            "nms_threshold": <float>,
+            "max_detections_per_image": <int>,
+            "batch_size": <n>,
+            "device": "<cpu|cuda|mps>",
+            "evaluation_step": <int>  # for live progress updates during evaluation
+        }
+        ```
+- Metrics:
+    - Mean Average Precision (mAP), including COCO-style mAP@[0.5:0.95:0.05]
+    - Area Under the Precision-Recall Curve (AUC-PR)
+    - Precision, Recall, F1-Score
+    - Per-class metrics and confusion matrices
+- Computational cost:
+    - Number of parameters, average inference time, model size
+- GUI Support:
+    - Real-time inference visualization
+    - Interactive dataset browsing
+    - Progress tracking during evaluation