ObjectTracker Class Reference

Simple color-based object detection/tracking. More...

Inheritance diagram for ObjectTracker:

Collaboration diagram for ObjectTracker:

Public Member Functions
	ObjectTracker (std::string const &instance)
	Constructor.
virtual	~ObjectTracker ()
	Virtual destructor for safe inheritance.
virtual void	process (jevois::InputFrame &&inframe) override
	Processing function, no USB video output.
virtual void	process (jevois::InputFrame &&inframe, jevois::OutputFrame &&outframe) override
	Processing function, with USB video output.
Public Member Functions inherited from jevois::StdModule
	StdModule (std::string const &instance)
virtual	~StdModule ()
void	sendSerialImg1Dx (unsigned int camw, float x, float size=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialStd1Dx (float x, float size=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialImg1Dy (unsigned int camh, float y, float size=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialStd1Dy (float y, float size=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialImg2D (unsigned int camw, unsigned int camh, float x, float y, float w=0.0F, float h=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialStd2D (float x, float y, float w=0.0F, float h=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialContour2D (unsigned int camw, unsigned int camh, std::vector< cv::Point_< T > > points, std::string const &id="", std::string const &extra="")
void	sendSerialStd3D (float x, float y, float z, float w=0.0F, float h=0.0F, float d=0.0F, float q1=0.0F, float q2=0.0F, float q3=0.0f, float q4=0.0F, std::string const &id="", std::string const &extra="")
void	sendSerialStd3D (std::vector< cv::Point3f > points, std::string const &id="", std::string const &extra="")
void	sendSerialObjReco (std::vector< ObjReco > const &res)
void	sendSerialObjDetImg2D (unsigned int camw, unsigned int camh, float x, float y, float w, float h, std::vector< ObjReco > const &res)
void	sendSerialObjDetImg2D (unsigned int camw, unsigned int camh, ObjDetect const &det)
void	sendSerialObjDetImg2D (unsigned int camw, unsigned int camh, ObjDetectOBB const &det)
	JEVOIS_DEFINE_ENUM_CLASS (SerStyle,(Terse)(Normal)(Detail)(Fine))
	JEVOIS_DECLARE_PARAMETER (serstyle, SerStyle, "Style for standardized serial messages as defined in " "http://jevois.org/doc/UserSerialStyle.html", SerStyle::Terse, SerStyle_Values, ParamCateg)
	JEVOIS_DECLARE_PARAMETER (serprec, unsigned int, "Number of decimal points in standardized serial messages as " "defined in http://jevois.org/doc/UserSerialStyle.html", 0U, jevois::Range< unsigned int >(0U, 10U), ParamCateg)
	JEVOIS_DEFINE_ENUM_CLASS (SerStamp,(None)(Frame)(Time)(FrameTime)(FrameDateTime))
	JEVOIS_DECLARE_PARAMETER (serstamp, SerStamp, "Prepend standardized serial messages with a frame number, " "time, frame+time, or frame+date+time. See details in " "http://jevois.org/doc/UserSerialStyle.html", SerStamp::None, SerStamp_Values, ParamCateg)
	JEVOIS_DEFINE_ENUM_CLASS (SerMark,(None)(Start)(Stop)(Both))
	JEVOIS_DECLARE_PARAMETER (sermark, SerMark, "Send serial message to mark the beginning (MARK START) of the " "processing of a video frame from the camera sensor, the end (MARK STOP), or both. " "Useful, among others, if one needs to know when no results were sent over serial " "on a given frame. Combine with parameter serstamp if you need to know the frame number.", SerMark::None, SerMark_Values, ParamCateg)
Public Member Functions inherited from jevois::Module
	Module (std::string const &instance)
virtual	~Module ()
virtual void	process (InputFrame &&inframe, GUIhelper &helper)
virtual void	sendSerial (std::string const &str)
virtual void	parseSerial (std::string const &str, std::shared_ptr< UserInterface > s)
virtual void	supportedCommands (std::ostream &os)
Public Member Functions inherited from jevois::Component
	Component (std::string const &instance)
virtual	~Component ()
std::shared_ptr< Comp >	addSubComponent (std::string const &instance, Args &&...args)
void	removeSubComponent (std::shared_ptr< Comp > &component)
void	removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
std::shared_ptr< Comp >	getSubComponent (std::string const &instance) const
bool	isTopLevel () const
bool	initialized () const
std::string const &	className () const
std::string const &	instanceName () const
std::vector< std::string >	setParamVal (std::string const &paramdescriptor, T const &val)
void	setParamValUnique (std::string const &paramdescriptor, T const &val)
std::vector< std::pair< std::string, T > >	getParamVal (std::string const &paramdescriptor) const
T	getParamValUnique (std::string const &paramdescriptor) const
std::vector< std::string >	setParamString (std::string const &paramdescriptor, std::string const &val)
void	setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
std::vector< std::pair< std::string, std::string > >	getParamString (std::string const &paramdescriptor) const
std::string	getParamStringUnique (std::string const &paramdescriptor) const
void	freezeParam (std::string const &paramdescriptor, bool doit)
void	freezeAllParams (bool doit)
std::string	descriptor () const
void	setParamsFromFile (std::string const &filename)
std::istream &	setParamsFromStream (std::istream &is, std::string const &absfile)
virtual void	paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
void	foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
void	setDynamicParameterCallback (std::string const &name, std::function< void(T const &)> cb, bool callnow=true)
void	removeDynamicParameter (std::string const &name, bool throw_if_not_found=true)
void	setPath (std::string const &path)
std::filesystem::path	absolutePath (std::filesystem::path const &path="")
std::shared_ptr< Comp >	addSubComponent (std::string const &instance, Args &&...args)
void	removeSubComponent (std::shared_ptr< Comp > &component)
void	removeSubComponent (std::string const &instance, bool warnIfNotFound=true)
std::shared_ptr< Comp >	getSubComponent (std::string const &instance) const
bool	isTopLevel () const
bool	initialized () const
std::string const &	className () const
std::string const &	instanceName () const
std::vector< std::string >	setParamVal (std::string const &paramdescriptor, T const &val)
void	setParamValUnique (std::string const &paramdescriptor, T const &val)
std::vector< std::pair< std::string, T > >	getParamVal (std::string const &paramdescriptor) const
T	getParamValUnique (std::string const &paramdescriptor) const
std::vector< std::string >	setParamString (std::string const &paramdescriptor, std::string const &val)
void	setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
std::vector< std::pair< std::string, std::string > >	getParamString (std::string const &paramdescriptor) const
std::string	getParamStringUnique (std::string const &paramdescriptor) const
void	freezeParam (std::string const &paramdescriptor, bool doit)
void	freezeAllParams (bool doit)
std::string	descriptor () const
void	setParamsFromFile (std::string const &filename)
std::istream &	setParamsFromStream (std::istream &is, std::string const &absfile)
virtual void	paramInfo (std::shared_ptr< UserInterface > s, std::map< std::string, std::string > &categs, bool skipFrozen, std::string const &cname="", std::string const &pfx="")
void	foreachParam (std::function< void(std::string const &compname, ParameterBase *p)> func, std::string const &cname="")
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ParameterCategory const &category)
std::shared_ptr< DynamicParameter< T > >	addDynamicParameter (std::string const &name, std::string const &description, T const &defaultValue, ValidValuesSpec< T > const &validValuesSpec, ParameterCategory const &category)
void	setDynamicParameterCallback (std::string const &name, std::function< void(T const &)> cb, bool callnow=true)
void	removeDynamicParameter (std::string const &name, bool throw_if_not_found=true)
void	setPath (std::string const &path)
std::filesystem::path	absolutePath (std::filesystem::path const &path="")
Public Member Functions inherited from jevois::ParameterRegistry
virtual	~ParameterRegistry ()

Related Symbols
(Note that these are not member symbols.)
	JEVOIS_DECLARE_PARAMETER (hrange, jevois::Range< unsigned char >, "Range of H values for HSV window (0=red/do not " "use because of wraparound, 30=yellow, 45=light green, 60=green, 75=green cyan, 90=cyan, " "105=light blue, 120=blue, 135=purple, 150=pink)", jevois::Range< unsigned char >(10, 245), ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (srange, jevois::Range< unsigned char >, "Range of S (saturation) values for HSV window", jevois::Range< unsigned char >(10, 245), ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (vrange, jevois::Range< unsigned char >, "Range of V (brightness) values for HSV window", jevois::Range< unsigned char >(10, 245), ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (maxnumobj, size_t, "Max number of objects to declare a clean image", 10, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (objectarea, jevois::Range< unsigned int >, "Range of object area (in pixels) to track", jevois::Range< unsigned int >(20 *20, 100 *100), ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (erodesize, size_t, "Erosion structuring element size (pixels)", 3, ParamCateg)
	Parameter.
	JEVOIS_DECLARE_PARAMETER (dilatesize, size_t, "Dilation structuring element size (pixels)", 8, ParamCateg)
	Parameter.

Additional Inherited Members
Protected Member Functions inherited from jevois::StdModule
void	sendSerialMarkStart ()
void	sendSerialMarkStop ()
std::string	getStamp () const
Protected Member Functions inherited from jevois::Component
virtual void	preInit ()
virtual void	postInit ()
virtual void	preUninit ()
virtual void	postUninit ()
virtual void	preInit ()
virtual void	postInit ()
virtual void	preUninit ()
virtual void	postUninit ()
Protected Member Functions inherited from jevois::ParameterRegistry
void	addParameter (ParameterBase *const param)
void	removeParameter (ParameterBase *const param)
void	callbackInitCall ()

Detailed Description

Simple color-based object detection/tracking.

This modules isolates pixels within a given HSV range (hue, saturation, and value of color pixels), does some cleanups, and extracts object contours. It sends information about object centers over serial.

This module usually works best with the camera sensor set to manual exposure, manual gain, manual color balance, etc so that HSV color values are reliable. See the file script.cfg file in this module's directory for an example of how to set the camera settings each time this module is loaded.

This code was loosely inspired by: https://raw.githubusercontent.com/kylehounslow/opencv-tuts/master/object-tracking-tut/objectTrackingTut.cpp written by Kyle Hounslow, 2013.

Serial Messages

This module can send standardized serial messages as described in Standardized serial messages formatting. One message is issued on every video frame for each detected and good object (good objects have a pixel area within the range specified by objectarea, and are only reported when the image is clean enough according to maxnumobj). The id field in the messages simply is blob for all messages.

• Serial message type: 2D
• id: always blob
• x, y, or vertices: standardized 2D coordinates of blob center or of corners of bounding box (depending on serstyle)
• w, h: standardized object size
• extra: none (empty string)

JeVois v1.8.1: Note that this module sends one message per detected object (blob) and per frame. You may want to specify setpar serstamp Frame if you need to get all the objects on one given frame (they will have the same frame number prefix). Here is an example output with setpar serstyle Detail and setpar serstamp Frame (see Standardized serial messages formatting for more info about serstamp and serstyle):

2940 D2 blob 4 -238 237 -238 19 13 19 13 237
2940 D2 blob 4 266 209 194 206 213 -277 285 -274
2940 D2 blob 4 575 -243 499 -511 613 -544 689 -275
2940 D2 blob 4 -150 -413 -150 -613 50 -613 50 -413
2940 D2 blob 4 -913 -306 -1000 -306 -1000 -750 -913 -750
2941 D2 blob 4 -313 119 -313 -106 -63 -106 -63 119
2941 D2 blob 4 189 105 115 99 157 -385 231 -379
2941 D2 blob 4 469 -275 469 -500 575 -500 575 -275
2941 D2 blob 4 -200 -531 -200 -744 -13 -744 -13 -531
2942 D2 blob 4 -381 -13 -381 -244 -113 -244 -113 -13
2942 D2 blob 4 478 -213 310 -402 414 -494 582 -305
2942 D2 blob 4 144 -6 53 -15 114 -668 206 -660

In this example, we detected 5 blobs on frame 2940, then 4 blobs on frame 2941, then 3 blobs on frame 2942.

See Standardized serial messages formatting for more on standardized serial messages, and Helper functions to convert coordinates from camera resolution to standardized for more info on standardized coordinates.

Trying it out

The default parameter settings (which are set in script.cfg explained below) attempt to detect light blue objects. Present a light blue object to the JeVois camera and see whether it is detected. When detected and good enough according to objectarea and maxnumobj, a green circle will be drawn at the center of each good object.

For further use of this module, you may want to check out the following tutorials:

• Tuning the color-based object tracker using a python graphical interface
• Making a motorized pan-tilt head for JeVois and tracking objects
• Tutorial on how to write Arduino code that interacts with JeVois

Tuning

You should adjust parameters hrange, srange, and vrange to isolate the range of Hue, Saturation, and Value (respectively) that correspond to the objects you want to detect. Note that there is a script.cfg file in this module's directory that provides a range tuned to a lighgt blue object, as shown in the demo screenshot.

Tuning the parameters is best done interactively by connecting to your JeVois camera while it is looking at some object of the desired color. Once you have achieved a tuning, you may want to set the hrange, srange, and vrange parameters in your script.cfg file for this module on the microSD card (see below).

Typically, you would start by narrowing down on the hue, then the value, and finally the saturation. Make sure you also move your camera around and show it typical background clutter so check for false positives (detections of things which you are not interested, which can happen if your ranges are too wide).

Config file

JeVois allows you to store parameter settings and commands in a file named script.cfg stored in the directory of a module. The file script.cfg may contain any sequence of commands as you would type them interactively in the JeVois command-line interface. For the ObjectTracker module, a default script is provided that sets the camera to manual color, gain, and exposure mode (for more reliable color values), and to setup communication with a pan/tilt head as described in Tutorial on how to write Arduino code that interacts with JeVois.

The script.cfg file for ObjectTracker is stored on your microSD at JEVOIS:/modules/JeVois/ObjectTracker/script.cfg and is shown in Tutorial on how to write Arduino code that interacts with JeVois as an example.

Author

Laurent Itti

Videomapping:

YUYV 320 254 60.0 YUYV 320 240 60.0 JeVois ObjectTracker

Videomapping:

NONE 0 0 0.0 YUYV 320 240 60.0 JeVois ObjectTracker

Email:

itti@usc.edu

Address:

University of Southern California, HNB-07A, 3641 Watt Way, Los Angeles, CA 90089-2520, USA

Copyright

Copyright (C) 2016 by Laurent Itti, iLab and the University of Southern California

Main URL:

http://jevois.org

Support URL:

http://jevois.org/doc

Other URL:

http://iLab.usc.edu

License:

GPL v3

Distribution:

Unrestricted

Restrictions:

None

Definition at line 159 of file ObjectTracker.C.

Constructor & Destructor Documentation

ObjectTracker()

ObjectTracker::ObjectTracker ( std::string const &  instance )

inline

Constructor.

Definition at line 163 of file ObjectTracker.C.

~ObjectTracker()

virtual ObjectTracker::~ObjectTracker ( )

inlinevirtual

Virtual destructor for safe inheritance.

Definition at line 170 of file ObjectTracker.C.

Member Function Documentation

process() [1/2]

virtual void ObjectTracker::process ( jevois::InputFrame &&  inframe )

inlineoverridevirtual

Processing function, no USB video output.

Reimplemented from jevois::Module.

Definition at line 173 of file ObjectTracker.C.

References jevois::rawimage::convertToCvBGR(), h, jevois::RawImage::height, jevois::StdModule::sendSerialContour2D(), and jevois::RawImage::width.

process() [2/2]

virtual void ObjectTracker::process ( jevois::InputFrame &&  inframe, jevois::OutputFrame &&  outframe  )

inlineoverridevirtual

Processing function, with USB video output.

Reimplemented from jevois::Module.

Definition at line 193 of file ObjectTracker.C.

References area(), jevois::async(), jevois::rawimage::convertToCvBGR(), jevois::rawimage::cvImage(), jevois::rawimage::drawCircle(), jevois::rawimage::drawFilledRect(), jevois::RawImage::fmt, h, jevois::RawImage::height, jevois::yuyv::LightGreen, jevois::yuyv::LightPink, jevois::rawimage::paste(), jevois::RawImage::require(), jevois::StdModule::sendSerialContour2D(), jevois::Timer::start(), jevois::Timer::stop(), jevois::yuyv::White, jevois::RawImage::width, and jevois::rawimage::writeText().

Friends And Related Symbol Documentation

JEVOIS_DECLARE_PARAMETER() [1/7]

JEVOIS_DECLARE_PARAMETER ( dilatesize  , size_t  , "Dilation structuring element size (pixels)"  , 8  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [2/7]

JEVOIS_DECLARE_PARAMETER ( erodesize  , size_t  , "Erosion structuring element size (pixels)"  , 3  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [3/7]

JEVOIS_DECLARE_PARAMETER ( hrange  , jevois::Range< unsigned char >  , "Range of H values for HSV window (0=red/do not " "use because of wraparound, 30=yellow, 45=light green, 60=green, 75=green cyan, 90=cyan, " "105=light blue, 120=blue, 135=purple, 150=pink)"  , jevois::Range< unsigned char >  10, 245, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [4/7]

JEVOIS_DECLARE_PARAMETER ( maxnumobj  , size_t  , "Max number of objects to declare a clean image"  , 10  , ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [5/7]

JEVOIS_DECLARE_PARAMETER ( objectarea  , jevois::Range< unsigned int >  , "Range of object area (in pixels) to track"  , jevois::Range< unsigned int >  20 *20, 100 *100, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [6/7]

JEVOIS_DECLARE_PARAMETER ( srange  , jevois::Range< unsigned char >  , "Range of S (saturation) values for HSV window"  , jevois::Range< unsigned char >  10, 245, ParamCateg    )

related

Parameter.

JEVOIS_DECLARE_PARAMETER() [7/7]

JEVOIS_DECLARE_PARAMETER ( vrange  , jevois::Range< unsigned char >  , "Range of V (brightness) values for HSV window"  , jevois::Range< unsigned char >  10, 245, ParamCateg    )

related

Parameter.

---

The documentation for this class was generated from the following files:

• src/Modules/ObjectTracker/ObjectTracker.C
• include/jevoisbase/Components/ObjectDetection/BlobDetector.H