Dev (#21)

Co-authored-by: TomDarmon <tom.darmon@artefact.com>
Co-authored-by: Tristan Pepin <122389133+tristanpepinartefact@users.noreply.github.com>
Co-authored-by: github-actions <github-actions@github.com>

.github/workflows/ci.yaml

@@ -29,7 +29,10 @@ jobs:
 
       - name: Install requirements
         run: |
-          poetry install
+          make install
 
       - name: Run Pre commit hooks
         run: make format-code
+
+      - name: Test with pytest
+        run: make run-tests

.github/workflows/deploy_docs.yaml

@@ -15,10 +15,12 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: "3.10"
-
+      - name: Install poetry
+        run: |
+          make download-poetry
       - name: Install requirements
         run: |
-          make install_project_requirements
+          make install
       - name: Deploying MkDocs documentation
         run: |
           mkdocs build

.gitignore

@@ -141,6 +141,7 @@ secrets/*
 # Data ignore everythin data/detections and data/frames
 data/detections/*
 data/frames/*
-
+*.mp4
+*.txt
 # poetry
 poetry.lock

.pre-commit-config.yaml

@@ -31,12 +31,4 @@ repos:
         types: [file]
         files: (.ipynb)$
         language: system
-      - id: pytest-check
-        name: Tests (pytest)
-        stages: [push]
-        entry: pytest tests/
-        types: [python]
-        language: system
-        pass_filenames: false
-        always_run: true
 exclude: ^(.svn|CVS|.bzr|.hg|.git|__pycache__|.tox|.ipynb_checkpoints|assets|tests/assets/|venv/|.venv/)

Makefile

@@ -1,10 +1,4 @@
-PYTHON_VERSION = 3.10
-USE_CONDA ?= 1
-INSTALL_SCRIPT = install_with_conda.sh
-ifeq (false,$(USE_CONDA))
-	INSTALL_SCRIPT = install_with_venv.sh
-endif
-
+PYTHON_VERSION = 3.10.13
 # help: help					- Display this makefile's help information
 .PHONY: help
 help:
@@ -17,6 +11,7 @@ download-poetry:
 # help: install					- Install python dependencies using poetry
 .PHONY: install
 install:
+	@poetry config virtualenvs.create true
 	@poetry env use $(PYTHON_VERSION)
 	@poetry lock -n
 	@poetry install -n
@@ -27,12 +22,6 @@ install:
 install-requirements:
 	@poetry install -n
 
-
-.PHONY: install-dev-requirements
-# help : install-dev-requirements 		- Install Python Dependencies for development
-install-dev-requirements:
-	@poetry install -n --with dev
-
 .PHONY: update-requirements
 #help: update-requirements				- Update Python Dependencies (requirements.txt and requirements-dev.txt)
 update-requirements:
@@ -43,6 +32,12 @@ update-requirements:
 format-code:
 	@poetry run pre-commit run -a
 
+.PHONY: run-tests
+#help: run-tests						- Run all tests with pytest
+run-tests:
+	@export PYTHONPATH=.
+	@poetry run pytest
+
 # help: deploy_docs				- Deploy documentation to GitHub Pages
 .PHONY: deploy_docs
 deploy_docs:

README.md

@@ -12,8 +12,6 @@
 [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-informational?logo=pre-commit&logoColor=white)](https://github.com/artefactory-fr/track-reid/blob/main/.pre-commit-config.yaml)
 </div>
 
-TODO: if not done already, check out the [Skaff documentation](https://artefact.roadie.so/catalog/default/component/repo-builder-ds/docs/) for more information about the generated repository.
-
 This Git repository is dedicated to the development of a Python library aimed at correcting the results of tracking algorithms. The primary goal of this library is to reconcile and reassign lost or misidentified IDs, ensuring a consistent and accurate tracking of objects over time.
 
 ## Table of Contents
@@ -27,13 +25,23 @@ This Git repository is dedicated to the development of a Python library aimed at
 
 ## Installation
 
+First, install poetry:
+
+```bash
+make download-poetry
+```
+
 To install the required packages in a virtual environment, run the following command:
 
 ```bash
 make install
 ```
 
-TODO: Choose between conda and venv if necessary or let the Makefile as is and copy/paste the [MORE INFO installation section](MORE_INFO.md#eased-installation) to explain how to choose between conda and venv.
+You can then activate the env with the following command:
+
+```bash
+poetry shell
+```
 
 A complete list of available commands can be found using the following command:
 
@@ -43,11 +51,22 @@ make help
 
 ## Usage
 
-TODO: Add usage instructions here
+For a quickstart, please refer to the documentation [here](https://artefactory-fr.github.io/track-reid/quickstart_user/). You also have at disposal a demo notebook in `notebooks/starer_kit_reid.ipynb`.
 
-## Documentation
+Lets say you have a `dataset` iterable object, composed for each iteartion of a frame id and its associated tracking results. You can call the `ReidProcessor` update class using the following:
+
+```python
+for frame_id, tracker_output in dataset:
+    corrected_results = reid_processor.update(frame_id = frame_id,                  tracker_output=tracker_output)
+```
+
+At the end of the for loop, information about the correction can be retrieved using the `ReidProcessor` properties. For instance, the list of tracked object can be accessed using:
 
-TODO: Github pages is not enabled by default, you need to enable it in the repository settings: Settings > Pages > Source: "Deploy from a branch" / Branch: "gh-pages" / Folder: "/(root)"
+```python
+reid_processor.seen_objects()
+```
+
+## Documentation
 
 A detailed documentation of this project is available [here](https://artefactory-fr.github.io/track-reid/)
 

bin/download_sample_sequences.sh

@@ -9,6 +9,8 @@ sequences_frames=$(gsutil ls gs://data-track-reid/frames | head -$N_SEQUENCES)
 sequences_detections=$(echo "$sequences_detections" | tail -n +2)
 sequences_frames=$(echo "$sequences_frames" | tail -n +2)
 
+mkdir -p data/detections
+mkdir -p data/frames
 
 # download the sequences to data/detections and data/frames
 for sequence in $sequences_detections; do

docs/custom_cost_selection.md

@@ -0,0 +1,148 @@
+# Designing custom cost and selection functions
+
+## Custom cost function
+
+In our codebase, a cost function is utilized to quantify the dissimilarity between two objects, specifically instances of [TrackedObjects](reference/tracked_object.md). The cost function plays a pivotal role in the matching process within the [Matcher class](reference/matcher.md), where it computes a cost matrix. Each element in this matrix represents the cost of assigning a candidate to a switcher. For a deeper understanding of cost functions, please refer to the [related documentation](reference/cost_functions.md).
+
+When initializing the [ReidProcessor](reference/reid_processor.md), you have the option to provide a custom cost function. The requirements for designing one are as follows:
+
+- The cost function must accept 2 [TrackedObjects](reference/tracked_object.md) instances: a candidate (a new object that appears and can potentially be matched), and a switcher (an object that has been lost and can potentially be re-matched).
+- All the [metadata](reference/tracked_object_metadata.md) of each [TrackedObject](reference/tracked_object.md) can be utilized to compute a cost.
+- If additional metadata is required, you should modify the [metadata](reference/tracked_object_metadata.md) class accordingly. Please refer to the [developer quickstart documentation](quickstart_dev.md) if needed.
+
+Here is an example of an Intersection over Union (IoU) distance function that you can use:
+
+```python
+def bounding_box_iou_distance(candidate: TrackedObject, switcher: TrackedObject) -> float:
+    """
+    Calculates the Intersection over Union (IoU) between the bounding boxes of two TrackedObjects.
+    This measure is used as a measure of similarity between the two objects, with a higher IoU
+    indicating a higher likelihood of the objects being the same.
+
+    Args:
+        candidate (TrackedObject): The first TrackedObject.
+        switcher (TrackedObject): The second TrackedObject.
+
+    Returns:
+        float: The IoU between the bounding boxes of the two TrackedObjects.
+    """
+    # Get the bounding boxes from the Metadata of each TrackedObject
+    bbox1 = candidate.metadata.bbox
+    bbox2 = switcher.metadata.bbox
+
+    # Calculate the intersection of the bounding boxes
+    x1 = max(bbox1[0], bbox2[0])
+    y1 = max(bbox1[1], bbox2[1])
+    x2 = min(bbox1[2], bbox2[2])
+    y2 = min(bbox1[3], bbox2[3])
+
+    # If the bounding boxes do not overlap, return 0
+    if x2 < x1 or y2 < y1:
+        return 0.0
+
+    # Calculate the area of the intersection
+    intersection_area = (x2 - x1) * (y2 - y1)
+
+    # Calculate the area of each bounding box
+    bbox1_area = (bbox1[2] - bbox1[0]) * (bbox1[3] - bbox1[1])
+    bbox2_area = (bbox2[2] - bbox2[0]) * (bbox2[3] - bbox2[1])
+
+    # Calculate the IoU
+    iou = intersection_area / float(bbox1_area + bbox2_area - intersection_area)
+
+    return 1 - iou
+
+```
+
+Next, pass this function during the initialization of your [ReidProcessor](reference/reid_processor.md):
+
+```python
+reid_processor = ReidProcessor(cost_function_threshold=0.3,
+                               cost_function = bounding_box_iou_distance,
+                               filter_confidence_threshold=...,
+                               filter_time_threshold=...,
+                               max_attempt_to_match=...,
+                               max_frames_to_rematch=...,
+                               save_to_txt=True,
+                               file_path="your_file.txt")
+```
+
+In this case, candidates and switchers with bounding boxes will be matched if their IoU is below 0.7. Among possible matches, the two bounding boxes with the lowest cost (i.e., larger IoU) will be matched. You can use all the available metadata. For instance, here is an example of a cost function based on the difference in confidence:
+
+```python
+def confidence_difference(candidate: TrackedObject, switcher: TrackedObject) -> float:
+    """
+    Calculates the absolute difference between the confidence values of two TrackedObjects.
+    This measure is used as a measure of dissimilarity between the two objects, with a smaller difference
+    indicating a higher likelihood of the objects being the same.
+
+    Args:
+        candidate (TrackedObject): The first TrackedObject.
+        switcher (TrackedObject): The second TrackedObject.
+
+    Returns:
+        float: The absolute difference between the confidence values of the two TrackedObjects.
+    """
+    # Get the confidence values from the Metadata of each TrackedObject
+    confidence1 = candidate.metadata.confidence
+    confidence2 = switcher.metadata.confidence
+
+    # Calculate the absolute difference between the confidence values
+    difference = abs(confidence1 - confidence2)
+
+    return difference
+
+```
+
+Then, pass this function during the initialization of your [ReidProcessor](reference/reid_processor.md):
+
+```python
+reid_processor = ReidProcessor(cost_function_threshold=0.1,
+                               cost_function = confidence_difference,
+                               filter_confidence_threshold=...,
+                               filter_time_threshold=...,
+                               max_attempt_to_match=...,
+                               max_frames_to_rematch=...,
+                               save_to_txt=True,
+                               file_path="your_file.txt")
+```
+
+In this case, candidates and switchers will be matched if their confidence is similar, with a threshold acceptance of 0.1. Among possible matches, the two objects with the lowest cost (i.e., lower confidence difference) will be matched.
+
+## Custom Selection function
+
+In the codebase, a selection function is used to determine whether two objects, specifically [TrackedObjects](reference/tracked_object.md) instances, should be considered for matching. The selection function is a key part of the matching process in the [Matcher class](reference/matcher.md). For a deeper understanding of selection functions, please refer to the [related documentation](reference/selection_functions.md).
+
+Here is an example of a selection function per zone that you can use:
+
+```python
+
+# Define the area of interest, [x_min, y_min, x_max, y_max]
+AREA_OF_INTEREST = [0, 0, 500, 500]
+
+def select_by_area(candidate: TrackedObject, switcher: TrackedObject) -> int:
+
+    # Check if both objects are inside the area of interest
+    if (candidate.bbox[0] > AREA_OF_INTEREST[0] and candidate.bbox[1] > AREA_OF_INTEREST[1] and
+        candidate.bbox[0] + candidate.bbox[2] < AREA_OF_INTEREST[2] and candidate.bbox[1] + candidate.bbox[3] < AREA_OF_INTEREST[3] and
+        switcher.bbox[0] > AREA_OF_INTEREST[0] and switcher.bbox[1] > AREA_OF_INTEREST[1] and
+        switcher.bbox[0] + switcher.bbox[2] < AREA_OF_INTEREST[2] and switcher.bbox[1] + switcher.bbox[3] < AREA_OF_INTEREST[3]):
+        return 1
+    else:
+        return 0
+
+```
+
+Then, pass this function during the initialization of your [ReidProcessor](reference/reid_processor.md):
+
+```python
+reid_processor = ReidProcessor(selection_function = select_by_area,
+                               filter_confidence_threshold=...,
+                               filter_time_threshold=...,
+                               max_attempt_to_match=...,
+                               max_frames_to_rematch=...,
+                               save_to_txt=True,
+                               file_path="your_file.txt")
+```
+
+In this case, candidates and switchers will be considerated for matching if they belong to the same zone. You can of course combine selection functions, for instance to selection only switchers and candidates that belong to the same area and belong to the same category.

docs/index.md

@@ -1,3 +1,3 @@
-# Welcome to the documentation!
+# Welcome to the documentation
 
 For more information, make sure to check the [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/getting-started/)