Package: deep-sort-realtime
Deep SORTIntroductionA more realtime adaptation of Deep SORT.Adapted from theofficial repo ofSimple Online and Realtime Tracking with a Deep Association Metric(Deep SORT)See theirpaperfor more technical information.Dependenciesrequirements.txtgives the default packages required (it installs torch/torchvision to use the default mobilenet embedder), modify accordingly.Main dependencies are:Python3NumPy,pip install numpySciPy,pip install scipycv2,pip install opencv-python(optional)Embedderrequires Pytorch & Torchvision (for the default MobiletnetV2 embedder) or Tensorflow 2+pip install torch torchvisionpip install tensorflow(optional) Additionally, to useTorchreidembedder,torchreidPython package needs to be installed. You can followinstallation guideonTorchreid's page. Without using conda, you can simply clone thatrepositoryand do apython3 -m pip install .from inside the repo.(optional) To useCLIPembedder,pip install git+https://github.com/openai/CLIP.gitInstallfromPyPIviapip3 install deep-sort-realtimeor, clone this repo & install deep-sort-realtime as a python package usingpipor as an editable package if you like (-eflag)cddeep_sort_realtime&&pip3install.or, download.whlfile in this repo'sreleasesRunExample usage:fromdeep_sort_realtime.deepsort_trackerimportDeepSorttracker=DeepSort(max_age=5)bbs=object_detector.detect(frame)tracks=tracker.update_tracks(bbs,frame=frame)# bbs expected to be a list of detections, each in tuples of ( [left,top,w,h], confidence, detection_class )fortrackintracks:ifnottrack.is_confirmed():continuetrack_id=track.track_idltrb=track.to_ltrb()To add project-specific logic into theTrackclass, you can make a subclass (ofTrack) and pass it in (override_track_classargument) when instantiatingDeepSort.Example with your own embedder/ReID model:fromdeep_sort_realtime.deepsort_trackerimportDeepSorttracker=DeepSort(max_age=5)bbs=object_detector.detect(frame)# your own object detectionobject_chips=chipper(frame,bbs)# your own logic to crop frame based on bbox valuesembeds=embedder(object_chips)# your own embedder to take in the cropped object chips, and output feature vectorstracks=tracker.update_tracks(bbs,embeds=embeds)# bbs expected to be a list of detections, each in tuples of ( [left,top,w,h], confidence, detection_class ), also, no need to give frame as your chips has already been embeddedfortrackintracks:ifnottrack.is_confirmed():continuetrack_id=track.track_idltrb=track.to_ltrb()Look intodeep_sort_realtime/deepsort_tracker.pyfor more hyperparameters which you can tune to suit your use-case.Getting bounding box of original detectionThe originalTrack.to_*methods for retrieving bounding box values returns only the Kalman predicted values. However, in some applications, it is better to return the bb values of the original detections the track was associated to at the current round.Here we added anorigargument to all theTrack.to_*methods. Iforigis flagged asTrueand this track is associated to a detection this update round, then the bounding box values returned by the method will be that associated to the original detection. Otherwise, it will still return the Kalman predicted values.orig_strictargument in all theTrack.to_*methods is only active whenorigisTrue. Flaggingorig_strict=Truewill mean it will outputNonewhen there's no original detection associated to this track at current frame, otherwise normally it will return Kalman predicted values.Storing supplementary info of original detectionSupplementary info can be pass into the track from the detection.Detectionclass now has anothersargument to store this and pass it to the associate track during update. Can be retrieved throughTrack.get_det_supplementarymethod. Can be passed in throughothersargument ofDeepSort.update_tracks, expects to be a list with same length asraw_detections. Examples of when you will this includes passing in corresponding instance segmentation masks, to be consumed when iterating through the tracks output.Polygon supportOther than horizontal bounding boxes, detections can now be given as polygons. We do not track polygon points per se, but merely convert the polygon to its bounding rectangle for tracking. That said, if embedding is enabled, the embedder works on the crop around the bounding rectangle, with area not covered by the polygon masked away.When instantiating aDeepSortobject (as indeepsort_tracker.py),polygonargument should be flagged toTrue. SeeDeepSort.update_tracksdocstring for details on the polygon format. In polygon mode, the original polygon coordinates are passed to the associated track through thesupplementary info.Differences from original repoRemove "academic style" offline processing style and implemented it to take in real-time detections and output accordingly.Provides both options of using an in-built appearance feature embedder or to provide embeddings during updateAdded pytorch mobilenetv2 as appearance embedder (tensorflow embedder is also available now too).AddedCLIPnetwork from OpenAI as embedder (pytorch).Skip nms completely in preprocessing detections ifnms_max_overlap == 1.0(which is the default), in the original repo, nms will still be done even if threshold is set to 1.0 (probably because it was not optimised for speed).Now able to override theTrackclass with a custom Track class (that inherits fromTrackclass) for custom track logicTakes in today's date now, which provides date for track naming and facilities track id reset every day, preventing overflow and overly large track ids when system runs for a long time.fromdatetimeimportdatetimetoday=datetime.now().date()Now supports polygon detections. We do not track polygon points per se, but merely convert the polygon to its bounding rectangle for tracking. That said, if embedding is enabled, the embedder works on the crop around the bounding rectangle, with area not covered by the polygon masked away.Read more here.The originalTrack.to_*methods for retrieving bounding box values returns only the Kalman predicted values. In some applications, it is better to return the bb values of the original detections the track was associated to at the current round. Added aorigargument which can be flaggedTrueto get that.Read more here.Addedget_det_supplementarymethod toTrackclass, in order to pass detection related info through the track.Read more here.[As of2fad967] Supports background masking by giving instance mask toDeepSort.update_tracks.Read more here.Other minor adjustments/optimisation of code.Highlevel overview of source files indeep_sort(from original repo)In packagedeep_sortis the main tracking code:detection.py: Detection base class.kalman_filter.py: A Kalman filter implementation and concrete
parametrization for image space filtering.linear_assignment.py: This module contains code for min cost matching and
the matching cascade.iou_matching.py: This module contains the IOU matching metric.nn_matching.py: A module for a nearest neighbor matching metric.track.py: The track class contains single-target track data such as Kalman
state, number of hits, misses, hit streak, associated feature vectors, etc.tracker.py: This is the multi-target tracker class.Testpython3-munittestAppearance Embedding NetworkPytorch Embedder (default)Default embedder is a pytorch MobilenetV2 (trained on Imagenet).For convenience (I know it's not exactly best practice) & since the weights file is quite small, it is pushed in this github repo and will be installed to your Python environment when you install deep_sort_realtime.TorchReIDTorchreidis a person re-identification library, and is supported here especially useful for extracting features of humans.Torchreidwill need to be installed (seedependenciessection above) It provides a zoo ofmodels. Select model type to use, note the model name and provide as arguments. Download the corresponding model weights file on the model zoo site and point to the downloaded file. Model 'osnet_ain_x1_0' with domain generalized training on (MS+D+C) is provide by default, together with the corresponding weights. Ifembedder='torchreid'when initalizingDeepSortobject without specifyingembedder_model_nameorembedder_wts, it will default to that.fromdeep_sort_realtime.deepsort_trackerimportDeepSorttracker=DeepSort(max_age=5,embedder='torchreid')bbs=object_detector.detect(frame)tracks=tracker.update_tracks(bbs,frame=frame)# bbs expected to be a list of detections, each in tuples of ( [left,top,w,h], confidence, detection_class )fortrackintracks:ifnottrack.is_confirmed():continuetrack_id=track.track_idltrb=track.to_ltrb()CLIPCLIPis added as another option of embedder due to its proven flexibility and generalisability. Download the CLIP model weights you want atdeep_sort_realtime/embedder/weights/download_clip_wts.shand store the weights at that directory as well, or you can provide your own CLIP weights throughembedder_wtsargument of theDeepSortobject.Tensorflow EmbedderAvailable now atdeep_sort_realtime/embedder/embedder_tf.py, as alternative to (the default) pytorch embedder. Tested on Tensorflow 2.3.1. You need to make your own code change to use it.The tf MobilenetV2 weights (pretrained on imagenet) are not available in this github repo (unlike the torch one). Download from thislinkor rundownload script. You may drop it intodeep_sort_realtime/embedder/weights/before pip installing.Background MaskingIf instance mask is given duringDeepSort.update_trackswith no external appearance embeddings given, the mask will be used to mask out the background of the corresponding detection crop so that only foreground information goes into the embedder. This reduces background bias.ExampleExample cosine distances between images in./test/("diff": rock vs smallapple, "close": smallapple vs smallapple slightly augmented).Testing pytorch embedder
close: 0.012196660041809082 vs diff: 0.4409685730934143

.Testing Torchreid embedder
Model: osnet_ain_x1_0
- params: 2,193,616
- flops: 978,878,352
Successfully loaded pretrained weights from "/Users/levan/Workspace/deep_sort_realtime/deep_sort_realtime/embedder/weights/osnet_ain_ms_d_c_wtsonly.pth"
close: 0.012312591075897217 vs diff: 0.4590487480163574