浏览代码

responding to PR feedback

/usim-randomization
Steven Leal 4 年前
当前提交
687816c5
共有 27 个文件被更改,包括 65 次插入128 次删除
  1. 32
      com.unity.perception/Documentation~/Randomization/Index.md
  2. 6
      com.unity.perception/Documentation~/Randomization/Parameters.md
  3. 2
      com.unity.perception/Editor/Randomization/ParameterElement.cs
  4. 4
      com.unity.perception/Editor/Randomization/StaticData.cs
  5. 2
      com.unity.perception/Runtime/Randomization/Configuration/ParameterConfiguration.cs
  6. 2
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/BooleanParameter.cs
  7. 8
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/ColorHsvaParameter.cs
  8. 2
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/FloatParameter.cs
  9. 2
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/IntegerParameter.cs
  10. 4
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector2Parameter.cs
  11. 6
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector3Parameter.cs
  12. 8
      com.unity.perception/Runtime/Randomization/Parameters/ParameterTypes/Vector4Parameter.cs
  13. 2
      com.unity.perception/Runtime/Randomization/Samplers/ISampler.cs
  14. 2
      com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/ConstantSampler.cs
  15. 10
      com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/NormalSampler.cs
  16. 2
      com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/UniformSampler.cs
  17. 8
      com.unity.perception/Runtime/Randomization/Samplers/SamplerUtility.cs
  18. 5
      com.unity.perception/Runtime/Randomization/Scenarios/ScenarioBase.cs
  19. 4
      com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs
  20. 14
      com.unity.perception/Tests/Runtime/Randomization/SamplerTests.cs
  21. 8
      com.unity.perception/Tests/Runtime/Randomization/ScenarioTests.cs
  22. 45
      com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/PlaceholderRangeSampler.cs
  23. 3
      com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/PlaceholderRangeSampler.cs.meta
  24. 9
      com.unity.perception/Runtime/Randomization/Samplers/SamplerException.cs
  25. 3
      com.unity.perception/Runtime/Randomization/Samplers/SamplerException.cs.meta
  26. 0
      /com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs.meta
  27. 0
      /com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs

32
com.unity.perception/Documentation~/Randomization/Index.md


# Overview
The perception package's randomization toolset enables users to incorporate domain randomization (DR) principles into Unity projects intended for synthetic training data generation.
The perception package's randomization toolset enables domain randomization (DR) during synthetic training data generation.
What is Domain Randomization?
**What is Domain Randomization?**
To this end, the perception package offers the following constructs to help facilitate the randomization of simulations:
1. Parameters
2. Samplers
3. Scenarios
**How can a Unity project be randomized using the Perception Randomization toolset?**
## Parameters
Randomizing a project involves the following steps:
1. Create a parameter configuration
2. Add parameters to the parameter configuration
3. Customize parameter properties and samplers
4. Create a scenario to control simulation execution
Parameters are used to map common types of simulation properties to random variables. For example, a Vector3 size parameter can be used to randomize the x, y, and z dimensions of an obstacle. Or a material parameter can be used to swap between different terrain surface materials.
As the first step mentions, randomization begins with creating a new ParameterConfiguration component. From here, users can configure and organize new random parameters to control various aspects of their simulation directly from the inspector in the Unity editor.
Parameters are configured and organized within a scene using a parameter configuration. Users can create new parameters, modify parameter randomization properties, and even assign target GameObjects to manipulate simulation properties directly from the inspector. Additionally, parameter sub-properties can be modified in playmode better visualize the impact of different randomization settings.
Next, create a few parameters and modify their properties. Parameters often customize their random variables through the parameter configuration using samplers. Samplers enable users to specify a type of probabilty distribution to use when generating random values.
Finally, add a Scenario component to the scene. Scenarios are used to coordinate the application of randomizations during the execution of a simulation.
Continue reading for more details concerning the three primary components driving randomizations in the perception package: parameters, samplers, and scenarios.
## Parameters
Parameters are used to map common types of simulation properties to random variables. For example, a Vector3 size parameter can be used to randomize the x, y, and z dimensions of an obstacle. Or a material parameter can be used to swap between different terrain surface materials. Additionally, parameter sub-properties can be modified from the parameter configuration in playmode better visualize the impact of different randomization settings.
To read more about how to create custom parameter types, navigate over to the [parameters doc](Parameters.md).

Samplers are classes that deterministically generate random float values from bounded probability distributions. Samplers are considered bounded since each random sampler generates float values within a range defined by a minumum and maximum value. The values generated from samplers are often used to randomize the sub components of parameters.
Samplers deterministically generate random float values from bounded probability distributions. They are considered bounded since each random sampler generates float values within a range defined by a minumum and maximum value. The values generated from samplers are often used to randomize the sub components of parameters.
![Example Parameters](./Images/ColorParameter.png)

Finally, scenarios define constants from which to expose global simulation behaviors automatically. By modifying serialized constants externally, users can customize their simulation runtime even after their project has been built.
Take a look at the [scenarios doc](Scenarios.md) to learn more about creating custom scenarios.
Visit our [randomization tutorial](Tutorial.md) to get started using the randomization tools in an example project.
## Getting Started

6
com.unity.perception/Documentation~/Randomization/Parameters.md


# Parameters
All parameters are derived from one of three abstract classes:
1. Categorical parameters
2. Struct parameters
3. Typed parameters
1. `Categorical parameters`
2. `Struct parameters`
3. `Typed parameters`
### Categorical Parameters

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


if (iterator.propertyPath == "m_Script" || iterator.propertyPath == "parameterName")
continue;
if (iterator.type.Contains("managedReference") &&
iterator.managedReferenceFieldTypename == StaticData.SamplerSerializedFieldType)
iterator.managedReferenceFieldTypename == StaticData.samplerSerializedFieldType)
m_ExtraProperties.Add(new SamplerElement(iterator.Copy()));
else
{

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


const string k_RandomizationDir = "Packages/com.unity.perception/Editor/Randomization";
public const string uxmlDir = k_RandomizationDir + "/Uxml";
public static readonly string SamplerSerializedFieldType;
public static readonly string samplerSerializedFieldType;
public static Type[] parameterTypes;
public static Type[] samplerTypes;

GatherParameterAndSamplerTypes();
var samplerType = typeof(ISampler);
SamplerSerializedFieldType = $"{samplerType.Assembly.GetName().Name} {samplerType.FullName}";
samplerSerializedFieldType = $"{samplerType.Assembly.GetName().Name} {samplerType.FullName}";
}
static void GatherParameterAndSamplerTypes()

2
com.unity.perception/Runtime/Randomization/Configuration/ParameterConfiguration.cs


/// Creates parameter interfaces for randomizing simulations
/// </summary>
[ExecuteInEditMode]
[AddComponentMenu("Randomization/ParameterConfiguration")]
[AddComponentMenu("Perception/Randomization/ParameterConfiguration")]
public class ParameterConfiguration : MonoBehaviour
{
public static HashSet<ParameterConfiguration> configurations = new HashSet<ParameterConfiguration>();

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


public override NativeArray<bool> Samples(int index, int sampleCount, out JobHandle jobHandle)
{
var samples = new NativeArray<bool>(sampleCount, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var rngSamples = value.CopyAndIterate(index).NativeSamples(sampleCount, out jobHandle);
var rngSamples = value.CopyAndIterate(index).Samples(sampleCount, out jobHandle);
jobHandle = new SamplesJob
{
rngSamples = rngSamples,

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


public override NativeArray<Color> Samples(int index, int sampleCount, out JobHandle jobHandle)
{
var samples = new NativeArray<Color>(sampleCount, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var hueRng = hue.CopyAndIterate(index).NativeSamples(sampleCount, out var hueHandle);
var satRng = saturation.CopyAndIterate(index).NativeSamples(sampleCount, out var satHandle);
var valRng = value.CopyAndIterate(index).NativeSamples(sampleCount, out var valHandle);
var alphaRng = alpha.CopyAndIterate(index).NativeSamples(sampleCount, out var alphaHandle);
var hueRng = hue.CopyAndIterate(index).Samples(sampleCount, out var hueHandle);
var satRng = saturation.CopyAndIterate(index).Samples(sampleCount, out var satHandle);
var valRng = value.CopyAndIterate(index).Samples(sampleCount, out var valHandle);
var alphaRng = alpha.CopyAndIterate(index).Samples(sampleCount, out var alphaHandle);
var handles = new NativeArray<JobHandle>(4, Allocator.TempJob)
{

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


public override NativeArray<float> Samples(int index, int sampleCount, out JobHandle jobHandle)
{
return value.CopyAndIterate(index).NativeSamples(sampleCount, out jobHandle);
return value.CopyAndIterate(index).Samples(sampleCount, out jobHandle);
}
}
}

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


public override NativeArray<int> Samples(int index, int totalSamples, out JobHandle jobHandle)
{
var samples = new NativeArray<int>(totalSamples, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var rngSamples = value.CopyAndIterate(index).NativeSamples(totalSamples, out jobHandle);
var rngSamples = value.CopyAndIterate(index).Samples(totalSamples, out jobHandle);
jobHandle = new SamplesJob
{
rngSamples = rngSamples,

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


public override NativeArray<Vector2> Samples(int index, int totalSamples, out JobHandle jobHandle)
{
var samples = new NativeArray<Vector2>(totalSamples, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var xRng = x.CopyAndIterate(index).NativeSamples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).NativeSamples(totalSamples, out var yHandle);
var xRng = x.CopyAndIterate(index).Samples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).Samples(totalSamples, out var yHandle);
var combinedJobHandles = JobHandle.CombineDependencies(xHandle, yHandle);
jobHandle = new SamplesJob
{

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


public override NativeArray<Vector3> Samples(int index, int totalSamples, out JobHandle jobHandle)
{
var samples = new NativeArray<Vector3>(totalSamples, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var xRng = x.CopyAndIterate(index).NativeSamples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).NativeSamples(totalSamples, out var yHandle);
var zRng = z.CopyAndIterate(index).NativeSamples(totalSamples, out var zHandle);
var xRng = x.CopyAndIterate(index).Samples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).Samples(totalSamples, out var yHandle);
var zRng = z.CopyAndIterate(index).Samples(totalSamples, out var zHandle);
var combinedJobHandles = JobHandle.CombineDependencies(xHandle, yHandle, zHandle);
jobHandle = new SamplesJob
{

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


public override NativeArray<Vector4> Samples(int index, int totalSamples, out JobHandle jobHandle)
{
var samples = new NativeArray<Vector4>(totalSamples, Allocator.TempJob, NativeArrayOptions.UninitializedMemory);
var xRng = x.CopyAndIterate(index).NativeSamples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).NativeSamples(totalSamples, out var yHandle);
var zRng = z.CopyAndIterate(index).NativeSamples(totalSamples, out var zHandle);
var wRng = w.CopyAndIterate(index).NativeSamples(totalSamples, out var wHandle);
var xRng = x.CopyAndIterate(index).Samples(totalSamples, out var xHandle);
var yRng = y.CopyAndIterate(index).Samples(totalSamples, out var yHandle);
var zRng = z.CopyAndIterate(index).Samples(totalSamples, out var zHandle);
var wRng = w.CopyAndIterate(index).Samples(totalSamples, out var wHandle);
var handles = new NativeArray<JobHandle>(4, Allocator.Temp)
{

2
com.unity.perception/Runtime/Randomization/Samplers/ISampler.cs


/// <summary>
/// Schedule a job to generate multiple samples
/// </summary>
NativeArray<float> NativeSamples(int sampleCount, out JobHandle jobHandle);
NativeArray<float> Samples(int sampleCount, out JobHandle jobHandle);
}
}

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


return value;
}
public NativeArray<float> NativeSamples(int sampleCount, out JobHandle jobHandle)
public NativeArray<float> Samples(int sampleCount, out JobHandle jobHandle)
{
return SamplerUtility.GenerateSamples(this, sampleCount, out jobHandle);
}

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


public struct NormalSampler : ISampler
{
public float mean;
public float stdDev;
public float standardDeviation;
[SerializeField] Unity.Mathematics.Random m_Random;
[field: SerializeField]

set => m_Random = new Unity.Mathematics.Random { state = value };
}
public NormalSampler(float min, float max, float mean, float stdDev)
public NormalSampler(float min, float max, float mean, float standardDeviation)
this.stdDev = stdDev;
this.standardDeviation = standardDeviation;
m_Random = new Unity.Mathematics.Random();
m_Random.InitState();
}

public float NextSample()
{
return SamplerUtility.TruncatedNormalSample(
m_Random.NextFloat(), range.minimum, range.maximum, mean, stdDev);
m_Random.NextFloat(), range.minimum, range.maximum, mean, standardDeviation);
public NativeArray<float> NativeSamples(int sampleCount, out JobHandle jobHandle)
public NativeArray<float> Samples(int sampleCount, out JobHandle jobHandle)
{
return SamplerUtility.GenerateSamples(this, sampleCount, out jobHandle);
}

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


return math.lerp(range.minimum, range.maximum, m_Random.NextFloat());
}
public NativeArray<float> NativeSamples(int sampleCount, out JobHandle jobHandle)
public NativeArray<float> Samples(int sampleCount, out JobHandle jobHandle)
{
return SamplerUtility.GenerateSamples(this, sampleCount, out jobHandle);
}

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


public static class SamplerUtility
{
public const uint largePrime = 0x202A96CF;
public const int SamplingBatchSize = 64;
public const int samplingBatchSize = 64;
/// <summary>
/// Non-deterministically generates a random seed

public static void ValidateRange(FloatRange range)
{
if (range.minimum > range.maximum)
throw new SamplerException("Invalid sampling range");
throw new ArgumentException("Invalid sampling range");
}
/// <summary>

{
sampler = sampler,
samples = samples
}.ScheduleBatch(totalSamples, SamplingBatchSize);
}.ScheduleBatch(totalSamples, samplingBatchSize);
return samples;
}

public void Execute(int startIndex, int count)
{
var endIndex = startIndex + count;
var batchIndex = (uint)startIndex / SamplingBatchSize;
var batchIndex = (uint)startIndex / samplingBatchSize;
sampler.seed = IterateSeed(batchIndex, sampler.seed);
for (var i = startIndex; i < endIndex; i++)
samples[i] = sampler.NextSample();

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


foreach (var perceptionCamera in FindObjectsOfType<PerceptionCamera>())
perceptionCamera.enabled = false;
QuitApplication();
}
void QuitApplication()
{
if (quitOnComplete)
#if UNITY_EDITOR
UnityEditor.EditorApplication.isPlaying = false;

4
com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs


/// <summary>
/// An example scenario where each scenario iteration runs for exactly one frame
/// </summary>
[AddComponentMenu("Randomization/Scenarios/Fixed Frame Length Scenario")]
public class FixedFrameLengthScenario: Scenario<FixedFrameLengthScenario.Constants>
[AddComponentMenu("Perception/Randomization/Scenarios/Fixed Length Scenario")]
public class FixedLengthScenario: Scenario<FixedLengthScenario.Constants>
{
[Serializable]
public class Constants

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


using System.Collections;
using System;
using System.Collections;
using NUnit.Framework;
using UnityEngine.Perception.Randomization.Samplers;
using UnityEngine.TestTools;

static void NativeSamplesInRange(ISampler sampler)
{
var samples = sampler.CopyAndIterate(k_ScenarioIteration).NativeSamples(k_TestSampleCount, out var handle);
var samples = sampler.CopyAndIterate(k_ScenarioIteration).Samples(k_TestSampleCount, out var handle);
handle.Complete();
Assert.AreEqual(samples.Length, k_TestSampleCount);
foreach (var sample in samples)

}
[Test]
public void PlaceholderRangeThrowsExceptionsWhenSamplingTest()
{
var phSampler = new PlaceholderRangeSampler();
Assert.Throws<SamplerException>(() => phSampler.NextSample());
}
[Test]
Assert.Throws<SamplerException>(() => SamplerUtility.ValidateRange(new FloatRange(1, -1)));
Assert.Throws<ArgumentException>(() => SamplerUtility.ValidateRange(new FloatRange(1, -1)));
}
}
}

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


public class ScenarioTests
{
GameObject m_TestObject;
FixedFrameLengthScenario m_Scenario;
FixedLengthScenario m_Scenario;
[SetUp]
public void Setup()

IEnumerator CreateNewScenario()
{
m_Scenario = m_TestObject.AddComponent<FixedFrameLengthScenario>();
m_Scenario = m_TestObject.AddComponent<FixedLengthScenario>();
m_Scenario.quitOnComplete = false;
yield return null;
}

yield return CreateNewScenario();
m_Scenario.serializedConstantsFileName = "perception_serialization_test";
var constants = new FixedFrameLengthScenario.Constants
var constants = new FixedLengthScenario.Constants
{
framesPerIteration = 2,
startingIteration = 2,

var changedConstants = new FixedFrameLengthScenario.Constants
var changedConstants = new FixedLengthScenario.Constants
{
framesPerIteration = 0,
startingIteration = 0,

45
com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/PlaceholderRangeSampler.cs


using System;
using Unity.Collections;
using Unity.Jobs;
namespace UnityEngine.Perception.Randomization.Samplers
{
/// <summary>
/// This sampler is useful for configuring sample ranges for non-perception related scripts,
/// particularly when these scripts have a public interface for manipulating a sample range
/// but perform the actual sampling logic internally.
/// </summary>
[Serializable]
[SamplerMetaData("Placeholder Range")]
public struct PlaceholderRangeSampler : ISampler
{
public uint seed
{
get => 0;
set { }
}
[field: SerializeField]
public FloatRange range { get; set; }
public PlaceholderRangeSampler(FloatRange floatRange)
{
range = floatRange;
}
public ISampler CopyAndIterate(int index)
{
return new PlaceholderRangeSampler(range);
}
public float NextSample()
{
throw new SamplerException("Cannot sample PlaceholderRangeSampler");
}
public NativeArray<float> NativeSamples(int sampleCount, out JobHandle jobHandle)
{
throw new SamplerException("Cannot sample PlaceholderRangeSampler");
}
}
}

3
com.unity.perception/Runtime/Randomization/Samplers/SamplerTypes/PlaceholderRangeSampler.cs.meta


fileFormatVersion: 2
guid: b7e21eaa68ac45b79c0c926f192f82ae
timeCreated: 1595454393

9
com.unity.perception/Runtime/Randomization/Samplers/SamplerException.cs


using System;
namespace UnityEngine.Perception.Randomization.Samplers
{
public class SamplerException : Exception
{
public SamplerException(string msg) : base(msg) { }
}
}

3
com.unity.perception/Runtime/Randomization/Samplers/SamplerException.cs.meta


fileFormatVersion: 2
guid: a73b322a6e67459aa02146af781a4a1d
timeCreated: 1595455830

/com.unity.perception/Runtime/Randomization/Scenarios/FixedFrameLengthScenario.cs.meta → /com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs.meta

/com.unity.perception/Runtime/Randomization/Scenarios/FixedFrameLengthScenario.cs → /com.unity.perception/Runtime/Randomization/Scenarios/FixedLengthScenario.cs

正在加载...
取消
保存