Skip to content

23. WorldModeller Configuration

Jump to bottom
Marco Marini edited this page Jul 21, 2026 · 1 revision

WorldModeller Configuration

The WorldModeller creates and updates the robot perception model by interpreting the event flow generated by the robot sensors.

It builds and maintains:

  • the radar map;
  • the polar map;
  • the robot-relative radar map;
  • the marker location map.

The configuration is validated against the world-modeller-schema-0.2 JSON schema before the modeller is created.

Configuration Parameters

Parameter Type Required Default Description
contactPersistence integer Yes - Persistence time of contact detections in the radar map (milliseconds).
correlationInterval integer Yes - Time interval used to correlate consecutive sensor events (milliseconds).
markerCleanDecay number Yes - Time decay used to remove obsolete marker information.
markerDecay number Yes - Time decay used to update marker position confidence.
markerSize number Yes - Physical size of detected markers (meters).
minNumberEvents integer No 1 Minimum number of events required before updating the marker map.
minRadarDistance number Yes - Minimum distance considered valid when generating the polar map (meters).
numSectors integer No - Number of sectors used by the polar map representation.
obstaclePersistence integer Yes - Persistence time of obstacle detections in the radar map (milliseconds).
radarCleanInterval integer Yes - Interval between radar map cleaning operations (milliseconds).
radarDecay number Yes 300000 Decay factor used for radar confidence reduction.
radarGrid number Yes - Size of each radar map cell (meters).
radarHeight integer Yes - Height of the radar grid (number of cells).
radarWidth integer Yes - Width of the radar grid (number of cells).
robotMapSize integer Yes - Size of the robot-relative map representation.

Example Configuration

radarWidth: 200
radarHeight: 200
radarGrid: 0.02

radarCleanInterval: 1000
correlationInterval: 500

obstaclePersistence: 5000
contactPersistence: 3000

radarDecay: 300000

numSectors: 72
minRadarDistance: 0.05

markerDecay: 300000
markerCleanDecay: 600000
markerSize: 0.2
minNumberEvents: 3

robotMapSize: 100

Parameter Description

radarWidth

Defines the horizontal dimension of the radar occupancy grid.

The value represents the number of cells composing the radar map width.

Together with radarHeight and radarGrid, it determines the physical extension of the radar map.

radarHeight

Defines the vertical dimension of the radar occupancy grid.

The value represents the number of cells composing the radar map height.

A larger grid increases the monitored area but requires more memory.

radarGrid

Defines the size of a single radar map cell in meters.

Example:

radarGrid: 0.02

means that every radar cell represents an area of:

2 cm x 2 cm

A smaller value increases spatial resolution but increases computational requirements.

radarCleanInterval

Defines the interval between radar map cleaning operations.

During cleaning, obsolete information is removed according to persistence and decay parameters.

A smaller value:

  • keeps the map more updated;
  • increases processing load.

A larger value:

  • reduces computation;
  • keeps old information longer.

correlationInterval

Defines the time window used to correlate consecutive sensor events.

Events received within this interval can contribute to the same world model update.

obstaclePersistence

Defines how long obstacle detections remain valid after the last confirmation.

The value is expressed in milliseconds.

Longer persistence values make the map more stable but can preserve outdated obstacles.

contactPersistence

Defines how long contact detections remain active in the radar model.

Contact events represent close-range interactions between the robot and obstacles.

radarDecay

Defines the decay parameter used by the radar model.

It controls the reduction of confidence of old radar observations.

Default value:

300000

numSectors

Defines the number of angular sectors used by the polar map.

The polar map converts the Cartesian radar grid into a directional representation.

A larger number of sectors provides better angular resolution.

Example:

numSectors: 72

creates sectors of approximately:

360 / 72 = 5 degrees

minRadarDistance

Defines the minimum distance considered valid during polar map generation.

Radar information closer than this threshold is ignored.

This avoids considering measurements affected by the robot body or sensor mounting position.

markerDecay

Defines the decay time used for marker position information.

Markers represent QR-code landmarks detected in the environment.

A larger value keeps marker information available for longer periods.

markerCleanDecay

Defines the time after which obsolete marker information is removed.

This value controls the cleaning of the marker map.

markerSize

Defines the physical size of detected markers in meters.

The value is used during marker observation processing and position estimation.

Example:

markerSize: 0.2

represents a marker with a side length of 20 cm.

minNumberEvents

Defines the minimum number of marker detection events required before updating the marker map.

Default value:

1

Increasing this value reduces the probability of updating the map from false detections.

robotMapSize

Defines the size of the robot-relative radar map.

The robot-relative map is centered on the robot and follows its movement.

Internal Initialization

During initialization the WorldModeller performs the following steps:

  1. Validates the configuration document.
  2. Creates the radar modeller.
  3. Creates the polar map modeller.
  4. Creates the marker locator.
  5. Creates the robot-relative map representation.
  6. Starts processing the sensor event flow.

The resulting modeller is ready to provide updated world models to the controller and inference components.

Radar Map Generation

The radar modeller maintains a grid representation of the environment.

Each grid cell can represent:

  • unknown space;
  • free space;
  • occupied space.

Sensor observations update cells and their confidence values.

Old observations are progressively reduced according to the configured decay parameters.

Polar Map Generation

The polar map is generated from the radar grid.

The environment is divided into angular sectors around the robot.

For each sector the closest relevant information is selected according to the following priority:

  1. obstacle detection;
  2. known free space;
  3. unknown space.

This representation is used for navigation and obstacle avoidance.

Marker Location

The marker locator processes QR-code observations.

Multiple observations can be correlated to estimate marker positions.

The update occurs only after the configured number of events has been reached.

Validation Rules

The configuration is validated before creating the WorldModeller.

The following parameters are mandatory:

  • radarWidth;
  • radarHeight;
  • radarGrid;
  • radarCleanInterval;
  • correlationInterval;
  • obstaclePersistence;
  • contactPersistence;
  • radarDecay;
  • markerDecay;
  • markerCleanDecay;
  • markerSize;
  • minRadarDistance;
  • robotMapSize.

Additional validation rules:

  • numeric values requiring positive values must be greater than zero;
  • integer dimensions must be at least one;
  • the document must conform to the world-modeller-schema-0.2 JSON schema.

If validation fails, modeller creation is aborted with an exception.

Release

Current version: 0.27.0

Clone this wiki locally