Separate class for fixed patterns

Author: manuelbl

CONTEXT.md

@@ -0,0 +1,62 @@
+# QrCodeGenerator Context
+
+Domain language for the QR code generation library. These are the terms specific
+to QR code structure and this library's layout pipeline — use them consistently in
+code, comments, and discussion.
+
+## Language
+
+**Module**:
+A single pixel of a QR code (dark or light); the unit the standard counts by.
+_Avoid_: pixel (reserve "pixel" for rendered output), cell.
+
+**Fixed patterns**:
+The modules placed identically for a given version regardless of payload — finder
+patterns, separators, timing patterns, alignment patterns, and version information —
+together with the reserved area for format information.
+_Avoid_: function patterns (the ISO/IEC 18004 term; we say "fixed patterns").
+
+**Footprint**:
+The area a fixed pattern occupies, independent of which modules within it are dark.
+A footprint is reserved even where its modules are light (e.g. separators, the light
+rings of a finder, format/version `0` bits).
+
+**Reserved modules**:
+The union of all fixed-pattern footprints — every module the payload must not use.
+
+**Payload-area map**:
+The complement of the reserved modules: the modules the payload zig-zag is allowed
+to fill. This is what `GetDataMask` returns.
+_Avoid_: "data mask" — see Flagged ambiguities.
+
+**Mask pattern**:
+One of the 8 XOR patterns (index 0–7) applied to the payload area and chosen by
+lowest penalty score. Exposed as `QrCode.Mask`.
+
+## Relationships
+
+- A **version** (1–40) fully determines the **fixed patterns** and therefore the
+  **reserved modules** and the **payload-area map**.
+- The **reserved modules** are the union of every fixed-pattern **footprint**;
+  the **payload-area map** is their complement.
+- Every dark **module** drawn by a fixed pattern lies within the **reserved modules**
+  (the load-bearing invariant: drawn ⊆ reserved).
+- A **mask pattern** is XORed only over the **payload-area map**, never over
+  **reserved modules**.
+
+## Example dialogue
+
+> **Dev:** "If I move an alignment pattern, do I update the drawn matrix and the
+> reserved modules separately?"
+> **Domain expert:** "No — they're two views of the same **fixed patterns**. One walk
+> emits both: it stamps the dark **modules** and reserves the **footprint** in the same
+> place. You can't infer reserved from drawn, because a footprint reserves light modules
+> too."
+
+## Flagged ambiguities
+
+- **"data mask"** was used for two distinct things: (1) the **payload-area map**
+  returned by `GetDataMask` / `DataMaskCache`, and (2) a **mask pattern** (the 8 XOR
+  patterns), as in `GetDataMaskPattern`. Resolved: prefer **payload-area map** for (1)
+  and **mask pattern** for (2). The existing `GetDataMask` method name is retained for
+  compatibility but denotes the payload-area map.

QrCodeGenerator/FixedPatterns.cs

@@ -0,0 +1,303 @@
+/*
+ * QR code generator library (.NET)
+ *
+ * Copyright (c) Manuel Bleichenbacher (MIT License)
+ * https://github.com/manuelbl/QrCodeGenerator
+ */
+
+using System.Collections.Concurrent;
+
+namespace Net.Codecrete.QrCodeGenerator
+{
+    /// <summary>
+    /// Single source of truth for the fixed-pattern geometry of a QR code version.
+    /// <para>
+    /// The fixed patterns are the modules placed identically for a given version
+    /// regardless of payload: finder patterns, separators, timing patterns,
+    /// alignment patterns and version information, plus the reserved area for the
+    /// format information.
+    /// </para>
+    /// <para>
+    /// <see cref="BuildFixedPatterns"/> produces two views of the same geometry in a
+    /// single walk:
+    /// </para>
+    /// <list type="bullet">
+    /// <item><c>drawn</c> — the actual dark/light modules of the fixed patterns.</item>
+    /// <item><c>reserved</c> — the union of all fixed-pattern footprints, i.e. every
+    /// module the payload must not use. A footprint is reserved even where its modules
+    /// are light (separators, the light rings of a finder, format/version <c>0</c> bits),
+    /// so the reserved view cannot be derived from the drawn one.</item>
+    /// </list>
+    /// <para>
+    /// The format information is reserve-only here; its bits depend on the error
+    /// correction level and the chosen mask pattern and are drawn later by
+    /// <see cref="QrCodeBuilder.DrawFormatInformation(BitMatrix, int, int)"/>.
+    /// </para>
+    /// </summary>
+    internal static class FixedPatterns
+    {
+        #region Caches
+
+        // version -> (drawn modules, payload-area map). The payload-area map is the
+        // inverted reserved mask (the modules the payload zig-zag may fill). Both are
+        // computed by a single BuildFixedPatterns walk and cached together.
+        // The cached instances are shared and must not be mutated (CreateWithFixedPatterns
+        // hands out a Copy; GetDataMask's result is treated as read-only by callers).
+        private static readonly ConcurrentDictionary<int, (BitMatrix Drawn, BitMatrix DataMask)> Cache
+            = new ConcurrentDictionary<int, (BitMatrix, BitMatrix)>();
+
+        private static (BitMatrix Drawn, BitMatrix DataMask) GetCached(int version)
+        {
+            return Cache.GetOrAdd(version, ComputeCached);
+        }
+
+        private static (BitMatrix Drawn, BitMatrix DataMask) ComputeCached(int version)
+        {
+            var (drawn, reserved) = BuildFixedPatterns(version);
+            // Turn the reserved mask into the payload-area map (where data goes).
+            reserved.Invert();
+            return (drawn, reserved);
+        }
+
+        #endregion
+
+        #region Accessors
+
+        /// <summary>
+        /// Creates a <see cref="BitMatrix"/> for the given version with the fixed
+        /// patterns (finder, timing, alignment, version) already drawn.
+        /// </summary>
+        /// <param name="version">The QR code version.</param>
+        /// <returns>A new (mutable) <see cref="BitMatrix"/> instance.</returns>
+        internal static BitMatrix CreateWithFixedPatterns(int version)
+        {
+            return GetCached(version).Drawn.Copy();
+        }
+
+        /// <summary>
+        /// Returns the payload-area map for the given version: a <see cref="BitMatrix"/>
+        /// with all bits set where payload data goes (the complement of the reserved
+        /// modules).
+        /// <para>
+        /// The returned matrix is shared and cached. Callers must not mutate it.
+        /// </para>
+        /// </summary>
+        /// <param name="version">The QR code version.</param>
+        /// <returns>A shared <see cref="BitMatrix"/> instance.</returns>
+        internal static BitMatrix GetDataMask(int version)
+        {
+            return GetCached(version).DataMask;
+        }
+
+        #endregion
+
+        #region Single walk
+
+        /// <summary>
+        /// Builds the fixed-pattern geometry for the given version in a single walk.
+        /// <para>
+        /// Each region stamps its dark modules into <c>drawn</c> and reserves its
+        /// footprint into <c>reserved</c> in the same place, so the two views cannot
+        /// drift apart. The drawn invariant <c>drawn AND NOT reserved == 0</c> holds
+        /// by construction.
+        /// </para>
+        /// <para>
+        /// Draw order is load-bearing: alignment patterns are drawn after the timing
+        /// patterns so they overwrite the timing line where the two overlap.
+        /// </para>
+        /// </summary>
+        /// <param name="version">The QR code version.</param>
+        /// <returns>The drawn modules and the reserved-module mask.</returns>
+        internal static (BitMatrix Drawn, BitMatrix Reserved) BuildFixedPatterns(int version)
+        {
+            var size = QrCodeBuilder.GetSize(version);
+            var drawn = new BitMatrix(size);
+            var reserved = new BitMatrix(size);
+
+            // Single asymmetric dark module
+            drawn.Set(8, size - 8, true);
+            reserved.Set(8, size - 8, true);
+
+            // Format information (reserve-only; bits drawn later, ecc/mask-dependent)
+            ReserveFormatInformation(reserved);
+
+            // Version information (versions 7 and up)
+            DrawVersionInformation(drawn, version);
+            ReserveVersionInformation(reserved, version);
+
+            // Finder patterns and adjacent separators (footprint 8x8, pattern 7x7)
+            DrawFinderPattern(drawn, 0, 0);
+            DrawFinderPattern(drawn, size - 7, 0);
+            DrawFinderPattern(drawn, 0, size - 7);
+            reserved.FillRect(0, 0, 8, 8);
+            reserved.FillRect(size - 8, 0, 8, 8);
+            reserved.FillRect(0, size - 8, 8, 8);
+
+            // Timing patterns
+            DrawTimingPattern(drawn);
+            reserved.FillRect(8, 6, size - 16, 1);
+            reserved.FillRect(6, 8, 1, size - 16);
+
+            // Alignment patterns (drawn after timing so they overwrite it on overlap)
+            DrawAndReserveAlignmentPatterns(drawn, reserved, version);
+
+            return (drawn, reserved);
+        }
+
+        #endregion
+
+        #region Finder patterns
+
+        private static void DrawFinderPattern(BitMatrix modules, int x, int y)
+        {
+            for (var i = 0; i < 7; i += 1)
+            {
+                modules.Set(x + i, y,     true);
+                modules.Set(x + i, y + 6, true);
+            }
+
+            for (var i = 1; i < 6; i += 1)
+            {
+                modules.Set(x,     y + i, true);
+                modules.Set(x + 1, y + i, false);
+                modules.Set(x + 5, y + i, false);
+                modules.Set(x + 6, y + i, true);
+            }
+
+            for (var i = 2; i < 5; i += 1)
+            {
+                modules.Set(x + i, y + 1, false);
+                modules.Set(x + i, y + 5, false);
+            }
+
+            for (var i = 2; i < 5; i += 1)
+            {
+                modules.Set(x + i, y + 2, true);
+                modules.Set(x + i, y + 3, true);
+                modules.Set(x + i, y + 4, true);
+            }
+        }
+
+        #endregion
+
+        #region Alignment patterns
+
+        private static void DrawAndReserveAlignmentPatterns(BitMatrix drawn, BitMatrix reserved, int version)
+        {
+            if (version == 1)
+            {
+                // no alignment patterns in version 1
+                return;
+            }
+
+            var positions = QrCodeBuilder.GetAlignmentPatternPosition(version);
+            var numPositions = positions.Length;
+
+            for (var x = 0; x < numPositions; x += 1)
+            {
+                for (var y = 0; y < numPositions; y += 1)
+                {
+                    if ((x == 0 && y == 0) || (x == numPositions - 1 && y == 0) || (x == 0 && y == numPositions - 1))
+                    {
+                        // no alignment patterns near the 3 finder patterns
+                        continue;
+                    }
+
+                    reserved.FillRect(positions[x] - 2, positions[y] - 2, 5, 5);
+                    DrawAlignmentPattern(drawn, positions[x], positions[y]);
+                }
+            }
+        }
+
+        private static void DrawAlignmentPattern(BitMatrix modules, int x, int y)
+        {
+            for (var i = -2; i <= 2; i += 1)
+            {
+                modules.Set(x + i, y - 2, true);
+                modules.Set(x + i, y + 2, true);
+            }
+
+            for (var i = -1; i <= 1; i += 1)
+            {
+                modules.Set(x - 2, y + i, true);
+                modules.Set(x + 2, y + i, true);
+            }
+
+            modules.Set(x, y, true);
+        }
+
+        #endregion
+
+        #region Timing patterns
+
+        private static void DrawTimingPattern(BitMatrix modules)
+        {
+            var size = modules.Size;
+            for (var x = 8; x < size - 8; x += 1)
+            {
+                var isDark = ((x + 1) & 1) != 0;
+                modules.Set(x, 6, isDark);
+                modules.Set(6, x, isDark);
+            }
+        }
+
+        #endregion
+
+        #region Version information
+
+        private static void ReserveVersionInformation(BitMatrix reserved, int version)
+        {
+            if (version < 7)
+            {
+                // no version information for versions 1-6
+                return;
+            }
+
+            var size = reserved.Size;
+            // left bottom corner
+            reserved.FillRect(0, size - 11, 6, 3);
+
+            // top right corner
+            reserved.FillRect(size - 11, 0, 3, 6);
+        }
+
+        private static void DrawVersionInformation(BitMatrix modules, int version)
+        {
+            if (version < 7)
+            {
+                // no version information for versions 1-6
+                return;
+            }
+
+            var size = modules.Size;
+            var bits = QrCodeBuilder.GetVersionInformationBits(version);
+
+            for (var bit = 0; bit < 18; bit += 1)
+            {
+                var isDark = (bits & (1 << bit)) != 0;
+                var x = bit / 3;
+                var y = bit % 3;
+
+                // left bottom corner
+                modules.Set(x, size - 11 + y, isDark);
+
+                // top right corner
+                modules.Set(size - 11 + y, x, isDark);
+            }
+        }
+
+        #endregion
+
+        #region Format information
+
+        private static void ReserveFormatInformation(BitMatrix reserved)
+        {
+            reserved.FillRect(8, 0, 1, 9);
+            reserved.FillRect(0, 8, 8, 1);
+            reserved.FillRect(reserved.Size - 8, 8, 8, 1);
+            reserved.FillRect(8, reserved.Size - 7, 1, 7);
+        }
+
+        #endregion
+    }
+}