POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models package

Catalog of per-channel nuPlan observation models, registered for user selection.

Each observation channel has its own module of concrete NuPlanObservationModel implementations (ego_models, agent_models). Importing a channel module runs its @register_observation_model decorators, so a planner environment can resolve a per-channel selection like {"ego": "gaussian", "agents": "factored"} into instances via build_observation_model().

To add a modality: create/extend its <channel>_models.py, register the class, and import it here so registration runs on import.

Functions:

register_observation_model: Decorator registering a factory under (channel, name). build_observation_model: Instantiate the model registered under (channel, name). available_observation_models: List the names registered for a channel.

Classes:

EgoObservationModel: Additive-Gaussian-noise ego proprioception with a matching density. FactoredAgentObservationModel: Per-slot detection + occlusion gating + Gaussian pose noise.

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.EgoObservationModel(ego_std=0.01)

Bases: NuPlanObservationModel

Ego proprioception corrupted by additive Gaussian noise, with a matching density.

nuPlan gives the ego near-perfect self-localisation, so this channel is modelled as the true ego block plus small zero-mean Gaussian measurement noise. Provides both a sampler and a matching density, so it can back a scoring generative model.

Parameters:

ego_std (float)

ego_std

Std of the zero-mean Gaussian noise added to the ego proprioception vector.

Example

>>> import numpy as np
>>> np.random.seed(0)
>>> model = EgoObservationModel(ego_std=0.01)
>>> perceived = model.perceive(np.zeros(7))
>>> perceived.shape
(7,)

channel: str = 'ego'

log_probability(clean_channel, channel_observation)

Log-density of channel_observation given the clean channel value.

Parameters:

• clean_channel (Any) – The noise-free value of this channel built from a state.

• channel_observation (Any) – The channel value whose likelihood is scored.

Return type:

float

Returns:

The channel’s observation log-probability.

Raises:

NotImplementedError – If this is a sample-only channel without a density.

perceive(clean_channel)

Sample this channel’s perceived value from its clean, fully-detected value.

Parameters:

clean_channel (Any) – The noise-free value of this channel, built from a state or taken from the world’s raw reading.

Return type:

ndarray

Returns:

The perceived value of the same channel.

supports_density: bool = True

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.FactoredAgentObservationModel(max_tracked_agents=5, perception_range=50.0, occlusion_radius=1.5, pose_std=0.5, detect_prob=0.95)

Bases: NuPlanObservationModel

Reference agent perception: per-slot detection gating plus additive Gaussian pose noise.

Each agent slot is detected only when in perception range and not geometrically occluded by another agent on the ego->target sight line; a detected agent’s pose is corrupted with additive Gaussian noise. Provides both a sampler and a matching density, so it can back a scoring generative model.

Parameters:

• max_tracked_agents (int)

• perception_range (float | None)

• occlusion_radius (float)

• pose_std (float)

• detect_prob (float)

max_tracked_agents

Number of fixed agent slots in the agents block.

perception_range

Metres beyond which an agent is undetectable (None disables the range gate).

occlusion_radius

Sight-line blocking radius among agents.

pose_std

Std of Gaussian noise on a detected agent’s pose measurement.

detect_prob

Probability of detecting a visible agent; 1 - detect_prob is the miss rate scored by the density.

Example

>>> import numpy as np
>>> np.random.seed(0)
>>> model = FactoredAgentObservationModel(max_tracked_agents=1, perception_range=50.0)
>>> agents = np.array([1.0, 10.0, 0.0, 0.0, 0.0])
>>> float(model.perceive(agents)[0])  # near agent detected
1.0

channel: str = 'agents'

log_probability(clean_channel, channel_observation)

Log-density of channel_observation given the clean channel value.

Parameters:

• clean_channel (Any) – The noise-free value of this channel built from a state.

• channel_observation (Any) – The channel value whose likelihood is scored.

Return type:

float

Returns:

The channel’s observation log-probability.

Raises:

NotImplementedError – If this is a sample-only channel without a density.

perceive(clean_channel)

Sample this channel’s perceived value from its clean, fully-detected value.

Parameters:

clean_channel (Any) – The noise-free value of this channel, built from a state or taken from the world’s raw reading.

Return type:

ndarray

Returns:

The perceived value of the same channel.

render(clean_channel, noisy)

Gate the clean agent block per slot, optionally sampling the sensor noise.

Parameters:

• clean_channel (Any) – The noise-free flat agents block.

• noisy (bool) – When True, take the sampler path — a visible slot is detected with probability detect_prob and its pose is corrupted by Gaussian noise, matching what log_probability() scores. When False, return the gated but noise-free block (every visible slot detected).

Return type:

ndarray

Returns:

The perceived flat agents block.

supports_density: bool = True

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.available_observation_models(channel)

Return the catalog names registered for channel, sorted.

Return type:

List[str]

Parameters:

channel (str)

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.build_observation_model(channel, name, **kwargs)

Instantiate the observation model registered under (channel, name).

Parameters:

• channel (str) – The observation-dict key to resolve the model for.

• name (str) – The registered catalog name within that channel.

• **kwargs (Any) – Forwarded to the registered factory.

Return type:

NuPlanObservationModel

Returns:

The instantiated per-channel observation model.

Raises:

KeyError – If no model is registered under (channel, name).

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.register_observation_model(channel, name)

Register an observation-model factory under (channel, name) for user selection.

Parameters:

• channel (str) – The observation-dict key the model handles (e.g. "ego", "agents").

• name (str) – The catalog name the user selects the model by within that channel.

Return type:

Callable[[TypeVar(_FactoryT, bound= Callable[..., NuPlanObservationModel])], TypeVar(_FactoryT, bound= Callable[..., NuPlanObservationModel])]

Returns:

A decorator that registers the factory (a class or callable returning a NuPlanObservationModel) and returns it unchanged (its type is preserved).

Submodules

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.agent_models module

Agent-channel observation models.

Catalog of per-channel models for the agents observation channel (the fixed agent-slot block). Add new agent-perception models here and register them with register_observation_model() so they can be selected by name.

Classes:

FactoredAgentObservationModel: Per-slot detection + occlusion gating + Gaussian pose noise.

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.agent_models.FactoredAgentObservationModel(max_tracked_agents=5, perception_range=50.0, occlusion_radius=1.5, pose_std=0.5, detect_prob=0.95)

Bases: NuPlanObservationModel

Reference agent perception: per-slot detection gating plus additive Gaussian pose noise.

Each agent slot is detected only when in perception range and not geometrically occluded by another agent on the ego->target sight line; a detected agent’s pose is corrupted with additive Gaussian noise. Provides both a sampler and a matching density, so it can back a scoring generative model.

Parameters:

• max_tracked_agents (int)

• perception_range (float | None)

• occlusion_radius (float)

• pose_std (float)

• detect_prob (float)

max_tracked_agents

Number of fixed agent slots in the agents block.

perception_range

Metres beyond which an agent is undetectable (None disables the range gate).

occlusion_radius

Sight-line blocking radius among agents.

pose_std

Std of Gaussian noise on a detected agent’s pose measurement.

detect_prob

Probability of detecting a visible agent; 1 - detect_prob is the miss rate scored by the density.

Example

>>> import numpy as np
>>> np.random.seed(0)
>>> model = FactoredAgentObservationModel(max_tracked_agents=1, perception_range=50.0)
>>> agents = np.array([1.0, 10.0, 0.0, 0.0, 0.0])
>>> float(model.perceive(agents)[0])  # near agent detected
1.0

channel: str = 'agents'

log_probability(clean_channel, channel_observation)

Log-density of channel_observation given the clean channel value.

Parameters:

• clean_channel (Any) – The noise-free value of this channel built from a state.

• channel_observation (Any) – The channel value whose likelihood is scored.

Return type:

float

Returns:

The channel’s observation log-probability.

Raises:

NotImplementedError – If this is a sample-only channel without a density.

perceive(clean_channel)

Sample this channel’s perceived value from its clean, fully-detected value.

Parameters:

clean_channel (Any) – The noise-free value of this channel, built from a state or taken from the world’s raw reading.

Return type:

ndarray

Returns:

The perceived value of the same channel.

render(clean_channel, noisy)

Gate the clean agent block per slot, optionally sampling the sensor noise.

Parameters:

• clean_channel (Any) – The noise-free flat agents block.

• noisy (bool) – When True, take the sampler path — a visible slot is detected with probability detect_prob and its pose is corrupted by Gaussian noise, matching what log_probability() scores. When False, return the gated but noise-free block (every visible slot detected).

Return type:

ndarray

Returns:

The perceived flat agents block.

supports_density: bool = True

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.ego_models module

Ego-channel observation models.

Catalog of per-channel models for the ego observation channel (the ego proprioception block [x, y, yaw, vx, vy, lat, heading_err]). Add new ego models here and register them with register_observation_model() so they can be selected by name.

Classes:

EgoObservationModel: Additive-Gaussian-noise ego proprioception with a matching density.

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.ego_models.EgoObservationModel(ego_std=0.01)

Bases: NuPlanObservationModel

Ego proprioception corrupted by additive Gaussian noise, with a matching density.

nuPlan gives the ego near-perfect self-localisation, so this channel is modelled as the true ego block plus small zero-mean Gaussian measurement noise. Provides both a sampler and a matching density, so it can back a scoring generative model.

Parameters:

ego_std (float)

ego_std

Std of the zero-mean Gaussian noise added to the ego proprioception vector.

Example

>>> import numpy as np
>>> np.random.seed(0)
>>> model = EgoObservationModel(ego_std=0.01)
>>> perceived = model.perceive(np.zeros(7))
>>> perceived.shape
(7,)

channel: str = 'ego'

log_probability(clean_channel, channel_observation)

Log-density of channel_observation given the clean channel value.

Parameters:

• clean_channel (Any) – The noise-free value of this channel built from a state.

• channel_observation (Any) – The channel value whose likelihood is scored.

Return type:

float

Returns:

The channel’s observation log-probability.

Raises:

NotImplementedError – If this is a sample-only channel without a density.

perceive(clean_channel)

Sample this channel’s perceived value from its clean, fully-detected value.

Parameters:

clean_channel (Any) – The noise-free value of this channel, built from a state or taken from the world’s raw reading.

Return type:

ndarray

Returns:

The perceived value of the same channel.

supports_density: bool = True

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.registry module

Registry of per-channel nuPlan observation models keyed by (channel, name).

Concrete per-channel models register themselves with the register_observation_model() decorator so a user can select, per observation channel, which model the planner’s generative environment holds — e.g. {"ego": "gaussian", "agents": "factored"}. The environment resolves the selection into instances via build_observation_model().

Functions:

register_observation_model: Decorator registering a factory under (channel, name). build_observation_model: Instantiate the model registered under (channel, name). available_observation_models: List the names registered for a channel.

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.registry.available_observation_models(channel)

Return the catalog names registered for channel, sorted.

Return type:

List[str]

Parameters:

channel (str)

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.registry.build_observation_model(channel, name, **kwargs)

Instantiate the observation model registered under (channel, name).

Parameters:

• channel (str) – The observation-dict key to resolve the model for.

• name (str) – The registered catalog name within that channel.

• **kwargs (Any) – Forwarded to the registered factory.

Return type:

NuPlanObservationModel

Returns:

The instantiated per-channel observation model.

Raises:

KeyError – If no model is registered under (channel, name).

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.registry.register_observation_model(channel, name)

Register an observation-model factory under (channel, name) for user selection.

Parameters:

• channel (str) – The observation-dict key the model handles (e.g. "ego", "agents").

• name (str) – The catalog name the user selects the model by within that channel.

Return type:

Callable[[TypeVar(_FactoryT, bound= Callable[..., NuPlanObservationModel])], TypeVar(_FactoryT, bound= Callable[..., NuPlanObservationModel])]

Returns:

A decorator that registers the factory (a class or callable returning a NuPlanObservationModel) and returns it unchanged (its type is preserved).