[Feedback Requested] : [RFC] Add Traffic Color Support to Route Visualization

[radityagumay]

Feature Name: traffic_color

Type: feature
Start Date: 2025-08-21
Author: Raditya Gumay
Related components: Ferrostar Core (annotations), Routing backend, Android MapLibre UI, iOS MapLibre UI, React Native UI
Link issues: (TBD)

Summary

Traffic color is a basic feature in map/navigation apps. Ferrostar currently does not provide traffic-based route coloring out of the box. This RFC describes how to leverage OSRM-style annotations (https://project-osrm.org/docs/v5.24.0/api/#annotation-object) and the Ferrostar annotations pipeline (https://stadiamaps.github.io/ferrostar/annotations.html) to add traffic-aware coloring.

I recommend a server-driven approach that provides pre-colored per-segment annotations, while supporting client-side derivation from speed metrics when colors are not provided. A simple Blue/Orange/Red scheme is proposed, with clear thresholds and a fallback.

Motivation

• Meet user expectations for traffic visualization in navigation UIs.
• Improve situational awareness and decision-making along the route.
• Maintain cross-platform consistency with a shared data model and color policy.
• Keep clients performant and simple by preferring server-provided colors, with a deterministic client fallback.

Goals

• Provide per-segment traffic coloring for the active route using OSRM-style annotations.
• Maintain a consistent, documented color policy across platforms.
• Enable a deterministic client fallback based on speed metrics when explicit colors are absent.

Non-Goals

• Real-time traffic-based rerouting decisions.
• Defining or standardizing traffic ontologies beyond what is needed for coloring.
• Replacing OSRM/annotation semantics with a bespoke segment model.

---

Functional Requirements (High Level)

• Per-segment coloring: The active route is colored per segment to reflect traffic conditions.
• Server-preferred, client-fallback: Use server-provided colors when present; otherwise derive from available metrics.
• Cross-platform consistency: Same inputs produce the same visual outcome on Android, iOS, and Web.
• Backward compatibility: Existing clients without traffic annotations remain unaffected.

Non-Functional Requirements (High Level)

• Performance: Maintain smooth map interaction; avoid UI-thread blocking for processing.
• Reliability: Gracefully handle partial, missing, or malformed annotations.
• Determinism: Given identical inputs, produce consistent, repeatable colors across platforms.
• Accessibility & UX: Default palette remains legible on common basemaps and supports future accessibility themes.
• Maintainability: Minimize core API changes; centralize color/threshold policy per platform.

---

Detailed design

Data model

Use OSRM-style per-segment annotations aligned with geometry (arrays of length N−1 for N coordinates). A recommended traffic object per segment:

{
  "annotation": {
    "traffic": [
      {
        "congestion_level": "free_flow",
        "speed_kmh": 65,
        "typical_speed_kmh": 75,
        "congestion_color": "#3583dd"
      },
      {
        "unknown" : true,
      },
      {
        "congestion_level": "heavy",
        "speed_kmh": 12,
        "typical_speed_kmh": 20,
        "congestion_color": "#E74C3C"
      }
    ]
  }
}

Notes:

• traffic.congestion_color is recommended (server-specified). If absent, clients derive color from speeds (or optionally from congestion_level).
• Ferrostar slices route-level annotations into step-level arrays exposed via RouteStep.annotations (length = step.geometry.size − 1).
• congestion_level and typical_speed_kmh are mandatory
• speed_kmh and typical_speed_kmh are optional.
• in the case that no traffic on particular segment, using "unknown" : true, will fallback the internal on the SDK to return polyline color to blue

Color scheme policy

• Blue: Free-flowing traffic (> 80% of typical speed) — "#3583dd"
• Orange: Moderate congestion (40–80% of typical speed) — "#FFA500"
• Red: Heavy congestion (< 40% of typical speed) — "#E74C3C"
• Fallback: Blue when no traffic data is available

Color selection precedence

1. Explicit server color

• If traffic.congestion_color is a valid hex, use it verbatim.

2. Derived from speeds

• Compute ratio = speed_kmh / typical_speed_kmh.
• If inputs are missing/invalid (e.g., typical ≤ 0), use fallback Blue.
• If ratio > 0.80: Blue
• Else if 0.40 ≤ ratio ≤ 0.80: Orange
• Else (ratio < 0.40): Red

3. Optional: Derived from congestion_level

• If speeds are missing but an abstract level is provided, map level to the nearest policy color.

Pseudocode:

function trafficColor(traffic):
  // 1) explicit color
  if traffic.color isValidHex:
    return traffic.color
  if traffic.color_hint isValidHex:
    return traffic.color_hint

  // 2) derived from speeds
  let s = traffic.speed_kmh
  let t = traffic.typical_speed_kmh
  if s != null and t != null and t > 0:
    let ratio = s / t
    if ratio > 0.80: return "#3583dd" // Blue
    else if ratio >= 0.40: return "#FFA500" // Orange
    else: return "#E74C3C" // Red

  // 3) (optional) congestion_level mapping if desired by product
  // else fallback
  return "#3583dd" // Blue

Rendering behavior (high level)

• Show traffic coloring only for the current and upcoming portions of the route; do not emphasize already-traveled segments.
• Coalesce adjacent segments with identical colors where feasible to reduce draw calls without altering appearance.
• Keep heavy processing (JSON parse, flattening, coalescing) off the UI thread.

Error handling

• If annotation arrays are misaligned or lengths differ, treat missing entries as “no data” and apply the fallback.
• Ignore unknown fields; tolerate malformed entries by defaulting to fallback.

Platform considerations

• All platforms consume the same annotation semantics and color policy.
• The internal transport may wrap per-segment annotations (e.g., under a value key); clients should extract the inner payload before applying the policy.
• Products may allow theming, but platform implementations must ensure the same policy yields the same visual result.

---

References

• OSRM Annotations: https://project-osrm.org/docs/v5.24.0/api/#annotation-object
• Ferrostar Annotations: https://stadiamaps.github.io/ferrostar/annotations.html

[hactar]

Some nice ideas in there. A couple of things to consider:

Colors

You define a color fallback system with hard coded colors. Developers will quickly want to change that. I suggest defining semantic colors (heavy, medium, low instead of blue, orange red) with default values, and allowing developers to override the semantic colors

Error handling

You propose tolerating malformed entries. Such an approach frequently leads to difficult debugging: a developer expects something to appear, misspelled "congestion_level", and the system accepts this but doesn't do anything. I suggest to throw an error in such cases, the developer can still decide to catch and ignore it if they would like to. At the very least, if you do want to accept malformed entries, a warning should be outputted to the console for the developer to notice.

[radityagumay]

Hi @hactar thank you for the feedback. that's make sense for the colors. will update that accordingly.

Yes for the error handling, i am thinking to have offensive programming during development, and on the production the defensive programming will be applied.

However at the moment since we don't have observability in place like OTEL or something, hence the client is not able to sink those silent error to the expected provider on the production.

[ianthetechie]

Colors

Semantic colors

+1 on semantic meaning over specific colors for most use cases. It communicates the intent, which can be used for many things, not just color derivation.

It also seems plausible that we may want to enable client-side localization of congestion coloring based on cultural norms. For example, in several East Asian countries, it's a good thing if the number in a stock ticker is red, and blue is bad. Just to be clear, I do not actually know of a specific case where red (or some other color besides green) indicates free flow traffic; in Korea they follow the western convention for this despite using red = good for stock price movements. But It seems plausible enough that we'd want to leave this open.

Color overrides

That said, having the ability for the server to override it with an explicit color is quite a reasonable request. I'm sure product/design teams will appreciate the ability to change or experiment with the visual appearance without needing to ship a new app build.

If traffic.congestion_color is a valid hex, use it verbatim.

Minor note, but I think we can probably also use other CSS-ish expressions? I think MapLibre supports most (all?) valid CSS expressions, including HSL(A) function style, alpha channel, etc..

(And in case we ever supported another renderer in the future, there are excellent ways we could handle this with a common expression parser in the Rust core; good crates for this already exist.)

Color precedence

IMO we probably do want 2 ways to control this. My proposal is slightly different.

While you and I both (I think) control our own routing APIs, not all developers will have this luxury. So, I think the first level is actually an explicit preference from the app developer. Additionally, the app may have different day/night styles, which would benefit from slightly different colors. We have a few ways of doing this sort of thing right now; @Archdoog can probably weigh in with specifics.

With a "theme" based approach, the theme can look at all available info and then make a decision from there for maximum flexibility.

From here, we can arrive at our two "default" themes for light/dark (day/night). They will use the server-provided values when present, or else fall back to sensible defaults. And of course developers can override this behavior with their own defaults / hard-coded values.

Color derived from current speed vs typical ratio?

I do not think that we need the calculation from typical speed at all.

• Many traffic data vendors actually send over a value per some taxonomy. This is trivial to translate to whatever we decide here.
• Some vendors (e.g. Mapbox) send over a numeric value directly. In the case of Mapbox, they actually send both.
• The server can compute this otherwise.
• I don't think the nav SDK ever actually cares about what speed is typical on a segment except to calculate whether traffic is currently congested. This is a weakly held opinion, so if you have another use case for this, let's discuss. But initially it seems like it's probably just dead weight in the payload.

Error handling

I actually forget what we do for this right now. I think we might fail if an annotation is invalid. I agree that if we don't throw an error (and give the developer the option to catch it easily), we should at the very least have clear logging. This is not something we do a great job at today regarding route parse errors, but we should improve this (and definitely not fail silently or interpolate values by default, though app developers are free to make this choice in error handling based on knowledge of their own routing API's behavior...).

[ianthetechie]

Thanks for putting this together @radityagumay! Just a few additional things to discuss from me. I'm sure we'll have a few more questions come up as you get into implementation, but it looks like all the foundational elements are here.

Colors

Already left a comment on Patrick's suggestion. TL;DR I also favor having semantic colors as a baseline with hex as an optional override.

General comment on how we can achieve the portability goals

Probably no surprise, but we can shift most of the heavy lifting to the Rust core, so we have a single implementation for arriving at the final state. I think the proposed theme object can be an enum in the core, with the following variants:

• One or two "default" variants (for day/night)
• A variant that accepts a struct with semantic color -> value mappings
• A custom variant which accepts a dyn trait object similar to how we do other custom behaviors like route deviation.

The custom variant provides a lot of flexibility, but most users probably won't actually need it (so we can actually drop this for now probably and keep it in the back of our heads to add later?). The others are pretty simple structures, which will easily work cross-platform with predictable behavior. The custom trait impls work perfectly on Android and iOS, but we don't currently expose these to TypeScript.

What is the "intermediate representation"?

This is squarely an implementation question, but starting the discussion anyways 😂 I don't think we currently have a cross-platform representation of a "color." But since I think MapLibre accepts most valid CSS strings, we can probably use that as the representation. I don't have a strong opinion on whether we should validate the color strings or not, but if we do, there are crates aplenty, like https://crates.io/crates/css-colors.

I also like your idea of combining adjacent segments with identical colors. MapLibre shouldn't have a super hard time with this either way.

So I guess the output after applying the theme would be a LineString and a CSS color.

[radityagumay]

Hi @hactar and @ianthetechie

Thank you so much for the feedbacks. i really appreciate the feedbacks on those lines. and here the changes i proposed will do. Essentially the semantic colors are given by default with the capabilities where the devs can override those semantic colors. and the semantic colors also available on different Theming.

By doing this way. the devs can override those default semantic colors, if they have a colors from the annotation such as congestion_color or similar, where they can have a parser to overrides the default semantic colors.

@hactar @ianthetechie i think this proposal will satisfy your feedbacks.

Colors

For the colors, i'll provide a semantic colors based on the congestion level with default values where the developers able to override those default value based on their convenience.

Example

/**
 * Raw traffic condition classification produced from annotations.
 */
enum class TrafficSeverity {
  FREE_FLOW,
  MODERATE,
  HEAVY,
  UNKNOWN
}

/**
 * Semantic color roles (do NOT encode brand or literal color meaning).
 * Developers override these roles rather than hunting for hard-coded hex values.
 */
enum class TrafficSemanticColor {
  FreeFlow,
  Moderate,
  Heavy,
  Unknown
}

/**
* These days apps has dark mode, better to provide those capabilities :) 
*/
enum class ThemeMode {
    DAY,
    NIGHT,
    HIGH_CONTRAST_DAY,
    HIGH_CONTRAST_NIGHT
}

/**
 * Resolves a concrete ARGB color for a semantic role in a given theme mode.
 */
fun interface TrafficColorResolver {
  fun colorFor(role: TrafficSemanticColor, mode: ThemeMode): Int
}

class DefaultTrafficColorResolver private constructor(
  private val table: Map<ThemeMode, Map<TrafficSemanticColor, Int>>,
  private val fallbackColor: Int
) : TrafficColorResolver {
  
    override fun colorFor(role: TrafficSemanticColor, mode: ThemeMode): Int {
      return table[mode]?.get(role)
         ?: table[ThemeMode.DAY]?.get(role)
         ?: fallbackColor
    }
    
    class Builder {
    
      private val base: MutableMap<ThemeMode, TrafficSemanticColor, Int> = 
        mutableMapOf(
          ThemeMode.DAY to mutableMapOf(
             TrafficSemanticColor.FreeFlow to 0xFF3583DD.toInt(),
             TrafficSemanticColor.Moderate to 0xFFFFA500.toInt(),
             TrafficSemanticColor.Heavy to 0xFFE74C3C.toInt(),
             TrafficSemanticColor.Fallback to 0xFF3583DD.toInt(),
           )
          // add other theme
        )

       private var explicitFallback: Int? = null

       // override single semantic role
       fun override(
         mode: ThemeMode,
         role: TrafficSemanticColor,
         color: Int
       ) : Builder = apply {
         base.getOrPut(mode) ...
       }

       // override all
       fun override(
         role: TrafficSemanticColor,
         color: Int
       ) : Builder = apply {
         base.keys.forEach { m -> base[m]?.set(role, color) }
       }
    }
    
   // complete examples will be raised on the PR
    ....
}

[radityagumay]

General comment on how we can achieve the portability goals

Yes that make sense!. will check on the core i believe we should make it multiplatform so that every platform can get advantages for the implementation

[radityagumay]

What is the "intermediate representation"?

On this line, should we put the multiplatform of the semantic color on the core module? which following the MapLibre CSS styles?

Note: i haven't tried the MapLibre CSS styles however when i added opacity on the color it turned to black

#EE2737CC	#EE2737

[ianthetechie]

Thanks! I think this more or less addresses my feedback and we can proceed to a PR from here.

I'd suggest starting with the core parts first (defining traits, enums, etc. there and doing UniFFI exports) and going from there.

[radityagumay]

thank you @ianthetechie will start the development!

notes: relevant opacity for the polyline Rallista/maplibre-compose-playground#120