Filter Configuration And Map Coloring

This document describes how track filters are configured, persisted, exposed to the UI, and used for map coloring and legends.

The important distinction is:

• A filter decides which tracks are returned.
• A filter can optionally assign each returned track to a group.
• Metadata on the filter tells the UI how to organize the filter, sort groups, label groups, and choose colors.

1. Filter Storage

Filters are stored in filter_config.

Core identity and execution fields:

UI and coloring metadata:

The audit table filter_config_audit mirrors these fields. The audit trigger must be updated whenever filter metadata columns are added.

2. Typed Metadata Values

The database stores metadata as text columns, but Java models fixed metadata sets as enums with @Enumerated(EnumType.STRING).

Source of truth:

FilterConfigEntity

GROUP_SEMANTICS

COLORING_STRATEGY

LEGEND_SORT_STRATEGY

These dimensions are intentionally separate. For example, an ordered weekday filter has group_semantics = ORDINAL but still uses categorical colors. A speed gradient filter has group_semantics = NUMERIC_BUCKET and coloring_strategy = SEQUENTIAL_GRADIENT.

3. SQL Filter Contract

A SQL filter returns at least:

id

Grouped/coloring filters also return:

grp

The raw grp value is the stable group key used by the map layer and by group visibility toggles. The UI can display a friendlier label using metadata, but the raw key should remain stable.

Most GPS track filters include the standard base filter:

[[~{/GPS_TRACK/SmartBaseFilter}]]

This keeps normal date, geo area, successful-load, duplicate, and planned-track constraints consistent across filters.

4. Filter Groups

Current top-level UI groups are:

The frontend orders selector groups by the lowest display_order inside each group, then uses a small known-group fallback order only for ties or missing orders. This keeps the database metadata as the primary source of ordering truth while still giving unknown group names stable behavior.

5. Presentation Defaults

preferred_palette describes the recommended first palette for a filter. Legend order is a client-side choice. The frontend stores user overrides in the client filter configuration, so changing legend order or palette does not mutate the system filter definition.

An explicit No coloring choice stores palette.noColoring = true and survives reloads, paused drafts, and view changes. An unset palette can still receive the view's preferred default. Older saved empty choices with the No coloring label are migrated to the explicit choice. Reset clears the choice; Undo restores it.

Changing views resets a custom category order to the new view's default. The view picker discloses this reset before applying the change.

If legend_sort_strategy is missing, the frontend preserves the first-seen group order returned by the SQL query. Filters that need a specific default order should make that order explicit in SQL. Numeric ordering is only used when NUMERIC_ASC is selected by the user.

The frontend uses preferred_palette when a filter is selected and no palette is active yet. It also replaces an obviously incompatible palette when switching between categorical and gradient filters:

• gradient filter with categorical palette: switch to the filter's preferred gradient palette
• categorical filter with gradient palette: switch to the filter's preferred categorical palette
• categorical filter with an existing categorical palette: keep the user's current choice

Current categorical defaults use existing palette keys:

ui_metadata.optionalParams lists params that may be left blank even when they are rendered as editable fields, for example DATE_TIME_FROM, DATE_TIME_TO, or gradient min/max range params.

6. Gradient Filters

Gradient filters are designed for ordered numeric buckets.

Current gradient filters:

These names and units are also exposed by the current filter API. The client uses filterParamUnits.ts to convert display input back to the metadata unit. The proposed public renames to meters and watt-hours have not been implemented; see the measurement-system status.

Each gradient filter assigns the current result set to bucket values 0 to 99. The bucket is based on sorted rank within the filtered result set, not on an absolute metric threshold. This keeps the full color range useful for the visible tracks.

For small result sets, the SQL scales rank positions across the full 0-99 range. With two tracks, the lower track gets bucket 0 and the higher track gets bucket 99. With one track, the bucket is 0.

Recommended metadata for gradient filters:

The frontend maps bucket values to palette indices. A 100-color palette maps bucket 0 to the first color and bucket 99 to the last color. Shorter palettes are scaled proportionally.

7. Group Labels

The raw group key should remain compact and stable. Display labels are derived in the UI.

For numeric buckets, group_label_template supports:

Example:

group_label_template = "Avg speed percentile {bucket}"
grp = "1"
display label = "Avg speed percentile 01"

This keeps legends readable while preserving numeric sorting.

8. YAML-Defined Filters

Filters can also be supplied through application YAML under:

mtl.filter-configs

Example metadata:

filter-group: People
group-semantics: CATEGORICAL
coloring-strategy: CATEGORICAL
legend-sort-strategy: LABEL_ASC
preferred-palette: 008_COLORS

The YAML properties bind directly to FilterConfigEntity, so enum values must match the Java enum names exactly.

The initializer only creates YAML filters that do not already exist in the database. Editing YAML does not update an existing row. Do not add a historical backfill unless explicitly requested; follow backend migration policy and document when recreation is required.

9. OpenAPI And Frontend Types

FilterConfigEntity is exposed through the OpenAPI schema. Because the metadata fields are Java enums, the generated TypeScript client exposes matching enum types.

Frontend code should use the generated enum constants instead of duplicating raw strings. This keeps UI behavior aligned with the server contract.

Relevant frontend behavior:

• the filter selector groups filters by filter_group
• the map legend and preview legend sort by the user override, otherwise preserve the first-seen group order returned by SQL
• gradient filters use coloring_strategy = SEQUENTIAL_GRADIENT
• display labels use group_label_template
• gradient help text is based on ui_metadata

10. Key Source Files