jgraving / pinpoint

pinpoint is a Python library for generating and tracking 2D barcode tags.

pinpoint: behavioral tracking using 2D barcode tags

pinpoint is a Python library for generating and tracking 2D barcode tags. The library uses numpy and matplotlib to generate barcode tags and uses OpenCV to automatically track each tag. It provides a high-level API for the automated measurement of animal behavior and locomotion.

This software is still in early-release development. Expect some adventures.

Citing

If you use this software for academic research, please consider citing it using this zenodo DOI:

Installation

Install the development version:

pip install git+https://www.github.com/jgraving/pinpoint.git

Dependencies

• Python 3.5+

• numpy

• scipy

• matplotlib

• scikit-learn

• numba

• OpenCV 3.1+

Development

https://github.com/jgraving/pinpoint

Please submit bugs or feature requests to the GitHub issue tracker

License

Released under a Apache 2.0 License. See LICENSE for details.

References

pinpoint is based on ArUco:

Garrido-Jurado, S., Muñoz-Salinas, R., Madrid-Cuevas, F. J., & Marín-Jiménez, M. J. (2014). Automatic generation and detection of highly reliable fiducial markers under occlusion. Pattern Recognition, 47(6), 2280-2292.

Other similar marker systems are also publicly available, such as AprilTag:

Wang, J., & Olson, E. (2016). AprilTag 2: Efficient and robust fiducial detection. In Intelligent Robots and Systems (IROS), 2016 IEEE/RSJ International Conference (pp. 4193-4198). IEEE.

If you require barcode tracking in MATLAB see BEETag:

Crall, J. D., Gravish, N., Mountcastle, A. M., & Combes, S. A. (2015). BEEtag: a low-cost, image-based tracking system for the study of animal behavior and locomotion. PloS one, 10(9), e0136487.

pinpoint's Issues

Error in match_barcodes

We get an error in match_barcodes while tracking, in line 677 utils.py:

best_id_list = id_list[index]

Probably when the last barcode of the barcode list is detected, since index always exceeds the size of the id_list (by 2). This could possibly affect also the matching for other barcodes, if all indeces are wrong.

best_id_list = id_list[index - 2]

prevents the error, but obviously the ids are wrong because of this. I guess videos get sometimes tracked without an error, because the tag with the last id is never detected, but in these videos, ids are still wrong. We couldn't track any video with reasonable results in the last few days (using different tags and pinpoint 0.2-dev and the newest).

Error installing pinpoint using pip

Its seems like you have some hidden or special character formatting on some of your Icon files like "barcodes/5x5_10bit/Icon\r" which is causing problems under installation on windows.

Console output:
C:\Users\user>pip install https://github.com/jgraving/pinpoint/archive/v0.0.1-alpha.zip
Collecting https://github.com/jgraving/pinpoint/archive/v0.0.1-alpha.zip
Downloading https://github.com/jgraving/pinpoint/archive/v0.0.1-alpha.zip \ 1.3MB 3.2MB/s
ERROR: Could not install packages due to an EnvironmentError: [Errno 22] Invalid argument: 'C:\Users\user\AppData\Local\Temp\pip-req-build-sru32ebf\barcodes/5x5_10bit/Icon\r

Generating barcodes

It'd be nice to have an example notebook to generate barcodes as well.

Thanks so much!

Vivek

Feature request: total frame count and metadata

Since the last frame with detected codes is not necessarily the last frame of the video, it would be helpful to have also the total frame count outputted in the h5 file (and maybe other video metadata).

This feature is especially important for multiple camera setups to avoid omitting frames between sequential videos.