[WIP] Various Improvements

.gitignore

@@ -137,8 +137,9 @@ dmypy.json
 
 *.cproject
 
-# generated parser
+# generated parser and checksum
 src/scenic/syntax/parser.py
+src/scenic/syntax/.parser_checksum
 
 # generated media/output
 simulation.gif

docs/api.rst

@@ -173,6 +173,15 @@ it to the replay, but this greatly increases the size of the encoded simulation.
 	can return to one later for further analysis), but it is not guaranteed to be
 	compatible across major versions of Scenic.
 
+.. _xosc_export:
+
+OpenScenarioXML Export
+----------------------
+
+Scenic provides experimental support for exporting completed simulations via `toOpenScenario`.
+This function currently only supports cars and pedestrians, and may be subject to breaking changes
+in the future.
+
 .. seealso:: If you get exceptions or unexpected behavior when using the API, Scenic provides various debugging features: see :ref:`debugging`.
 
 .. rubric:: Footnotes

docs/reference/operators.rst

@@ -28,6 +28,12 @@ apparent heading of *OrientedPoint* [from *vector*]
 ---------------------------------------------------
 The apparent heading of the OrientedPoint, with respect to the line of sight from ego (or the position provided with the optional from vector)
 
+.. _apparent heading to {vector} [from {OrientedPoint}]:
+
+apparent heading to *vector* [from *OrientedPoint*]
+---------------------------------------------------
+The apparent heading to the vector, with respect to the line of sight from ego (or the OrientedPoint provided with the optional from OrientedPoint)
+
 .. _distance [from {vector}] to {vector}:
 .. _distance from:
 
@@ -75,6 +81,15 @@ Whether an `Object`/`Region` intersects another `Object`/`Region`, i.e. whether
 
 When working with 2D regions, it can be useful to check intersection with the :term:`footprint` of a region, e.g. when checking whether a car intersects a given lane. In this case, one would write :scenic:`car intersects lane.footprint` instead of :scenic:`car intersects lane`. For more details, see :term:`footprint`.
 
+.. _{vector} (ahead of | behind | left of | right of) {region}:
+
+*vector* (ahead of | behind | left of | right of) *OrientedPoint*
+-----------------------------------------------------------------
+Whether a vector is to a respective side of an `OrientedPoint` (i.e. within +- ~90 degrees from that direction), accounting for the heading of the `OrientedPoint`. These operators are convenient shorthand for comparing :sampref:`apparent heading to {vector} [from {OrientedPoint}]` to a range of values.
+
+Note: For vectors very close to a boundary point (i.e. an apparent heading to the vector in (89.99, 90.01) or (-89.99, -90.01) for "ahead of" and "behind"), both operators will resolve to False.
+
+Example: If an `OrientedPoint` had an apparent heading to a vector of 45 degrees, it would be both "ahead of" and "left of" the `OrientedPoint` but not "behind" or "right of".
 
 Orientation Operators
 =====================

docs/simulators.rst

@@ -14,6 +14,10 @@ See the individual entries for details on each interface's capabilities and how
 	While Scenic aims to support multiple Python versions, some simulators may have more limited compatibility.
 	Be sure to check the documentation of each simulator to confirm which Python versions are supported.
 
+.. note::
+	Scenic also supports outputing data in formats that may be imported into other simulators and tools (e.g. :ref:`xosc_export`).
+	For more details, see :ref:`serialization`.
+
 .. contents:: List of Simulators
    :local:
 
@@ -163,7 +167,6 @@ This interface is part of the VerifAI toolkit; documentation and examples can be
 
 .. _VerifAI repository: https://github.com/BerkeleyLearnVerify/VerifAI
 
-
 Deprecated
 ==========
 

pyproject.toml

@@ -60,6 +60,9 @@ metadrive = [
 	"metadrive-simulator >= 0.4.3",
 	"sumolib >= 1.21.0",
 ]
+openscenario = [
+	"scenariogeneration"
+]
 test = [	# minimum dependencies for running tests (used for tox virtualenvs)
 	"pytest >= 7.0.0",
 	"pytest-cov >= 3.0.0",
@@ -68,6 +71,7 @@ test = [	# minimum dependencies for running tests (used for tox virtualenvs)
 test-full = [  # like 'test' but adds dependencies for optional features
 	"scenic[test]",       # all dependencies from 'test' extra above
 	"scenic[guideways]",  # for running guideways modules
+	"scenic[openscenario]",
 	"astor >= 0.8.1",
 	'carla >= 0.9.12; python_version <= "3.12" and (platform_system == "Linux" or platform_system == "Windows")',
 	"dill",

src/scenic/core/dynamics/behaviors.py

@@ -109,7 +109,7 @@ def alarmHandler(signum, frame):
             try:
                 actions = self._runningIterator.send(None)
             except StopIteration:
-                actions = ()  # behavior ended early
+                return None
         return actions
 
     def _stop(self, reason=None):
@@ -124,18 +124,39 @@ def _isFinished(self):
     def _invokeInner(self, agent, subs):
         import scenic.syntax.veneer as veneer
 
-        assert len(subs) == 1
-        sub = subs[0]
-        if not isinstance(sub, Behavior):
-            raise TypeError(f"expected a behavior, got {sub}")
-        sub._start(agent)
-        with veneer.executeInBehavior(sub):
+        # Validate all inner behaviors
+        for sub in subs:
+            if not isinstance(sub, Behavior):
+                raise TypeError(f"expected a behavior, got {sub}")
+            sub._start(agent)
+
+        # Create a generator for each inner behavior that yields the appropriate actions, cleaning up when done.
+        def make_inner_generator(sub):
             try:
-                yield from sub._runningIterator
+                while sub._isRunning:
+                    actions = sub._step()
+                    if actions is None:
+                        return
+                    yield actions
             finally:
                 if sub._isRunning:
                     sub._stop()
 
+        inner_generators = [make_inner_generator(sub) for sub in subs]
+
+        # Yield from a generator that zips all the inner generators together without padding, until all inner generators have terminated.
+        while True:
+            try:
+                raw_actions_list = next(itertools.zip_longest(*inner_generators))
+                yield tuple(
+                    filter(
+                        lambda x: x is not None,
+                        itertools.chain.from_iterable(raw_actions_list),
+                    )
+                )
+            except StopIteration:
+                return
+
     def __repr__(self):
         items = itertools.chain(
             (repr(arg) for arg in self._args),

src/scenic/core/object_types.py

@@ -988,6 +988,10 @@ def distancePast(self, vec):
         diff = self.position - vec
         return diff.rotatedBy(-self.heading).y
 
+    def apparentHeadingTo(self, vec):
+        """The apparent heading to a given point, from the perspective of this `OrientedPoint`."""
+        return normalizeAngle(self.position.angleTo(vec) - self.heading)
+
     def toHeading(self) -> float:
         return self.heading