109. Using Evaluation Pipeline plugins

Several pipeline stages delegate their work to a plugin — a small, swappable component that handles one stage for one kind of data. Because raw recordings differ between data sources, the explore and parse stages in particular are almost always plugin-backed, so the pipeline can read your data without changing the pipeline itself.

This section explains how to select and configure plugins that already exist. To write your own, see Writing custom plugins.

109.1 Stages that use plugins

Stage	Plugin role
`explore`	Discover the data files associated with a recording.
`parse`	Convert a raw recording into a Foretellix object list.
`map`	Provide a usable map; can also call a map-generation or third-party plugin.
`ext_match`	Enrich a run with externally provided match data.
`post_process`	Run custom post-processing over the results.

The denoise, ingest, match, and post_match stages do not use plugins.

Configure them directly in the flow — see Configuring the Evaluation Pipeline flow.

109.2 Referencing a plugin

In the flow configuration, select a plugin with the plugin: key in the stage's block, using the form <library>.<plugin_name>:

explore:
  plugin: common.pandaset_explorer

parse:
  plugin: common.pandaset_parser

The part before the dot is the plugin library; the part after it is the plugin name within that library.

109.3 Plugin libraries

A plugin library is a directory of plugin definitions, located through an environment variable named FTX_EVALUATE_<LIBRARY>_PLUGIN_LIB. For the library named common, that variable is FTX_EVALUATE_COMMON_PLUGIN_LIB.

The installer sets the environment variable for each plugin library included in your distribution, so a plugin reference such as common.pandaset_parser resolves out of the box.

109.3.1 common library

The common library ships with the base Foretify installation and provides general-purpose plugins:

Plugin	Stage	Purpose
`common.pandaset_explorer`	`explore`	Discover files in a Pandaset-format recording directory.
`common.pandaset_parser`	`parse`	Convert Pandaset recordings to a Foretellix object list.
`common.ol_explorer`	`explore`	Discover files for recordings already in object list format.
`common.standard_map`	`map`	Provide an existing map, with optional map-generation and third-party fallbacks.
`common.foretify_result_explorer`	`explore`	Discover files for inputs that are already Foretify run results.
`common.stub_vendor`	`map` (third-party)	Placeholder third-party map vendor — raises until replaced with a real vendor integration.

Pandaset is a public autonomous-driving dataset; the pandaset_* plugins read recordings laid out in that format, where each recording is a sequence directory. The pipeline accepts only single-file drive_data inputs, so reference a sequence by its meta/gps.json anchor file — for example "drive_data": "/datasets/pandaset/001/meta/gps.json". The explorer derives and validates the sequence directory from the anchor. The common library ships a parser for Pandaset only — for any other recording format, write a custom parser. When your data is already a Foretellix object list (a .pb file), reference common.ol_explorer and omit the parse stage.

Additional plugin libraries may be included in your distribution depending on the data sources you work with. Each sets its own FTX_EVALUATE_<LIBRARY>_PLUGIN_LIB environment variable and is referenced the same way.

109.4 Plugin reference resolution

When the pipeline reads plugin: <library>.<plugin_name>, it looks for a YAML fragment at $FTX_EVALUATE_<LIBRARY>_PLUGIN_LIB/<stage_subdir>/<plugin_name>.yaml.

The stage subdirectory depends on the stage type: explorers, parsers, mapgens, map_providers, third_party_maps, ext_matchers, or post_processors. So common.pandaset_parser resolves to $FTX_EVALUATE_COMMON_PLUGIN_LIB/parsers/pandaset_parser.yaml.

Each library fragment names the Python class to load and provides the plugin's default configuration:

# parsers/pandaset_parser.yaml
class: evaluation_pipeline.plugins.parsers.pandaset_parser.PandasetParser
config:
  conversion_to_ms: 1000      # ns -> ms factor
  utm_crs: "EPSG:32610"       # UTM zone used during ego-motion projection
  dataset_crs: "EPSG:4326"    # native dataset CRS (lat/lon)
  print_unique_objects: false

You do not edit library fragments to use a plugin — you reference the plugin from your flow and, when needed, override its defaults there.

109.5 Overriding a plugin's configuration

Values you set under a stage's config: block deep-merge on top of the plugin's defaults, so you only specify what you want to change:

parse:
  plugin: common.pandaset_parser
  config:
    utm_crs: "EPSG:32632"     # override just this default

Plugin-based stages also accept the stage's common options — shared by every plugin of that stage — at the top level of the block, alongside plugin::

parse:
  plugin: common.pandaset_parser
  max_clip_length_s: 30        # common stage option — applies to every parser
  round_times: true
  config:
    utm_crs: "EPSG:32632"

109.6 Pandaset end-to-end example

The following flow uses only common-library plugins to run an end-to-end evaluation on Pandaset-format recordings:

stages: [explore, parse, denoise, map, ingest, match, post_match]

user_top_file: $FTX/evaluate/library/config/user_configs/ftlx_user_config_pandaset_top.osc

explore:
  plugin: common.pandaset_explorer

parse:
  plugin: common.pandaset_parser

denoise:
  config: $FTX/evaluate/library/config/stage_configs/ftlx_denoiser_config_full.yaml

map:
  plugin: common.standard_map
  format: xodr
  enable_mapgen: false
  enable_third_party: false

When no existing plugin supports your data, write a custom plugin — see Writing custom plugins.