{"record":{"id":"699f9cbfd4534925","repo":"Unity-Technologies/ml-agents","slug":"when-using-compression-type-m-compressiontype-th","errorCode":null,"errorMessage":"When using compression type {m_CompressionType} the data value has to be normalized between 0-1. Received value[{dataValues[j]}] for {detectedObject.name}","messagePattern":"When using compression type (.+?) the data value has to be normalized between 0-1\\. Received value\\[(.+?)\\] for (.+?)","errorType":"exception","errorClass":"UnityAgentsException","httpStatus":null,"severity":"error","filePath":"com.unity.ml-agents/Runtime/Sensors/GridSensorBase.cs","lineNumber":265,"sourceCode":"        protected internal virtual ProcessCollidersMethod GetProcessCollidersMethod()\n        {\n            return ProcessCollidersMethod.ProcessClosestColliders;\n        }\n\n        /// <summary>\n        /// If using PNG compression, check if the values are normalized.\n        /// </summary>\n        void ValidateValues(float[] dataValues, GameObject detectedObject)\n        {\n            if (m_CompressionType != SensorCompressionType.PNG)\n            {\n                return;\n            }\n\n            for (int j = 0; j < dataValues.Length; j++)\n            {\n                if (dataValues[j] < 0 || dataValues[j] > 1)\n                    throw new UnityAgentsException($\"When using compression type {m_CompressionType} the data value has to be normalized between 0-1. \" +\n                        $\"Received value[{dataValues[j]}] for {detectedObject.name}\");\n            }\n        }\n\n        /// <summary>\n        /// Collect data from the detected object if a detectable tag is matched.\n        /// </summary>\n        internal void ProcessDetectedObject(GameObject detectedObject, int cellIndex)\n        {\n            Profiler.BeginSample(\"GridSensor.ProcessDetectedObject\");\n            for (var i = 0; i < m_DetectableTags.Length; i++)\n            {\n                if (!ReferenceEquals(detectedObject, null) && detectedObject.CompareTag(m_DetectableTags[i]))\n                {\n                    if (GetProcessCollidersMethod() == ProcessCollidersMethod.ProcessAllColliders)\n                    {\n                        Array.Copy(m_PerceptionBuffer, cellIndex * m_CellObservationSize, m_CellDataBuffer, 0, m_CellObservationSize);\n                    }","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/com.unity.ml-agents/Runtime/Sensors/GridSensorBase.cs#L247-L283","documentation":"When the grid sensor uses a compression type (e.g. PNG), the per-cell data written by DetectableObjects must be normalized to [0, 1] because the values are later packed into a texture/color channels. ValidateValues throws if any value written for a detected object falls outside 0-1.","triggerScenarios":"A custom GridSensorBase subclass's GetObjectData() returning raw values >1 or <0 (e.g. counts, world-space distances, byte-valued 0-255 data) while CompressionType is not None; returning negative values such as signed velocities.","commonSituations":"Feeding raw distances or hit counts as cell data and switching compression on for bandwidth; porting sensor code from None to PNG compression without rescaling; passing color values as 0-255 ints instead of 0-1 floats.","solutions":["Normalize all values returned by GetObjectData() to the [0,1] range (e.g. divide by max value or use Mathf.Clamp01 if clamping is acceptable)","Set the sensor's compression type to None if you need unbounded raw values (larger payloads)","Pre-scale data in the subclass: value / maxValue before returning the dataValues array","Check for negative sources (velocities, signed angles) and remap them, e.g. (v + 1) / 2 for [-1,1] inputs"],"exampleFix":"// before\nfloat[] data = { distance }; // distance can be 0..100, compression=PNG\n// after\nfloat[] data = { Mathf.Clamp01(distance / maxDetectionDistance) };","handlingStrategy":"validation","validationCode":"// Unity C#: before returning cell data in GetObjectData\nfor (int i = 0; i < dataValues.Length; i++)\n{\n    if (dataValues[i] < 0f || dataValues[i] > 1f)\n        dataValues[i] = Mathf.Clamp01(dataValues[i]); // or normalize by max\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    ProcessDetectedObject(hit.collider.gameObject);\n}\ncatch (UnityAgentsException e) when (e.Message.Contains(\"normalized between 0-1\"))\n{\n    Debug.LogError(\"Cell data not in [0,1] while compression is enabled: \" + e.Message);\n}","preventionTips":["Normalize values by a known max before returning them from GetObjectData()","Use CompressionType.None if raw unbounded values are required","Unit-test GetObjectData() outputs to assert range [0,1] when compression is on"],"tags":["unity","ml-agents","grid-sensor","normalization","compression"],"backgroundTag":"value-out-of-normalized-range","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}