Unity-Technologies · chriselion · Apr 23, 2020 · Apr 23, 2020 · Apr 23, 2020 · Apr 23, 2020
diff --git a/Project/Assets/ML-Agents/Examples/SharedAssets/Scripts/SensorBase.cs b/Project/Assets/ML-Agents/Examples/SharedAssets/Scripts/SensorBase.cs
@@ -22,18 +22,18 @@ public abstract class SensorBase : ISensor
 
         /// <summary>
         /// Default implementation of Write interface. This creates a temporary array,
-        /// calls WriteObservation, and then writes the results to the WriteAdapter.
+        /// calls WriteObservation, and then writes the results to the ObservationWriter.
         /// </summary>
-        /// <param name="adapter"></param>
+        /// <param name="writer"></param>
         /// <returns>The number of elements written.</returns>
-        public virtual int Write(WriteAdapter adapter)
+        public virtual int Write(ObservationWriter writer)
         {
             // TODO reuse buffer for similar agents, don't call GetObservationShape()
             var numFloats = this.ObservationSize();
             float[] buffer = new float[numFloats];
             WriteObservation(buffer);
 
-            adapter.AddRange(buffer);
+            writer.AddRange(buffer);
 
             return numFloats;
         }

diff --git a/com.unity.ml-agents/CHANGELOG.md b/com.unity.ml-agents/CHANGELOG.md
@@ -78,6 +78,8 @@ and this project adheres to
   added in `CollectObservations()`. (#3825)
 - Model updates can now happen asynchronously with environment steps for better performance. (#3690)
 - `num_updates` and `train_interval` for SAC were replaced with `steps_per_update`. (#3690)
+- `WriteAdapter` was renamed to `ObservationWriter`. If you have a custom `ISensor` implementation,
+you will need to change the signature of its `Write()` method. (#3834)
 
 ### Bug Fixes
 

diff --git a/com.unity.ml-agents/Editor/RayPerceptionSensorComponentBaseEditor.cs b/com.unity.ml-agents/Editor/RayPerceptionSensorComponentBaseEditor.cs
@@ -37,7 +37,7 @@ protected void OnRayPerceptionInspectorGUI(bool is3d)
             // it is not editable during play mode.
             EditorGUI.BeginDisabledGroup(!EditorUtilities.CanUpdateModelProperties());
             {
-                EditorGUILayout.PropertyField(so.FindProperty("m_ObservationStacks"), true);
+                EditorGUILayout.PropertyField(so.FindProperty("m_ObservationStacks"), new GUIContent("Stacked Raycasts"), true);
             }
             EditorGUI.EndDisabledGroup();
 

diff --git a/com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs b/com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs
@@ -227,14 +227,14 @@ public static ObservationProto ToProto(this Observation obs)
         }
 
         /// <summary>
-        /// Generate an ObservationProto for the sensor using the provided WriteAdapter.
+        /// Generate an ObservationProto for the sensor using the provided ObservationWriter.
         /// This is equivalent to producing an Observation and calling Observation.ToProto(),
         /// but avoid some intermediate memory allocations.
         /// </summary>
         /// <param name="sensor"></param>
-        /// <param name="writeAdapter"></param>
+        /// <param name="observationWriter"></param>
         /// <returns></returns>
-        public static ObservationProto GetObservationProto(this ISensor sensor, WriteAdapter writeAdapter)
+        public static ObservationProto GetObservationProto(this ISensor sensor, ObservationWriter observationWriter)
         {
             var shape = sensor.GetObservationShape();
             ObservationProto observationProto = null;
@@ -249,8 +249,8 @@ public static ObservationProto GetObservationProto(this ISensor sensor, WriteAda
                     floatDataProto.Data.Add(0.0f);
                 }
 
-                writeAdapter.SetTarget(floatDataProto.Data, sensor.GetObservationShape(), 0);
-                sensor.Write(writeAdapter);
+                observationWriter.SetTarget(floatDataProto.Data, sensor.GetObservationShape(), 0);
+                sensor.Write(observationWriter);
 
                 observationProto = new ObservationProto
                 {

diff --git a/com.unity.ml-agents/Runtime/Communicator/RpcCommunicator.cs b/com.unity.ml-agents/Runtime/Communicator/RpcCommunicator.cs
@@ -27,7 +27,7 @@ internal class RpcCommunicator : ICommunicator
 
         List<string> m_BehaviorNames = new List<string>();
         bool m_NeedCommunicateThisStep;
-        WriteAdapter m_WriteAdapter = new WriteAdapter();
+        ObservationWriter m_ObservationWriter = new ObservationWriter();
         Dictionary<string, SensorShapeValidator> m_SensorShapeValidators = new Dictionary<string, SensorShapeValidator>();
         Dictionary<string, List<int>> m_OrderedAgentsRequestingDecisions = new Dictionary<string, List<int>>();
 
@@ -322,7 +322,7 @@ public void PutObservations(string behaviorName, AgentInfo info, List<ISensor> s
                 {
                     foreach (var sensor in sensors)
                     {
-                        var obsProto = sensor.GetObservationProto(m_WriteAdapter);
+                        var obsProto = sensor.GetObservationProto(m_ObservationWriter);
                         agentInfoProto.Observations.Add(obsProto);
                     }
                 }

diff --git a/com.unity.ml-agents/Runtime/Demonstrations/DemonstrationWriter.cs b/com.unity.ml-agents/Runtime/Demonstrations/DemonstrationWriter.cs
@@ -20,7 +20,7 @@ public class DemonstrationWriter
         DemonstrationMetaData m_MetaData;
         Stream m_Writer;
         float m_CumulativeReward;
-        WriteAdapter m_WriteAdapter = new WriteAdapter();
+        ObservationWriter m_ObservationWriter = new ObservationWriter();
 
         /// <summary>
         /// Create a DemonstrationWriter that will write to the specified stream.
@@ -117,7 +117,7 @@ internal void Record(AgentInfo info, List<ISensor> sensors)
             var agentProto = info.ToInfoActionPairProto();
             foreach (var sensor in sensors)
             {
-                agentProto.AgentInfo.Observations.Add(sensor.GetObservationProto(m_WriteAdapter));
+                agentProto.AgentInfo.Observations.Add(sensor.GetObservationProto(m_ObservationWriter));
             }
 
             agentProto.WriteDelimitedTo(m_Writer);

diff --git a/com.unity.ml-agents/Runtime/Inference/GeneratorImpl.cs b/com.unity.ml-agents/Runtime/Inference/GeneratorImpl.cs
@@ -82,7 +82,7 @@ internal class VectorObservationGenerator : TensorGenerator.IGenerator
     {
         readonly ITensorAllocator m_Allocator;
         List<int> m_SensorIndices = new List<int>();
-        WriteAdapter m_WriteAdapter = new WriteAdapter();
+        ObservationWriter m_ObservationWriter = new ObservationWriter();
 
         public VectorObservationGenerator(ITensorAllocator allocator)
         {
@@ -115,8 +115,8 @@ public void Generate(TensorProxy tensorProxy, int batchSize, IEnumerable<AgentIn
                     foreach (var sensorIndex in m_SensorIndices)
                     {
                         var sensor = info.sensors[sensorIndex];
-                        m_WriteAdapter.SetTarget(tensorProxy, agentIndex, tensorOffset);
-                        var numWritten = sensor.Write(m_WriteAdapter);
+                        m_ObservationWriter.SetTarget(tensorProxy, agentIndex, tensorOffset);
+                        var numWritten = sensor.Write(m_ObservationWriter);
                         tensorOffset += numWritten;
                     }
                     Debug.AssertFormat(
@@ -350,7 +350,7 @@ internal class VisualObservationInputGenerator : TensorGenerator.IGenerator
     {
         readonly int m_SensorIndex;
         readonly ITensorAllocator m_Allocator;
-        WriteAdapter m_WriteAdapter = new WriteAdapter();
+        ObservationWriter m_ObservationWriter = new ObservationWriter();
 
         public VisualObservationInputGenerator(
             int sensorIndex, ITensorAllocator allocator)
@@ -375,8 +375,8 @@ public void Generate(TensorProxy tensorProxy, int batchSize, IEnumerable<AgentIn
                 }
                 else
                 {
-                    m_WriteAdapter.SetTarget(tensorProxy, agentIndex, 0);
-                    sensor.Write(m_WriteAdapter);
+                    m_ObservationWriter.SetTarget(tensorProxy, agentIndex, 0);
+                    sensor.Write(m_ObservationWriter);
                 }
                 agentIndex++;
             }

diff --git a/com.unity.ml-agents/Runtime/Policies/HeuristicPolicy.cs b/com.unity.ml-agents/Runtime/Policies/HeuristicPolicy.cs
@@ -19,7 +19,7 @@ internal class HeuristicPolicy : IPolicy
         bool m_Done;
         bool m_DecisionRequested;
 
-        WriteAdapter m_WriteAdapter = new WriteAdapter();
+        ObservationWriter m_ObservationWriter = new ObservationWriter();
         NullList m_NullList = new NullList();
 
 
@@ -128,8 +128,8 @@ void StepSensors(List<ISensor> sensors)
             {
                 if (sensor.GetCompressionType() == SensorCompressionType.None)
                 {
-                    m_WriteAdapter.SetTarget(m_NullList, sensor.GetObservationShape(), 0);
-                    sensor.Write(m_WriteAdapter);
+                    m_ObservationWriter.SetTarget(m_NullList, sensor.GetObservationShape(), 0);
+                    sensor.Write(m_ObservationWriter);
                 }
                 else
                 {

diff --git a/com.unity.ml-agents/Runtime/Sensors/CameraSensor.cs b/com.unity.ml-agents/Runtime/Sensors/CameraSensor.cs
@@ -91,16 +91,16 @@ public byte[] GetCompressedObservation()
         }
 
         /// <summary>
-        /// Writes out the generated, uncompressed image to the provided <see cref="WriteAdapter"/>.
+        /// Writes out the generated, uncompressed image to the provided <see cref="ObservationWriter"/>.
         /// </summary>
-        /// <param name="adapter">Where the observation is written to.</param>
+        /// <param name="writer">Where the observation is written to.</param>
         /// <returns></returns>
-        public int Write(WriteAdapter adapter)
+        public int Write(ObservationWriter writer)
         {
             using (TimerStack.Instance.Scoped("CameraSensor.WriteToTensor"))
             {
                 var texture = ObservationToTexture(m_Camera, m_Width, m_Height);
-                var numWritten = Utilities.TextureToTensorProxy(texture, adapter, m_Grayscale);
+                var numWritten = Utilities.TextureToTensorProxy(texture, writer, m_Grayscale);
                 DestroyTexture(texture);
                 return numWritten;
             }

diff --git a/com.unity.ml-agents/Runtime/Sensors/ISensor.cs b/com.unity.ml-agents/Runtime/Sensors/ISensor.cs
@@ -31,15 +31,15 @@ public interface ISensor
         int[] GetObservationShape();
 
         /// <summary>
-        /// Write the observation data directly to the <see cref="WriteAdapter"/>.
+        /// Write the observation data directly to the <see cref="ObservationWriter"/>.
         /// This is considered an advanced interface; for a simpler approach, use
         /// <see cref="SensorBase"/> and override <see cref="SensorBase.WriteObservation"/> instead.
         /// Note that this (and  <see cref="GetCompressedObservation"/>) may
         /// be called multiple times per agent step, so should not mutate any internal state.
         /// </summary>
-        /// <param name="adapter">Where the observations will be written to.</param>
+        /// <param name="writer">Where the observations will be written to.</param>
         /// <returns>The number of elements written.</returns>
-        int Write(WriteAdapter adapter);
+        int Write(ObservationWriter writer);
 
         /// <summary>
         /// Return a compressed representation of the observation. For small observations,

diff --git a/...ml-agents/Runtime/Sensors/WriteAdapter.cs → ...ents/Runtime/Sensors/ObservationWriter.cs b/...ml-agents/Runtime/Sensors/WriteAdapter.cs → ...ents/Runtime/Sensors/ObservationWriter.cs
@@ -8,7 +8,7 @@ namespace MLAgents.Sensors
     /// <summary>
     /// Allows sensors to write to both TensorProxy and float arrays/lists.
     /// </summary>
-    public class WriteAdapter
+    public class ObservationWriter
     {
         IList<float> m_Data;
         int m_Offset;
@@ -18,10 +18,10 @@ public class WriteAdapter
 
         TensorShape m_TensorShape;
 
-        internal WriteAdapter() { }
+        internal ObservationWriter() { }
 
         /// <summary>
-        /// Set the adapter to write to an IList at the given channelOffset.
+        /// Set the writer to write to an IList at the given channelOffset.
         /// </summary>
         /// <param name="data">Float array or list that will be written to.</param>
         /// <param name="shape">Shape of the observations to be written.</param>
@@ -44,7 +44,7 @@ internal void SetTarget(IList<float> data, int[] shape, int offset)
         }
 
         /// <summary>
-        /// Set the adapter to write to a TensorProxy at the given batch and channel offset.
+        /// Set the writer to write to a TensorProxy at the given batch and channel offset.
         /// </summary>
         /// <param name="tensorProxy">Tensor proxy that will be written to.</param>
         /// <param name="batchIndex">Batch index in the tensor proxy (i.e. the index of the Agent).</param>

diff --git a/...ents/Runtime/Sensors/WriteAdapter.cs.meta → ...Runtime/Sensors/ObservationWriter.cs.meta b/...ents/Runtime/Sensors/WriteAdapter.cs.meta → ...Runtime/Sensors/ObservationWriter.cs.meta
diff --git a/com.unity.ml-agents/Runtime/Sensors/RayPerceptionSensor.cs b/com.unity.ml-agents/Runtime/Sensors/RayPerceptionSensor.cs
@@ -286,11 +286,11 @@ internal void SetRayPerceptionInput(RayPerceptionInput rayInput)
 
         /// <summary>
         /// Computes the ray perception observations and saves them to the provided
-        /// <see cref="WriteAdapter"/>.
+        /// <see cref="ObservationWriter"/>.
         /// </summary>
-        /// <param name="adapter">Where the ray perception observations are written to.</param>
+        /// <param name="writer">Where the ray perception observations are written to.</param>
         /// <returns></returns>
-        public int Write(WriteAdapter adapter)
+        public int Write(ObservationWriter writer)
         {
             using (TimerStack.Instance.Scoped("RayPerceptionSensor.Perceive"))
             {
@@ -322,8 +322,8 @@ public int Write(WriteAdapter adapter)
 
                     rayOutput.ToFloatArray(numDetectableTags, rayIndex, m_Observations);
                 }
-                // Finally, add the observations to the WriteAdapter
-                adapter.AddRange(m_Observations);
+                // Finally, add the observations to the ObservationWriter
+                writer.AddRange(m_Observations);
             }
             return m_Observations.Length;
         }

diff --git a/com.unity.ml-agents/Runtime/Sensors/RayPerceptionSensorComponentBase.cs b/com.unity.ml-agents/Runtime/Sensors/RayPerceptionSensorComponentBase.cs
@@ -112,7 +112,7 @@ public LayerMask RayLayerMask
 
         [HideInInspector, SerializeField, FormerlySerializedAs("observationStacks")]
         [Range(1, 50)]
-        [Tooltip("Whether to stack previous observations. Using 1 means no previous observations.")]
+        [Tooltip("Number of raycast results that will be stacked before being fed to the neural network.")]
         int m_ObservationStacks = 1;
 
         /// <summary>

diff --git a/com.unity.ml-agents/Runtime/Sensors/RenderTextureSensor.cs b/com.unity.ml-agents/Runtime/Sensors/RenderTextureSensor.cs
@@ -68,12 +68,12 @@ public byte[] GetCompressedObservation()
         }
 
         /// <inheritdoc/>
-        public int Write(WriteAdapter adapter)
+        public int Write(ObservationWriter writer)
         {
             using (TimerStack.Instance.Scoped("RenderTextureSensor.Write"))
             {
                 var texture = ObservationToTexture(m_RenderTexture);
-                var numWritten = Utilities.TextureToTensorProxy(texture, adapter, m_Grayscale);
+                var numWritten = Utilities.TextureToTensorProxy(texture, writer, m_Grayscale);
                 DestroyTexture(texture);
                 return numWritten;
             }

diff --git a/com.unity.ml-agents/Runtime/Sensors/StackingSensor.cs b/com.unity.ml-agents/Runtime/Sensors/StackingSensor.cs
@@ -33,7 +33,7 @@ public class StackingSensor : ISensor
         float[][] m_StackedObservations;
 
         int m_CurrentIndex;
-        WriteAdapter m_LocalAdapter = new WriteAdapter();
+        ObservationWriter m_LocalWriter = new ObservationWriter();
 
         /// <summary>
         /// Initializes the sensor.
@@ -76,19 +76,19 @@ public StackingSensor(ISensor wrapped, int numStackedObservations)
         }
 
         /// <inheritdoc/>
-        public int Write(WriteAdapter adapter)
+        public int Write(ObservationWriter writer)
         {
-            // First, call the wrapped sensor's write method. Make sure to use our own adapter, not the passed one.
+            // First, call the wrapped sensor's write method. Make sure to use our own writer, not the passed one.
             var wrappedShape = m_WrappedSensor.GetObservationShape();
-            m_LocalAdapter.SetTarget(m_StackedObservations[m_CurrentIndex], wrappedShape, 0);
-            m_WrappedSensor.Write(m_LocalAdapter);
+            m_LocalWriter.SetTarget(m_StackedObservations[m_CurrentIndex], wrappedShape, 0);
+            m_WrappedSensor.Write(m_LocalWriter);
 
             // Now write the saved observations (oldest first)
             var numWritten = 0;
             for (var i = 0; i < m_NumStackedObservations; i++)
             {
                 var obsIndex = (m_CurrentIndex + 1 + i) % m_NumStackedObservations;
-                adapter.AddRange(m_StackedObservations[obsIndex], numWritten);
+                writer.AddRange(m_StackedObservations[obsIndex], numWritten);
                 numWritten += m_UnstackedObservationSize;
             }
 

diff --git a/com.unity.ml-agents/Runtime/Sensors/VectorSensor.cs b/com.unity.ml-agents/Runtime/Sensors/VectorSensor.cs
@@ -33,7 +33,7 @@ public VectorSensor(int observationSize, string name = null)
         }
 
         /// <inheritdoc/>
-        public int Write(WriteAdapter adapter)
+        public int Write(ObservationWriter writer)
         {
             var expectedObservations = m_Shape[0];
             if (m_Observations.Count > expectedObservations)
@@ -57,7 +57,7 @@ public int Write(WriteAdapter adapter)
                     m_Observations.Add(0);
                 }
             }
-            adapter.AddRange(m_Observations);
+            writer.AddRange(m_Observations);
             return expectedObservations;
         }
 

diff --git a/com.unity.ml-agents/Runtime/Utilities.cs b/com.unity.ml-agents/Runtime/Utilities.cs
@@ -7,13 +7,13 @@ namespace MLAgents
     internal static class Utilities
     {
         /// <summary>
-        /// Puts a Texture2D into a WriteAdapter.
+        /// Puts a Texture2D into a ObservationWriter.
         /// </summary>
         /// <param name="texture">
         /// The texture to be put into the tensor.
         /// </param>
-        /// <param name="adapter">
-        /// Adapter to fill with Texture data.
+        /// <param name="obsWriter">
+        /// Writer to fill with Texture data.
         /// </param>
         /// <param name="grayScale">
         /// If set to <c>true</c> the textures will be converted to grayscale before
@@ -22,7 +22,7 @@ internal static class Utilities
         /// <returns>The number of floats written</returns>
         internal static int TextureToTensorProxy(
             Texture2D texture,
-            WriteAdapter adapter,
+            ObservationWriter obsWriter,
             bool grayScale)
         {
             var width = texture.width;
@@ -38,15 +38,15 @@ internal static int TextureToTensorProxy(
                     var currentPixel = texturePixels[(height - h - 1) * width + w];
                     if (grayScale)
                     {
-                        adapter[h, w, 0] =
+                        obsWriter[h, w, 0] =
                             (currentPixel.r + currentPixel.g + currentPixel.b) / 3f / 255.0f;
                     }
                     else
                     {
                         // For Color32, the r, g and b values are between 0 and 255.
-                        adapter[h, w, 0] = currentPixel.r / 255.0f;
-                        adapter[h, w, 1] = currentPixel.g / 255.0f;
-                        adapter[h, w, 2] = currentPixel.b / 255.0f;
+                        obsWriter[h, w, 0] = currentPixel.r / 255.0f;
+                        obsWriter[h, w, 1] = currentPixel.g / 255.0f;
+                        obsWriter[h, w, 2] = currentPixel.b / 255.0f;
                     }
                 }
             }