owlps/owlps-positioner/src/measurement.hh

/*
 * This file is part of the Owl Positioning System (OwlPS).
 * OwlPS is a project of the University of Franche-Comté
 * (Université de Franche-Comté), France.
 */


#ifndef _OWLPS_POSITIONING_MEASUREMENT_HH_
#define _OWLPS_POSITIONING_MEASUREMENT_HH_

#include "accesspoint.hh"

#include <map>
#include <ostream>
#include <cmath>

typedef uint_fast16_t pkt_id_t ;
typedef int_fast16_t ss_t ;

/// Represents a list of signal strengths captured by one AccessPoint
class Measurement
{
protected:
  /// The AccessPoint that performed the measurement
  AccessPoint *ap ;
  /// List of signal strengths captured (in dBm)
  std::map<pkt_id_t, ss_t> ss_list ;
  /// Average of all the captured signal strengths (dBm)
  float average_dbm ;
  /// Average of all the captured signal strengths (mW)
  float average_mw ;
  /// Variance of all the captured signal strengths
  float variance ;

private:
  /// Intermediate variable used to compute the variance
  float variance_m2 ;


protected:
  /** @name Operations */
  //@{
  /// Recalculates entirely the average and variance from #ss_list
  void recalculate_average(void) ;
  /// Update the average and variance with a new SS
  void update_average(ss_t ss_dbm) ;
  //@}


public:
  Measurement(const AccessPoint *_ap = NULL):
    ap(const_cast<AccessPoint*>(_ap)), average_dbm(0),
    average_mw(0), variance(0), variance_m2(0) {}

  Measurement(const Measurement &source):
    ap(source.ap), ss_list(source.ss_list),
    average_dbm(source.average_dbm), average_mw(source.average_mw),
    variance(source.variance), variance_m2(0) {}

  ~Measurement(void) ;

  /** @name Read accessors */
  //@{
  /// Returns the AccessPoint associated with the Measurement
  AccessPoint* get_ap() const ;
  /// Returns the packet number \em pkt_id
  ss_t get_ss(pkt_id_t pkt_id) const ;
  /// Returns the mean of the SS list, in dBm
  float get_average_dbm() const ;
  /// Returns the variance of the SS list
  float get_variance() const ;
  /// Returns the standard deviation of the SS list
  float get_std_deviation() const ;
  /// Returns the number of SS in the SS list
  int get_nb_ss() const ;
  //@}

  /** @name Write accessors */
  //@{
  /// Associate the Measurement with an AccessPoint
  void set_ap(const AccessPoint *_ap) ;
  /// Adds a signal strength (in dBm) to #ss_list
  void add_ss(const pkt_id_t packet_id, const ss_t ss_dbm) ;
  /// Adds several signal strengths (in dBm) to #ss_list
  void add_ss_list(const std::map<pkt_id_t, ss_t> &_ss_list) ;
  /// Merges a given Measurement into the current Measurement
  void merge(const Measurement &source) ;
  /// Reset all the attributes
  void clear(void) ;
  //@}

  /** @name Operations */
  //@{
  /// Computes the similarity with another Measurement in the SS space
  float similarity(const Measurement &source) const ;
  /// Computes the distance to another Measurement's SS average
  float ss_square_distance(const Measurement &source) const ;
  /// Computes the distance to another SS value (in dBm)
  float ss_square_distance(const float &ss_dbm) const ;
  /// Computes the distance to another Measurement's variance
  float variance_square_distance(const Measurement &source) const ;
  /// Computes the distance to another variance value
  float variance_square_distance(const float &var) const ;
  //@}

  /** @name Operators */
  //@{
  Measurement& operator=(const Measurement &m) ;
  bool operator==(const Measurement &m) const ;
  bool operator!=(const Measurement &m) const ;
  operator bool(void) const ;
  //@}

  /** @name Conversion accessors */
  //@{
  /// Converts to a CSV string
  const std::string to_csv(void) const ;
  //@}

  /// Displays a Measurement
  friend std::ostream &operator<<(std::ostream &os, const Measurement &m) ;
} ;



/* *** Read accessors *** */


inline AccessPoint* Measurement::get_ap() const
{
  return ap ;
}


inline float Measurement::get_average_dbm() const
{
  return average_dbm ;
}


inline float Measurement::get_variance() const
{
  return variance ;
}


inline float Measurement::get_std_deviation() const
{
  return sqrt(variance) ;
}


inline int Measurement::get_nb_ss() const
{
  return ss_list.size() ;
}



/* *** Write accessors *** */


inline void Measurement::set_ap(const AccessPoint *_ap)
{
  ap = const_cast<AccessPoint*>(_ap) ;
}



/* *** Operations *** */


inline float Measurement::
ss_square_distance(const Measurement &source) const
{
  return ss_square_distance(source.average_dbm) ;
}


inline float Measurement::ss_square_distance(const float &ss_dbm) const
{
  return ((ss_dbm - average_dbm) * (ss_dbm - average_dbm)) ;
}


inline float Measurement::
variance_square_distance(const Measurement &source) const
{
  return variance_square_distance(source.variance) ;
}


inline float Measurement::
variance_square_distance(const float &var) const
{
  return ((var - variance) * (var - variance)) ;
}



/* *** Operators *** */


inline bool Measurement::operator!=(const Measurement &m) const
{
  return !(*this == m) ;
}


/**
 * @return \em false if the Measurement is empty.
 * @return \em true if at least one attribute is initialised.
 */
inline Measurement::operator bool() const
{
  return
    ap != NULL ||
    ! ss_list.empty() ;
}



#endif // _OWLPS_POSITIONING_MEASUREMENT_HH_