Support for structured append (mulitple linked QR codes)

Author: manuelbl

QrCodeGenerator/QrCode.cs

@@ -29,6 +29,8 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Linq;
+using System.Text;
 
 namespace Net.Codecrete.QrCodeGenerator
 {
@@ -91,6 +93,65 @@ public static QrCode EncodeText(string text, Ecc ecl)
             return EncodeSegments(segments, ecl);
         }
 
+        /// <summary>
+        /// Creates a series of QR codes representing the specified text.
+        /// <para>
+        /// The result will consist of the minimal number of QR codes needed
+        /// to encode the text with the given error correction level and version (size of QR code).
+        /// If multiple QR codes are required, <em>Structured Append</em> data is included to link the QR codes.
+        /// </para>
+        /// <para>
+        /// The text is split at character boundaries even though the underlying UTF-8 encoding requires
+        /// multiple bytes for some characters. This increases compatibility with QR code scanners assuming
+        /// that each individual QR codes contains a valid UTF-8 string.
+        /// </para>
+        /// </summary>
+        /// <param name="text">The text to be encoded. The full range of Unicode characters may be used.</param>
+        /// <param name="ecl">The minimum error correction level to use.</param>
+        /// <param name="version">The version (size of QR code) to use. Default is 29.</param>
+        /// <param name="boostEcl">Whether error correction level should be upgraded if possible. Default is false.</param>
+        /// <returns>A list of QR codes representing the specified text.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="text"/> or <paramref name="ecl"/> is <c>null</c>.</exception>
+        /// <exception cref="DataTooLongException">The text is too long to fit the maximum of 16 QR codes with the given parameters.</exception>
+        public static List<QrCode> EncodeTextInMultipleCodes(string text, Ecc ecl, int version = 29, bool boostEcl = true)
+        {
+            Objects.RequireNonNull(text);
+            Objects.RequireNonNull(ecl);
+
+            var textBytes = Encoding.UTF8.GetBytes(text);
+            var numCharCountBits = QrSegment.Mode.Byte.NumCharCountBits(version);
+            var numDataCodewords = GetNumDataCodewords(version, ecl);
+
+            if ((numCharCountBits + 7) / 8 + textBytes.Length <= numDataCodewords)
+            {
+                // text is short enough to fit into a single QR code
+                var segment = QrSegment.MakeBytes(textBytes);
+                var qrCode = EncodeSegments(new List<QrSegment> { segment }, ecl, minVersion: version, maxVersion: version, boostEcl: boostEcl);
+                return new List<QrCode> { qrCode };
+            }
+
+            var overhead = (2 * 4 + numCharCountBits + 16 + 7) / 8; // 2 mode indicators + char count + structured append + byte alignment
+            var maxSliceSize = numDataCodewords - overhead;
+            int numSlices = (textBytes.Length + maxSliceSize - 1) / maxSliceSize;
+
+            var segments = QrSegment.MakeStructuredAppendSegments(textBytes, numSlices, considerUtf8Boundaries: true);
+            if (segments.Max(s => s[1].NumChars) > maxSliceSize)
+            {
+                numSlices++;
+                segments = QrSegment.MakeStructuredAppendSegments(textBytes, numSlices, considerUtf8Boundaries: true);
+            }
+
+            if (numSlices > 16)
+            {
+                throw new DataTooLongException("Text is too long to fit in 16 QR codes with the given version and ECL");
+            }
+
+            int balancedSliceSize = (textBytes.Length + numSlices - 1) / numSlices;
+            return segments
+                .Select(segmentList => EncodeSegments(segmentList, ecl, minVersion: version, maxVersion: version, boostEcl: boostEcl))
+                .ToList();
+        }
+
         /// <summary>
         /// Creates a QR code representing the specified binary data using the specified error correction level.
         /// <para>
@@ -936,7 +997,7 @@ private int[] GetAlignmentPatternPositions()
         {
             if (Version == 1)
             {
-                return new int[] { };
+                return Array.Empty<int>();
             }
             else
             {
@@ -952,9 +1013,13 @@ private int[] GetAlignmentPatternPositions()
             }
         }
 
-        // Returns the number of data bits that can be stored in a QR code of the given version number, after
-        // all function modules are excluded. This includes remainder bits, so it might not be a multiple of 8.
-        // The result is in the range [208, 29648]. This could be implemented as a 40-entry lookup table.
+        /// <summary>
+        /// Returns the number of data bits that can be stored in a QR code of the given version.
+        /// <para>
+        /// The returned number is after all function modules are excluded. This includes remainder bits,
+        /// so it might not be a multiple of 8. The result is in the range [208, 29648].
+        /// </para>
+        /// </summary>
         private static int GetNumRawDataModules(int ver)
         {
             if (ver < MinVersion || ver > MaxVersion)
@@ -986,10 +1051,16 @@ private static int GetNumRawDataModules(int ver)
         }
 
 
-        // Returns the number of 8-bit data (i.e. not error correction) codewords contained in any
-        // QR code of the given version number and error correction level, with remainder bits discarded.
-        // This stateless pure function could be implemented as a (40*4)-cell lookup table.
-        internal static int GetNumDataCodewords(int ver, Ecc ecl)
+        /// <summary>
+        /// Returns the number of 8-bit data codewords contained in a QR code of the given version number and error correction level.
+        /// <para>
+        /// The result is the net data capacity, without error correction data, and after discarding remainder bits.
+        /// </para>
+        /// </summary>
+        /// <param name="ver">The version number.</param>
+        /// <param name="ecl">The error correction level.</param>
+        /// <returns>The number of codewords.</returns>
+        public static int GetNumDataCodewords(int ver, Ecc ecl)
         {
             return GetNumRawDataModules(ver) / 8
                 - EccCodewordsPerBlock[ecl.Ordinal, ver]

QrCodeGenerator/QrSegment.cs

@@ -87,6 +87,48 @@ public static QrSegment MakeBytes(byte[] data)
         }
 
 
+        /// <summary>
+        /// Creates a segment representing the specified binary data
+        /// encoded in byte mode. All input byte arrays are acceptable.
+        /// <para>
+        /// Any text string can be converted to UTF-8 bytes (using <c>Encoding.UTF8.GetBytes(str)</c>)
+        /// and encoded as a byte mode segment.
+        /// </para>
+        /// </summary>
+        /// <param name="data">The binary data to encode.</param>
+        /// <returns>The created segment containing the specified data.</returns>
+        /// <exception cref="ArgumentNullException"><c>data</c> is <c>null</c>.</exception>
+        public static QrSegment MakeBytes(ArraySegment<byte> data)
+        {
+            Objects.RequireNonNull(data);
+            var ba = new BitArray(0);
+            foreach (var b in data)
+            {
+                ba.AppendBits(b, 8);
+            }
+
+            return new QrSegment(Mode.Byte, data.Count, ba);
+        }
+
+
+        /// <summary>
+        /// Creates a segment for the structured append header.
+        /// </summary>
+        /// <param name="parity">The parity value.</param>
+        /// <param name="position">The position of the code within the sequence of codes (1 based).</param>
+        /// <param name="total">The total number of codes in the sequence of codes.</param>
+        /// <returns>The created segment containing the specified header.</returns>
+        /// <exception cref="ArgumentNullException"><c>data</c> is <c>null</c>.</exception>
+        private static QrSegment MakeStructuredAppend(byte parity, int position, int total)
+        {
+            var bitArray = new BitArray(0);
+            bitArray.AppendBits((uint)position - 1, 4);
+            bitArray.AppendBits((uint)total - 1, 4);
+            bitArray.AppendBits(parity, 8);
+            return new QrSegment(Mode.StructuredAppend, 0, bitArray);
+        }
+
+
         /// <summary>
         /// Creates a segment representing the specified string of decimal digits.
         /// The segment is encoded in numeric mode.
@@ -195,6 +237,77 @@ public static List<QrSegment> MakeSegments(string text)
         }
 
 
+        /// <summary>
+        /// Creates the segments represeting the specified binary data,
+        /// split into multiple QR codes (Structured Append).
+        /// <para>
+        /// The outer list represents the series of QR codes to be created.
+        /// The inner lists contains the QR segments for each QR code.
+        /// Each inner list contains at least two segments: the structured append segment and the binary data.
+        /// </para>
+        /// <para>
+        /// The data is split into slices of similar size.
+        /// </para>
+        /// <para>
+        /// If <paramref name="considerUtf8Boundaries"/> is set to <c>true</c>, the provided data is interpreted
+        /// as UTF-8 encoded text and the data is split only at UTF-8 character boundaries, i.e. no split occurs
+        /// in the middle of a multi-byte UTF-8 character sequence.
+        /// </para>
+        /// <para>
+        /// The structured append segment specifies the number of QR codes (0-15), the position within
+        /// those (0-15) and a parity which needs to be the same for all.
+        /// </para>
+        /// </summary>
+        /// <param name="data">The binary data to encode in multiple QR codes</param>
+        /// <param name="numberOfCodes">The number of codes to create.</param>
+        /// <param name="considerUtf8Boundaries">If set to <c>true</c>, splits are made only at UTF-8 character boundaries.</param>
+        /// <returns>A list of list of QR segments.</returns>
+        public static List<List<QrSegment>> MakeStructuredAppendSegments(byte[] data, int numberOfCodes, bool considerUtf8Boundaries = false)
+        {
+            var result = new List<List<QrSegment>>();
+
+            byte parity = 0;
+            foreach (var val in data)
+            {
+                parity ^= (byte)(val >> 8);
+            }
+
+            var startOfSlice = 0;
+            var length = (long)data.Length;
+            for (int position = 1; position <= numberOfCodes; position += 1)
+            {
+                var endOfSlice = (int)(length * position / numberOfCodes);
+                if (considerUtf8Boundaries)
+                {
+                    endOfSlice = NextCharacterBoundary(data, endOfSlice);
+                }
+                if (startOfSlice == endOfSlice)
+                {
+                    continue;
+                }
+
+                result.Add(new List<QrSegment>
+                {
+                    MakeStructuredAppend(parity, position, numberOfCodes),
+                    MakeBytes(new ArraySegment<byte>(data, startOfSlice, endOfSlice - startOfSlice))
+                });
+
+                startOfSlice = endOfSlice;
+            }
+
+            return result;
+        }
+
+        private static int NextCharacterBoundary(byte[] data, int startIndex)
+        {
+            while (startIndex < data.Length && (data[startIndex] & 0xC0) == 0x80)
+            {
+                startIndex += 1;
+            }
+            return startIndex;
+        }
+
+
         /// <summary>
         /// Creates a segment representing an Extended Channel Interpretation
         /// (ECI) designator with the specified assignment value.
@@ -333,9 +446,16 @@ public BitArray GetData()
         }
 
 
-        // Calculates the number of bits needed to encode the given segments at the given version.
-        // Returns a non-negative number if successful. Otherwise returns -1 if a segment has too
-        // many characters to fit its length field, or the total bits exceeds int.MaxValue.
+        /// <summary>
+        /// Calculates the number of bits needed to encode the given segments.
+        /// <para>
+        /// Returns a non-negative number if successful. Otherwise returns -1 if a segment has too
+        /// many characters to fit its length field, or the total bits exceeds int.MaxValue.
+        /// </para>
+        /// </summary>
+        /// <param name="segments">The segements.</param>
+        /// <param name="version">The version number.</param>
+        /// <returns>The number of bits, or -1.</returns>
         internal static int GetTotalBits(List<QrSegment> segments, int version)
         {
             Objects.RequireNonNull(segments);
@@ -417,6 +537,11 @@ public sealed class Mode
             /// <value>ECI encoding mode.</value>
             public static readonly Mode Eci = new Mode(0x7, 0, 0, 0);
 
+            /// <summary>
+            /// Structured append encoding mode.
+            /// </summary>
+            /// <value>Structured append encoding mode.</value>
+            public static readonly Mode StructuredAppend = new Mode(0x3, 0, 0, 0);
 
             /// <summary>
             /// Mode indicator value.