POMDPPlanners.environments.nuplan_pomdp.nuplan_perception package

Standalone, swappable perception stack for the nuPlan planner.

This subpackage turns the nuPlan world’s raw {ego, agents} reading into the perceived observation the planner reasons about. It is decoupled from both the world and the belief, so a user can swap in a different perception model without touching either:

• observation_model — the shared per-channel NuPlanObservationModel interface (one clean channel -> one perceived channel) that the planner’s generative models compose into a {channel: model} map.

• observation_models — the catalog of concrete per-channel models (EgoObservationModel, FactoredAgentObservationModel) registered for user selection by name.

The public names below are re-exported here so callers can import them straight from the subpackage (e.g. from ...nuplan_perception import NuPlanObservationModel).

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.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.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

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.NuPlanObservationModel

Bases: ABC

Abstract single-channel observation model: clean channel -> perceived channel.

A concrete perception maps one observation channel’s clean, fully-detected value (built from a state by a model, or taken from the world’s raw reading) to the degraded value a planner sees. Implementations declare which channel they handle via channel and set supports_density to True when they also provide log_probability().

channel

The observation-dict key this model handles (e.g. "ego" or "agents").

supports_density

Whether log_probability() is implemented. Sample-only channels leave this False and are usable only where sampling is needed.

Note

This is an abstract base class and cannot be instantiated directly.

channel: str = ''

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.

abstractmethod 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:

Any

Returns:

The perceived value of the same channel.

supports_density: bool = False

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.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.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.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).

Subpackages

• POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models package
  • EgoObservationModel
    • EgoObservationModel.ego_std
    • EgoObservationModel.channel
    • EgoObservationModel.log_probability()
    • EgoObservationModel.perceive()
    • EgoObservationModel.supports_density
  • FactoredAgentObservationModel
    • FactoredAgentObservationModel.max_tracked_agents
    • FactoredAgentObservationModel.perception_range
    • FactoredAgentObservationModel.occlusion_radius
    • FactoredAgentObservationModel.pose_std
    • FactoredAgentObservationModel.detect_prob
    • FactoredAgentObservationModel.channel
    • FactoredAgentObservationModel.log_probability()
    • FactoredAgentObservationModel.perceive()
    • FactoredAgentObservationModel.render()
    • FactoredAgentObservationModel.supports_density
  • available_observation_models()
  • build_observation_model()
  • register_observation_model()
  • Submodules
  • POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.agent_models module
    • FactoredAgentObservationModel
      • FactoredAgentObservationModel.max_tracked_agents
      • FactoredAgentObservationModel.perception_range
      • FactoredAgentObservationModel.occlusion_radius
      • FactoredAgentObservationModel.pose_std
      • FactoredAgentObservationModel.detect_prob
      • FactoredAgentObservationModel.channel
      • FactoredAgentObservationModel.log_probability()
      • FactoredAgentObservationModel.perceive()
      • FactoredAgentObservationModel.render()
      • FactoredAgentObservationModel.supports_density
  • POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.ego_models module
    • EgoObservationModel
      • EgoObservationModel.ego_std
      • EgoObservationModel.channel
      • EgoObservationModel.log_probability()
      • EgoObservationModel.perceive()
      • EgoObservationModel.supports_density
  • POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_models.registry module
    • available_observation_models()
    • build_observation_model()
    • register_observation_model()

Submodules

POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_model module

Per-channel observation model: one clean observation channel in, one perceived channel out.

The forward-only world emits a raw, ground-truth observation; the planner-side generative model degrades it into the reading a planner actually sees. That degradation is factored by observation channel — each channel (ego, agents, and, in future, image / lidar) is handled by its own NuPlanObservationModel, and the generative model composes a {channel: NuPlanObservationModel} map. This module holds the single-channel interface; concrete per-channel models live in the observation_models catalog.

Two capabilities, with different reach:

• NuPlanObservationModel.perceive() — sample this channel’s perceived value from its clean one. Required; used by a model to generate a tree observation (sample_observation) and to encode the world’s raw channel (encode_observation).

• NuPlanObservationModel.log_probability() — this channel’s observation density. Optional; a sample-only channel (e.g. a learned encoder) may leave it unimplemented and is still usable to generate observations, but is rejected by a generative model that must score observations for a belief update.

Classes:

NuPlanObservationModel: Abstract single-channel clean -> perceived observation interface.

class POMDPPlanners.environments.nuplan_pomdp.nuplan_perception.observation_model.NuPlanObservationModel

Bases: ABC

Abstract single-channel observation model: clean channel -> perceived channel.

A concrete perception maps one observation channel’s clean, fully-detected value (built from a state by a model, or taken from the world’s raw reading) to the degraded value a planner sees. Implementations declare which channel they handle via channel and set supports_density to True when they also provide log_probability().

channel

The observation-dict key this model handles (e.g. "ego" or "agents").

supports_density

Whether log_probability() is implemented. Sample-only channels leave this False and are usable only where sampling is needed.

Note

This is an abstract base class and cannot be instantiated directly.

channel: str = ''

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.

abstractmethod 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:

Any

Returns:

The perceived value of the same channel.

supports_density: bool = False