Feature: Delay Iteration (Merge PR #366 from scene-randomizer-support)

Ported over the ability to delay the current iteration

Author: aryan-mann

com.unity.perception/CHANGELOG.md

@@ -21,6 +21,8 @@ Users can now choose the base folder location to store their generated datasets.
 
 Added a `projection` field in the capture.sensor metadata. Values are either "perspective" or "orthographic".
 
+Users can now delay the current iteration for one frame from within randomizers by calling the `DelayIteration` function of the active scenario.
+
 ### Changed
 
 Changed the JSON serialization key of Normal Sampler's standard deviation property from "standardDeviation" to "stddev". Scneario JSON configurations that were generated using previous versions will need to be manually updated to reflect this change.

com.unity.perception/Runtime/Randomization/Scenarios/ScenarioBase.cs

@@ -48,6 +48,8 @@ private set
         public TextAsset configuration;
 
         private bool m_ShouldRestartIteration;
+        private bool m_ShouldDelayIteration;
+
         private const int k_MaxIterationStartCount = 100;
 
         /// <summary>
@@ -359,13 +361,22 @@ void IterationLoop()
                 do
                 {
                     m_ShouldRestartIteration = false;
+                    m_ShouldDelayIteration = false;
                     iterationStartCount++;
                     foreach (var randomizer in activeRandomizers)
                     {
                         randomizer.IterationStart();
                         if (m_ShouldRestartIteration)
                             break;
+
+                        if (m_ShouldDelayIteration)
+                        {
+                            Debug.Log($"Iteration was delayed by {randomizer.GetType().Name}");
+                            break;
+                        }
                     }
+                    if (m_ShouldDelayIteration)
+                        break;
                 } while (m_ShouldRestartIteration && iterationStartCount < k_MaxIterationStartCount);
 
                 if (m_ShouldRestartIteration)
@@ -381,7 +392,9 @@ void IterationLoop()
                 randomizer.Update();
 
             // Iterate scenario frame count
-            currentIterationFrame++;
+            if (!m_ShouldDelayIteration)
+                currentIterationFrame++;
+
             framesSinceInitialization++;
         }
 
@@ -504,5 +517,18 @@ public void RestartIteration()
         {
             m_ShouldRestartIteration = true;
         }
+
+        /// <summary>
+        /// Delays the current iteration by one frame.
+        /// This results in <see cref="OnIterationStart" /> being called again for the same iteration.
+        /// </summary>
+        /// <remarks>
+        /// Must be called from within the <see cref="OnIterationStart"/> function of a class
+        /// inheriting from <see cref="Randomizer" />.
+        /// </remarks>
+        public void DelayIteration()
+        {
+            m_ShouldDelayIteration = true;
+        }
     }
 }

com.unity.perception/Tests/Runtime/Randomization/ScenarioTests/ExampleDelayRandomizer.cs

@@ -0,0 +1,43 @@
+using System;
+using UnityEngine;
+using UnityEngine.Perception.Randomization.Randomizers;
+
+namespace RandomizationTests.ScenarioTests
+{
+    /// <summary>
+    /// Delays the scenario every Nth iteration where N is given by <see cref="m_IterationDelay" />.
+    /// Does not delay the very first iteration i.e. iteration 0.
+    /// </summary>
+    /// <remarks>
+    /// With <see cref="m_IterationDelay" /> set to 2, the iterations 2, 4, 6, ..., etc. will be delayed once.
+    /// </remarks>
+    [Serializable]
+    [AddRandomizerMenu("Perception Tests/Example Delay Randomizer")]
+    public class ExampleDelayRandomizer : Randomizer
+    {
+        int m_IterationDelay = 2;
+        bool m_DelayedThisIteration = false;
+
+        public ExampleDelayRandomizer(int iterationDelay = 2)
+        {
+            m_IterationDelay = Math.Max(2, iterationDelay);
+        }
+
+        protected override void OnIterationStart()
+        {
+            if (m_DelayedThisIteration)
+            {
+                m_DelayedThisIteration = false;
+                return;
+            }
+
+            var currentIteration = scenario.currentIteration;
+            if (currentIteration > 0 && ((currentIteration) % m_IterationDelay) == 0)
+            {
+                Debug.Log($"Delaying iteration {currentIteration} once.");
+                m_DelayedThisIteration = true;
+                scenario.DelayIteration();
+            }
+        }
+    }
+}

com.unity.perception/Tests/Runtime/Randomization/ScenarioTests/ExampleDelayRandomizer.cs.meta

@@ -1,10 +1,13 @@
 using System;
 using System.Collections;
+using System.Collections.Generic;
+using System.Linq;
 using NUnit.Framework;
 using UnityEngine;
 using UnityEngine.Perception.Randomization.Randomizers.SampleRandomizers;
 using UnityEngine.Perception.Randomization.Samplers;
 using UnityEngine.Perception.GroundTruth;
+using UnityEngine.Perception.Randomization.Randomizers;
 using UnityEngine.Perception.Randomization.Scenarios;
 using UnityEngine.TestTools;
 using Object = UnityEngine.Object;
@@ -30,11 +33,20 @@ public void TearDown()
         }
 
         // TODO: update this function once the perception camera doesn't skip the first frame
-        IEnumerator CreateNewScenario(int totalIterations, int framesPerIteration)
+        IEnumerator CreateNewScenario(int totalIterations, int framesPerIteration, Randomizer[] randomizers = null)
         {
             m_Scenario = m_TestObject.AddComponent<TestFixedLengthScenario>();
             m_Scenario.constants.totalIterations = totalIterations;
             m_Scenario.constants.framesPerIteration = framesPerIteration;
+
+            if (randomizers != null)
+            {
+                foreach (var rnd in randomizers)
+                {
+                    m_Scenario.AddRandomizer(rnd);
+                }
+            }
+
             yield return null; // Skip first frame
             yield return null; // Skip first Update() frame
         }
@@ -142,6 +154,43 @@ public IEnumerator GeneratedRandomSeedsChangeWithScenarioIteration()
                 Assert.AreNotEqual(seeds[i], SamplerState.NextRandomState());
         }
 
+
+        [UnityTest]
+        public IEnumerator IterationCorrectlyDelays()
+        {
+            yield return CreateNewScenario(5, 1, new Randomizer[]
+            {
+                // Delays every other iteration
+                new ExampleDelayRandomizer(2)
+            });
+
+            // State: currentIteration = 0
+            Assert.AreEqual(0, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 1
+            Assert.AreEqual(1, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 2
+            // Action: ExampleDelayRandomizer will delay the iteration
+            Assert.AreEqual(2, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 2
+            Assert.AreEqual(2, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 3;
+            Assert.AreEqual(3, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 4
+            // Action: ExampleDelayRandomizer will delay the iteration
+            Assert.AreEqual(4, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 4
+            Assert.AreEqual(4, m_Scenario.currentIteration);
+            yield return null;
+            // State: currentIteration = 5
+            Assert.AreEqual(5, m_Scenario.currentIteration);
+        }
+
         PerceptionCamera SetupPerceptionCamera()
         {
             m_TestObject.SetActive(false);