feat: Mise à jour du README pour inclure la détection de ballon, les modèles requis et les instructions d'utilisation pour l'application Gradio.

README.md

@@ -13,20 +13,23 @@ pinned: false
 
 This project uses the TvCalib library to calculate the homography matrix for a football pitch image. This matrix allows mapping image points onto a standard 2D representation of the pitch (minimap).
 
-The project also includes a pose estimation step (ViTPose) to detect players and calculate the average color of their torso.
+The project also includes:
+*   **Ball detection** using a YOLO model (`yolo_football.pt`).
+*   **Pose estimation** (ViTPose) to detect players and calculate the average color of their torso.
 
-**The main result is a minimap where each player is represented by their colored skeleton, drawn at a *dynamically* reduced scale around their projected position on the pitch.**
-The position is determined by projecting a reference point (feet/bottom of bbox) using the homography. The skeleton is then drawn using its relative coordinates (original image), scaled, and translated. The scale used depends on the **player's vertical position (Y) on the minimap** (higher on the minimap = smaller) and a base factor adjustable via the `--target_avg_scale` option.
+**The main result is a minimap where each player is represented by their colored skeleton, drawn at a *dynamically* reduced scale around their projected position on the pitch, and the ball is represented by a white circle.**
+The position is determined by projecting a reference point (feet/bottom of bbox for players, bottom center for ball) using the homography. The skeleton is then drawn using its relative coordinates (original image), scaled, and translated. The scale used depends on the **player's vertical position (Y) on the minimap** (higher on the minimap = smaller) and a base factor adjustable via the `--target_avg_scale` option.
 
 It is also possible to visualize a minimap with the projection of the original image for comparison.
 
 ## Features
 
 *   Homography calculation from a single image via TvCalib.
+*   Ball detection using YOLO (`yolo_football.pt`).
 *   Person detection (RT-DETR) and pose estimation (ViTPose).
 *   Calculation of the filtered average torso color for each player.
-*   Projection of each player's reference point (feet/bbox) onto the minimap.
-*   Generation of a minimap with the **original skeletons (colored, dynamically scaled based on projected Y position, and offset) drawn around the projected point**.
+*   Projection of each player's and the ball's reference point onto the minimap.
+*   Generation of a minimap with the **original skeletons (colored, dynamically scaled based on projected Y position, and offset) drawn around the projected player points, and a white marker for the projected ball position**.
 *   (Optional) Generation of a minimap with the projected original image.
 *   Possibility to save the calculated homography matrix.
 
@@ -39,13 +42,16 @@ It is also possible to visualize a minimap with the projection of the original i
 ├── common/             # Common Python modules (potentially)
 ├── data/               # Data (input images, etc.)
 ├── models/
+│   ├── detection/
+│   │   └── yolo_football.pt # YOLO model for ball detection (TO DOWNLOAD)
 │   └── segmentation/
 │       └── train_59.pt # Pre-trained segmentation model (TO DOWNLOAD)
 ├── tvcalib/            # Source code of the TvCalib library (or a fork/adaptation)
 │   └── infer/
 │       └── module.py   # Main module for TvCalib inference
 ├── .gitignore          # Files ignored by Git
-├── main.py             # Main script entry point
+├── app.py              # Gradio web application entry point
+├── main.py             # Main script entry point (command line)
 ├── requirements.txt    # Python dependencies file
 ├── visualizer.py       # Module for generating visualization minimaps
 ├── pose_estimator.py   # Module for pose estimation and player data extraction
@@ -70,50 +76,65 @@ It is also possible to visualize a minimap with the projection of the original i
     ```powershell
     pip install -r requirements.txt
     ```
-    *(Make sure to install PyTorch with appropriate CUDA support if needed.)*
+    *(Make sure to install PyTorch with appropriate CUDA support if needed, see comment in `requirements.txt`)*
 
-4.  **Download the segmentation model:**
-    Place `train_59.pt` in `models/segmentation/`.
+4.  **Download the required models:**
+    *   Place the segmentation model `train_59.pt` in `models/segmentation/`.
+    *   Place the YOLO ball detection model `yolo_football.pt` in `models/detection/`. (You need to obtain this model separately).
 
-5.  **(Automatic) Download detection/pose models:**
-    The RT-DETR and ViTPose models will be downloaded automatically.
+5.  **(Automatic) Download other detection/pose models:**
+    The RT-DETR and ViTPose models will be downloaded automatically by the `transformers` library on first use.
 
 ## Usage
 
-Run the `main.py` script providing the path to the image:
+Run the `main.py` script (command line) or `app.py` (Gradio interface) providing the path to the image:
 
+**Command Line:**
 ```powershell
 python main.py path/to/your/image.jpg [OPTIONS]
 ```
 
-**Options:**
+**Gradio App:**
+```powershell
+python app.py 
+# Then open the provided local URL in your browser.
+```
+
+**Options (for `main.py`):**
 
 *   `image_path`: Path to the input image (required).
 *   `--output_homography PATH.npy`: Saves the calculated homography matrix.
-*   `--optim_steps NUMBER`: Number of optimization steps for calibration (default: 500, was 1000 in original README example).
-*   `--target_avg_scale FLOAT`: **Target average** scale factor for drawing skeletons (default: 0.35). The script attempts to adjust the internal base scale so that the resulting average scale (after inverse dynamic modulation) is close to this value.
+*   `--optim_steps NUMBER`: Number of optimization steps for calibration (default: 500).
+*   `--target_avg_scale FLOAT`: **Target average** scale factor for drawing skeletons (default: 1.0). The script attempts to adjust the internal base scale so that the resulting average scale (after inverse dynamic modulation) is close to this value.
 
 **Example:**
 
 ```powershell
-# Simple usage (target average size 0.35)
+# Simple usage (target average size 1.0)
 python main.py data/img3.png
 
-# Aim for larger skeletons on average (target 0.5)
-python main.py data/img2.png --target_avg_scale 0.5
+# Aim for larger skeletons on average (target 1.5)
+python main.py data/img2.png --target_avg_scale 1.5 
 ```
 
-The script will display:
-*   Time taken and homography matrix.
-*   Estimated internal base scale.
-*   Requested TARGET average scale.
-*   ACTUALLY applied FINAL average scale.
-*   Window: **Minimap with Original Projection**.
-*   Window: **Minimap with Offset Skeletons** (dynamically scaled inversely, targeting the average scale).
-*   Press any key to close.
+The script (`main.py`) or Gradio app (`app.py`) will display:
+*   Time taken for different steps (console output for `main.py`).
+*   Calculated homography matrix (console output for `main.py`).
+*   Information about detected ball and players (console output for `main.py`).
+*   Estimated internal base scale for skeletons (console output for `main.py`).
+*   Requested TARGET average scale (console output for `main.py`).
+*   ACTUALLY applied FINAL average scale (console output for `main.py`).
+*   Window/Image Output 1: **Minimap with Original Projection**.
+*   Window/Image Output 2: **Minimap with Offset Skeletons** (dynamically scaled inversely, targeting the average scale) **and Ball Marker**.
+*   (`main.py` only) Press any key to close the display windows.
 
 ## Key Dependencies
 
 *   PyTorch, OpenCV, NumPy, PyTorch Lightning
-*   SoccerNet, Kornia, Hugging Face Transformers, Pillow 
+*   SoccerNet, Kornia, Hugging Face Transformers, Pillow
+*   `ultralytics` (for YOLO ball detection)
+*   `gradio` (for the web interface `app.py`)
+
+--- 
+Note: Ensure the `tvcalib` directory is correctly structured or added to your PYTHONPATH if you encounter import errors related to it.