Implementation of jamFactor in HSDK

Displayed Correctly When Using jamFactor in HERE SDK
====================================================

Applies To
----------

HERE SDK (HSDK)
Android applications using MapPolyline
Traffic visualization based on route or traffic flow attributes

Symptoms
--------

Customers may observe one or more of the following:

Traffic polylines are not displayed on the map for some road segments.
Only yellow, red, or black traffic lines are visible while other segments are not rendered.
jamFactor values below a certain threshold do not produce any visual output.
Route traffic congestion appears incomplete compared to expected traffic coverage.
Traffic severity colors do not match the perceived traffic conditions.

Answer
------

This behavior is expected. The jamFactor is a numeric traffic severity indicator ranging from 0 to 10. In the provided implementation, road segments with a jamFactor below 4 are intentionally not rendered because the method returns null, which causes the rendering logic to skip those segments.

The following mapping is used:

| jamFactor Value | Traffic Condition | Rendering Behavior |
| --- | --- | --- |
| 0 <= jamFactor < 4 | No traffic or light traffic | Not rendered (null returned) |
| 4 <= jamFactor < 8 | Moderate or slow traffic | Yellow polyline |
| 8 <= jamFactor < 10 | Heavy or severe traffic | Red polyline |
| jamFactor = 10 | Road blocked | Black polyline |

Root Cause
----------

The implementation intentionally suppresses visualization of low-congestion segments to reduce map clutter and highlight relevant traffic conditions. The logic is defined in the getTrafficColor() method:

if (jamFactor == null || jamFactor < 4) {<br /><br />return null;<br /><br />}

When null is returned, the addTrafficPolylines() method exits before creating a MapPolyline.

Impact
------

Roads with light or free-flowing traffic are not displayed as traffic overlays.
Users may incorrectly assume traffic data is missing when the actual cause is the rendering logic.
Only moderate, severe, and blocked traffic conditions receive visual emphasis.

Recommended Action
------------------

If all traffic levels should be displayed, modify the color mapping logic to assign a color to low-congestion segments instead of returning null.

If the goal is to emphasize only traffic delays and congestion, the current implementation is appropriate and can remain unchanged.

Expected vs. Unexpected Behavior
--------------------------------

Expected Behavior

No overlay is displayed for jamFactor < 4.
Yellow overlay is displayed for moderate congestion.
Red overlay is displayed for severe congestion.
Black overlay is displayed for blocked roads (jamFactor = 10).

Unexpected Behavior

Valid jamFactor >= 4 values do not render despite successful polyline creation.
* Exceptions occur during MapPolyline or MapMeasureDependentRenderSize instantiation.

Example Color Mapping
---------------------

@Nullable

private Color getTrafficColor(Double jamFactor) {<br /><br />if (jamFactor == null || jamFactor < 4) {<br /><br />return null;<br /><br />} else if (jamFactor >= 4 && jamFactor < 8) {<br /><br />return Color.valueOf(1, 1, 0, 0.63f);<br /><br />} else if (jamFactor >= 8 && jamFactor < 10) {<br /><br />return Color.valueOf(1, 0, 0, 0.63f);<br /><br />}<br /><br />return Color.valueOf(0, 0, 0, 0.63f);<br /><br />}

Keywords / Tags
---------------

jamFactor, traffic visualization, HERE SDK, HSDK Android, MapPolyline, traffic congestion, route traffic, traffic colors, blocked road, severe traffic, moderate traffic, traffic overlay, GeoPolyline, map rendering, traffic flow data