drifty/comaps
1
0
Fork 0
mirror of https://codeberg.org/comaps/comaps synced 2025-12-19 13:03:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

[traffic] Add documentation

Browse Source 
Signed-off-by: mvglasow <michael -at- vonglasow.com>
This commit is contained in:
mvglasow
2025-04-08 20:28:20 +03:00
parent 1574b5b7cb
commit 9c93f421ac
3 changed files with 120 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
map/traffic_manager.hpp
View File

@@ -68,9 +68,27 @@ public:
void SetStateListener(TrafficStateChangedFn const & onStateChangedFn);
void SetDrapeEngine(ref_ptr<df::DrapeEngine> engine);
/**
* @brief Sets the version of the MWM used locally.
*/
void SetCurrentDataVersion(int64_t dataVersion);
/**
* @brief Enables or disables the traffic manager.
*
* This sets the internal state and notifies the drape engine. Enabling the traffic manager will
* invalidate its data, disabling it will notify the observer that traffic data has been cleared.
*
* Calling this function with `enabled` identical to the current state is a no-op.
*
* @param enabled True to enable, false to disable
*/
void SetEnabled(bool enabled);
/**
* @brief Whether the traffic manager is enabled.
*
* @return True if enabled, false if not
*/
bool IsEnabled() const;
void UpdateViewport(ScreenBase const & screen);

50
traffic/speed_groups.hpp
View File

@@ -5,6 +5,15 @@
namespace traffic
{
/**
* A bucket for the ratio of the speed of moving traffic to the posted speed limit.
*
* Let Vmax be the posted speed limit and Vreal the speed at which traffic is currently flowing
* or expected to flow. The possible ratios (Vreal/Vmax) are grouped into buckets and, from then
* on, only the bucket number is used.
*
* The threshold ratios for the individual values are defined in `kSpeedGroupThresholdPercentage`.
*/
enum class SpeedGroup : uint8_t
{
G0 = 0,
@@ -20,24 +29,33 @@ enum class SpeedGroup : uint8_t
static_assert(static_cast<uint8_t>(SpeedGroup::Count) <= 8, "");
// Let M be the maximal speed that is possible on a free road
// and let V be the maximal speed that is possible on this road when
// taking the traffic data into account.
// We group all possible ratios (V/M) into a small number of
// buckets and only use the number of a bucket everywhere.
// That is, we forget the specific values of V when transmitting and
// displaying traffic information. The value M of a road is known at the
// stage of building the mwm containing this road.
//
// kSpeedGroupThresholdPercentage[g] denotes the maximal value of (V/M)
// that is possible for group |g|. Values falling on a border of two groups
// may belong to either group.
//
// The threshold percentage is defined to be 100 for the
// special groups where V is unknown or not defined.
/**
* Threshold ratios for the individual values of `SpeedGroup`.
*
* Let Vmax be the posted speed limit and Vreal the speed at which traffic is currently flowing
* or expected to flow. The possible ratios (Vreal/Vmax) are grouped into buckets and, from then
* on, only the bucket number is used.
*
* `kSpeedGroupThresholdPercentage[g]` is the maximum percentage of Vreal/Vmax for group g. Values
* falling on the border of two groups may belong to either group.
*
* For special groups, where Vreal/Vmax is unknown or undefined, the threshold is 100%.
*/
extern uint32_t const kSpeedGroupThresholdPercentage[static_cast<size_t>(SpeedGroup::Count)];
/// \note This method is used in traffic jam generation.
/**
* Converts the ratio between speed of flowing traffic and the posted limit to a `SpeedGroup`.
*
* This method is used in traffic jam generation: Let Vmax be the posted speed limit and Vreal the
* speed at which traffic is currently flowing or expected to flow. The possible ratios
* (Vreal/Vmax) are grouped into buckets and, from then on, only the bucket number is used.
*
* This method performs the conversion from the ratio to a `SpeedGroup` bucket.
*
* @param p Vreal / Vmax * 100% (ratio expressed in percent)
*
* @return the `SpeedGroup` value which corresponds to `p`
*/
SpeedGroup GetSpeedGroupByPercentage(double p);
std::string DebugPrint(SpeedGroup const & group);

86
traffic/traffic_info.hpp
View File

@@ -15,8 +15,10 @@ class HttpClient;
namespace traffic
{
// This class is responsible for providing the real-time
// information about road traffic for one mwm file.
/**
* @brief The `TrafficInfo` class is responsible for providing the real-time information about road
* traffic for one MWM.
*/
class TrafficInfo
{
public:
@@ -32,6 +34,16 @@ public:
Unknown
};
/**
* @brief The RoadSegmentId struct models a segment of a road.
*
* A road segment is the link between two consecutive points of an OSM way. The way must be
* tagged with a valid `highway` tag. A segment refers to a single direction.
*
* Therefore, an OSM way with `n` points has `n - 1` segments if tagged as one-way, `2 (n - 1)`
* otherwise (as each pair of adjacent points is connected by two segments, one in each
* direction.)
*/
struct RoadSegmentId
{
// m_dir can be kForwardDirection or kReverseDirection.
@@ -71,6 +83,9 @@ public:
uint8_t m_dir : 1;
};
/**
* @brief Mapping from feature segments to speed groups (see `speed_groups.hpp`), for one MWM.
*/
// todo(@m) unordered_map?
using Coloring = std::map<RoadSegmentId, SpeedGroup>;
@@ -78,30 +93,62 @@ public:
TrafficInfo(MwmSet::MwmId const & mwmId, int64_t currentDataVersion);
/**
* @brief Returns a `TrafficInfo` instance with pre-populated traffic information.
* @param coloring The traffic information (road segments and their speed group)
* @return The new `TrafficInfo` instance
*/
static TrafficInfo BuildForTesting(Coloring && coloring);
void SetTrafficKeysForTesting(std::vector<RoadSegmentId> const & keys);
// Fetches the latest traffic data from the server and updates the coloring and ETag.
// Construct the url by passing an MwmId.
// The ETag or entity tag is part of HTTP, the protocol for the World Wide Web.
// It is one of several mechanisms that HTTP provides for web cache validation,
// which allows a client to make conditional requests.
// *NOTE* This method must not be called on the UI thread.
/**
* @brief Fetches the latest traffic data from the server and updates the coloring and ETag.
*
* The url is constructed using the `mwmId` specified in the constructor.
*
* The ETag or entity tag is part of HTTP, the protocol for the World Wide Web.
* It is one of several mechanisms that HTTP provides for web cache validation,
* which allows a client to make conditional requests.
*
* NOTE: This method must not be called on the UI thread.
*
* @param etag The entity tag
* @return True on success, false on failure.
*/
bool ReceiveTrafficData(std::string & etag);
// Returns the latest known speed group by a feature segment's id
// or SpeedGroup::Unknown if there is no information about the segment.
/**
* @brief Returns the latest known speed group by a feature segment's ID.
* @param id The road segment ID.
* @return The speed group, or `SpeedGroup::Unknown` if no information is available.
*/
SpeedGroup GetSpeedGroup(RoadSegmentId const & id) const;
MwmSet::MwmId const & GetMwmId() const { return m_mwmId; }
Coloring const & GetColoring() const { return m_coloring; }
Availability GetAvailability() const { return m_availability; }
// Extracts RoadSegmentIds from mwm and stores them in a sorted order.
/**
* @brief Extracts RoadSegmentIds from an MWM and stores them in a sorted order.
* @param mwmPath Path to the MWM file
*/
static void ExtractTrafficKeys(std::string const & mwmPath, std::vector<RoadSegmentId> & result);
// Adds the unknown values to the partially known coloring map |knownColors|
// so that the keys of the resulting map are exactly |keys|.
/**
* @brief Adds unknown values to a partially known coloring map.
*
* After this method returns, the keys of `result` will be exactly `keys`. The speed group
* associated with each key will be the same as in `knownColors`, or `SpeedGroup::Unknown` for
* keys which are not found in `knownColors`.
*
* Keys in `knownColors` which are not in `keys` will be ignored.
*
* If `result` contains mappings prior to this method being called, they will be deleted.
*
* @param keys The keys for the result map.
* @param knownColors The map containing the updates.
* @param result The map to be updated.
*/
static void CombineColorings(std::vector<TrafficInfo::RoadSegmentId> const & keys,
TrafficInfo::Coloring const & knownColors,
TrafficInfo::Coloring & result);
@@ -143,13 +190,16 @@ private:
ServerDataStatus ProcessFailure(platform::HttpClient const & request, int64_t const mwmVersion);
// The mapping from feature segments to speed groups (see speed_groups.hpp).
/**
* @brief The mapping from feature segments to speed groups (see speed_groups.hpp).
*/
Coloring m_coloring;
// The keys of the coloring map. The values are downloaded periodically
// and combined with the keys to form m_coloring.
// *NOTE* The values must be received in the exact same order that the
// keys are saved in.
/**
* @brief The keys of the coloring map. The values are downloaded periodically
* and combined with the keys to form `m_coloring`.
* *NOTE* The values must be received in the exact same order that the keys are saved in.
*/
std::vector<RoadSegmentId> m_keys;
MwmSet::MwmId m_mwmId;