vision
gml_TrackedObject.h

00001 // gml_TrackedObject.h
00002 //
00003 //   Define the gml_TTrackedObject class.
00004 //
00005 //  Copyright (c) 2004 CLIPS-IMAG
00006 //
00007 //  See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00008 //  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00009 //
00010 //  Created in March 2004 (JL).
00011 
00012 #ifndef __GML_TRACKED_OBJECT__
00013 #define __GML_TRACKED_OBJECT__
00014 
00015 // project headers
00016 #include "gml/image/gml_Geometry.h"
00017 #include "gml/base/gml_Types.h"
00018 #include "gml/base/gml_Errors.h"
00019 #include "gml/base/gml_Queue.h"
00020 
00021 
00022 ///
00023 /// gml_TTrackingEvent --
00024 ///   Type of events that can occur during tracking
00025 ///
00026 struct gml_TTrackingEvent
00027 {
00028   /// categories of tracking events
00029   enum Type { Noop, Appear, Motion, Disappear };
00030 
00031   Type            fType;        ///< type of the event
00032   UInt32          fIdentity;    ///< unique identifier of the event source object
00033   gml_TPointFloat fPoint;       ///< coordinates associated with the event
00034   UInt64          fTimeStamp;   ///< event generation timestamp (nanoseconds)
00035 
00036   char *Name ();                ///< name associated with the event's type
00037 };
00038 
00039 
00040 ///
00041 /// gml_TTrackingEventQueue --
00042 ///   Queues of tracking events
00043 ///
00044 typedef gml_TQueue<gml_TTrackingEvent> gml_TTrackingEventQueue;
00045 
00046 
00047 
00048 ////////////////////////////////////////////////////////////////////////////////
00049 //                                                                            //
00050 //                      gml_TTrackedObject class declaration                  //
00051 //                                                                            //
00052 ////////////////////////////////////////////////////////////////////////////////
00053 
00054 ///
00055 /// gml_TTrackedObject --
00056 ///   Representation of objects tracked in 2D by the gml_TTracker class.
00057 ///
00058 class gml_TTrackedObject : public gml_TPointFloat
00059 {
00060 public:
00061 
00062   ///
00063   /// State -- 
00064   ///   Internal tracking state of a tracked object
00065   ///
00066   ///   Possible state transitions:
00067   ///   @verbatim
00068   ///             .-> Alive <--> Zombie -,
00069   ///       Born -|                      |-> Dead
00070   ///             '----------------------'          @endverbatim
00071   enum State { 
00072     Born,         ///< the object was recently detected
00073     Alive,        ///< the object was consistently detected and is tracked
00074     Zombie,       ///< the object wasn't detected, and might be either gone or missed
00075     Dead          ///< the object is not to be tracked anymore
00076   };
00077 
00078   /// 
00079   /// Init --
00080   ///   Setup tracked object data
00081   ///
00082   gml_TError Init (
00083     gml_TPointFloat object,
00084     gml_TTrackingEventQueue *queue,                       ///< where to push the events
00085     UInt64 startDelay     = sDefaultStartDelay(),         ///< see fStartDelay
00086     UInt64 ttlDelay       = sDefaultTTLDelay(),           ///< see fTTLDelay
00087     Float32 stability     = sDefaultStaticStability()     ///< see fStaticStability
00088   );
00089   
00090   
00091   ///
00092   /// Dispose --
00093   ///
00094   void Dispose (UInt64 time);
00095   
00096   
00097   ///
00098   /// Update --
00099   ///   Update object's state and (eventually) generate events
00100   ///
00101   gml_TError Update (
00102       bool detected,                  ///< was the object detected ?
00103       UInt64 gap,                     ///< since when (in nanoseconds) ?
00104       UInt64 time,                    ///< the current timestamp (nanoseconds)
00105       gml_TPointFloat * object        ///< the current object position (or NULL)
00106     );
00107 
00108 
00109   /// 
00110   /// GetState --
00111   ///   Return the current state of the tracked object
00112   ///
00113   State GetState () { return fState; }
00114 
00115 protected:
00116 
00117   UInt32    fIdentity;        ///< UID of the object
00118   UInt64    fLifeTime;        ///< time since the object was born   (relevant while in Born state)
00119   UInt64    fTimeToLive;      ///< remaining lifetime of the object (relevant while in Zombie state)
00120   State     fState;           ///< current object state
00121   
00122   UInt64    fStartDelay;      ///< time after which a consistently detected object will be tracked (nanoseconds).
00123                               ///< i.e. delay for the Born -> Alive transition
00124   UInt64    fTTLDelay;        ///< time after which an object will die if undetected (nanoseconds).
00125                               ///< i.e. delay for the Zombie -> Dead transition
00126   Float32   fStaticStability; ///< threshold under which object motion is discarded (pixels).
00127   
00128   gml_TTrackingEventQueue* fQueue;
00129 
00130 
00131 public:
00132 
00133   // errors
00134   static gml_TError sErrorBadState;
00135 
00136   // defaults
00137   static UInt64   sDefaultStartDelay() { return (UInt64) 200e6; } ///< default for fStartDelay
00138   static UInt64   sDefaultTTLDelay()   { return (UInt64) 150e6; } ///< default for fTTLDelay
00139   static Float32  sDefaultStaticStability() { return 1.5F; }      ///< default for fStaticStability
00140 
00141 protected:
00142   // setup
00143   static void ClassInit ();     ///< class setup
00144   static bool sModuleInited;    ///< was ClassInit() called ? 
00145 
00146 };
00147 
00148 #endif /* __GML_TRACKED_OBJECT__ */
00149