Add initial support for subsampeling in interleave mode none

Add as first step a 3 component unit test in interleave mode none that can be encoded and decoded.

Author: vbaderks

src/ErrorCode.cs

@@ -202,6 +202,11 @@ public enum ErrorCode
     /// </summary>
     InvalidParameterMappingTableContinuation = 38,
 
+    /// <summary>
+    /// This error is returned when the stream contains an invalid sampling factor.
+    /// </summary>
+    InvalidParameterSamplingFactor = 39,
+
     // Logic errors:
 
     /// <summary>

src/JpegLSEncoder.cs

@@ -27,6 +27,9 @@ public sealed class JpegLSEncoder
     private JpegLSPresetCodingParameters? _userPresetCodingParameters = new();
     private State _state = State.Initial;
     private int _encodedComponentCount;
+    private byte[]? _samplingFactors;
+    private int _horizontalSamplingMax;
+    private int _verticalSamplingMax;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="JpegLSEncoder"/> class.
@@ -247,6 +250,23 @@ public Memory<byte> Destination
 
     private bool IsFrameInfoConfigured => FrameInfo.Height != 0;
 
+    /// <summary>
+    /// Configures the sampling factor when encoding a component.
+    /// </summary>
+    /// <param name="componentIndex">The index of the component to set the mapping table ID for.</param>
+    /// <param name="horizontalFactor">The horizontal subsampling factor.</param>
+    /// <param name="verticalFactor">The vertical subsampling factor.</param>
+    public void SetSamplingFactor(int componentIndex, int horizontalFactor, int verticalFactor)
+    {
+        ThrowHelper.ThrowIfOutsideRange(Constants.MinimumComponentIndex, Constants.MaximumComponentIndex, componentIndex);
+        ThrowHelper.ThrowIfOutsideRange(0, 4, horizontalFactor);
+        ThrowHelper.ThrowIfOutsideRange(0, 4, verticalFactor);
+
+        // Usage of sampling factors is rare: use lazy initialization.
+        _samplingFactors ??= new byte[Constants.MaximumComponentCount];
+        _samplingFactors[componentIndex] = (byte)((horizontalFactor << 4) | verticalFactor);
+    }
+
     /// <summary>
     /// Configures the mapping table ID the encoder should reference when encoding a component.
     /// The referenced mapping table can be included in the stream or provided in another JPEG-LS abbreviated format stream.
@@ -298,14 +318,14 @@ public void EncodeComponents(ReadOnlySpan<byte> source, int sourceComponentCount
         ThrowHelper.ThrowInvalidOperationIfFalse(IsFrameInfoConfigured);
         ThrowHelper.ThrowArgumentExceptionIfFalse(sourceComponentCount <= FrameInfo.ComponentCount - _encodedComponentCount, nameof(sourceComponentCount));
         CheckInterleaveModeAgainstComponentCount(sourceComponentCount);
-        int scanStride = CheckStrideAndSourceLength(source.Length, stride, sourceComponentCount);
 
         int maximumSampleValue = CalculateMaximumSampleValue(FrameInfo.BitsPerSample);
         if (!_userPresetCodingParameters!.TryMakeExplicit(maximumSampleValue, NearLossless, out var explicitCodingParameters))
             throw ThrowHelper.CreateArgumentException(ErrorCode.InvalidArgumentPresetCodingParameters);
 
         if (_encodedComponentCount == 0)
         {
+            DetermineMaxSamplingFactors();
             TransitionToTablesAndMiscellaneousState();
             WriteColorTransformSegment();
             WriteStartOfFrameSegment();
@@ -315,24 +335,28 @@ public void EncodeComponents(ReadOnlySpan<byte> source, int sourceComponentCount
 
         if (InterleaveMode == InterleaveMode.None)
         {
-            int byteCountComponent = scanStride * FrameInfo.Height;
             for (int component = 0; ;)
             {
+                int scanWidth = GetScanWidth(_encodedComponentCount + component);
+                int scanHeight = GetScanHeight(_encodedComponentCount + component);
+                int scanStride = CheckStrideAndSourceLengthInterleaveModeNone(source.Length, stride, scanWidth, scanHeight);
                 _writer.WriteStartOfScanSegment(1, NearLossless, InterleaveMode);
-                EncodeScan(source, scanStride, 1, explicitCodingParameters);
+                EncodeScan(source, scanStride, scanWidth, scanHeight, 1, explicitCodingParameters);
 
                 ++component;
                 if (component == sourceComponentCount)
                     break;
 
                 // Synchronize the source stream (EncodeScan works on a local copy)
+                int byteCountComponent = scanStride * scanHeight;
                 source = source[byteCountComponent..];
             }
         }
         else
         {
+            int scanStride = CheckStrideAndSourceLength(source.Length, stride, sourceComponentCount);
             _writer.WriteStartOfScanSegment(sourceComponentCount, NearLossless, InterleaveMode);
-            EncodeScan(source, scanStride, sourceComponentCount, explicitCodingParameters);
+            EncodeScan(source, scanStride, FrameInfo.Width, FrameInfo.Height, sourceComponentCount, explicitCodingParameters);
         }
 
         _encodedComponentCount += sourceComponentCount;
@@ -526,10 +550,10 @@ public static Memory<byte> Encode(
         return encoder.EncodedData;
     }
 
-    private void EncodeScan(ReadOnlySpan<byte> source, int stride, int componentCount, JpegLSPresetCodingParameters codingParameters)
+    private void EncodeScan(ReadOnlySpan<byte> source, int stride, int scanWidth, int scanHeight, int componentCount, JpegLSPresetCodingParameters codingParameters)
     {
         _scanEncoder = new ScanEncoder(
-            new FrameInfo(FrameInfo.Width, FrameInfo.Height, FrameInfo.BitsPerSample, componentCount),
+            new FrameInfo(scanWidth, scanHeight, FrameInfo.BitsPerSample, componentCount),
             codingParameters,
             new CodingParameters
             {
@@ -592,7 +616,7 @@ private void WriteColorTransformSegment()
 
     private void WriteStartOfFrameSegment()
     {
-        if (_writer.WriteStartOfFrameSegment(FrameInfo))
+        if (_writer.WriteStartOfFrameSegment(FrameInfo, _samplingFactors))
         {
             // Image dimensions are oversized and need to be written to a JPEG-LS preset parameters (LSE) segment.
             _writer.WriteJpegLSPresetParametersSegment(FrameInfo.Height, FrameInfo.Width);
@@ -652,6 +676,28 @@ private int CheckStrideAndSourceLength(int sourceLength, int stride, int sourceC
         return stride;
     }
 
+    private int CheckStrideAndSourceLengthInterleaveModeNone(int sourceLength, int stride, int scanWidth, int scanHeight)
+    {
+        int minimumStride = scanWidth * BitToByteCount(FrameInfo.BitsPerSample);
+        if (stride == AutoCalculateStride)
+        {
+            stride = minimumStride;
+        }
+        else
+        {
+            if (stride < minimumStride)
+                ThrowHelper.ThrowArgumentException(ErrorCode.InvalidArgumentStride);
+        }
+
+        int notUsedBytesAtEnd = stride - minimumStride;
+        int minimumSourceLength = (stride * scanHeight) - notUsedBytesAtEnd;
+
+        if (sourceLength < minimumSourceLength)
+            ThrowHelper.ThrowArgumentException(ErrorCode.InvalidArgumentSize);
+
+        return stride;
+    }
+
     private int CalculateMinimumStride(int sourceComponentCount)
     {
         int stride = FrameInfo.Width * BitToByteCount(FrameInfo.BitsPerSample);
@@ -661,6 +707,54 @@ private int CalculateMinimumStride(int sourceComponentCount)
         return stride * sourceComponentCount;
     }
 
+    private void DetermineMaxSamplingFactors()
+    {
+        if (_samplingFactors == null)
+            return;
+
+        _horizontalSamplingMax = 1;
+        _verticalSamplingMax = 1;
+        for (int i = 0; i < FrameInfo.ComponentCount; ++i)
+        {
+            _horizontalSamplingMax = Math.Max(_horizontalSamplingMax, GetHorizontalSamplingFactor(i));
+            _verticalSamplingMax = Math.Max(_verticalSamplingMax, GetVerticalSamplingFactor(i));
+        }
+    }
+
+    private int GetScanWidth(int componentIndex)
+    {
+        if (_samplingFactors == null)
+            return FrameInfo.Width;
+
+        return FrameInfo.Width * GetHorizontalSamplingFactor(componentIndex) / _horizontalSamplingMax;
+    }
+
+    private int GetScanHeight(int componentIndex)
+    {
+        if (_samplingFactors == null)
+            return FrameInfo.Height;
+
+        return FrameInfo.Height * GetVerticalSamplingFactor(componentIndex) / _verticalSamplingMax;
+    }
+
+    private int GetHorizontalSamplingFactor(int componentIndex)
+    {
+        byte samplingFactor = _samplingFactors![componentIndex];
+        if (samplingFactor == 0)
+            return 1;
+
+        return samplingFactor >> 4;
+    }
+
+    private int GetVerticalSamplingFactor(int componentIndex)
+    {
+        byte samplingFactor = _samplingFactors![componentIndex];
+        if (samplingFactor == 0)
+            return 1;
+
+        return samplingFactor & 0xF;
+    }
+
     private static ReadOnlySpan<byte> ToUtf8(string text)
     {
         if (string.IsNullOrEmpty(text))

src/JpegStreamReader.cs

@@ -16,8 +16,8 @@ internal struct JpegStreamReader
     private readonly object _eventSender;
     private readonly List<ComponentInfo> _componentInfos;
     private readonly List<MappingTableEntry> _mappingTables = [];
+
     private State _state;
-    private bool _dnlMarkerExpected;
     private int _nearLossless;
     private int _segmentDataSize;
     private int _segmentStartPosition;
@@ -26,6 +26,9 @@ internal struct JpegStreamReader
     private int _bitsPerSample;
     private int _componentCount;
     private int _readComponentCount;
+    private int _horizontalSamplingMax = 1;
+    private int _verticalSamplingMax = 1;
+    private bool _dnlMarkerExpected;
     private bool _componentWithMappingTableExists;
 
     public JpegStreamReader()
@@ -72,7 +75,8 @@ private enum State
 
     internal int ScanComponentCount { get; private set; }
 
-    internal readonly FrameInfo ScanFrameInfo => new(_width, _height, _bitsPerSample, ScanComponentCount);
+    internal readonly FrameInfo ScanFrameInfo =>
+        new(GetScanWidth(_readComponentCount - ScanComponentCount), GetScanHeight(_readComponentCount - ScanComponentCount), _bitsPerSample, ScanComponentCount);
 
     internal CompressedDataFormat CompressedDataFormat { get; private set; }
 
@@ -483,10 +487,9 @@ private void ReadStartOfFrameSegment()
         for (int i = 0; i != _componentCount; i++)
         {
             // Component specification parameters
-            AddComponent(ReadByte()); // Ci = Component identifier
+            byte componentIdentifier = ReadByte(); // Ci = Component identifier
             byte horizontalVerticalSamplingFactor = ReadByte(); // Hi + Vi = Horizontal sampling factor + Vertical sampling factor
-            if (horizontalVerticalSamplingFactor != 0x11)
-                ThrowHelper.ThrowInvalidDataException(ErrorCode.ParameterValueNotSupported);
+            AddComponent(componentIdentifier, horizontalVerticalSamplingFactor);
 
             SkipByte(); // Tqi = Quantization table destination selector (reserved for JPEG-LS, should be set to 0)
         }
@@ -820,12 +823,27 @@ private readonly void CheckSegmentSize(int expectedSize)
             ThrowHelper.ThrowInvalidDataException(ErrorCode.InvalidMarkerSegmentSize);
     }
 
-    private readonly void AddComponent(byte componentId)
+    private void AddComponent(byte componentId, byte horizontalVerticalSamplingFactor)
     {
         if (_componentInfos.Exists(scan => scan.Id == componentId))
             ThrowHelper.ThrowInvalidDataException(ErrorCode.DuplicateComponentIdInStartOfFrameSegment);
 
-        _componentInfos.Add(new ComponentInfo(componentId));
+        byte horizontalSamplingFactor = (byte)(horizontalVerticalSamplingFactor >> 4);
+        byte verticalSamplingFactor = (byte)(horizontalVerticalSamplingFactor & 0xF);
+        if (horizontalSamplingFactor < 1 || horizontalSamplingFactor > 4 || verticalSamplingFactor < 1 || verticalSamplingFactor > 4)
+            ThrowHelper.ThrowInvalidDataException(ErrorCode.InvalidParameterSamplingFactor);
+
+        _componentInfos.Add(new ComponentInfo(componentId, horizontalSamplingFactor, verticalSamplingFactor));
+
+        if (horizontalSamplingFactor > _horizontalSamplingMax)
+        {
+            _horizontalSamplingMax = horizontalSamplingFactor;
+        }
+
+        if (verticalSamplingFactor > _verticalSamplingMax)
+        {
+            _verticalSamplingMax = verticalSamplingFactor;
+        }
     }
 
     private readonly void CheckWidth()
@@ -862,6 +880,24 @@ private void SetHeight(int value, bool finalUpdate)
         _height = value;
     }
 
+    private readonly int GetScanWidth(int componentIndex)
+    {
+        int horizontalSamplingFactor = _componentInfos[componentIndex].HorizontalSamplingFactor;
+        if (_horizontalSamplingMax == horizontalSamplingFactor)
+            return _width;
+
+        return _width * horizontalSamplingFactor / _horizontalSamplingMax;
+    }
+
+    private readonly int GetScanHeight(int componentIndex)
+    {
+        int verticalSamplingFactor = _componentInfos[componentIndex].VerticalSamplingFactor;
+        if (_verticalSamplingMax == verticalSamplingFactor)
+            return _height;
+
+        return _height * verticalSamplingFactor / _verticalSamplingMax;
+    }
+
     private void StoreComponentInfo(byte componentId, byte tableId, int nearLossless, InterleaveMode interleaveMode)
     {
         // Ignore when info is default, prevent search and ID mismatch issues.
@@ -877,7 +913,7 @@ private void StoreComponentInfo(byte componentId, byte tableId, int nearLossless
             _componentWithMappingTableExists = true;
         }
 
-        _componentInfos[index] = new ComponentInfo(componentId, tableId, nearLossless, interleaveMode);
+        _componentInfos[index] = new ComponentInfo(_componentInfos[index], tableId, nearLossless, interleaveMode);
     }
 
     private static void CheckInterleaveMode(InterleaveMode mode, int componentCountInScan)
@@ -966,14 +1002,25 @@ or sofDifferentialProgressive or sofDifferentialLossless or sofExtendedArithmeti
 
     private readonly struct ComponentInfo
     {
-        internal readonly int NearLossless;
-        internal readonly InterleaveMode InterleaveMode;
         internal readonly byte Id;
+        internal readonly byte HorizontalSamplingFactor;
+        internal readonly byte VerticalSamplingFactor;
         internal readonly byte MappingTableId;
+        internal readonly int NearLossless;
+        internal readonly InterleaveMode InterleaveMode;
 
-        internal ComponentInfo(byte id, byte mappingTableId = 0, int nearLossless = 0, InterleaveMode interleaveMode = InterleaveMode.None)
+        internal ComponentInfo(byte id, byte horizontalSamplingFactor, byte verticalSamplingFactor)
         {
             Id = id;
+            HorizontalSamplingFactor = horizontalSamplingFactor;
+            VerticalSamplingFactor = verticalSamplingFactor;
+        }
+
+        internal ComponentInfo(ComponentInfo componentInfo, byte mappingTableId, int nearLossless, InterleaveMode interleaveMode)
+        {
+            Id = componentInfo.Id;
+            HorizontalSamplingFactor = componentInfo.HorizontalSamplingFactor;
+            VerticalSamplingFactor = componentInfo.VerticalSamplingFactor;
             MappingTableId = mappingTableId;
             NearLossless = nearLossless;
             InterleaveMode = interleaveMode;

src/JpegStreamWriter.cs

@@ -129,7 +129,7 @@ internal void WriteJpegLSPresetParametersSegment(int height, int width)
         WriteUint32(width);      // Xe: number of columns in the image.
     }
 
-    internal bool WriteStartOfFrameSegment(FrameInfo frameInfo)
+    internal bool WriteStartOfFrameSegment(FrameInfo frameInfo, byte[]? samplingFactors)
     {
         // Create a Frame Header as defined in ISO/IEC 14495-1, C.2.2 and T.81, B.2.2
         int dataSize = 6 + (frameInfo.ComponentCount * 3);
@@ -145,12 +145,12 @@ internal bool WriteStartOfFrameSegment(FrameInfo frameInfo)
 
         // Use by default 1 as the start component identifier to remain compatible with the
         // code sample of ISO/IEC 14495-1, H.4 and the JPEG-LS ISO conformance sample files.
-        for (int componentId = 1; componentId <= frameInfo.ComponentCount; ++componentId)
+        for (int i = 0; i < frameInfo.ComponentCount; i++)
         {
             // Component Specification parameters
-            WriteByte((byte)componentId); // Ci = Component identifier
-            WriteByte(0x11);              // Hi + Vi = Horizontal sampling factor + Vertical sampling factor
-            WriteByte(0);                 // Tqi = Quantization table destination selector (reserved for JPEG-LS, should be set to 0)
+            WriteByte((byte)(i + 1));                         // Ci = Component identifier
+            WriteByte(GetSamplingFactor(samplingFactors, i)); // Hi + Vi = Horizontal sampling factor + Vertical sampling factor
+            WriteByte(0);                                     // Tqi = Quantization table destination selector (reserved for JPEG-LS, should be set to 0)
         }
 
         return oversizedImage;
@@ -295,4 +295,15 @@ private void WriteUint32(int value)
         BinaryPrimitives.WriteUInt32BigEndian(Destination.Span[_position..], (uint)value);
         _position += sizeof(uint);
     }
+
+    private static byte GetSamplingFactor(byte[]? samplingFactors, int componentIndex)
+    {
+        const byte defaultNoSamplingFactor = 0x11;
+
+        if (samplingFactors == null)
+            return defaultNoSamplingFactor;
+
+        byte samplingFactor = samplingFactors[componentIndex];
+        return samplingFactor == 0 ? defaultNoSamplingFactor : samplingFactor;
+    }
 }

src/ThrowHelper.cs

@@ -136,6 +136,7 @@ private static string GetErrorMessage(ErrorCode errorCode)
             ErrorCode.InvalidParameterColorTransformation => "Invalid JPEG-LS stream: Color transformation segment contains invalid values or frame info mismatch",
             ErrorCode.InvalidParameterMappingTableId => "Invalid JPEG-LS stream: mapping table ID outside valid range or duplicate",
             ErrorCode.InvalidParameterMappingTableContinuation => "Invalid JPEG-LS stream: mapping table continuation without matching mapping table specification",
+            ErrorCode.InvalidParameterSamplingFactor => "Invalid JPEG-LS stream: sampling factor outside range [1, 4] or overall sum(h*v) > 10",
             ErrorCode.InvalidOperation => "Method call is invalid for the current state",
             ErrorCode.InvalidArgument => "Invalid argument",
             ErrorCode.InvalidArgumentHeight => "The height argument is outside the supported range [1, 2147483647]",