search

openjournals / joss-reviews

Reviews for the Journal of Open Source Software
Creative Commons Zero v1.0 Universal
694 stars 36 forks source link

[REVIEW]: OfflineMOT: A Python Package for multiple objects detection and tracking from bird view stationary drone videos #4099

Closed whedon closed 2 years ago

whedon commented 2 years ago

Submitting author: !--author-handle-->@engyasin<!--end-author-handle-- (Yasin Yousif) Repository: https://github.com/engyasin/Offline_MOT Branch with paper.md (empty if default branch): Version: v1.0.9 Editor: !--editor-->@hugoledoux<!--end-editor-- Reviewers: @Shiming94, @lucaferranti Archive: 10.5281/zenodo.6644282

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/94ab6a9e87d3423efc025216e897fcc3"><img src="https://joss.theoj.org/papers/94ab6a9e87d3423efc025216e897fcc3/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/94ab6a9e87d3423efc025216e897fcc3/status.svg)](https://joss.theoj.org/papers/94ab6a9e87d3423efc025216e897fcc3)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@Shiming94 & @lucaferranti , please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

  1. Make sure you're logged in to your GitHub account
  2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @hugoledoux know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @Shiming94

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

Review checklist for @lucaferranti

✨ Important: Please do not use the Convert to issue functionality when working through this checklist, instead, please open any new issues associated with your review in the software repository associated with the submission. ✨

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

whedon commented 2 years ago

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @Shiming94, @lucaferranti it looks like you're currently assigned to review this paper :tada:.

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

  1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

watching

  1. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf
whedon commented 2 years ago

Wordcount for paper.md is 1254

whedon commented 2 years ago 
Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.13 s (274.4 files/s, 51169.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                          24            800           1172           2217
Jupyter Notebook                 8              0           1994            286
Markdown                         3            108              0            177
TeX                              1             11              0            112
YAML                             1              1              4             18
-------------------------------------------------------------------------------
SUM:                            37            920           3170           2810
-------------------------------------------------------------------------------

Statistical information for the repository '976a991ef7ec46dfca5b4518' was
gathered on 2022/01/26.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Yasin Yousif                    20         10098           5909          100.00

Below are the number of rows from each author that have survived and are still
intact in the current revision:

Author                     Rows      Stability          Age       % in comments
Yasin Yousif               4189           41.5          0.7               11.36
whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1109/iccv.2019.00103 is OK
- 10.1109/icip.2017.8296962 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.1109/ivs.2019.8814092 is OK

MISSING DOIs

- None

INVALID DOIs

- None
hugoledoux commented 2 years ago

@whedon re-invite @Shiming94 as reviewer

whedon commented 2 years ago

OK, the reviewer has been re-invited.

@shiming94 please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations

whedon commented 2 years ago

:wave: @lucaferranti , please update us on how your review is going (this is an automated reminder).

whedon commented 2 years ago

:wave: @Shiming94, please update us on how your review is going (this is an automated reminder).

lucaferranti commented 2 years ago

I'm planning to post my review this weekend

Shiming94 commented 2 years ago

I am reviewing...

I found several problems:

@hugoledoux , what should I do next? Should I propose an issur in the original repo?

engyasin commented 2 years ago

I am reviewing...

I found several problems:

  • a lot of typo erros in the README.md, but didn't affect the understanding
  • I tried to run the first command python offline_mot\main.py -v [directroy of the videos, ex: docs\sample.mp4], but failed.

@hugoledoux , what should I do next? Should I propose an issur in the original repo?

Thanks for the feedback,

Shiming94 commented 2 years ago

Hi, @engyasin, I install your requirement.txt in the virtual env with python 3.7. The traceback is shown blow:

Traceback (most recent call last):
  File "offlinemot/main.py", line 401, in <module>
    main(args)
  File "offlinemot/main.py", line 184, in main
    objects,detector = FirstFrame(frame)
  File "offlinemot/main.py", line 147, in FirstFrame
    detector  = YoloDetector(config.model_config,config.model_name,use_cuda=config.use_cuda)
  File "/home/shiming/12.Offline_MOT/offlinemot/detection.py", line 61, in __init__
    self.m.load_state_dict(torch.load(weightfile))
  File "/home/shiming/anaconda3/envs/mot/lib/python3.7/site-packages/torch/serialization.py", line 608, in load
    return _legacy_load(opened_file, map_location, pickle_module, **pickle_load_args)
  File "/home/shiming/anaconda3/envs/mot/lib/python3.7/site-packages/torch/serialization.py", line 777, in _legacy_load
    magic_number = pickle_module.load(f, **pickle_load_args)
_pickle.UnpicklingError: invalid load key, 'v'.

I think ther should be some errors in the config file.

engyasin commented 2 years ago

Thanks for reporting @Shiming94

I tried to reproduce the error, but I couldn't. It seems it is related to the Yolo network file (models/Yolo4_epoch300.pth). it is a big file (244 MB), which needs git lfs to be uploaded (and cloned?) . Can you check if it's downloaded correctly in your cloned repo?

Shiming94 commented 2 years ago

@engyasin I just downloaded all the files in your repo and followed your instructions, and then the error appeared. I will try the new checkpoint file like you said. But I recommend that you create a download script at the beginning of your Readme.md. That will make the followers and the audience much easier to follow.

engyasin commented 2 years ago

Yes, that's right, I will test it on another device without git lfs. and update the readme with the needed instructions.

lucaferranti commented 2 years ago

@whedon generate pdf

lucaferranti commented 2 years ago

@whedon check references

whedon commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1109/iccv.2019.00103 is OK
- 10.1109/icip.2017.8296962 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.1109/ivs.2019.8814092 is OK

MISSING DOIs

- None

INVALID DOIs

- None
whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

lucaferranti commented 2 years ago

Hi @engyasin , overall very nice work, here are some preliminary comments regarding the software

lucaferranti commented 2 years ago

regarding the issue reported by @Shiming94 , I checked my cloned repository and the model folder seems to match the content on this repository, so I think it did download the network? (but maybe corrupted if I didn't download with git lfs?)

lferrant@LAPTOP-HGM2FD2S:/mnt/c/Users/lucaa/Desktop/Offline_MOT/model$ ll
total 1356
drwxrwxrwx 1 lferrant lferrant     512 Feb 15 13:07 ./
drwxrwxrwx 1 lferrant lferrant     512 Feb 15 20:00 ../
-rwxrwxrwx 1 lferrant lferrant 1373697 Feb 15 13:07 00120.jpg*
-rwxrwxrwx 1 lferrant lferrant     134 Feb 15 13:07 Yolov4_epoch300.pth*
-rwxrwxrwx 1 lferrant lferrant      22 Feb 15 13:07 obj.names*
-rwxrwxrwx 1 lferrant lferrant   12248 Feb 15 13:07 yolov4-obj.cfg*
-rwxrwxrwx 1 lferrant lferrant     134 Feb 15 13:07 yolov4-pytorch.pth*

anyway, I am not sure such big data files belong to the source code (but you can disagree). The readme states that a separated model for detection is needed, so I feel the users should be able to install the package without having to download such a heavy model (e.g. if they want to use a different one anyway in their research project). An alternative could be to have a smaller lightweight model to make the package "battery included" and have a script/function to download the yolo4 network if the user wants to use it.

When running the tests, you could check if the yolo4 network is downloaded in a predesigned location and if it isn't download it. This way you could still run the tests on the CI and you wouldn't redownload the big file every time you run tests locally. A maybe even better alternative could be to run the tests with the smaller lightweight model, the final performance metrics will probably be lower than with yolo, but I think that's orthogonal to testing for correctness.

lucaferranti commented 2 years ago

@whedon generate pdf

whedon commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

lucaferranti commented 2 years ago

and here the second part of my review for the paper

hugoledoux commented 2 years ago
  • a lot of typo erros in the README.md, but didn't affect the understanding

@Shiming94 if there are many typos then the authors should go over the text and indeed fix them. If you spot a few, the best would be to fork the paper, fix them, and make a pull request.

Shiming94 commented 2 years ago
  • a lot of typo erros in the README.md, but didn't affect the understanding

@Shiming94 if there are many typos then the authors should go over the text and indeed fix them. If you spot a few, the best would be to fork the paper, fix them, and make a pull request.

Thanks a lot, I will do that.

hugoledoux commented 2 years ago

anyway, I am not sure such big data files belong to the source code (but you can disagree). The readme states that a separated model for detection is needed, so I feel the users should be able to install the package without having to download such a heavy model (e.g. if they want to use a different one anyway in their research project). An alternative could be to have a smaller lightweight model to make the package "battery included" and have a script/function to download the yolo4 network if the user wants to use it.

@engyasin I share the opinion of @lucaferranti here, ideally your main test dataset should be small, small enough to be committed to a standard git repo at least. Most users just want to pip install X (so I think you should consider this too, although not a strict requirement for JOSS) and then test if the code works

hugoledoux commented 2 years ago
  • [ ] Authorship: could you clarify the contribution of Awad Mukbil and Jörg Müller to the package development? Based on the list of commits, they don't seem to be contributors

@engyasin please read this: https://joss.readthedocs.io/en/latest/submitting.html?highlight=contributors#authorship JOSS is slightly different from mainstream academic publishers and has rules for authorship. Of course it's not black-and-white, so you can just explain us here what was done by those who didn't contribute to the code (in the git commits)

engyasin commented 2 years ago

Dear editor @hugoledoux and Dear reviewers @Shiming94 @lucaferranti ,

Many thank for your valuable comments, I will try to reply to all of them in the next few days, both with change of code and clarifying my assumptions. Some of which are already addressed (the package is now a pip installable, docs are built with sphinx and auto-testing with GitHub actions is added) The documentation and paper therefore, need to be updated as well regarding the installing instructions, this will be done in the next few days hopefully.

engyasin commented 2 years ago

Hello, In the following, the responses to previously raised issues regarding the submission are listed

  • [ ] Installation: Currently the software is installed by cloning the repository and doing the installation manually. Have you considered adding this to pypi? This way I could install it with just pip install offlinemot. In the example notebooks, you have indeed a first cell to manually add the path of offlinemot and be able to import functionality. This can be a little annoying for other people using the software in their research. It also makes sharing work harder, imagine I write a notebook that uses your software and share it with a colleague, it would require my colleague to clone your repository and adjust the path to match their installation.

The package is now on pypi.

  • [ ] Documentation 1: With a quick glance at the source code, most functions seem have excellent docstrings. Unfortunately, these docstrings are not collected into a full API documentation. This makes it hard for the user to investigate the interface of the package. I would strongly suggest to generate a documentation page for the software, e.g. using sphinx. The documentation page should have the API documentation and could also have the current notebooks as tutorials.

Documentation with full API is in https://engyasin.github.io/Offline_MOT

  • [ ] Testing: I get some tests failing when testing locally, possibly for the reason reported by the other reviewer. I will dig deeper into this and open an issue if needed. Anyway, I think the current setup where tests are run locally can make maintaining the package harder, mainly for two reasons. First, if someone opens a PR to your code, either you trust they have already tested locally or you have to clone their branch and test the tests locally every time. Second, unless you have several different machines, tests will be run only on one operating system, hence OS dependent failures are easier to slip through (the most common case would be that things work on linux/macos but not on windows, these bugs are fairly usual if you work with paths). For this reason, I would strongly suggest to setup a CI workflow (e.g with github actions) to run the tests on each push and PR, possibly on different operating systems. Some coverage measure with codecov or coveralls would also be nice to have, although not compulsory.

CI workflow with github actions is added. For local testing pytest is needed to be run on the tests folder.

  • [ ] Contributing: I feel the current "How to contribute" section doesn't say how to contribute, as it merely encourages to read the documentation and browse the code. I would suggest some rewording, for example just replicating there the first two sentences of the Support section in the readme would make it much better. Style guide is missing, but fwiw I don't think this is strictly needed to be done before getting the paper published (but please do add that at some point :) )

Noted, the suggestion is adopted (although short but good for now). Regarding the style guide, will be on top of the list of the future works for the repo.

  • [ ] Functionality: I get the same error reported by the other reviewer, a couple of more comments

    • The example command in the readme has probably a typo, I think should be offline_mot/main.py -> offlinemot/main.py, same for the other examples

I think now it should work, ( a big download will be triggered when this command is run) Offlinemot.main.main()

  • Can I use the package with other detection models? Do they have to be pytorch or can it be a tensorflow model? It would be nice to have an example about this.

Sadly, the file should be .pth in order to be loaded, so pytorch is a requirement. But if the user wants to train on tensorflow, he needs simply to convert the output trained model to pytorch format. The model structure however, should be only Yolo v4. I think this note is added to the docs now. Another detection structure is mentioned (other than Yolo). But Yolo is actually very common for the detection tasks so it’s not a bad choice.

This was the first round about the code, I'll now read the paper.

@engyasin I just downloaded all the files in your repo and followed your instructions, and then the error appeared. I will try the new checkpoint file like you said. But I recommend that you create a download script at the beginning of your Readme.md. That will make the followers and the audience much easier to follow.

The big file was for the Yolo trained network, (due to the big size of the network). Now it's only downloadable when the example model is run for the first time. it is no longer on github

and here the second part of my review for the paper

  • [ ] Authorship: could you clarify the contribution of Awad Mukbil and Jörg Müller to the package development? Based on the list of commits, they don't seem to be contributors

My two co-authors didn’t directly write the code for the repo, but had an active project participation and influencing directing. Upon review of the Journal guideline, active projects participants are considered for an authorship as well, so the credit was assigned that way. Due to the nature of this work, which required designing process of the method and in specific details about extracting trajectories, discovering shadows and fixing the view, my co-authors had a direct involvement in the form of discussions and guidance. Other colleagues who collaborated with us for the training were listed in the acknowledgment part of the paper because their part was mainly about training the detection model not the method itself.

  • [ ] State of the field: The paper at the moment compares the presented method to other methods, since this is a software paper, I think the focus should be on comparing the implementation to other existing packages. Are there other packages / codes tackling this problem, how does offlineMOT compare to them? At the moment, the section tells me some approaches have been developed but I am missing pointers to if and where they are implemented.

Comparing with other methods while interesting, still has some difficulties in our case, First, we need a dataset with ground truth data in order to show the errors for all the methods at the end. These datasets should be compatible with our condition (stationary top-view). The biggest dataset for the field of multi-object tracking (MOT: https://motchallenge.net/ ) doesn't has such videos. Other datasets for drones (https://cvgl.stanford.edu/projects/uav_data/) don’t have initial bounding boxes for detection, so the detection should be done with pretrained models. This detection will produce its own errors, making the comparison less accurate.

What we showed instead is a new approach that combine well-known methods to solve restricted case for multi-objects tracking. The paper mentions two methods among the state-of-the-art. Deep Sort and Tracktor .

  • [ ] Example usage: I find this section in the current form a little confusing, I don't think installation instructions are needed in the paper, they should be covered in the documentation / readme. Furthermore, the current section is briefly showing a command line to call a specific script and commenting the results. If some usage examples are to be included, I think they should be more focused on the interface of the software and not the result. For example, before the pseudocode it is mentioned that the package is implemented in a modular way and it's easy to turn off and/or tune different parts, instead of the pseudocode, I think it would be more useful to have a code snippet showing how to build each block (if this can be done with a few lines of code, if the example is longer, better to just refer to the documentation)

This section was meant to walk through a complete example from start to end. but you are right regarding the point about installation, it isn't needed so It is now deleted. For the modular design, a config file can be shown in parts, while walking through the example. There's a doc page explaining the many parameters, but perhaps in the paper it can be more configuration oriented than example oriented. Now in the paper, this section is replaced with Parameters Tuning , with a table showing the most influencing parameters along with their effect.

I hope I did cover all the points, thanks again.

engyasin commented 2 years ago

@whedon generate pdf

editorialbot commented 2 years ago

My name is now @editorialbot

engyasin commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

lucaferranti commented 2 years ago

thank you very much for the updates! I will go through them this weekend or early next week

lucaferranti commented 2 years ago

Hi @engyasin (cc @hugoledoux ),

apologies for the huge delay with this. Pretty busy month and fell off my radar...

Anyway, after the changes I think the submission looks mainly ok, I have a few comments

I'll still double check the other examples in the docs to make sure everything works, but otherwise it starts to look ready to me

engyasin commented 2 years ago

Hi @lucaferranti,

Thanks for the additional comments and feedback. Also for me the past month was busy, so there wasn't more improvements since the last time.

In the coming weeks, I will try to address these points and others. I will inform as soon as they are ready.

engyasin commented 2 years ago

@editorialbot generate pdf

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

engyasin commented 2 years ago

Dear editor @hugoledoux and reviewers @Shiming94 @lucaferranti ,

Some changes, according to the latest comments from @lucaferranti were made. Namely, the configs is a class now, providing Configparser interface of changing and showing the different parameters. So this will avoid the editing of a single file, and encourage saving different set of parameters to each case (and distributing it).

Also, code coverage is added. It shows only 51% however, many of the non-tested scripts are for creating the structure of Yolo network, and this mostly shouldn't be changed at all (all the scripts are in tools folder).

Contributing instructions are more detailed now. Instructions for creating a special type of issues for accuracy problem are shown as well.

Typos are fixed in the docs and code.

I hope I addressed your points. Of course, the improvement road is still wide open, but I hope a continuous cycle of enhancing would still be ongoing for the benefit of the community.

Thanks again,

Shiming94 commented 2 years ago

@editorialbot generate pdf

Shiming94 commented 2 years ago

@editorialbot check references

editorialbot commented 2 years ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

editorialbot commented 2 years ago 
Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1109/iccv.2019.00103 is OK
- 10.1109/icip.2017.8296962 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.1109/ivs.2019.8814092 is OK

MISSING DOIs

- None

INVALID DOIs

- None
Shiming94 commented 2 years ago

Hi @engyasin and @hugoledoux

Sorry for my delayed reply. I just moved to another country last month, and it was a really busy month.

I checked your repo again, and it is really great that the structure and contents of the code were significantly improved! But I was still stuck in the Installation step. I tried to run the code in a cond virtuel environment. The pypi installation worked fine for me, but I got errors when I ran the first line in the Getting Started, here is the traceback:

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
/tmp/ipykernel_26571/510862866.py in <module>
----> 1 import offlinemot

~/12.Offline_MOT/offlinemot/__init__.py in <module>
     16 import fix_view
     17 
---> 18 import objects_classes
     19 
     20 import post_process

~/12.Offline_MOT/offlinemot/objects_classes.py in <module>
      7 from utils_ import check_box
      8 
----> 9 class TrafficObj():
     10     """
     11     A class used to represent any traffic entity, with its full track

~/12.Offline_MOT/offlinemot/objects_classes.py in TrafficObj()
    106     """
    107 
--> 108     def __init__(self,frame,frame_id,box,track_id,config=configs(),tracker=cv2.TrackerKCF_create,class_id=-1,detection_way=1,detect_prob=0.0):
    109         """
    110         Parameters

AttributeError: module 'cv2' has no attribute 'TrackerKCF_create'

I tried to tackle this problem by adapting the version of opencv-python, but they all failed. So there are several suggestions from my side:

I hope these are helpful for you. I will still try to tackle the open-cv problem, I hope it could be automatically solved when you update the dependencies' versions.

engyasin commented 2 years ago

Hi @Shiming94 ,

Thanks for reporting. I think ,for opencv error, this has to do with the needed installation is "opencv-contrib-python" not "opencv-python", you may need also to uninstall opencv-python as mentioned here (https://github.com/opencv/opencv/issues/15723#issuecomment-543063004). This wouldn't happen if requirements.txt is used only, as shown in readme (pypi should use it as well). Just simply run : pip uninstall opencv-python python -m pip install opencv-contrib-python

Regarding your second point, the readme should be md file, but there's some notebooks for starting in : https://github.com/engyasin/Offline_MOT/blob/main/docs/source/tutorials/A_Working_Example.ipynb

hugoledoux commented 2 years ago

Thanks for reporting. I think ,for opencv error, this has to do with the needed installation is "opencv-contrib-python" not "opencv-python", you may need also to uninstall opencv-python as mentioned here (opencv/opencv#15723 (comment)). This wouldn't happen if requirements.txt is used only, as shown in readme (pypi should use it as well). Just simply run : pip uninstall opencv-python python -m pip install opencv-contrib-python

@engyasin Maybe it would be good to stress this in the installation manual? I would assume this is something others might run into, and have it documented somewhere would be good practice.

hugoledoux commented 2 years ago

Regarding your second point, the readme should be md file, but there's some notebooks for starting in : https://github.com/engyasin/Offline_MOT/blob/main/docs/source/tutorials/A_Working_Example.ipynb

@engyasin Same here: inform the users in the readme.md that this exists and link to it?

Shiming94 commented 2 years ago

Hi @Shiming94 ,

Thanks for reporting. I think ,for opencv error, this has to do with the needed installation is "opencv-contrib-python" not "opencv-python", you may need also to uninstall opencv-python as mentioned here (opencv/opencv#15723 (comment)). This wouldn't happen if requirements.txt is used only, as shown in readme (pypi should use it as well). Just simply run : pip uninstall opencv-python python -m pip install opencv-contrib-python

Regarding your second point, the readme should be md file, but there's some notebooks for starting in : https://github.com/engyasin/Offline_MOT/blob/main/docs/source/tutorials/A_Working_Example.ipynb

Hi @engyasin, thanks for your reply.

I tried the way you mentioned but it didn't work here. I think the problem is that we use different releases of opencv, and the API's name also changed. So my suggestion would be to give a clear description of which dependencies and which releases you are using before the Installation, so that users can check their environment.

Regarding the second part, I totally agree with @hugoledoux. You should let the users know that you already have these notebooks.