Module Scenario

Scenario

Scenario class

class commonocean.scenario.scenario.Scenario(dt: float, scenario_id: Union[str, ScenarioID], author: Optional[str] = None, tags: Optional[Set[Tag]] = None, affiliation: Optional[str] = None, source: Optional[str] = None, location: Optional[Location] = None, benchmark_id: Optional[str] = None)

Class which describes a Scenario entity according to the CommonOcean specification. Each scenario is described by a ocean network consisting of waters (see commonocean.scenario.water.WatersNetwork) and a set of obstacles which can be either static or dynamic (see commonocean.scenario.obstacle.Obstacle).

property dt: float

Global time step size of the time-discrete scenario.

property benchmark_id: str

Unique benchmark ID of a scenario as specified in the CommonOcean XML-file.

property dynamic_obstacles: List[DynamicObstacle]

Returns a list of all dynamic obstacles in the scenario.

property static_obstacles: List[StaticObstacle]

Returns a list of all static obstacles in the scenario.

property obstacles: List[Union[Obstacle, StaticObstacle, DynamicObstacle]]

Returns a list of all static and dynamic obstacles in the scenario.

add_objects(scenario_object: Union[List[Union[Obstacle, Waters, WatersNetwork, TrafficSign]], Obstacle, Waters, WatersNetwork, TrafficSign], waters_ids: Union[None, Set[int]] = None, traffic_sign_parameters: Optional[Dict[str, Any]] = None)

Function to add objects, e.g., waters, dynamic and static obstacles, to the scenario.

Parameters:

• scenario_object – object(s) to be added to the scenario

• waters_ids – water IDs a traffic sign should be referenced from

• traffic_sign_parameters – dict of parameters of the obstacle related with the traffic sign (keys must be ‘obstacle_type’, ‘obstacle_id’ and ‘radius’)

Raises:

ValueError – a value error is raised if the type of scenario_object is invalid.

remove_obstacle(obstacle: Union[Obstacle, List[Obstacle]])

Removes a static, dynamic or a list of obstacles from the scenario. If the obstacle ID is not assigned, a warning message is given.

Parameters:

obstacle – obstacle to be removed

erase_waters_network()

Removes all elements from waters network.

replace_waters_network(waters_network: WatersNetwork)

Removes waters network with all its elements from the scenario and replaces it with new waters network.

Parameters:

waters_network – new waters network

remove_hanging_waters_members(remove_waters: Union[List[Waters], Waters])

After removing waters from remove_waters, this function removes all traffic lights and signs that are not used by other waters.

Parameters:

remove_waters – Waters that should be removed from scenario.

remove_waters(waters: Union[List[Waters], Waters], referenced_elements: bool = True)

Removes a waters or a list of waters from a scenario.

Parameters:

• waters – Waters which should be removed from scenario.

• referenced_elements – Boolean indicating whether references of waters should also be removed.

remove_traffic_sign(traffic_sign: Union[List[TrafficSign], TrafficSign])

Removes a traffic sign or a list of traffic signs from the scenario.

Parameters:

traffic_sign – Traffic sign which should be removed from scenario.

generate_object_id() → int

Generates a unique ID which is not assigned to any object in the scenario.

Returns:

unique object ID

property shallows: List[Shallow]

Returns a list of all shallows in the WatersNetwork of the scenario.

property waterways: List[Waterway]

Returns a list of all waterways in the WatersNetwork of the scenario.

property waters: List[Waters]

Returns a list of all waters (waterways and shallows) in the WatersNetwork of the scenario.

occupancies_at_time_step(time_step: int, obstacle_role: Union[None, ObstacleRole] = None) → List[Occupancy]

Returns the occupancies of all static and dynamic obstacles at a specific time step.

Parameters:

• time_step – occupancies of obstacles at this time step

• obstacle_role – obstacle role as defined in CommonOcean, e.g., static or dynamic

Returns:

list of occupancies of the obstacles

obstacle_by_id(obstacle_id: int) → Optional[Union[Obstacle, DynamicObstacle, StaticObstacle]]

Finds an obstacle for a given obstacle_id

Parameters:

obstacle_id – ID of the queried obstacle

Returns:

the obstacle object if the ID exists, otherwise None

obstacles_by_role_and_type(obstacle_role: Union[None, ObstacleRole] = None, obstacle_type: Union[None, ObstacleType] = None) → List[Obstacle]

Filters the obstacles by their role and type.

Parameters:

• obstacle_role – obstacle role as defined in CommonOcean, e.g., static or dynamic

• obstacle_type – obstacle type as defined in CommonOcean, e.g., car, train, or bus

Returns:

list of all obstacles satisfying the given obstacle_role and obstacle_type

obstacles_by_position_intervals(position_intervals: ~typing.List[~commonroad.common.util.Interval], obstacle_role: ~typing.Tuple[~commonocean.scenario.obstacle.ObstacleRole] = (<ObstacleRole.DYNAMIC: 'dynamic'>, <ObstacleRole.STATIC: 'static'>), time_step: ~typing.Optional[int] = None) → List[Obstacle]

Returns obstacles which center is located within in the given x-/y-position intervals.

Parameters:

• position_intervals – list of intervals for x- and y-coordinates [interval_x, interval_y]

• obstacle_role – tuple containing the desired obstacle roles

Returns:

list of obstacles in the position intervals

obstacle_states_at_time_step(time_step: int) → Dict[int, GeneralState]

Returns all obstacle states which exist at a provided time step.

Parameters:

time_step – time step of interest

Returns:

dictionary which maps id to obstacle state at time step

translate_rotate(translation: ndarray, angle: float)

Translates and rotates all objects, e.g., obstacles and water network, in the scenario.

Parameters:

• translation – translation vector [x_off, y_off] in x- and y-direction

• angle – rotation angle in radian (counter-clockwise)

Tag class

class commonocean.scenario.scenario.Tag(value)

Enum containing all possible tags of a CommonOcean scenario.

OPENSEA = 'open_sea'

TRAFFICSIGN = 'traffic_sign'

NARROWWATERS = 'narrow_waters'

TRAFFICSEPERATIONZONE = 'traffic_separation_zone'

HARBOUR = 'harbour'

COMFORT = 'comfort'

CRITICAL = 'critical'

EVASIVE = 'evasive'

SPEED_LIMIT = 'speed_limit'

GeoTransformation class

class commonocean.scenario.scenario.GeoTransformation(geo_reference: Optional[str] = None, x_translation: Optional[float] = None, y_translation: Optional[float] = None, z_rotation: Optional[float] = None, scaling: Optional[float] = None)

Class which describes the transformation from geodetic to projected Cartesian coordinates according to the CommonOcean specification

Location class

class commonocean.scenario.scenario.Location(geo_name_id: int = -999, gps_latitude: float = 999, gps_longitude: float = 999, geo_transformation: Optional[GeoTransformation] = None, environment: Optional[Environment] = None)

Class which describes a location according to the CommonOcean specification.

property geo_name_id: int

property gps_latitude: float

property gps_longitude: float

property geo_transformation: GeoTransformation

property environment: Environment

Waters network

WatersNetwork class

class commonocean.scenario.waters.WatersNetwork(center_nav_area: ndarray, length_nav_area: float, width_nav_area: float, orientation_nav_area: float)

Class which represents a network of connected waters (waterways and shallows)

property navigationable_area: Rectangle

property waters: List[Waters]

property waterways: List[Waters]

property shallows: List[Waters]

property traffic_signs: List[TrafficSign]

find_waters_by_id(waters_id: int) → Waters

Finds a water (shallow or waterway) for a given waters_id

Parameters:

waters_id – The id of the waterway to find

Returns:

The waters object if the id exists and None otherwise

find_waterway_by_id(waters_id: int) → Waters

Finds a waterway for a given waters_id

Parameters:

waters_id – The id of the waterway to find

Returns:

The waterway object if the id exists and None otherwise

find_shallow_by_id(waters_id: int) → Waters

Finds a shallow for a given waters_id

Parameters:

waters_id – The id of the shallow to find

Returns:

The shallow object if the id exists and None otherwise

find_traffic_sign_by_id(traffic_sign_id: int) → TrafficSign

Finds a traffic sign for a given traffic_sign_id

Parameters:

traffic_sign_id – The id of the traffic sign to find

Returns:

The traffic sign object if the id exists and None otherwise

add_waters(water: Waters)

Adds a waters (shallow and waterway) to the WatersNetwork

Parameters:

water – The waters to add

Returns:

True if the waters has successfully been added to the network, false otherwise

add_traffic_sign(traffic_sign: TrafficSign, waters_ids: Union[None, Set[int]] = None)

Adds a traffic sign to the WatersNetwork

Parameters:

• traffic_sign – The traffic sign to add

• waters_ids – Waters the traffic sign should be referenced from

Returns:

True if the traffic sign has successfully been added to the network, false otherwise

post_assign_traffic_sign(traffic_sign_id: int, waters_ids: Set[int])

Assign an unassigned traffic sign to the WatersNetwork

Parameters:

• traffic_sign_id – The traffic sign id to be assigned

• waters_ids – Waters the traffic sign should be referenced from

Returns:

True if the traffic sign has successfully been added to the network, false otherwise

add_waters_from_network(waters_network: WatersNetwork)

Adds waters from a given network object to the current network

Parameters:

waters_network – The water network

Returns:

True if all waters have been added to the network, false otherwise

remove_waters(waters_id: int)

Removes waters from a waters network and deletes all references.

@param waters_id: ID of waters which should be removed.

remove_traffic_sign(traffic_sign_id: int)

Removes a traffic sign from a waters network and deletes all references.

@param traffic_sign_id: ID of traffic sign which should be removed.

translate_rotate(translation: ndarray, angle: float)

Translates and rotates the complete waters network

Parameters:

• translation – The translation given as [x_off,y_off] for the x and y translation

• angle – The rotation angle in radian (counter-clockwise defined)

find_waterway_by_position(point_list: List[ndarray]) → List[List[int]]

Finds the waterway id of a given position

Parameters:

point_list – The list of positions to check

Returns:

A list of water ids. If the position could not be matched to a water, an empty list is returned

find_waterway_by_shape(shape: Shape) → List[int]

Finds the waterway id of a given shape

Parameters:

shape – The shape to check

Returns:

A list of water ids. If the position could not be matched to a water, an empty list is returned

filter_obstacles_in_network(obstacles: List[Obstacle]) → List[Obstacle]

Returns the list of obstacles which are located in the water network

Parameters:

obstacles – The list of obstacles to check

Returns:

The list of obstacles which are located in the water network

map_obstacles_to_waters(obstacles: List[Obstacle]) → Dict[int, List[Obstacle]]

Maps a given list of obstacles to the waters of the water network

Parameters:

obstacles – The list of CR obstacles

Returns:

A dictionary with the water id as key and the list of obstacles on the water as a List[Obstacles]

waterways_in_proximity(point: list, radius: float) → List[Waters]

Finds all waterways which intersect a given circle, defined by the center point and radius

Parameters:

• point – The center of the circle

• radius – The radius of the circle

Returns:

The list of waters which intersect the given circle

shallow_depth_for_positions(positions: List[ndarray]) → List

This function returns the shallow depth for positions

Parameters:

positions – List of positions where each position is a 2D ndarray

Returns:

List with the respective depths of the positions of the input list

Waters class

class commonocean.scenario.waters.Waters

Abstract class for waters in CommonOcean

abstract property waters_type

abstract property waters_id

abstract translate_rotate(translation: ndarray, angle: float)

abstract contains_points(point: ndarray)

abstract get_obstacles()

WatersType class

class commonocean.scenario.waters.WatersType(value)

Enum describing different types of waters

UNKNOWN = 'unknown'

FAIRWAY = 'fairway'

SHALLOW = 'shallow'

TRAFFICSEPARATIONZONE = 'trafficseparationzone'

WatersUser class

class commonocean.scenario.waters.WatersUser(value)

Enum describing different types of water users

VESSEL = 'vessel'

MOTORVESSEL = 'motorvessel'

SAILINGVESSEL = 'sailingvessel'

CARGOSHIP = 'cargoship'

SWIMMER = 'swimmer'

Traffic Signs

TrafficSignElement class

class commonocean.scenario.traffic_sign.TrafficSignElement(traffic_sign_element_id: TrafficSignElementID, additional_values: List[str])

Class which represents a collection of traffic signs at one position

property traffic_sign_element_id: <module 'enum' from '/home/docs/.asdf/installs/python/3.7.17/lib/python3.7/enum.py'>

property additional_values: List[str]

TrafficSign class

class commonocean.scenario.traffic_sign.TrafficSign(traffic_sign_id: int, traffic_sign_elements: List[TrafficSignElement], position: ndarray, virtual: bool = False)

Class to represent a traffic sign

property traffic_sign_id: int

property position: Union[None, ndarray]

property traffic_sign_elements: List[TrafficSignElement]

property virtual: bool

property related_obstacle: Union[None, int]

translate_rotate(translation: ndarray, angle: float)

This method translates and rotates a traffic sign

Parameters:

• translation – The translation given as [x_off,y_off] for the x and y translation

• angle – The rotation angle in radian (counter-clockwise defined)

Obstacles

Different kinds of traffic participants are modeled as obstacles within the scenario. An obstacle is either static or dynamic.

ObstacleRole class

class commonocean.scenario.obstacle.ObstacleRole(value)

Enum containing all possible obstacle roles defined in CommonOcean.

STATIC = 'static'

DYNAMIC = 'dynamic'

ObstacleType class

class commonocean.scenario.obstacle.ObstacleType(value)

Enum containing all possible obstacle types defined in CommonOcean.

UNKNOWN = 'unknown'

BUOY = 'buoy'

LAND = 'land'

MOTORVESSEL = 'motorvessel'

SAILINGVESSEL = 'sailingvessel'

FISHINGVESSEL = 'fishingvessel'

MILITARYVESSEL = 'militaryvessel'

CARGOSHIP = 'cargoship'

VESSELNOTUNDERCOMMAND = 'vesselNotUnderCommand'

RESTRICTEDMANEUVERABILITYVESSEL = 'restrictedManeuverabilityVessel'

ANCHOREDVESSEL = 'anchoredvessel'

WINDFARM = 'windfarm'

OILRIG = 'oilrig'

WATERSBOUNDARY = 'watersboundary'

Obstacle class

class commonocean.scenario.obstacle.Obstacle(obstacle_id: int, obstacle_role: ObstacleRole, obstacle_type: ObstacleType, obstacle_shape: Shape, initial_state: GeneralState, depth: Optional[float] = None)

Superclass for dynamic and static obstacles holding common properties defined in CommonOcean.

property initial_center_waters_ids: Union[None, Set[int]]

Initial waters of obstacle center, e.g., obtained through localization.

property initial_shape_waters_ids: Union[None, Set[int]]

Initial waters of obstacle shape, e.g., obtained through localization.

property initial_state: GeneralState

Initial state of the obstacle, e.g., obtained through sensor measurements.

property obstacle_id: int

Unique ID of the obstacle.

property obstacle_role: ObstacleRole

Obstacle role as defined in CommonOcean.

property obstacle_shape: Shape

Obstacle shape as defined in CommonOcean.

property obstacle_type: ObstacleType

Obstacle type as defined in CommonOcean.

StaticObstacle class

class commonocean.scenario.obstacle.StaticObstacle(obstacle_id: int, obstacle_type: ObstacleType, obstacle_shape: Shape, initial_state: GeneralState, depth: Optional[float] = None)

Class representing static obstacles as defined in CommonOcean.

property initial_center_waters_ids: Union[None, Set[int]]

Initial waters of obstacle center, e.g., obtained through localization.

property initial_shape_waters_ids: Union[None, Set[int]]

Initial waters of obstacle shape, e.g., obtained through localization.

property initial_state: GeneralState

Initial state of the obstacle, e.g., obtained through sensor measurements.

property obstacle_id: int

Unique ID of the obstacle.

property obstacle_role: ObstacleRole

Obstacle role as defined in CommonOcean.

property obstacle_shape: Shape

Obstacle shape as defined in CommonOcean.

property obstacle_type: ObstacleType

Obstacle type as defined in CommonOcean.

occupancy_at_time(time_step: int) → Occupancy

Returns the predicted occupancy of the obstacle at a specific time step.

Parameters:

time_step – discrete time step

Returns:

occupancy of the static obstacle at time step

state_at_time(time_step: int) → GeneralState

Returns the state the obstacle at a specific time step.

Parameters:

time_step – discrete time step

Returns:

state of the static obstacle at time step

translate_rotate(translation: ndarray, angle: float)

First translates the static obstacle, then rotates the static obstacle around the origin.

Parameters:

• translation – translation vector [x_off, y_off] in x- and y-direction

• angle – rotation angle in radian (counter-clockwise)

DynamicObstacle class

class commonocean.scenario.obstacle.DynamicObstacle(obstacle_id: int, obstacle_type: ObstacleType, obstacle_shape: Shape, initial_state: GeneralState, prediction: Union[None, Prediction, TrajectoryPrediction, SetBasedPrediction] = None, depth: Optional[float] = None)

Class representing dynamic obstacles as defined in CommonOcean. Each dynamic obstacle has stored its predicted movement in future time steps.

extreme_limits()

Calculate the extreme limits that the obstacle reaches during the movement.

property initial_center_waters_ids: Union[None, Set[int]]

Initial waters of obstacle center, e.g., obtained through localization.

property initial_shape_waters_ids: Union[None, Set[int]]

Initial waters of obstacle shape, e.g., obtained through localization.

property initial_state: GeneralState

Initial state of the obstacle, e.g., obtained through sensor measurements.

property obstacle_id: int

Unique ID of the obstacle.

property obstacle_role: ObstacleRole

Obstacle role as defined in CommonOcean.

property obstacle_shape: Shape

Obstacle shape as defined in CommonOcean.

property obstacle_type: ObstacleType

Obstacle type as defined in CommonOcean.

occupancy_at_time(time_step: int) → Union[None, Occupancy]

Returns the predicted occupancy of the obstacle at a specific time step.

Parameters:

time_step – discrete time step

Returns:

predicted occupancy of the obstacle at time step

property prediction: Optional[Union[Prediction, TrajectoryPrediction, SetBasedPrediction]]

Prediction describing the movement of the dynamic obstacle over time.

state_at_time(time_step: int) → Union[None, GeneralState]

Returns the predicted state of the obstacle at a specific time step.

Parameters:

time_step – discrete time step

Returns:

predicted state of the obstacle at time step

translate_rotate(translation: ndarray, angle: float)

First translates the dynamic obstacle, then rotates the dynamic obstacle around the origin.

Parameters:

• translation – translation vector [x_off, y_off] in x- and y-direction

• angle – rotation angle in radian (counter-clockwise)