Add Getting started guide #208
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dekked
changed the title
There was a problem hiding this comment.
It looks great @javiber! Thanks for adding the Getting Started section, it is an excellent addition to Norfair's documentation.
I left a bunch of comments, mostly formatting issues, but apart from that, I think it's ready to merge. I assumed the formatting was expected to work as in Markdown, I didn't try it in the actual documentation, so feel free to dismiss the comments if you checked that the formatting was correct.
Comment on lines
+20
to
+21
| !!! Note | ||
| Norfair is a Detection-Based-Tracker (DBT) and as such, its performance is highly dependent on the performance of the model of choice. |
There was a problem hiding this comment.
I'm not sure what was the expected formatting for this note, but I believe it isn't working correctly in Markdown.
There was a problem hiding this comment.
The !!! Note is not standard markdown and I don't think Github renders it correctly but it's part of our mkdocs theme
| !!! Note | ||
| Norfair is a Detection-Based-Tracker (DBT) and as such, its performance is highly dependent on the performance of the model of choice. | ||
|
|
||
| The detections from the model will need to be wrapped in an instance of [Detection][norfair.tracker.Detection] before passing them to Norfair. |
There was a problem hiding this comment.
Check this link and its format.
There was a problem hiding this comment.
This is how to define links to other sections in mkdocstring
docs/getting_started.md
Outdated
|
|
||
| ## Install | ||
|
|
||
| Installing Norfair is extremely easy, simply run `pip install norfair` to install the latest version from [pypi](https://pypi.org/project/norfair/). |
There was a problem hiding this comment.
Maybe change pypi for PyPI?
| Norfair offers optional functionality to process videos (mp4 and mov formats are supported) or capture a live feed from a camera. | ||
| To use this functionality you need to install Norfair with the `video` extra using this command: `pip install norfair[video]`. | ||
|
|
||
| Check the [Video class][norfair.video.Video] for more info on how to use it. |
There was a problem hiding this comment.
Check this link and its format.
|
|
||
| Most common problem is that the tracking has errors or is not precise enough. In this case, the first thing to check is whether this is a detection error or a tracking error. As mentioned above if the detector fails the tracking will suffer. | ||
|
|
||
| To debug this use [`draw_points`][norfair.drawing.draw_points] or [`draw_boxes`][norfair.drawing.draw_boxes] to inspect the detections and analyze if they are precise enough. If you are filtering the detections based on scores, this is a good time to tweak the threshold. If you decide that the detections are not good enough you can try a different architecture, a bigger version of the model, or consider fine-tuning the model on your domain. |
docs/getting_started.md
Outdated
| - **Incorrect matches** between Detections and TrackedObjects, a couple of scenarios can cause this: | ||
| - `distance_threshold` is too big so the Tracker matches Detections to TrackedObjects that are simply too far. Lower the threshold until you fix the error, the correct value will depend on the distance function that you're using. | ||
| - Mismatches when objects overlap. In this case, tracking becomes more challenging, usually, the quality of the detection degrades causing one of the objects to be missed or creating a single big detection that includes both objects. On top of the detection issues, the tracker needs to decide which detection should be matched to which TrackedObject which can be error-prone if only considering spatial information. The solution is not easy but incorporating the notion of the appearance similarity based on some kind of embedding to your distance_finction can help. | ||
| - Can't **recover** an object **after oclussions**. Use ReID distance, see [this demo](TODO) for an example but for real-world use you will need a good ReID model that can provide good embeddings. |
There was a problem hiding this comment.
oclussions -> occlusions
docs/getting_started.md
Outdated
| - Objects take **too long to start**, this can have multiple causes: | ||
| - `initialization_delay` is too big on the Tracker. Makes the TrackedObject stay on initializing for too long, `3` is usually a good value to start with. | ||
| - `distance_threshold` is too big on the Tracker. Prevents the Detections to be matched with the correct TrackedObject. The best value depends on the distance used. | ||
| - Incorrect `distance_function` on the Tracker. Some distances might not be valid in some cases, for instance, if using IoU but the objects in your video move so quickly that there is never an overlap between the detections of consecutive frames. Try different distances, `frobenious` or `create_normalized_mean_euclidean_distance` are good starting points. |
There was a problem hiding this comment.
frobenious -> frobenius
docs/getting_started.md
Outdated
| - **Incorrect matches** between Detections and TrackedObjects, a couple of scenarios can cause this: | ||
| - `distance_threshold` is too big so the Tracker matches Detections to TrackedObjects that are simply too far. Lower the threshold until you fix the error, the correct value will depend on the distance function that you're using. | ||
| - Mismatches when objects overlap. In this case, tracking becomes more challenging, usually, the quality of the detection degrades causing one of the objects to be missed or creating a single big detection that includes both objects. On top of the detection issues, the tracker needs to decide which detection should be matched to which TrackedObject which can be error-prone if only considering spatial information. The solution is not easy but incorporating the notion of the appearance similarity based on some kind of embedding to your distance_finction can help. | ||
| - Can't **recover** an object **after oclussions**. Use ReID distance, see [this demo](TODO) for an example but for real-world use you will need a good ReID model that can provide good embeddings. |
There was a problem hiding this comment.
Check ReID demo link.
docs/getting_started.md
Outdated
|
|
||
| - Objects take **too long to start**, this can have multiple causes: | ||
| - `initialization_delay` is too big on the Tracker. Makes the TrackedObject stay on initializing for too long, `3` is usually a good value to start with. | ||
| - `distance_threshold` is too big on the Tracker. Prevents the Detections to be matched with the correct TrackedObject. The best value depends on the distance used. |
There was a problem hiding this comment.
Didn't get the idea behind this recommendation. Shouldn't it be that the distance_threshold is too small?
Based on Facundo's feedback
facundo-lezama
approved these changes
Oct 26, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
/referencepage which was not navigatable before to contain the docstring from norfair. Open to suggestions for better alternatives though.