more api documentation

com.unity.perception/Editor/Randomization/ParameterConfigurationEditor.cs

 using UnityEditor.UIElements;
 using UnityEngine.Perception.Randomization.Configuration;
 using UnityEngine.Perception.Randomization.Parameters;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
-using UnityEngine.Perception.Randomization.Samplers;
 using UnityEngine.UIElements;
 
 namespace UnityEngine.Perception.Randomization.Editor
             foreach (var parameterType in StaticData.parameterTypes)
             {
                 parameterTypeMenu.menu.AppendAction(
-                    ParameterMetaData.GetMetaData(parameterType).typeDisplayName,
+                    ParameterDisplayName.GetDisplayName(parameterType).displayName,
                     a => { AddParameter(parameterType); },
                     a => DropdownMenuAction.Status.Normal);
             }

com.unity.perception/Editor/Randomization/ParameterElement.cs

             removeButton.RegisterCallback<MouseUpEvent>(evt => paramConfigEditor.RemoveParameter(this));
 
             var parameterTypeLabel = this.Query<Label>("parameter-type-label").First();
-            parameterTypeLabel.text = parameter.MetaData.typeDisplayName;
+            parameterTypeLabel.text = parameter.displayName.displayName;
 
             var parameterNameField = this.Q<TextField>("name");
             parameterNameField.isDelayed = true;

com.unity.perception/Editor/Randomization/SamplerElement.cs

 
             m_Properties = this.Q<VisualElement>("fields-container");
             m_SamplerTypeDropdown = this.Q<ToolbarMenu>("sampler-type-dropdown");
-            m_SamplerTypeDropdown.text = SamplerMetaData.GetMetaData(m_Sampler.GetType()).displayName;
+            m_SamplerTypeDropdown.text = SamplerDisplayName.GetDisplayName(m_Sampler.GetType()).displayName;
-                var displayName = SamplerMetaData.GetMetaData(samplerType).displayName;
+                var displayName = SamplerDisplayName.GetDisplayName(samplerType).displayName;
                 m_SamplerTypeDropdown.menu.AppendAction(
                     displayName,
                     a => { ReplaceSampler(samplerType); },
         void ReplaceSampler(Type samplerType)
         {
             CreateSampler(samplerType);
-            m_SamplerTypeDropdown.text = SamplerMetaData.GetMetaData(m_Sampler.GetType()).displayName;
+            m_SamplerTypeDropdown.text = SamplerDisplayName.GetDisplayName(m_Sampler.GetType()).displayName;
             CreatePropertyFields();
         }
 

com.unity.perception/Editor/Randomization/StaticData.cs

 using System;
 using System.Collections.Generic;
 using System.Reflection;
-using Newtonsoft.Json;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
 using UnityEngine.Perception.Randomization.Samplers;
 
 namespace UnityEngine.Perception.Randomization.Editor
                 {
                     var isNotAbstract = (type.Attributes & TypeAttributes.Abstract) == 0;
                     if (typeof(Parameter).IsAssignableFrom(type) && isNotAbstract &&
-                        ParameterMetaData.GetMetaData(type) != null)
+                        ParameterDisplayName.GetDisplayName(type) != null)
-                        isNotAbstract && SamplerMetaData.GetMetaData(type) != null)
+                        isNotAbstract && SamplerDisplayName.GetDisplayName(type) != null)
                     {
                         samplerTypesList.Add(type);
                     }

com.unity.perception/Runtime/Randomization/Parameters/NumericParameter.cs

             base.Validate();
             foreach (var sampler in samplers)
                 if (sampler is IRandomRangedSampler rangedSampler)
-                    SamplerUtility.ValidateRange(rangedSampler);
+                    rangedSampler.range.Validate();
         }
     }
 }

com.unity.perception/Runtime/Randomization/Parameters/Parameter.cs

 using System;
 using UnityEngine;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
 using UnityEngine.Perception.Randomization.Samplers;
 
 namespace UnityEngine.Perception.Randomization.Parameters
         /// <summary>
         /// Returns meta information regarding this type of parameter
         /// </summary>
-        internal ParameterMetaData MetaData =>
-            (ParameterMetaData)Attribute.GetCustomAttribute(GetType(), typeof(ParameterMetaData));
+        internal ParameterDisplayName displayName =>
+            (ParameterDisplayName)Attribute.GetCustomAttribute(GetType(), typeof(ParameterDisplayName));
 
         /// <summary>
         /// The sample type generated by this parameter

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/BooleanParameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating boolean samples
+    /// </summary>
-    [ParameterMetaData("Bool")]
+    [ParameterDisplayName("Bool")]
     public class BooleanParameter : NumericParameter<bool>
     {
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/ColorHsvaParameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating Color samples
+    /// </summary>
-    [ParameterMetaData("ColorHSVA")]
+    [ParameterDisplayName("ColorHSVA")]
+        /// <summary>
+        /// The sampler used for randomizing the hue component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the saturation component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the value component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the alpha component of generated samples
+        /// </summary>
         [SerializeReference] public ISampler alpha = new ConstantSampler(1f);
 
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/FloatParameter.cs

 using System;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating float samples
+    /// </summary>
-    [ParameterMetaData("Float")]
+    [ParameterDisplayName("Float")]
+        /// <summary>
+        /// The sampler used to generate random float values
+        /// </summary>
         [SerializeReference] public ISampler value = new UniformSampler(0f, 1f);
 
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/GameObjectParameter.cs

 using System;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
 
 namespace UnityEngine.Perception.Randomization.Parameters
 {
     [Serializable]
-    [ParameterMetaData("GameObject")]
+    [ParameterDisplayName("GameObject")]
     public class GameObjectParameter : CategoricalParameter<GameObject> { }
 }

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/IntegerParameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating integer samples
+    /// </summary>
-    [ParameterMetaData("Int")]
+    [ParameterDisplayName("Int")]
     public class IntegerParameter : NumericParameter<int>
     {
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/MaterialParameter.cs

 using System;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
 
 namespace UnityEngine.Perception.Randomization.Parameters
 {
     [Serializable]
-    [ParameterMetaData("Material")]
+    [ParameterDisplayName("Material")]
     public class MaterialParameter : CategoricalParameter<Material> {}
 }

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/StringParameter.cs

 using System;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
 
 namespace UnityEngine.Perception.Randomization.Parameters
 {
     [Serializable]
-    [ParameterMetaData("String")]
+    [ParameterDisplayName("String")]
     public class StringParameter : CategoricalParameter<string> {}
 }

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector2Parameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating Vector2 samples
+    /// </summary>
-    [ParameterMetaData("Vector2")]
+    [ParameterDisplayName("Vector2")]
+        /// <summary>
+        /// The sampler used for randomizing the x component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the y component of generated samples
+        /// </summary>
         [SerializeReference] public ISampler y = new UniformSampler(0f, 1f);
 
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector3Parameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating Vector3 samples
+    /// </summary>
-    [ParameterMetaData("Vector3")]
+    [ParameterDisplayName("Vector3")]
+        /// <summary>
+        /// The sampler used for randomizing the x component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the y component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the z component of generated samples
+        /// </summary>
         [SerializeReference] public ISampler z = new UniformSampler(0f, 1f);
 
         /// <summary>

com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector4Parameter.cs

 using Unity.Burst;
 using Unity.Collections;
 using Unity.Jobs;
-using UnityEngine.Perception.Randomization.Parameters.Attributes;
+    /// <summary>
+    /// A numeric parameter for generating Vector4 samples
+    /// </summary>
-    [ParameterMetaData("Vector4")]
+    [ParameterDisplayName("Vector4")]
+        /// <summary>
+        /// The sampler used for randomizing the x component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the y component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the z component of generated samples
+        /// </summary>
+
+        /// <summary>
+        /// The sampler used for randomizing the w component of generated samples
+        /// </summary>
-        /// Returns the samplers employed by this parameter
+        /// The sampler used the samplers employed by this parameter
         /// </summary>
         public override ISampler[] samplers => new []{ x, y, z, w };
 

com.unity.perception/Runtime/Randomization/Samplers/FloatRange.cs

             minimum = min;
             maximum = max;
         }
+
+        public void Validate()
+        {
+            if (minimum > maximum)
+                throw new ArgumentException("Invalid sampling range");
+        }
     }
 }

com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/ConstantSampler.cs

     /// Returns a constant value when sampled
     /// </summary>
     [Serializable]
-    [SamplerMetaData("Constant")]
+    [SamplerDisplayName("Constant")]
     public struct ConstantSampler : ISampler
     {
         public float value;

com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/NormalSampler.cs

     /// https://en.wikipedia.org/wiki/Truncated_normal_distribution
     /// </summary>
     [Serializable]
-    [SamplerMetaData("Normal")]
+    [SamplerDisplayName("Normal")]
     public struct NormalSampler : ISampler, IRandomRangedSampler
     {
         Unity.Mathematics.Random m_Random;

com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/UniformSampler.cs

     /// Returns uniformly distributed random values within a designated range.
     /// </summary>
     [Serializable]
-    [SamplerMetaData("Uniform")]
+    [SamplerDisplayName("Uniform")]
     public struct UniformSampler : ISampler, IRandomRangedSampler
     {
         Unity.Mathematics.Random m_Random;

com.unity.perception/Runtime/Randomization/Samplers/SamplerUtility.cs

 {
     public static class SamplerUtility
     {
-        public const uint largePrime = 0x202A96CF;
-        public const int samplingBatchSize = 64;
+        internal const uint largePrime = 0x202A96CF;
+        const int k_SamplingBatchSize = 64;
+        /// <returns>A non-deterministically generated random seed</returns>
         public static uint GenerateRandomSeed()
         {
             return (uint)Random.Range(1, uint.MaxValue);
         /// </summary>
         /// <param name="index">Usually the current scenario iteration or framesSinceInitialization</param>
         /// <param name="baseSeed">The seed to be offset</param>
+        /// <returns>A new random state</returns>
         public static uint IterateSeed(uint index, uint baseSeed)
         {
             return ShuffleSeed(index + 1) * baseSeed;
         }
 
         /// <summary>
-        /// Throws an exception if a sampler has an invalid range
-        /// </summary>
-        public static void ValidateRange(IRandomRangedSampler rangedSampler)
-        {
-            if (rangedSampler.range.minimum > rangedSampler.range.maximum)
-                throw new ArgumentException("Invalid sampling range");
-        }
-
-        /// <summary>
-        /// Generates an array of samples
-        /// </summary>
-        public static float[] GenerateSamples(ISampler sampler, int totalSamples)
-        {
-            var samples = new float[totalSamples];
-            for (var i = 0; i < totalSamples; i++)
-                samples[i] = sampler.Sample();
-            return samples;
-        }
-
-        /// <summary>
+        /// <param name="sampler">The sampler to generate samples from</param>
+        /// <param name="sampleCount">The number of samples to generate</param>
+        /// <param name="jobHandle">The handle of the scheduled job</param>
+        /// <typeparam name="T">The type of sampler to sample</typeparam>
+        /// <returns>A NativeArray of generated samples</returns>
-            T sampler, int totalSamples, out JobHandle jobHandle) where T : struct, ISampler
+            T sampler, int sampleCount, out JobHandle jobHandle) where T : struct, ISampler
-                totalSamples, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
+                sampleCount, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
-            }.ScheduleBatch(totalSamples, samplingBatchSize);
+            }.ScheduleBatch(sampleCount, k_SamplingBatchSize);
-        /// <summary>
-        /// A multi-threaded job for generating an array of samples
-        /// </summary>
         [BurstCompile]
         struct SampleJob<T> : IJobParallelForBatch where T : ISampler
         {
             public void Execute(int startIndex, int count)
             {
                 var endIndex = startIndex + count;
-                var batchIndex = startIndex / samplingBatchSize;
+                var batchIndex = startIndex / k_SamplingBatchSize;
                 sampler.IterateState(batchIndex);
                 for (var i = startIndex; i < endIndex; i++)
                     samples[i] = sampler.Sample();
         /// <summary>
         /// https://www.johndcook.com/blog/csharp_phi/
         /// </summary>
-        public static float NormalCdf(float x)
+        static float NormalCdf(float x)
         {
             const float a1 = 0.254829592f;
             const float a2 = -0.284496736f;
         /// <summary>
         /// https://www.johndcook.com/blog/csharp_phi_inverse/
         /// </summary>
-        /// <param name="p">Must be with the range (0, 1)</param>
-        public static float NormalCdfInverse(float p)
+        /// <param name="probability">Must be with the range (0, 1)</param>
+        static float NormalCdfInverse(float probability)
-            if (p <= 0f || p >= 1.0f)
-                throw new ArgumentOutOfRangeException($"p == {p}");
+            if (probability <= 0f || probability >= 1.0f)
+                throw new ArgumentOutOfRangeException($"Probability {probability} is outside the range (0, 1)");
-            return p < 0.5f
-                ? -RationalApproximation(math.sqrt(-2.0f * math.log(p)))
-                : RationalApproximation(math.sqrt(-2.0f * math.log(1.0f - p)));
+            return probability < 0.5f
+                ? -RationalApproximation(math.sqrt(-2.0f * math.log(probability)))
+                : RationalApproximation(math.sqrt(-2.0f * math.log(1.0f - probability)));
+        /// Generates samples from a truncated normal distribution.
+        /// Further reading about this distribution can be found here:
-        /// TODO: fix issues with sampling at the either ends of the distribution
         /// </summary>
         public static float TruncatedNormalSample(float u, float min, float max, float mean, float stdDev)
         {

com.unity.perception/Tests/Runtime/Randomization/SamplerTests/ConstantSamplerTests.cs

         public void ConstantSamplerGeneratesConstantValues()
         {
             var constantSampler = new ConstantSampler();
-            var samples = SamplerUtility.GenerateSamples(constantSampler, TestValues.TestSampleCount);
-            Assert.AreEqual(samples.Length, TestValues.TestSampleCount);
-            foreach (var sample in samples)
-                Assert.AreEqual(sample, constantSampler.value);
+            var sample1 = constantSampler.Sample();
+            var sample2 = constantSampler.Sample();
+            Assert.AreEqual(sample1, sample2);
         }
     }
 }

com.unity.perception/Tests/Runtime/Randomization/SamplerTests/RangedSamplerTests.cs

         [Test]
         public void SamplesInRange()
         {
-            var samples = SamplerUtility.GenerateSamples(m_Sampler, k_TestSampleCount);
-
+            var samples = m_Sampler.Samples(k_TestSampleCount, out var handle);
+            handle.Complete();
-
+            samples.Dispose();
         }
 
         [Test]
 
             samples1.Dispose();
             samples2.Dispose();
-        }
-
-        [Test]
-        public void InvalidRange()
-        {
-            m_Sampler.range = new FloatRange(1, -1);
-            Assert.Throws<ArgumentException>(() => SamplerUtility.ValidateRange(m_Sampler));
         }
     }
 }

com.unity.perception/Runtime/Randomization/Parameters/ParameterDisplayName.cs

+using System;
+
+namespace UnityEngine.Perception.Randomization.Parameters
+{
+    /// <summary>
+    /// Defines the label used to identify a parameter types in a parameter configuration
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class)]
+    public class ParameterDisplayName : Attribute
+    {
+        /// <summary>
+        /// Returns the ParameterDisplayName attribute annotating a particular parameter type
+        /// </summary>
+        /// <param name="type">The type of parameter</param>
+        /// <returns>A ParameterDisplayName attribute</returns>
+        public static ParameterDisplayName GetDisplayName(Type type) =>
+            (ParameterDisplayName)GetCustomAttribute(type, typeof(ParameterDisplayName));
+
+        /// <summary>
+        /// The parameter label string
+        /// </summary>
+        public string displayName;
+
+        /// <summary>
+        /// Constructs a new ParameterDisplayName attribute
+        /// </summary>
+        /// <param name="displayName">The parameter label string</param>
+        public ParameterDisplayName(string displayName)
+        {
+            this.displayName = displayName;
+        }
+    }
+}

com.unity.perception/Runtime/Randomization/Samplers/SamplerDisplayName.cs

+using System;
+
+namespace UnityEngine.Perception.Randomization.Samplers
+{
+    /// <summary>
+    /// Defines the label used to identify a sampler types in the sampler drop down menu
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Struct)]
+    public class SamplerDisplayName : Attribute
+    {
+        /// <summary>
+        /// Returns the SamplerDisplayName attribute annotating a particular sampler type
+        /// </summary>
+        /// <param name="type">The type of sampler</param>
+        /// <returns>A SamplerDisplayName attribute</returns>
+        public static SamplerDisplayName GetDisplayName(Type type) =>
+            (SamplerDisplayName)GetCustomAttribute(type, typeof(SamplerDisplayName));
+
+        /// <summary>
+        /// The sampler label string
+        /// </summary>
+        public string displayName;
+
+        /// <summary>
+        /// Constructs a new SamplerDisplayName attribute
+        /// </summary>
+        /// <param name="displayName">The sampler label string</param>
+        public SamplerDisplayName(string displayName)
+        {
+            this.displayName = displayName;
+        }
+    }
+}

com.unity.perception/Tests/Runtime/Randomization/SamplerTests/FloatRangeTests.cs

+using System;
+using NUnit.Framework;
+using UnityEngine.Perception.Randomization.Samplers;
+
+namespace RandomizationTests.SamplerTests
+{
+    [TestFixture]
+    public class FloatRangeTests
+    {
+        [Test]
+        public void InvalidRange()
+        {
+            Assert.Throws<ArgumentException>(() => new FloatRange(1, -1).Validate());
+        }
+    }
+}

com.unity.perception/Tests/Runtime/Randomization/SamplerTests/FloatRangeTests.cs.meta

+fileFormatVersion: 2
+guid: 75f6733e0b774298892d1b88069fdca2
+timeCreated: 1597556434

com.unity.perception/Runtime/Randomization/Samplers/SamplerMetaData.cs

-using System;
-
-namespace UnityEngine.Perception.Randomization.Samplers
-{
-    [AttributeUsage(AttributeTargets.Struct)]
-    public class SamplerMetaData : Attribute
-    {
-        public static SamplerMetaData GetMetaData(Type type) =>
-            (SamplerMetaData)GetCustomAttribute(type, typeof(SamplerMetaData));
-
-        public string displayName;
-
-        public SamplerMetaData(string displayName)
-        {
-            this.displayName = displayName;
-        }
-    }
-}