png_conform 0.1.0

data/lib/png_conform/validators/ancillary/cicp_validator.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for cICP (Coding-Independent Code Points) chunk
+      #
+      # The cICP chunk specifies color space information using MPEG/ITU-T standards.
+      # Introduced in PNG 3rd edition (ISO/IEC 15948-1:2023).
+      #
+      # Structure:
+      # - Color primaries (1 byte): ITU-T H.273 / ISO/IEC 23091-2
+      # - Transfer function (1 byte): ITU-T H.273 / ISO/IEC 23091-2
+      # - Matrix coefficients (1 byte): ITU-T H.273 / ISO/IEC 23091-2
+      # - Video full range flag (1 byte): 0 or 1
+      #
+      # Constraints:
+      # - Must contain exactly 4 bytes
+      # - Must appear before PLTE and IDAT
+      # - At most one cICP chunk allowed
+      # - Should not coexist with iCCP or sRGB chunks
+      #
+      class CicpValidator < BaseValidator
+        CHUNK_TYPE = "cICP"
+
+        # Valid color primaries codes (ITU-T H.273 / ISO/IEC 23091-2)
+        VALID_COLOR_PRIMARIES = [
+          0,   # Reserved
+          1,   # BT.709
+          2,   # Unspecified
+          4,   # BT.470M
+          5,   # BT.470BG
+          6,   # BT.601
+          7,   # SMPTE 240M
+          8,   # Generic film
+          9,   # BT.2020
+          10,  # XYZ
+          11,  # SMPTE 431
+          12,  # SMPTE 432
+          22, # EBU Tech 3213
+        ].freeze
+
+        # Valid transfer function codes (ITU-T H.273 / ISO/IEC 23091-2)
+        VALID_TRANSFER_FUNCTIONS = [
+          0,   # Reserved
+          1,   # BT.709
+          2,   # Unspecified
+          4,   # Gamma 2.2
+          5,   # Gamma 2.8
+          6,   # BT.601
+          7,   # SMPTE 240M
+          8,   # Linear
+          9,   # Logarithmic (100:1 range)
+          10,  # Logarithmic (100*sqrt(10):1 range)
+          11,  # IEC 61966-2-4
+          12,  # BT.1361
+          13,  # sRGB/sYCC
+          14,  # BT.2020 (10-bit)
+          15,  # BT.2020 (12-bit)
+          16,  # SMPTE ST 2084 (PQ)
+          17,  # SMPTE ST 428
+          18, # HLG
+        ].freeze
+
+        # Valid matrix coefficients codes (ITU-T H.273 / ISO/IEC 23091-2)
+        VALID_MATRIX_COEFFICIENTS = [
+          0,   # Identity
+          1,   # BT.709
+          2,   # Unspecified
+          4,   # FCC
+          5,   # BT.470BG
+          6,   # BT.601
+          7,   # SMPTE 240M
+          8,   # YCgCo
+          9,   # BT.2020 non-constant luminance
+          10,  # BT.2020 constant luminance
+          11,  # SMPTE 2085
+          12,  # Chromaticity-derived non-constant luminance
+          13,  # Chromaticity-derived constant luminance
+          14, # ICtCp
+        ].freeze
+
+        def validate
+          check_chunk_length
+          check_uniqueness
+          check_position
+          validate_fields if chunk.chunk_data.bytesize == 4
+          check_conflicts
+        end
+
+        private
+
+        def check_chunk_length
+          return if check_length(4)
+
+          add_error("invalid chunk length: #{chunk.chunk_data.bytesize} bytes")
+        end
+
+        def check_uniqueness
+          return unless context.seen?(CHUNK_TYPE)
+
+          add_error("multiple cICP chunks not allowed")
+        end
+
+        def check_position
+          add_error("cICP must appear before PLTE") if context.seen?("PLTE")
+
+          return unless context.seen?("IDAT")
+
+          add_error("cICP must appear before IDAT")
+        end
+
+        def validate_fields
+          data = chunk.chunk_data.bytes
+
+          validate_color_primaries(data[0])
+          validate_transfer_function(data[1])
+          validate_matrix_coefficients(data[2])
+          validate_video_full_range_flag(data[3])
+        end
+
+        def validate_color_primaries(value)
+          unless VALID_COLOR_PRIMARIES.include?(value)
+            add_error(
+              "invalid color primaries: #{value} " \
+              "(valid: #{VALID_COLOR_PRIMARIES.join(', ')})",
+            )
+          end
+
+          return unless value.zero?
+
+          add_warning("color primaries = 0 (reserved)")
+        end
+
+        def validate_transfer_function(value)
+          unless VALID_TRANSFER_FUNCTIONS.include?(value)
+            add_error(
+              "invalid transfer function: #{value} " \
+              "(valid: #{VALID_TRANSFER_FUNCTIONS.join(', ')})",
+            )
+          end
+
+          return unless value.zero?
+
+          add_warning("transfer function = 0 (reserved)")
+        end
+
+        def validate_matrix_coefficients(value)
+          unless VALID_MATRIX_COEFFICIENTS.include?(value)
+            add_error(
+              "invalid matrix coefficients: #{value} " \
+              "(valid: #{VALID_MATRIX_COEFFICIENTS.join(', ')})",
+            )
+          end
+
+          return unless value.zero? && rgb_color?
+
+          add_info(
+            "matrix coefficients = 0 (identity) is recommended for RGB",
+          )
+        end
+
+        def validate_video_full_range_flag(value)
+          return if check_enum(value, [0, 1], "video full range flag")
+
+          add_error("invalid video full range flag: #{value} (must be 0 or 1)")
+        end
+
+        def check_conflicts
+          check_iccp_conflict
+          check_srgb_conflict
+        end
+
+        def check_iccp_conflict
+          return unless context.seen?("iCCP")
+
+          add_warning(
+            "cICP should not coexist with iCCP " \
+            "(both specify color space information)",
+          )
+        end
+
+        def check_srgb_conflict
+          return unless context.seen?("sRGB")
+
+          add_warning(
+            "cICP should not coexist with sRGB " \
+            "(both specify color space information)",
+          )
+        end
+
+        def rgb_color?
+          color_type = context.retrieve(:color_type)
+          return false unless color_type
+
+          # RGB (2) or RGB with alpha (6)
+          [2, 6].include?(color_type)
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/ancillary/gama_validator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG gAMA (Image Gamma) chunk
+      #
+      # gAMA specifies the gamma of the image for proper display.
+      # The value is encoded as a 4-byte unsigned integer representing
+      # gamma times 100,000.
+      #
+      # Validation rules from PNG spec:
+      # - Must be exactly 4 bytes
+      # - Must appear before PLTE and IDAT
+      # - Only one gAMA chunk allowed
+      # - Value of 0 is invalid
+      # - Typical values: 45455 (gamma 2.2), 100000 (gamma 1.0)
+      class GamaValidator < BaseValidator
+        # Common gamma values (gamma * 100000)
+        GAMMA_2_2 = 45_455  # Standard display gamma
+        GAMMA_1_0 = 100_000 # Linear gamma
+
+        # Validate gAMA chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_length(4)
+          return false unless check_position
+          return false unless check_uniqueness
+          return false unless check_value
+
+          store_gamma_info
+          true
+        end
+
+        private
+
+        # Check gAMA position relative to other chunks
+        def check_position
+          valid = true
+
+          # gAMA should appear before PLTE and IDAT
+          if context.seen?("PLTE")
+            add_error("gAMA chunk after PLTE (should be before)")
+            valid = false
+          end
+
+          if context.seen?("IDAT")
+            add_error("gAMA chunk after IDAT (must be before)")
+            valid = false
+          end
+
+          valid
+        end
+
+        # Check that only one gAMA chunk is present
+        def check_uniqueness
+          if context.seen?("gAMA")
+            add_error("duplicate gAMA chunk")
+            return false
+          end
+          true
+        end
+
+        # Check gamma value
+        def check_value
+          gamma = chunk.chunk_data.unpack1("N")
+
+          if gamma.zero?
+            add_error("invalid gAMA value (0)")
+            return false
+          end
+
+          # Check sRGB interaction
+          if context.seen?("sRGB") && gamma != GAMMA_2_2
+            add_warning("gAMA value #{gamma} with sRGB present (should be #{GAMMA_2_2} for gamma 2.2)")
+          end
+
+          # Info about common values
+          case gamma
+          when GAMMA_2_2
+            add_info("gAMA: 2.2 (standard display gamma)")
+          when GAMMA_1_0
+            add_info("gAMA: 1.0 (linear)")
+          else
+            actual_gamma = gamma / 100_000.0
+            add_info("gAMA: #{format('%.5f', actual_gamma)}")
+          end
+
+          true
+        end
+
+        # Store gamma information in context
+        def store_gamma_info
+          gamma = chunk.chunk_data.unpack1("N")
+          context.store(:gamma, gamma)
+          context.store(:gamma_value, gamma / 100_000.0)
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/ancillary/hist_validator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG hIST (Palette Histogram) chunk
+      #
+      # hIST provides the approximate usage frequency of each palette entry:
+      # - One 2-byte value per palette entry
+      # - Values are proportional, not absolute
+      #
+      # Validation rules from PNG spec:
+      # - Must appear after PLTE chunk
+      # - Must appear before first IDAT chunk
+      # - Must have exactly 2 bytes per palette entry
+      # - Only valid for color type 3 (indexed color)
+      # - Only one hIST chunk allowed
+      class HistValidator < BaseValidator
+        # Validate hIST chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_uniqueness
+          return false unless check_color_type
+          return false unless check_palette_exists
+          return false unless check_position
+          return false unless check_length
+
+          store_histogram_info
+          true
+        end
+
+        private
+
+        # Check that only one hIST chunk exists
+        def check_uniqueness
+          if context.retrieve(:has_histogram)
+            add_error("Multiple hIST chunks (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that color type is indexed (3)
+        def check_color_type
+          color_type = context.retrieve(:color_type)
+
+          unless color_type
+            add_error("hIST chunk before IHDR")
+            return false
+          end
+
+          unless color_type == 3
+            add_error("hIST chunk invalid for color type #{color_type} " \
+                      "(only valid for indexed color)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that PLTE chunk exists
+        def check_palette_exists
+          has_palette = context.retrieve(:has_palette)
+
+          unless has_palette
+            add_error("hIST chunk without preceding PLTE chunk")
+            return false
+          end
+
+          true
+        end
+
+        # Check that hIST appears after PLTE but before IDAT
+        def check_position
+          # Must come after PLTE
+          unless context.seen?("PLTE")
+            add_error("hIST chunk before PLTE chunk")
+            return false
+          end
+
+          # Must come before IDAT
+          if context.seen?("IDAT")
+            add_error("hIST chunk after IDAT chunk")
+            return false
+          end
+
+          true
+        end
+
+        # Check that length matches palette size
+        def check_length
+          palette_entries = context.retrieve(:palette_entries)
+          expected_length = palette_entries * 2
+          actual_length = chunk.chunk_data.length
+
+          unless actual_length == expected_length
+            add_error("hIST chunk wrong length (#{actual_length} bytes, " \
+                      "expected #{expected_length} for #{palette_entries} " \
+                      "palette entries)")
+            return false
+          end
+
+          true
+        end
+
+        # Store histogram information in context
+        def store_histogram_info
+          data = chunk.chunk_data
+          palette_entries = context.retrieve(:palette_entries)
+
+          # Read frequency values (2 bytes each, big-endian)
+          frequencies = []
+          (0...palette_entries).each do |i|
+            offset = i * 2
+            freq = (data[offset].ord << 8) | data[offset + 1].ord
+            frequencies << freq
+          end
+
+          # Store in context
+          context.store(:has_histogram, true)
+          context.store(:histogram_frequencies, frequencies)
+
+          # Add info about histogram
+          total = frequencies.sum
+          if total.zero?
+            add_info("hIST: #{palette_entries} entries (all zero)")
+          else
+            # Find most and least used colors
+            max_freq = frequencies.max
+            max_idx = frequencies.index(max_freq)
+            min_freq = frequencies.reject(&:zero?).min || 0
+            min_idx = frequencies.index(min_freq)
+
+            add_info("hIST: #{palette_entries} palette entries, " \
+                     "most used: index #{max_idx} (#{max_freq}), " \
+                     "least used: index #{min_idx} (#{min_freq})")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/ancillary/iccp_validator.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+require "zlib"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG iCCP (Embedded ICC Profile) chunk
+      #
+      # iCCP contains an ICC color profile:
+      # - Profile name (1-79 bytes, Latin-1)
+      # - Null separator (1 byte)
+      # - Compression method (1 byte, must be 0)
+      # - Compressed profile (deflate compressed ICC profile)
+      #
+      # Validation rules from PNG spec:
+      # - Profile name must be 1-79 characters, Latin-1 printable
+      # - Profile name must not have leading/trailing/consecutive spaces
+      # - Compression method must be 0 (deflate)
+      # - Profile must be successfully decompressible
+      # - Must appear before PLTE and IDAT chunks
+      # - Only one iCCP chunk allowed
+      # - Should not appear with sRGB chunk (warns if both present)
+      class IccpValidator < BaseValidator
+        # Maximum profile name length
+        MAX_PROFILE_NAME_LENGTH = 79
+
+        # Latin-1 printable characters (space to tilde + high ASCII)
+        PRINTABLE_LATIN1 = (32..126).to_a + (161..255).to_a
+
+        # Valid compression method
+        COMPRESSION_DEFLATE = 0
+
+        # ICC profile signature (first 4 bytes of decompressed data)
+        ICC_SIGNATURE_OFFSET = 36
+        ICC_SIGNATURE = "acsp"
+
+        # Validate iCCP chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_uniqueness
+          return false unless check_position
+          return false unless check_structure
+          return false unless check_profile_name
+          return false unless check_compression_method
+          return false unless check_decompression
+
+          check_srgb_conflict
+
+          store_profile_info
+          true
+        end
+
+        private
+
+        # Check that only one iCCP chunk exists
+        def check_uniqueness
+          if context.retrieve(:has_icc_profile)
+            add_error("Multiple iCCP chunks (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that iCCP appears before PLTE and IDAT
+        def check_position
+          # Must come before PLTE
+          if context.seen?("PLTE")
+            add_error("iCCP chunk after PLTE chunk")
+            return false
+          end
+
+          # Must come before IDAT
+          if context.seen?("IDAT")
+            add_error("iCCP chunk after IDAT chunk")
+            return false
+          end
+
+          true
+        end
+
+        # Check iCCP chunk structure
+        def check_structure
+          data = chunk.chunk_data
+
+          # Must contain at least name + null + compression method
+          if data.length < 3
+            add_error("iCCP chunk too short (minimum 3 bytes)")
+            return false
+          end
+
+          # Must contain null separator
+          null_pos = data.index("\0")
+          unless null_pos
+            add_error("iCCP chunk missing null separator")
+            return false
+          end
+
+          true
+        end
+
+        # Check profile name validity
+        def check_profile_name
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          profile_name = data[0, null_pos]
+
+          # Check profile name length
+          if profile_name.empty?
+            add_error("iCCP chunk has empty profile name")
+            return false
+          end
+
+          if profile_name.length > MAX_PROFILE_NAME_LENGTH
+            add_error("iCCP profile name too long (#{profile_name.length}, " \
+                      "max #{MAX_PROFILE_NAME_LENGTH})")
+            return false
+          end
+
+          # Check for Latin-1 printable characters
+          profile_name.bytes.each do |byte|
+            next if PRINTABLE_LATIN1.include?(byte)
+
+            add_error("iCCP profile name contains non-printable " \
+                      "character (0x#{byte.to_s(16)})")
+            return false
+          end
+
+          # Check for leading/trailing spaces
+          if profile_name.start_with?(" ")
+            add_error("iCCP profile name has leading space")
+            return false
+          end
+
+          if profile_name.end_with?(" ")
+            add_error("iCCP profile name has trailing space")
+            return false
+          end
+
+          # Check for consecutive spaces
+          if profile_name.include?("  ")
+            add_error("iCCP profile name has consecutive spaces")
+            return false
+          end
+
+          true
+        end
+
+        # Check compression method
+        def check_compression_method
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          compression_method = data[null_pos + 1].ord
+
+          unless compression_method == COMPRESSION_DEFLATE
+            add_error("iCCP invalid compression method " \
+                      "(#{compression_method}, must be 0)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that profile data can be decompressed and validate ICC
+        # signature
+        def check_decompression
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          compressed_data = data[(null_pos + 2)..] || ""
+
+          # Try to decompress
+          begin
+            decompressed = Zlib::Inflate.inflate(compressed_data)
+
+            # Check minimum ICC profile size (128 bytes header)
+            if decompressed.length < 128
+              add_error("iCCP decompressed profile too short " \
+                        "(#{decompressed.length} bytes, minimum 128)")
+              return false
+            end
+
+            # Verify ICC signature if enough data
+            if decompressed.length >= ICC_SIGNATURE_OFFSET + 4
+              signature = decompressed[ICC_SIGNATURE_OFFSET, 4]
+              unless signature == ICC_SIGNATURE
+                add_warning("iCCP profile signature mismatch " \
+                            "(expected 'acsp', got '#{signature}')")
+              end
+            end
+          rescue Zlib::Error => e
+            add_error("iCCP decompression failed: #{e.message}")
+            return false
+          end
+
+          true
+        end
+
+        # Check for conflict with sRGB chunk
+        def check_srgb_conflict
+          if context.retrieve(:uses_srgb)
+            add_warning("iCCP chunk present with sRGB chunk " \
+                        "(iCCP takes precedence)")
+          end
+
+          true
+        end
+
+        # Store ICC profile information in context
+        def store_profile_info
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          profile_name = data[0, null_pos]
+          compressed_data = data[(null_pos + 2)..] || ""
+
+          # Decompress profile
+          decompressed = Zlib::Inflate.inflate(compressed_data)
+
+          # Store in context
+          context.store(:has_icc_profile, true)
+          context.store(:icc_profile_name, profile_name)
+          context.store(:icc_profile_size, decompressed.length)
+
+          # Add info about the ICC profile
+          compression_ratio = if compressed_data.length.positive?
+                                (decompressed.length.to_f /
+                                 compressed_data.length).round(2)
+                              else
+                                0
+                              end
+
+          add_info("iCCP: \"#{profile_name}\" " \
+                   "(#{decompressed.length} bytes, " \
+                   "compressed from #{compressed_data.length} bytes, " \
+                   "ratio #{compression_ratio}:1)")
+        end
+      end
+    end
+  end
+end