Module scenariogeneration.xosc.storyboard

scenariogeneration: https://github.com/pyoscx/scenariogeneration

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

Copyright (c) 2022 The scenariogeneration Authors.

Classes

class Act (name: str,
starttrigger: scenariogeneration.xosc.utils._TriggerType | None = None,
stoptrigger: scenariogeneration.xosc.utils._TriggerType | None = None)

Expand source code

class Act(VersionBase):
    """The Act class creates the Act of the OpenScenario.

    Parameters
    ----------
    name : str
        Name of the act.
    starttrigger : _TriggerType, optional
        Start trigger of the act. Default is
        ValueTrigger('act_start', 0, ConditionEdge.none,
        SimulationTimeCondition(0, Rule.greaterThan)).
    stoptrigger : _TriggerType, optional
        Stop trigger of the act. Default is EmptyTrigger("stop").

    Attributes
    ----------
    name : str
        Name of the act.
    starttrigger : _TriggerType
        Start trigger of the act.
    stoptrigger : _TriggerType
        Stop trigger of the act.
    maneuvergroup : list of ManeuverGroup
        List of ManeuverGroups belonging to the act.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_maneuver_group(maneuvergroup)
        Adds a maneuver group to the act.
    get_element()
        Returns the full ElementTree of the class.
    get_attributes()
        Returns a dictionary of all attributes of the class.
    """

    def __init__(
        self,
        name: str,
        starttrigger: Optional[_TriggerType] = None,
        stoptrigger: Optional[_TriggerType] = None,
    ) -> None:
        """Initializes the Act.

        Parameters
        ----------
        name : str
            Name of the act.
        starttrigger : _TriggerType, optional
            Start trigger of the act. Default behavior depends on
            the OpenSCENARIO version.
            OpenSCENARIO 1.2 or less:
                Default is ValueTrigger('act_start', 0, ConditionEdge.none,
                SimulationTimeCondition(0, Rule.greaterThan)).
            OpenSCENARIO 1.3:
                None. The act starts when the Storyboard enters runningState.
        stoptrigger : _TriggerType, optional
            Stop trigger of the act. Default is EmptyTrigger("stop").
        """
        self.name = name
        self._none_starttrigger_input = False
        if starttrigger is None:
            self._none_starttrigger_input = True
            self._starttrigger = None
        elif not isinstance(starttrigger, _TriggerType):
            raise TypeError("starttrigger is not a valid TriggerType")
        elif starttrigger._triggerpoint == "StopTrigger":
            raise ValueError(
                "the starttrigger provided does not have start as the triggeringpoint"
            )
        else:
            self._starttrigger = starttrigger

        if stoptrigger is None:
            self.stoptrigger = Trigger("stop")
        elif not isinstance(stoptrigger, _TriggerType):
            raise TypeError("stoptrigger is not a valid TriggerType")
        elif stoptrigger._triggerpoint == "StartTrigger":
            raise ValueError(
                "the stoptrigger provided is not of type StopTrigger"
            )
        else:
            self.stoptrigger = stoptrigger

        self.maneuvergroup = []

    def __eq__(self, other: object) -> bool:
        if isinstance(other, Act):
            if (
                self._check_starttrigger(other)
                and self.stoptrigger == other.stoptrigger
                and self.maneuvergroup == other.maneuvergroup
            ):
                return True
        return False

    @property
    def starttrigger(self) -> Optional[Union[_TriggerType, _ValueTriggerType]]:
        """Returns the start trigger of the act."""
        if self._starttrigger is None:
            if self.isVersionEqLarger(1, 3):
                return None
            else:
                return self._default_starttrigger
        return self._starttrigger

    @starttrigger.setter
    def starttrigger(self, value):
        if value is not None and not isinstance(value, _TriggerType):
            raise TypeError(
                f"starttrigger must be None, _TriggerType, or _ValueTriggerType, not {type(value).__name__}"
            )

        self._starttrigger = value

    @property
    def _default_starttrigger(self) -> _ValueTriggerType:
        """Returns the start trigger of the act."""
        start_trigger = ValueTrigger(
            "act_start",
            0,
            ConditionEdge.none,
            SimulationTimeCondition(0, Rule.greaterThan),
        )
        return start_trigger

    def _check_starttrigger(self, other) -> bool:

        if self.isVersionEqLarger(1, 3):
            if self._none_starttrigger_input:
                return other.starttrigger is None
        return self.starttrigger == other.starttrigger

    @staticmethod
    def parse(element: ET.Element) -> "Act":
        """Parses the XML element of Act.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            An Act element (same as generated by the class itself).

        Returns
        -------
        Act
            An Act object.
        """
        name = element.attrib["name"]
        stoptrigger = None
        starttrigger = None
        if element.find("StopTrigger") is not None:
            stoptrigger = Trigger.parse(
                find_mandatory_field(element, "StopTrigger")
            )
        if element.find("StartTrigger") is not None:
            # TODO: If XML version is 1.3 or higher, starttrigger may be None;
            #  for earlier versions, a _TriggerType is required.
            starttrigger = Trigger.parse(
                find_mandatory_field(element, "StartTrigger")
            )

        act = Act(name, starttrigger, stoptrigger)
        for m in element.findall("ManeuverGroup"):
            act.add_maneuver_group(ManeuverGroup.parse(m))
        return act

    def add_maneuver_group(self, maneuvergroup: ManeuverGroup) -> "Act":
        """Adds a maneuver group to the act.

        Parameters
        ----------
        maneuvergroup : ManeuverGroup
            The maneuver group to add.
        """
        if not isinstance(maneuvergroup, ManeuverGroup):
            raise TypeError("maneuvergroup is not of type ManeuverGroup")
        self.maneuvergroup.append(maneuvergroup)
        return self

    def get_attributes(self) -> dict:
        """Returns the attributes as a dict of the Act.

        Returns
        -------
        dict
            A dictionary of all attributes of the class.
        """
        return {"name": self.name}

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the Act.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the Act.
        """
        if not self.maneuvergroup:
            raise ValueError("no maneuver group added to the act")
        element = ET.Element("Act", attrib=self.get_attributes())
        for mangr in self.maneuvergroup:
            element.append(mangr.get_element())
        starttrigger = self.starttrigger
        if self._none_starttrigger_input:
            if self.isVersionEqLarger(1, 3):
                starttrigger = None

            else:
                starttrigger = self._default_starttrigger
        if starttrigger is not None:
            element.append(starttrigger.get_element())
        element.append(self.stoptrigger.get_element())
        return element

The Act class creates the Act of the OpenScenario.

Parameters

name : str

Name of the act.

starttrigger : _TriggerType, optional

Start trigger of the act. Default is ValueTrigger('act_start', 0, ConditionEdge.none, SimulationTimeCondition(0, Rule.greaterThan)).

stoptrigger : _TriggerType, optional

Stop trigger of the act. Default is EmptyTrigger("stop").

Attributes

name : str

Name of the act.

starttrigger : _TriggerType

Start trigger of the act.

stoptrigger : _TriggerType

Stop trigger of the act.

maneuvergroup : list of ManeuverGroup

List of ManeuverGroups belonging to the act.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_maneuver_group(maneuvergroup) Adds a maneuver group to the act. get_element() Returns the full ElementTree of the class. get_attributes() Returns a dictionary of all attributes of the class.

Initializes the Act.

Parameters

name : str

Name of the act.

starttrigger : _TriggerType, optional

Start trigger of the act. Default behavior depends on the OpenSCENARIO version. OpenSCENARIO 1.2 or less: Default is ValueTrigger('act_start', 0, ConditionEdge.none, SimulationTimeCondition(0, Rule.greaterThan)). OpenSCENARIO 1.3: None. The act starts when the Storyboard enters runningState.

stoptrigger : _TriggerType, optional

Stop trigger of the act. Default is EmptyTrigger("stop").

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> Act

Expand source code

@staticmethod
def parse(element: ET.Element) -> "Act":
    """Parses the XML element of Act.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        An Act element (same as generated by the class itself).

    Returns
    -------
    Act
        An Act object.
    """
    name = element.attrib["name"]
    stoptrigger = None
    starttrigger = None
    if element.find("StopTrigger") is not None:
        stoptrigger = Trigger.parse(
            find_mandatory_field(element, "StopTrigger")
        )
    if element.find("StartTrigger") is not None:
        # TODO: If XML version is 1.3 or higher, starttrigger may be None;
        #  for earlier versions, a _TriggerType is required.
        starttrigger = Trigger.parse(
            find_mandatory_field(element, "StartTrigger")
        )

    act = Act(name, starttrigger, stoptrigger)
    for m in element.findall("ManeuverGroup"):
        act.add_maneuver_group(ManeuverGroup.parse(m))
    return act

Parses the XML element of Act.

Parameters

element : xml.etree.ElementTree.Element

An Act element (same as generated by the class itself).

Returns

Act

An Act object.

Instance variables

prop starttrigger : scenariogeneration.xosc.utils._TriggerType | scenariogeneration.xosc.utils._ValueTriggerType | None

Expand source code

@property
def starttrigger(self) -> Optional[Union[_TriggerType, _ValueTriggerType]]:
    """Returns the start trigger of the act."""
    if self._starttrigger is None:
        if self.isVersionEqLarger(1, 3):
            return None
        else:
            return self._default_starttrigger
    return self._starttrigger

Returns the start trigger of the act.

Methods

def add_maneuver_group(self,
maneuvergroup: ManeuverGroup) ‑> Act

Expand source code

def add_maneuver_group(self, maneuvergroup: ManeuverGroup) -> "Act":
    """Adds a maneuver group to the act.

    Parameters
    ----------
    maneuvergroup : ManeuverGroup
        The maneuver group to add.
    """
    if not isinstance(maneuvergroup, ManeuverGroup):
        raise TypeError("maneuvergroup is not of type ManeuverGroup")
    self.maneuvergroup.append(maneuvergroup)
    return self

Adds a maneuver group to the act.

Parameters

maneuvergroup : ManeuverGroup

The maneuver group to add.

def get_attributes(self) ‑> dict

Expand source code

def get_attributes(self) -> dict:
    """Returns the attributes as a dict of the Act.

    Returns
    -------
    dict
        A dictionary of all attributes of the class.
    """
    return {"name": self.name}

Returns the attributes as a dict of the Act.

Returns

dict

A dictionary of all attributes of the class.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the Act.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the Act.
    """
    if not self.maneuvergroup:
        raise ValueError("no maneuver group added to the act")
    element = ET.Element("Act", attrib=self.get_attributes())
    for mangr in self.maneuvergroup:
        element.append(mangr.get_element())
    starttrigger = self.starttrigger
    if self._none_starttrigger_input:
        if self.isVersionEqLarger(1, 3):
            starttrigger = None

        else:
            starttrigger = self._default_starttrigger
    if starttrigger is not None:
        element.append(starttrigger.get_element())
    element.append(self.stoptrigger.get_element())
    return element

Returns the ElementTree of the Act.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the Act.

class Event (name: str,
priority: Priority,
maxexecution: int = 1)

Expand source code

class Event(VersionBase):
    """The Event class creates the event of OpenScenario.

    Parameters
    ----------
    name : str
        Name of the event.
    priority : Priority
        What priority the event has.
    maxexecution : int, optional
        The maximum allowed executions of the event. Default is 1.

    Attributes
    ----------
    name : str
        Name of the event.
    priority : Priority
        What priority the event has.
    maxexecution : int
        The maximum allowed executions of the event.
    action : list of _Action
        All actions belonging to the event.
    trigger : _TriggerType
        A start trigger to the event.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_trigger(trigger)
        Adds a trigger to the event.
    add_action(actionname, action)
        Adds an action to the event (can be called multiple times).
    get_element()
        Returns the full ElementTree of the class.
    get_attributes()
        Returns a dictionary of all attributes of the class.
    """

    def __init__(
        self, name: str, priority: Priority, maxexecution: int = 1
    ) -> None:
        """Initializes the Event.

        Parameters
        ----------
        name : str
            Name of the event.
        priority : Priority
            What priority the event has.
        maxexecution : int, optional
            The maximum allowed executions of the event. Default is 1.
        """
        self.name = name
        self.priority = convert_enum(priority, Priority)
        self.action = []
        self.trigger = None
        self.maxexecution = convert_int(maxexecution)

    def __eq__(self, other: object) -> bool:
        if isinstance(other, Event):
            if (
                self.get_attributes() == other.get_attributes()
                and self.trigger == other.trigger
                and self.action == other.action
            ):
                return True
        return False

    @staticmethod
    def parse(element: ET.Element) -> "Event":
        """Parses the XML element of Event.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            An Event element (same as generated by the class itself).

        Returns
        -------
        Event
            An Event object.
        """
        name = element.attrib["name"]
        maxexec = None
        if "maximumExecutionCount" in element.attrib:
            maxexec = convert_int(element.attrib["maximumExecutionCount"])
        prio = getattr(Priority, element.attrib["priority"])

        event = Event(name, prio, maxexec)

        event.add_trigger(
            Trigger.parse(find_mandatory_field(element, "StartTrigger"))
        )

        for a in element.findall("Action"):
            event.action.append(_Action.parse(a))

        return event

    def add_trigger(self, trigger: _TriggerType) -> "Event":
        """Adds a starting trigger to the event.

        Parameters
        ----------
        trigger : _TriggerType
            Adds a trigger to start the event (not EmptyTrigger).
        """
        if not isinstance(trigger, _TriggerType):
            if isinstance(trigger, _ValueTriggerType):
                raise TypeError(
                    "trigger input is a value trigger condition, "
                    "please add it to a ValueTrigger."
                )
            if isinstance(trigger, _EntityTriggerType):
                raise TypeError(
                    "trigger input is an entity trigger condition, "
                    "please add it to an EntityTrigger."
                )
            raise TypeError("trigger input is not a valid trigger")
        self.trigger = trigger
        return self

    def add_action(self, actionname: str, action: _ActionType) -> "Event":
        """Adds an action to the Event. Multiple actions can be added and will
        be ordered as added.

        Parameters
        ----------
        actionname : str
            Name of the action.
        action : _ActionType
            Any action to be added to the event.
        """
        if not isinstance(action, _ActionType):
            raise TypeError("action input is not a valid Action")
        self.action.append(_Action(actionname, action))
        return self

    def get_attributes(self) -> dict:
        """Returns the attributes as a dict of the Event.

        Returns
        -------
        dict
            A dictionary of all attributes of the class.
        """
        retdict = {"name": self.name, "priority": self.priority.get_name()}
        if self.maxexecution is not None:
            retdict["maximumExecutionCount"] = str(self.maxexecution)
        return retdict

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the Event.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the Event.
        """
        if not self.action:
            raise ValueError("no action(s) set")
        if self.isVersion(minor=0) and not self.trigger:
            raise ValueError("no trigger set")

        element = ET.Element("Event", attrib=self.get_attributes())
        for action in self.action:
            element.append(action.get_element())
        if self.trigger:
            element.append(self.trigger.get_element())
        return element

The Event class creates the event of OpenScenario.

Parameters

name : str

Name of the event.

priority : Priority

What priority the event has.

maxexecution : int, optional

The maximum allowed executions of the event. Default is 1.

Attributes

name : str

Name of the event.

priority : Priority

What priority the event has.

maxexecution : int

The maximum allowed executions of the event.

action : list of _Action

All actions belonging to the event.

trigger : _TriggerType

A start trigger to the event.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_trigger(trigger) Adds a trigger to the event. add_action(actionname, action) Adds an action to the event (can be called multiple times). get_element() Returns the full ElementTree of the class. get_attributes() Returns a dictionary of all attributes of the class.

Initializes the Event.

Parameters

name : str

Name of the event.

priority : Priority

What priority the event has.

maxexecution : int, optional

The maximum allowed executions of the event. Default is 1.

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> Event

Expand source code

@staticmethod
def parse(element: ET.Element) -> "Event":
    """Parses the XML element of Event.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        An Event element (same as generated by the class itself).

    Returns
    -------
    Event
        An Event object.
    """
    name = element.attrib["name"]
    maxexec = None
    if "maximumExecutionCount" in element.attrib:
        maxexec = convert_int(element.attrib["maximumExecutionCount"])
    prio = getattr(Priority, element.attrib["priority"])

    event = Event(name, prio, maxexec)

    event.add_trigger(
        Trigger.parse(find_mandatory_field(element, "StartTrigger"))
    )

    for a in element.findall("Action"):
        event.action.append(_Action.parse(a))

    return event

Parses the XML element of Event.

Parameters

element : xml.etree.ElementTree.Element

An Event element (same as generated by the class itself).

Returns

Event

An Event object.

Methods

def add_action(self, actionname: str, action: scenariogeneration.xosc.actions._ActionType) ‑> Event

Expand source code

def add_action(self, actionname: str, action: _ActionType) -> "Event":
    """Adds an action to the Event. Multiple actions can be added and will
    be ordered as added.

    Parameters
    ----------
    actionname : str
        Name of the action.
    action : _ActionType
        Any action to be added to the event.
    """
    if not isinstance(action, _ActionType):
        raise TypeError("action input is not a valid Action")
    self.action.append(_Action(actionname, action))
    return self

Adds an action to the Event. Multiple actions can be added and will be ordered as added.

Parameters

actionname : str

Name of the action.

action : _ActionType

Any action to be added to the event.

def add_trigger(self, trigger: scenariogeneration.xosc.utils._TriggerType) ‑> Event

Expand source code

def add_trigger(self, trigger: _TriggerType) -> "Event":
    """Adds a starting trigger to the event.

    Parameters
    ----------
    trigger : _TriggerType
        Adds a trigger to start the event (not EmptyTrigger).
    """
    if not isinstance(trigger, _TriggerType):
        if isinstance(trigger, _ValueTriggerType):
            raise TypeError(
                "trigger input is a value trigger condition, "
                "please add it to a ValueTrigger."
            )
        if isinstance(trigger, _EntityTriggerType):
            raise TypeError(
                "trigger input is an entity trigger condition, "
                "please add it to an EntityTrigger."
            )
        raise TypeError("trigger input is not a valid trigger")
    self.trigger = trigger
    return self

Adds a starting trigger to the event.

Parameters

trigger : _TriggerType

Adds a trigger to start the event (not EmptyTrigger).

def get_attributes(self) ‑> dict

Expand source code

def get_attributes(self) -> dict:
    """Returns the attributes as a dict of the Event.

    Returns
    -------
    dict
        A dictionary of all attributes of the class.
    """
    retdict = {"name": self.name, "priority": self.priority.get_name()}
    if self.maxexecution is not None:
        retdict["maximumExecutionCount"] = str(self.maxexecution)
    return retdict

Returns the attributes as a dict of the Event.

Returns

dict

A dictionary of all attributes of the class.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the Event.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the Event.
    """
    if not self.action:
        raise ValueError("no action(s) set")
    if self.isVersion(minor=0) and not self.trigger:
        raise ValueError("no trigger set")

    element = ET.Element("Event", attrib=self.get_attributes())
    for action in self.action:
        element.append(action.get_element())
    if self.trigger:
        element.append(self.trigger.get_element())
    return element

Returns the ElementTree of the Event.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the Event.

class Init

Expand source code

class Init(VersionBase):
    """The Init class creates the init part of the storyboard.

    Attributes
    ----------
    initactions : dict
        A dictionary containing all init actions of the scenario.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    get_element()
        Returns the full ElementTree of the class.
    add_init_action(entityname, action)
        Adds a private action to the init.
    add_global_action(action)
        Adds a global action to the init.
    add_user_defined_action(action)
        Adds a user-defined action to the init.
    """

    def __init__(self) -> None:
        """Initializes the Init class."""
        self.initactions = {}
        self.global_actions = []
        self.user_defined_actions = []

    def __eq__(self, other: object) -> bool:
        if isinstance(other, Init):
            if (
                self.initactions == other.initactions
                and self.global_actions == other.global_actions
                and self.user_defined_actions == other.user_defined_actions
            ):
                return True
        return False

    @staticmethod
    def parse(element: ET.Element) -> "Init":
        """Parses the XML element of Init.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            An Init element (same as generated by the class itself).

        Returns
        -------
        Init
            An Init object.


        Notes
        -----
        Cannot parse UserDefinedAction.
        """
        init = Init()
        action_element = find_mandatory_field(element, "Actions")
        global_elements = action_element.findall("GlobalAction")
        for ga in global_elements:
            globalaction = _GlobalActionFactory.parse_globalaction(ga)
            init.add_global_action(globalaction)

        private_elements = action_element.findall("Private")
        for pe in private_elements:
            actor = pe.attrib["entityRef"]
            all_private_actions = pe.findall("PrivateAction")
            for pa in all_private_actions:
                privateaction = _PrivateActionFactory.parse_privateaction(pa)
                init.add_init_action(actor, privateaction)

        return init

    def add_init_action(
        self, entityname: str, action: _PrivateActionType
    ) -> None:
        """Adds a private action to the init.

        Parameters
        ----------
        entityname : str
            Name of the entity to add the action to.
        action : _PrivateActionType
            Any private action to be added (e.g., TeleportAction).
        """
        if not isinstance(action, _PrivateActionType):
            if isinstance(action, _ActionType):
                raise TypeError(
                    "the action provided is a global action, please use add_global_action instead"
                )
            raise TypeError("action input is not a valid action")
        if entityname not in self.initactions:
            self.initactions[entityname] = []

        self.initactions[entityname].append(action)

    def add_global_action(self, action: _ActionType) -> "Init":
        """Adds a global action to the init.

        Parameters
        ----------
        action : _ActionType
            Any global action to add to the init.
        """
        if isinstance(action, _PrivateActionType):
            raise TypeError(
                "action input is a Private action, please use add_init_action instead"
            )
        if not isinstance(action, _ActionType):
            raise TypeError("action input is not a valid action")
        self.global_actions.append(action)
        return self

    def add_user_defined_action(self, action: CustomCommandAction) -> "Init":
        """Adds a user-defined action to the init.

        Parameters
        ----------
        action : CustomCommandAction
            A custom command action.
        """
        if not isinstance(action, CustomCommandAction):
            raise TypeError("action is not of type CustomCommandAction")
        self.user_defined_actions.append(action)
        return self

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the Init.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the Init.
        """
        element = ET.Element("Init")
        actions = ET.SubElement(element, "Actions")

        # add global actions
        for i in self.global_actions:
            actions.append(i.get_element())

        # add user defined actions
        for i in self.user_defined_actions:
            actions.append(i.get_element())

        # add private actions
        for key, val in self.initactions.items():
            private = ET.SubElement(
                actions, "Private", attrib={"entityRef": key}
            )
            for j in val:
                private.append(j.get_element())

        return element

The Init class creates the init part of the storyboard.

Attributes

initactions : dict

A dictionary containing all init actions of the scenario.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. get_element() Returns the full ElementTree of the class. add_init_action(entityname, action) Adds a private action to the init. add_global_action(action) Adds a global action to the init. add_user_defined_action(action) Adds a user-defined action to the init.

Initializes the Init class.

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> Init

Expand source code

@staticmethod
def parse(element: ET.Element) -> "Init":
    """Parses the XML element of Init.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        An Init element (same as generated by the class itself).

    Returns
    -------
    Init
        An Init object.


    Notes
    -----
    Cannot parse UserDefinedAction.
    """
    init = Init()
    action_element = find_mandatory_field(element, "Actions")
    global_elements = action_element.findall("GlobalAction")
    for ga in global_elements:
        globalaction = _GlobalActionFactory.parse_globalaction(ga)
        init.add_global_action(globalaction)

    private_elements = action_element.findall("Private")
    for pe in private_elements:
        actor = pe.attrib["entityRef"]
        all_private_actions = pe.findall("PrivateAction")
        for pa in all_private_actions:
            privateaction = _PrivateActionFactory.parse_privateaction(pa)
            init.add_init_action(actor, privateaction)

    return init

Parses the XML element of Init.

Parameters

element : xml.etree.ElementTree.Element

An Init element (same as generated by the class itself).

Returns

Init

An Init object.

Notes

Cannot parse UserDefinedAction.

Methods

def add_global_action(self, action: scenariogeneration.xosc.actions._ActionType) ‑> Init

Expand source code

def add_global_action(self, action: _ActionType) -> "Init":
    """Adds a global action to the init.

    Parameters
    ----------
    action : _ActionType
        Any global action to add to the init.
    """
    if isinstance(action, _PrivateActionType):
        raise TypeError(
            "action input is a Private action, please use add_init_action instead"
        )
    if not isinstance(action, _ActionType):
        raise TypeError("action input is not a valid action")
    self.global_actions.append(action)
    return self

Adds a global action to the init.

Parameters

action : _ActionType

Any global action to add to the init.

def add_init_action(self,
entityname: str,
action: scenariogeneration.xosc.actions._PrivateActionType) ‑> None

Expand source code

def add_init_action(
    self, entityname: str, action: _PrivateActionType
) -> None:
    """Adds a private action to the init.

    Parameters
    ----------
    entityname : str
        Name of the entity to add the action to.
    action : _PrivateActionType
        Any private action to be added (e.g., TeleportAction).
    """
    if not isinstance(action, _PrivateActionType):
        if isinstance(action, _ActionType):
            raise TypeError(
                "the action provided is a global action, please use add_global_action instead"
            )
        raise TypeError("action input is not a valid action")
    if entityname not in self.initactions:
        self.initactions[entityname] = []

    self.initactions[entityname].append(action)

Adds a private action to the init.

Parameters

entityname : str

Name of the entity to add the action to.

action : _PrivateActionType

Any private action to be added (e.g., TeleportAction).

def add_user_defined_action(self,
action: CustomCommandAction) ‑> Init

Expand source code

def add_user_defined_action(self, action: CustomCommandAction) -> "Init":
    """Adds a user-defined action to the init.

    Parameters
    ----------
    action : CustomCommandAction
        A custom command action.
    """
    if not isinstance(action, CustomCommandAction):
        raise TypeError("action is not of type CustomCommandAction")
    self.user_defined_actions.append(action)
    return self

Adds a user-defined action to the init.

Parameters

action : CustomCommandAction

A custom command action.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the Init.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the Init.
    """
    element = ET.Element("Init")
    actions = ET.SubElement(element, "Actions")

    # add global actions
    for i in self.global_actions:
        actions.append(i.get_element())

    # add user defined actions
    for i in self.user_defined_actions:
        actions.append(i.get_element())

    # add private actions
    for key, val in self.initactions.items():
        private = ET.SubElement(
            actions, "Private", attrib={"entityRef": key}
        )
        for j in val:
            private.append(j.get_element())

    return element

Returns the ElementTree of the Init.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the Init.

class Maneuver (name: str,
parameters: ParameterDeclarations | None = None)

Expand source code

class Maneuver(_BaseCatalog):
    """The Maneuver class creates the Maneuver of OpenScenario.

    Parameters
    ----------
    name : str
        Name of the Maneuver.
    parameters : ParameterDeclarations, optional
        Parameter declarations for the maneuver. Default is None.

    Attributes
    ----------
    name : str
        Name of the Maneuver.
    events : list of Event
        All events belonging to the Maneuver.
    parameters : ParameterDeclarations
        Parameter declarations for the maneuver.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_event(event)
        Adds an event to the Maneuver.
    append_to_catalog(filename)
        Adds the vehicle to an existing catalog.
    dump_to_catalog(filename, name, description, author)
        Creates a new catalog with the vehicle.
    get_element()
        Returns the full ElementTree of the class.
    get_attributes()
        Returns a dictionary of all attributes of the class.
    """

    def __init__(
        self, name: str, parameters: Optional[ParameterDeclarations] = None
    ) -> None:
        """Initializes the Maneuver.

        Parameters
        ----------
        name : str
            Name of the Maneuver.
        parameters : ParameterDeclarations, optional
            Parameter declarations for the maneuver. Default is None.
        """
        super().__init__()
        if parameters is not None and not isinstance(
            parameters, ParameterDeclarations
        ):
            raise TypeError("parameters is not of type ParameterDeclarations")
        if parameters is not None:
            self.parameters = parameters
        self.name = name
        self.events = []

    def __eq__(self, other: object) -> bool:
        if isinstance(other, Maneuver):
            if (
                self.get_attributes() == other.get_attributes()
                and self.parameters == other.parameters
                and self.events == other.events
            ):
                return True
        return False

    @staticmethod
    def parse(element: ET.Element) -> "Maneuver":
        """Parses the XML element of Maneuver.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            A Maneuver element (same as generated by the class
            itself).

        Returns
        -------
        Maneuver
            A Maneuver object.
        """
        parameters = None
        if element.find("ParameterDeclarations") is not None:
            parameters = ParameterDeclarations.parse(
                find_mandatory_field(element, "ParameterDeclarations")
            )
        name = element.attrib["name"]
        man = Maneuver(name, parameters)

        for e in element.findall("Event"):
            man.add_event(Event.parse(e))
        return man

    def add_event(self, event: "Event") -> "Maneuver":
        """Adds an event to the Maneuver.

        Parameters
        ----------
        event : Event
            The event to add to the Maneuver.
        """
        if not isinstance(event, Event):
            raise TypeError("event input is not of type Event")
        self.events.append(event)
        return self

    def get_attributes(self) -> dict:
        """Returns the attributes as a dict of the Maneuver.

        Returns
        -------
        dict
            A dictionary of all attributes of the class.
        """
        return {"name": self.name}

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the Maneuver.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the Maneuver.
        """
        if not self.events:
            raise ValueError("no events added to the maneuver")

        element = ET.Element("Maneuver", attrib=self.get_attributes())
        self.add_parameters_to_element(element)
        for event in self.events:
            element.append(event.get_element())

        return element

The Maneuver class creates the Maneuver of OpenScenario.

Parameters

name : str

Name of the Maneuver.

parameters : ParameterDeclarations, optional

Parameter declarations for the maneuver. Default is None.

Attributes

name : str

Name of the Maneuver.

events : list of Event

All events belonging to the Maneuver.

parameters : ParameterDeclarations

Parameter declarations for the maneuver.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_event(event) Adds an event to the Maneuver. append_to_catalog(filename) Adds the vehicle to an existing catalog. dump_to_catalog(filename, name, description, author) Creates a new catalog with the vehicle. get_element() Returns the full ElementTree of the class. get_attributes() Returns a dictionary of all attributes of the class.

Initializes the Maneuver.

Parameters

name : str

Name of the Maneuver.

parameters : ParameterDeclarations, optional

Parameter declarations for the maneuver. Default is None.

Ancestors

• scenariogeneration.xosc.utils._BaseCatalog
• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> Maneuver

Expand source code

@staticmethod
def parse(element: ET.Element) -> "Maneuver":
    """Parses the XML element of Maneuver.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        A Maneuver element (same as generated by the class
        itself).

    Returns
    -------
    Maneuver
        A Maneuver object.
    """
    parameters = None
    if element.find("ParameterDeclarations") is not None:
        parameters = ParameterDeclarations.parse(
            find_mandatory_field(element, "ParameterDeclarations")
        )
    name = element.attrib["name"]
    man = Maneuver(name, parameters)

    for e in element.findall("Event"):
        man.add_event(Event.parse(e))
    return man

Parses the XML element of Maneuver.

Parameters

element : xml.etree.ElementTree.Element

A Maneuver element (same as generated by the class itself).

Returns

Maneuver

A Maneuver object.

Methods

def add_event(self,
event: Event) ‑> Maneuver

Expand source code

def add_event(self, event: "Event") -> "Maneuver":
    """Adds an event to the Maneuver.

    Parameters
    ----------
    event : Event
        The event to add to the Maneuver.
    """
    if not isinstance(event, Event):
        raise TypeError("event input is not of type Event")
    self.events.append(event)
    return self

Adds an event to the Maneuver.

Parameters

event : Event

The event to add to the Maneuver.

def get_attributes(self) ‑> dict

Expand source code

def get_attributes(self) -> dict:
    """Returns the attributes as a dict of the Maneuver.

    Returns
    -------
    dict
        A dictionary of all attributes of the class.
    """
    return {"name": self.name}

Returns the attributes as a dict of the Maneuver.

Returns

dict

A dictionary of all attributes of the class.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the Maneuver.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the Maneuver.
    """
    if not self.events:
        raise ValueError("no events added to the maneuver")

    element = ET.Element("Maneuver", attrib=self.get_attributes())
    self.add_parameters_to_element(element)
    for event in self.events:
        element.append(event.get_element())

    return element

Returns the ElementTree of the Maneuver.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the Maneuver.

class ManeuverGroup (name: str, maxexecution: int = 1, selecttriggeringentities: bool = False)

Expand source code

class ManeuverGroup(VersionBase):
    """The ManeuverGroup creates the ManeuverGroup of the OpenScenario.

    Parameters
    ----------
    name : str
        Name of the ManeuverGroup.
    maxexecution : int, optional
        Maximum number of iterations. Default is 1.
    selecttriggeringentities : bool, optional
        Have no idea what this does. Default is False.

    Attributes
    ----------
    name : str
        Name of the ManeuverGroup.
    maxexecution : int
        Maximum number of iterations.
    selecttriggeringentities : bool
        Have no idea what this does.
    maneuvers : list of Maneuver
        The maneuvers in the ManeuverGroup.
    actors : _Actors
        All actors of the ManeuverGroup.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_maneuver(maneuver)
        Adds a maneuver to the ManeuverGroup.
    add_actor(entity)
        Adds an actor to the ManeuverGroup.
    get_element()
        Returns the full ElementTree of the class.
    get_attributes()
        Returns a dictionary of all attributes of the class.
    """

    def __init__(
        self,
        name: str,
        maxexecution: int = 1,
        selecttriggeringentities: bool = False,
    ) -> None:
        """Initializes the ManeuverGroup.

        Parameters
        ----------
        name : str
            Name of the ManeuverGroup.
        maxexecution : int, optional
            Maximum number of iterations. Default is 1.
        selecttriggeringentities : bool, optional
            Have no idea what this does. Default is False.
        """
        self.name = name
        self.maxexecution = convert_int(maxexecution)
        self.actors = _Actors(selecttriggeringentities)
        self.maneuvers = []

    def __eq__(self, other: object) -> bool:
        if isinstance(other, ManeuverGroup):
            if (
                self.get_attributes() == other.get_attributes()
                and self.actors == other.actors
                and self.maneuvers == other.maneuvers
            ):
                return True
        return False

    @staticmethod
    def parse(element: ET.Element) -> "ManeuverGroup":
        """Parses the XML element of ManeuverGroup.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            A ManeuverGroup element (same as generated by the class
            itself).

        Returns
        -------
        ManeuverGroup
            A ManeuverGroup object.
        """
        name = element.attrib["name"]
        maxexec = convert_int(element.attrib["maximumExecutionCount"])
        actors = _Actors.parse(find_mandatory_field(element, "Actors"))
        maneuver_group = ManeuverGroup(name, maxexec)
        maneuver_group.actors = actors
        for m in element.findall("Maneuver"):
            maneuver_group.add_maneuver(Maneuver.parse(m))
        for cr in element.findall("CatalogReference"):
            maneuver_group.add_maneuver(CatalogReference.parse(cr))

        return maneuver_group

    def add_maneuver(
        self, maneuver: Union[Maneuver, CatalogReference]
    ) -> "ManeuverGroup":
        """Adds a maneuver to the ManeuverGroup.

        Parameters
        ----------
        maneuver : Maneuver or CatalogReference
            The maneuver to add.
        """
        if not isinstance(maneuver, (Maneuver, CatalogReference)):
            raise TypeError("maneuver input is not of type Maneuver")
        self.maneuvers.append(maneuver)
        return self

    def add_actor(self, entity: str) -> "ManeuverGroup":
        """Adds an actor to the ManeuverGroup.

        Parameters
        ----------
        entity : str
            Name of the entity to add as an actor.
        """
        self.actors.add_actor(entity)
        return self

    def get_attributes(self) -> dict:
        """Returns the attributes as a dict of the ManeuverGroup.

        Returns
        -------
        dict
            A dictionary of all attributes of the class.
        """
        return {
            "name": self.name,
            "maximumExecutionCount": str(self.maxexecution),
        }

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the ManeuverGroup.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the ManeuverGroup.
        """
        element = ET.Element("ManeuverGroup", attrib=self.get_attributes())
        element.append(self.actors.get_element())
        for man in self.maneuvers:
            element.append(man.get_element())
        return element

The ManeuverGroup creates the ManeuverGroup of the OpenScenario.

Parameters

name : str

Name of the ManeuverGroup.

maxexecution : int, optional

Maximum number of iterations. Default is 1.

selecttriggeringentities : bool, optional

Have no idea what this does. Default is False.

Attributes

name : str

Name of the ManeuverGroup.

maxexecution : int

Maximum number of iterations.

selecttriggeringentities : bool

Have no idea what this does.

maneuvers : list of Maneuver

The maneuvers in the ManeuverGroup.

actors : _Actors

All actors of the ManeuverGroup.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_maneuver(maneuver) Adds a maneuver to the ManeuverGroup. add_actor(entity) Adds an actor to the ManeuverGroup. get_element() Returns the full ElementTree of the class. get_attributes() Returns a dictionary of all attributes of the class.

Initializes the ManeuverGroup.

Parameters

name : str

Name of the ManeuverGroup.

maxexecution : int, optional

Maximum number of iterations. Default is 1.

selecttriggeringentities : bool, optional

Have no idea what this does. Default is False.

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> ManeuverGroup

Expand source code

@staticmethod
def parse(element: ET.Element) -> "ManeuverGroup":
    """Parses the XML element of ManeuverGroup.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        A ManeuverGroup element (same as generated by the class
        itself).

    Returns
    -------
    ManeuverGroup
        A ManeuverGroup object.
    """
    name = element.attrib["name"]
    maxexec = convert_int(element.attrib["maximumExecutionCount"])
    actors = _Actors.parse(find_mandatory_field(element, "Actors"))
    maneuver_group = ManeuverGroup(name, maxexec)
    maneuver_group.actors = actors
    for m in element.findall("Maneuver"):
        maneuver_group.add_maneuver(Maneuver.parse(m))
    for cr in element.findall("CatalogReference"):
        maneuver_group.add_maneuver(CatalogReference.parse(cr))

    return maneuver_group

Parses the XML element of ManeuverGroup.

Parameters

element : xml.etree.ElementTree.Element

A ManeuverGroup element (same as generated by the class itself).

Returns

ManeuverGroup

A ManeuverGroup object.

Methods

def add_actor(self, entity: str) ‑> ManeuverGroup

Expand source code

def add_actor(self, entity: str) -> "ManeuverGroup":
    """Adds an actor to the ManeuverGroup.

    Parameters
    ----------
    entity : str
        Name of the entity to add as an actor.
    """
    self.actors.add_actor(entity)
    return self

Adds an actor to the ManeuverGroup.

Parameters

entity : str

Name of the entity to add as an actor.

def add_maneuver(self,
maneuver: Maneuver | CatalogReference) ‑> ManeuverGroup

Expand source code

def add_maneuver(
    self, maneuver: Union[Maneuver, CatalogReference]
) -> "ManeuverGroup":
    """Adds a maneuver to the ManeuverGroup.

    Parameters
    ----------
    maneuver : Maneuver or CatalogReference
        The maneuver to add.
    """
    if not isinstance(maneuver, (Maneuver, CatalogReference)):
        raise TypeError("maneuver input is not of type Maneuver")
    self.maneuvers.append(maneuver)
    return self

Adds a maneuver to the ManeuverGroup.

Parameters

maneuver : Maneuver or CatalogReference

The maneuver to add.

def get_attributes(self) ‑> dict

Expand source code

def get_attributes(self) -> dict:
    """Returns the attributes as a dict of the ManeuverGroup.

    Returns
    -------
    dict
        A dictionary of all attributes of the class.
    """
    return {
        "name": self.name,
        "maximumExecutionCount": str(self.maxexecution),
    }

Returns the attributes as a dict of the ManeuverGroup.

Returns

dict

A dictionary of all attributes of the class.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the ManeuverGroup.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the ManeuverGroup.
    """
    element = ET.Element("ManeuverGroup", attrib=self.get_attributes())
    element.append(self.actors.get_element())
    for man in self.maneuvers:
        element.append(man.get_element())
    return element

Returns the ElementTree of the ManeuverGroup.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the ManeuverGroup.

class Story (name: str,
parameters: ParameterDeclarations = <scenariogeneration.xosc.utils.ParameterDeclarations object>)

Expand source code

class Story(VersionBase):
    """The Story class creates a story of the OpenScenario.

    Parameters
    ----------
    name : str
        Name of the story.
    parameters : ParameterDeclarations, optional
        The parameters of the Story. Default is
        ParameterDeclarations().

    Attributes
    ----------
    name : str
        Name of the story.
    parameters : ParameterDeclarations
        The parameters of the story.
    acts : list of Act
        All acts belonging to the story.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_act(act)
        Adds an act to the story.
    get_element()
        Returns the full ElementTree of the class.
    get_attributes()
        Returns a dictionary of all attributes of the class.
    """

    def __init__(
        self,
        name: str,
        parameters: ParameterDeclarations = ParameterDeclarations(),
    ) -> None:
        """Initializes the Story class.

        Parameters
        ----------
        name : str
            Name of the story.
        parameters : ParameterDeclarations, optional
            The parameters of the Story. Default is
            ParameterDeclarations().
        """
        self.name = name

        self.acts = []
        if not isinstance(parameters, ParameterDeclarations):
            raise TypeError(
                "parameters input is not of type ParameterDeclarations"
            )

        self.parameter = parameters

    def __eq__(self, other: object) -> bool:
        if isinstance(other, Story):
            if (
                self.get_attributes() == other.get_attributes()
                and self.parameter == other.parameter
                and self.acts == other.acts
            ):
                return True
        return False

    @staticmethod
    def parse(element: ET.Element) -> "Story":
        """Parses the XML element of Story.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            A Story element (same as generated by the class itself).

        Returns
        -------
        Story
            A Story object.
        """
        name = element.attrib["name"]
        if element.find("ParameterDeclarations") is not None:
            parameters = ParameterDeclarations.parse(
                find_mandatory_field(element, "ParameterDeclarations")
            )
        else:
            parameters = ParameterDeclarations()
        story = Story(name, parameters)
        for a in element.findall("Act"):
            story.add_act(Act.parse(a))
        return story

    def add_act(self, act: Act) -> "Story":
        """Adds an act to the story.

        Parameters
        ----------
        act : Act
            Act to add to the story.
        """
        if not isinstance(act, Act):
            raise TypeError("act input is not of type Act")
        self.acts.append(act)
        return self

    def get_attributes(self) -> dict:
        """Returns the attributes as a dict of the Story.

        Returns
        -------
        dict
            A dictionary of all attributes of the class.
        """
        return {"name": self.name}

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the Story.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the Story.
        """
        element = ET.Element("Story", attrib=self.get_attributes())
        if self.parameter.get_element():
            element.append(self.parameter.get_element())
        if not self.acts:
            raise ValueError("no acts added to the story")
        for a in self.acts:
            element.append(a.get_element())
        return element

The Story class creates a story of the OpenScenario.

Parameters

name : str

Name of the story.

parameters : ParameterDeclarations, optional

The parameters of the Story. Default is ParameterDeclarations().

Attributes

name : str

Name of the story.

parameters : ParameterDeclarations

The parameters of the story.

acts : list of Act

All acts belonging to the story.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_act(act) Adds an act to the story. get_element() Returns the full ElementTree of the class. get_attributes() Returns a dictionary of all attributes of the class.

Initializes the Story class.

Parameters

name : str

Name of the story.

parameters : ParameterDeclarations, optional

The parameters of the Story. Default is ParameterDeclarations().

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> Story

Expand source code

@staticmethod
def parse(element: ET.Element) -> "Story":
    """Parses the XML element of Story.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        A Story element (same as generated by the class itself).

    Returns
    -------
    Story
        A Story object.
    """
    name = element.attrib["name"]
    if element.find("ParameterDeclarations") is not None:
        parameters = ParameterDeclarations.parse(
            find_mandatory_field(element, "ParameterDeclarations")
        )
    else:
        parameters = ParameterDeclarations()
    story = Story(name, parameters)
    for a in element.findall("Act"):
        story.add_act(Act.parse(a))
    return story

Parses the XML element of Story.

Parameters

element : xml.etree.ElementTree.Element

A Story element (same as generated by the class itself).

Returns

Story

A Story object.

Methods

def add_act(self,
act: Act) ‑> Story

Expand source code

def add_act(self, act: Act) -> "Story":
    """Adds an act to the story.

    Parameters
    ----------
    act : Act
        Act to add to the story.
    """
    if not isinstance(act, Act):
        raise TypeError("act input is not of type Act")
    self.acts.append(act)
    return self

Adds an act to the story.

Parameters

act : Act

Act to add to the story.

def get_attributes(self) ‑> dict

Expand source code

def get_attributes(self) -> dict:
    """Returns the attributes as a dict of the Story.

    Returns
    -------
    dict
        A dictionary of all attributes of the class.
    """
    return {"name": self.name}

Returns the attributes as a dict of the Story.

Returns

dict

A dictionary of all attributes of the class.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the Story.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the Story.
    """
    element = ET.Element("Story", attrib=self.get_attributes())
    if self.parameter.get_element():
        element.append(self.parameter.get_element())
    if not self.acts:
        raise ValueError("no acts added to the story")
    for a in self.acts:
        element.append(a.get_element())
    return element

Returns the ElementTree of the Story.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the Story.

class StoryBoard (init: Init = <scenariogeneration.xosc.storyboard.Init object>,
stoptrigger: scenariogeneration.xosc.utils._TriggerType | None = None)

Expand source code

class StoryBoard(VersionBase):
    """The StoryBoard class creates the storyboard of OpenScenario.

    Parameters
    ----------
    init : Init, optional
        The init part of the storyboard. Default is Init().
    stoptrigger : _TriggerType, optional
        The stop trigger of the storyboard. Default is
        EmptyTrigger("stop").

    Attributes
    ----------
    init : Init
        The init of the storyboard.
    stoptrigger : _TriggerType
        The stop trigger of the storyboard.
    stories : list of Story
        All stories of the scenario.

    Methods
    -------
    parse(element)
        Parses an ElementTree created by the class and returns an
        instance of the class.
    add_story(story)
        Adds a story to the storyboard.
    get_element()
        Returns the full ElementTree of the class.
    """

    def __init__(
        self,
        init: Init = Init(),
        stoptrigger: Optional[_TriggerType] = None,
    ) -> None:
        """Initializes the StoryBoard.

        Parameters
        ----------
        init : Init, optional
            The init part of the storyboard. Default is Init().
        stoptrigger : _TriggerType, optional
            The stop trigger of the storyboard.
            OpenSCENARIO 1.2 or less:
                Default is Trigger("stop").
            OpenSCENARIO 1.3:
                None. The Storyboard will never be stopped.
        """
        if not isinstance(init, Init):
            raise TypeError("init is not of type Init")
        if stoptrigger is None:
            self._stoptrigger = None
        else:
            if not isinstance(stoptrigger, _TriggerType):
                raise TypeError("stoptrigger is not a valid Trigger")
            # check that the stoptrigger has a triggeringpoint that is 'stop'
            elif stoptrigger._triggerpoint == "StartTrigger":
                raise ValueError(
                    "the stoptrigger provided does not have stop as the triggeringpoint"
                )
            else:
                self._stoptrigger = stoptrigger

        self.init = init
        self.stories = []

    def __eq__(self, other: object) -> bool:
        if not self.stories:
            self.get_element()
        if isinstance(other, StoryBoard):
            if (
                self.init == other.init
                and self.stoptrigger == other.stoptrigger
                and self.stories == other.stories
            ):
                return True
        return False

    @property
    def stoptrigger(self) -> Optional[Union[_TriggerType, _ValueTriggerType]]:
        """Returns the stop trigger of the storyboard."""
        if self._stoptrigger is None:
            if self.isVersionEqLarger(1, 3):
                return None
            else:
                return Trigger("stop")
        return self._stoptrigger

    @stoptrigger.setter
    def stoptrigger(self, value):
        if value is not None and not isinstance(value, _TriggerType):
            raise TypeError(
                f"stoptrigger must be None, _TriggerType, or _ValueTriggerType, not {type(value).__name__}"
            )
        if self.isVersionEqLess(1, 2) and value is None:
            raise ValueError(
                "stoptrigger cannot be None for OpenSCENARIO version 1.2 or less"
            )
        self._stoptrigger = value

    @staticmethod
    def parse(element: ET.Element) -> "StoryBoard":
        """Parses the XML element of StoryBoard.

        Parameters
        ----------
        element : xml.etree.ElementTree.Element
            A StoryBoard element (same as generated by the class
            itself).

        Returns
        -------
        StoryBoard
            A StoryBoard object.
        """
        init = Init.parse(find_mandatory_field(element, "Init"))
        stoptrigger = None
        if element.find("StopTrigger") is not None:
            stoptrigger = Trigger.parse(
                find_mandatory_field(element, "StopTrigger")
            )
        storyboard = StoryBoard(init, stoptrigger)
        for s in element.findall("Story"):
            storyboard.add_story(Story.parse(s))
        return storyboard

    def add_story(self, story: Story) -> "StoryBoard":
        """Adds a story to the storyboard.

        Parameters
        ----------
        story : Story
            The story to be added.
        """
        if not isinstance(story, Story):
            raise TypeError("story input is not of type Story")
        self.stories.append(story)
        return self

    def add_act(
        self,
        act: Act,
        parameters: ParameterDeclarations = ParameterDeclarations(),
    ) -> "StoryBoard":
        """Adds a single act to one story. For multi-act scenarios, use Story
        instead.

        Parameters
        ----------
        act : Act
            The Act to add.
        parameters : ParameterDeclarations, optional
            The parameters of the story. Default is
            ParameterDeclarations().
        """
        if not isinstance(act, Act):
            raise TypeError("act input is not of type Act")
        newstory = Story("story_" + act.name, parameters)
        newstory.add_act(act)
        self.stories.append(newstory)
        return self

    def add_maneuver_group(
        self,
        maneuvergroup: ManeuverGroup,
        starttrigger: Optional[_TriggerType] = None,
        stoptrigger: _TriggerType = Trigger("stop"),
        parameters: ParameterDeclarations = ParameterDeclarations(),
    ) -> "StoryBoard":
        """Adds a single maneuver group to one story. For multi maneuver group
        scenarios, use Act instead.

        Parameters
        ----------
        maneuvergroup : ManeuverGroup
            The ManeuverGroup to add.
        starttrigger : _TriggerType, optional
            Start trigger for the act. Default is at simulation time
            0.
        stoptrigger : _TriggerType, optional
            Stop trigger for the act. Default is Trigger("stop").
        parameters : ParameterDeclarations, optional
            The parameters of the story. Default is
            ParameterDeclarations().
        """
        if not isinstance(maneuvergroup, ManeuverGroup):
            raise TypeError("maneuvergroup input is not of type ManeuverGroup")
        if starttrigger is None:
            starttrigger = ValueTrigger(
                "act_start",
                0,
                ConditionEdge.rising,
                SimulationTimeCondition(0, Rule.greaterThan),
            )
        elif not isinstance(starttrigger, _TriggerType):
            raise TypeError("starttrigger is not a Trigger type")
        elif starttrigger._triggerpoint == "StopTrigger":
            raise ValueError(
                "the starttrigger provided does not have start as the triggeringpoint"
            )
        if not isinstance(stoptrigger, _TriggerType):
            raise TypeError("stoptrigger is not a Trigger type")
        if stoptrigger._triggerpoint == "StartTrigger":
            raise ValueError(
                "the stoptrigger provided is not of type StopTrigger"
            )
        newact = Act("act_" + maneuvergroup.name, starttrigger, stoptrigger)
        newact.add_maneuver_group(maneuvergroup)
        self.add_act(newact, parameters)
        return self

    def add_maneuver(
        self,
        maneuver: Union[Maneuver, CatalogReference],
        actors: Optional[Union[List[str], str]] = None,
        starttrigger: Optional[_TriggerType] = None,
        stoptrigger: _TriggerType = Trigger("stop"),
        parameters: ParameterDeclarations = ParameterDeclarations(),
    ) -> "StoryBoard":
        """Adds a single maneuver to one story. For multi-maneuver scenarios,
        use ManeuverGroup instead.

        Parameters
        ----------
        maneuver : Maneuver or CatalogReference
            The Maneuver to add.
        actors : list of str or str, optional
            List of all actors in the maneuver or just a name of the
            actor.
        starttrigger : _TriggerType, optional
            Start trigger for the act. Default is at simulation time
            0.
        stoptrigger : _TriggerType, optional
            Stop trigger for the act. Default is Trigger("stop").
        parameters : ParameterDeclarations, optional
            The parameters of the story. Default is None.
        """
        if not isinstance(maneuver, (Maneuver, CatalogReference)):
            raise TypeError("maneuver input is not of type Maneuver")
        if isinstance(maneuver, Maneuver):
            mangr = ManeuverGroup("maneuvuergroup_" + maneuver.name)
        else:
            mangr = ManeuverGroup("maneuvuergroup_from_catalog")

        if actors is not None:
            if isinstance(actors, list):
                for a in actors:
                    mangr.add_actor(a)
            else:
                mangr.add_actor(actors)
        mangr.add_maneuver(maneuver)
        self.add_maneuver_group(
            mangr,
            starttrigger=starttrigger,
            stoptrigger=stoptrigger,
            parameters=parameters,
        )
        return self

    def get_element(self) -> ET.Element:
        """Returns the ElementTree of the StoryBoard.

        Returns
        -------
        xml.etree.ElementTree.Element
            The ElementTree representation of the StoryBoard.
        """
        element = ET.Element("Storyboard")
        element.append(self.init.get_element())

        # if not self.stories:
        #     raise ValueError('no stories available for storyboard')

        if not self.stories and self.isVersionEqLess(minor=1):
            self.add_maneuver_group(ManeuverGroup("empty"), Trigger())
        for story in self.stories:
            element.append(story.get_element())

        stoptrigger = self.stoptrigger
        if stoptrigger is not None:
            element.append(stoptrigger.get_element())

        return element

The StoryBoard class creates the storyboard of OpenScenario.

Parameters

init : Init, optional

The init part of the storyboard. Default is Init().

stoptrigger : _TriggerType, optional

The stop trigger of the storyboard. Default is EmptyTrigger("stop").

Attributes

init : Init

The init of the storyboard.

stoptrigger : _TriggerType

The stop trigger of the storyboard.

stories : list of Story

All stories of the scenario.

Methods

parse(element) Parses an ElementTree created by the class and returns an instance of the class. add_story(story) Adds a story to the storyboard. get_element() Returns the full ElementTree of the class.

Initializes the StoryBoard.

Parameters

init : Init, optional

The init part of the storyboard. Default is Init().

stoptrigger : _TriggerType, optional

The stop trigger of the storyboard. OpenSCENARIO 1.2 or less: Default is Trigger("stop"). OpenSCENARIO 1.3: None. The Storyboard will never be stopped.

Ancestors

• VersionBase

Static methods

def parse(element: xml.etree.ElementTree.Element) ‑> StoryBoard

Expand source code

@staticmethod
def parse(element: ET.Element) -> "StoryBoard":
    """Parses the XML element of StoryBoard.

    Parameters
    ----------
    element : xml.etree.ElementTree.Element
        A StoryBoard element (same as generated by the class
        itself).

    Returns
    -------
    StoryBoard
        A StoryBoard object.
    """
    init = Init.parse(find_mandatory_field(element, "Init"))
    stoptrigger = None
    if element.find("StopTrigger") is not None:
        stoptrigger = Trigger.parse(
            find_mandatory_field(element, "StopTrigger")
        )
    storyboard = StoryBoard(init, stoptrigger)
    for s in element.findall("Story"):
        storyboard.add_story(Story.parse(s))
    return storyboard

Parses the XML element of StoryBoard.

Parameters

element : xml.etree.ElementTree.Element

A StoryBoard element (same as generated by the class itself).

Returns

StoryBoard

A StoryBoard object.

Instance variables

prop stoptrigger : scenariogeneration.xosc.utils._TriggerType | scenariogeneration.xosc.utils._ValueTriggerType | None

Expand source code

@property
def stoptrigger(self) -> Optional[Union[_TriggerType, _ValueTriggerType]]:
    """Returns the stop trigger of the storyboard."""
    if self._stoptrigger is None:
        if self.isVersionEqLarger(1, 3):
            return None
        else:
            return Trigger("stop")
    return self._stoptrigger

Returns the stop trigger of the storyboard.

Methods

def add_act(self,
act: Act,
parameters: ParameterDeclarations = <scenariogeneration.xosc.utils.ParameterDeclarations object>) ‑> StoryBoard

Expand source code

def add_act(
    self,
    act: Act,
    parameters: ParameterDeclarations = ParameterDeclarations(),
) -> "StoryBoard":
    """Adds a single act to one story. For multi-act scenarios, use Story
    instead.

    Parameters
    ----------
    act : Act
        The Act to add.
    parameters : ParameterDeclarations, optional
        The parameters of the story. Default is
        ParameterDeclarations().
    """
    if not isinstance(act, Act):
        raise TypeError("act input is not of type Act")
    newstory = Story("story_" + act.name, parameters)
    newstory.add_act(act)
    self.stories.append(newstory)
    return self

Adds a single act to one story. For multi-act scenarios, use Story instead.

Parameters

act : Act

The Act to add.

parameters : ParameterDeclarations, optional

The parameters of the story. Default is ParameterDeclarations().

def add_maneuver(self,
maneuver: Maneuver | CatalogReference,
actors: List[str] | str | None = None,
starttrigger: scenariogeneration.xosc.utils._TriggerType | None = None,
stoptrigger: scenariogeneration.xosc.utils._TriggerType = <scenariogeneration.xosc.triggers.Trigger object>,
parameters: ParameterDeclarations = <scenariogeneration.xosc.utils.ParameterDeclarations object>) ‑> StoryBoard

Expand source code

def add_maneuver(
    self,
    maneuver: Union[Maneuver, CatalogReference],
    actors: Optional[Union[List[str], str]] = None,
    starttrigger: Optional[_TriggerType] = None,
    stoptrigger: _TriggerType = Trigger("stop"),
    parameters: ParameterDeclarations = ParameterDeclarations(),
) -> "StoryBoard":
    """Adds a single maneuver to one story. For multi-maneuver scenarios,
    use ManeuverGroup instead.

    Parameters
    ----------
    maneuver : Maneuver or CatalogReference
        The Maneuver to add.
    actors : list of str or str, optional
        List of all actors in the maneuver or just a name of the
        actor.
    starttrigger : _TriggerType, optional
        Start trigger for the act. Default is at simulation time
        0.
    stoptrigger : _TriggerType, optional
        Stop trigger for the act. Default is Trigger("stop").
    parameters : ParameterDeclarations, optional
        The parameters of the story. Default is None.
    """
    if not isinstance(maneuver, (Maneuver, CatalogReference)):
        raise TypeError("maneuver input is not of type Maneuver")
    if isinstance(maneuver, Maneuver):
        mangr = ManeuverGroup("maneuvuergroup_" + maneuver.name)
    else:
        mangr = ManeuverGroup("maneuvuergroup_from_catalog")

    if actors is not None:
        if isinstance(actors, list):
            for a in actors:
                mangr.add_actor(a)
        else:
            mangr.add_actor(actors)
    mangr.add_maneuver(maneuver)
    self.add_maneuver_group(
        mangr,
        starttrigger=starttrigger,
        stoptrigger=stoptrigger,
        parameters=parameters,
    )
    return self

Adds a single maneuver to one story. For multi-maneuver scenarios, use ManeuverGroup instead.

Parameters

maneuver : Maneuver or CatalogReference

The Maneuver to add.

actors : list of str or str, optional

List of all actors in the maneuver or just a name of the actor.

starttrigger : _TriggerType, optional

Start trigger for the act. Default is at simulation time 0.

stoptrigger : _TriggerType, optional

Stop trigger for the act. Default is Trigger("stop").

parameters : ParameterDeclarations, optional

The parameters of the story. Default is None.

def add_maneuver_group(self,
maneuvergroup: ManeuverGroup,
starttrigger: scenariogeneration.xosc.utils._TriggerType | None = None,
stoptrigger: scenariogeneration.xosc.utils._TriggerType = <scenariogeneration.xosc.triggers.Trigger object>,
parameters: ParameterDeclarations = <scenariogeneration.xosc.utils.ParameterDeclarations object>) ‑> StoryBoard

Expand source code

def add_maneuver_group(
    self,
    maneuvergroup: ManeuverGroup,
    starttrigger: Optional[_TriggerType] = None,
    stoptrigger: _TriggerType = Trigger("stop"),
    parameters: ParameterDeclarations = ParameterDeclarations(),
) -> "StoryBoard":
    """Adds a single maneuver group to one story. For multi maneuver group
    scenarios, use Act instead.

    Parameters
    ----------
    maneuvergroup : ManeuverGroup
        The ManeuverGroup to add.
    starttrigger : _TriggerType, optional
        Start trigger for the act. Default is at simulation time
        0.
    stoptrigger : _TriggerType, optional
        Stop trigger for the act. Default is Trigger("stop").
    parameters : ParameterDeclarations, optional
        The parameters of the story. Default is
        ParameterDeclarations().
    """
    if not isinstance(maneuvergroup, ManeuverGroup):
        raise TypeError("maneuvergroup input is not of type ManeuverGroup")
    if starttrigger is None:
        starttrigger = ValueTrigger(
            "act_start",
            0,
            ConditionEdge.rising,
            SimulationTimeCondition(0, Rule.greaterThan),
        )
    elif not isinstance(starttrigger, _TriggerType):
        raise TypeError("starttrigger is not a Trigger type")
    elif starttrigger._triggerpoint == "StopTrigger":
        raise ValueError(
            "the starttrigger provided does not have start as the triggeringpoint"
        )
    if not isinstance(stoptrigger, _TriggerType):
        raise TypeError("stoptrigger is not a Trigger type")
    if stoptrigger._triggerpoint == "StartTrigger":
        raise ValueError(
            "the stoptrigger provided is not of type StopTrigger"
        )
    newact = Act("act_" + maneuvergroup.name, starttrigger, stoptrigger)
    newact.add_maneuver_group(maneuvergroup)
    self.add_act(newact, parameters)
    return self

Adds a single maneuver group to one story. For multi maneuver group scenarios, use Act instead.

Parameters

maneuvergroup : ManeuverGroup

The ManeuverGroup to add.

starttrigger : _TriggerType, optional

Start trigger for the act. Default is at simulation time 0.

stoptrigger : _TriggerType, optional

Stop trigger for the act. Default is Trigger("stop").

parameters : ParameterDeclarations, optional

The parameters of the story. Default is ParameterDeclarations().

def add_story(self,
story: Story) ‑> StoryBoard

Expand source code

def add_story(self, story: Story) -> "StoryBoard":
    """Adds a story to the storyboard.

    Parameters
    ----------
    story : Story
        The story to be added.
    """
    if not isinstance(story, Story):
        raise TypeError("story input is not of type Story")
    self.stories.append(story)
    return self

Adds a story to the storyboard.

Parameters

story : Story

The story to be added.

def get_element(self) ‑> xml.etree.ElementTree.Element

Expand source code

def get_element(self) -> ET.Element:
    """Returns the ElementTree of the StoryBoard.

    Returns
    -------
    xml.etree.ElementTree.Element
        The ElementTree representation of the StoryBoard.
    """
    element = ET.Element("Storyboard")
    element.append(self.init.get_element())

    # if not self.stories:
    #     raise ValueError('no stories available for storyboard')

    if not self.stories and self.isVersionEqLess(minor=1):
        self.add_maneuver_group(ManeuverGroup("empty"), Trigger())
    for story in self.stories:
        element.append(story.get_element())

    stoptrigger = self.stoptrigger
    if stoptrigger is not None:
        element.append(stoptrigger.get_element())

    return element

Returns the ElementTree of the StoryBoard.

Returns

xml.etree.ElementTree.Element

The ElementTree representation of the StoryBoard.