png_conform 0.1.0

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

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+require "zlib"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG iTXt (International Textual Data) chunk
+      #
+      # iTXt contains international textual information with UTF-8 encoding:
+      # - Keyword (1-79 bytes, Latin-1)
+      # - Null separator (1 byte)
+      # - Compression flag (1 byte, 0=uncompressed, 1=compressed)
+      # - Compression method (1 byte, must be 0 if compressed)
+      # - Language tag (0+ bytes, ASCII)
+      # - Null separator (1 byte)
+      # - Translated keyword (0+ bytes, UTF-8)
+      # - Null separator (1 byte)
+      # - Text (0+ bytes, UTF-8, possibly compressed)
+      #
+      # Validation rules from PNG spec:
+      # - Keyword must be 1-79 characters, Latin-1 printable
+      # - Keyword must not have leading/trailing/consecutive spaces
+      # - Compression flag must be 0 or 1
+      # - Compression method must be 0 if compressed
+      # - Language tag must be ASCII (RFC 3066 format)
+      # - Translated keyword and text must be valid UTF-8
+      # - Multiple iTXt chunks allowed with different keywords
+      class ItxtValidator < BaseValidator
+        # Maximum keyword length
+        MAX_KEYWORD_LENGTH = 79
+
+        # Latin-1 printable characters (space to tilde + high ASCII)
+        PRINTABLE_LATIN1 = (32..126).to_a + (161..255).to_a
+
+        # Valid compression flag values
+        UNCOMPRESSED = 0
+        COMPRESSED = 1
+
+        # Valid compression method
+        COMPRESSION_DEFLATE = 0
+
+        # Validate iTXt chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_structure
+          return false unless check_keyword
+          return false unless check_compression_flags
+          return false unless check_language_tag
+          return false unless check_utf8_fields
+
+          return false if compressed? && compressed? && !check_decompression
+
+          store_text_info
+          true
+        end
+
+        private
+
+        # Check iTXt chunk structure
+        def check_structure
+          data = chunk.chunk_data
+
+          # Must contain at least keyword + 3 nulls + flags
+          if data.length < 5
+            add_error("iTXt chunk too short (minimum 5 bytes)")
+            return false
+          end
+
+          # Must contain three null separators
+          nulls = data.bytes.each_index.select { |i| data[i] == "\0" }
+          if nulls.length < 3
+            add_error("iTXt chunk missing null separators " \
+                      "(found #{nulls.length}, need 3)")
+            return false
+          end
+
+          true
+        end
+
+        # Check keyword validity
+        def check_keyword
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          keyword = data[0, null_pos]
+
+          # Check keyword length
+          if keyword.empty?
+            add_error("iTXt chunk has empty keyword")
+            return false
+          end
+
+          if keyword.length > MAX_KEYWORD_LENGTH
+            add_error("iTXt keyword too long (#{keyword.length}, " \
+                      "max #{MAX_KEYWORD_LENGTH})")
+            return false
+          end
+
+          # Check for Latin-1 printable characters
+          keyword.bytes.each do |byte|
+            next if PRINTABLE_LATIN1.include?(byte)
+
+            add_error("iTXt keyword contains non-printable character " \
+                      "(0x#{byte.to_s(16)})")
+            return false
+          end
+
+          # Check for leading/trailing spaces
+          if keyword.start_with?(" ")
+            add_error("iTXt keyword has leading space")
+            return false
+          end
+
+          if keyword.end_with?(" ")
+            add_error("iTXt keyword has trailing space")
+            return false
+          end
+
+          # Check for consecutive spaces
+          if keyword.include?("  ")
+            add_error("iTXt keyword has consecutive spaces")
+            return false
+          end
+
+          true
+        end
+
+        # Check compression flag and method
+        def check_compression_flags
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          compression_flag = data[null_pos + 1].ord
+          compression_method = data[null_pos + 2].ord
+
+          unless [UNCOMPRESSED, COMPRESSED].include?(compression_flag)
+            add_error("iTXt invalid compression flag " \
+                      "(#{compression_flag}, must be 0 or 1)")
+            return false
+          end
+
+          if compression_flag == COMPRESSED &&
+              compression_method != COMPRESSION_DEFLATE
+            add_error("iTXt invalid compression method " \
+                      "(#{compression_method}, must be 0 when compressed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check language tag (should be ASCII, RFC 3066 format)
+        def check_language_tag
+          data = chunk.chunk_data
+          first_null = data.index("\0")
+          second_null = data.index("\0", first_null + 3)
+          lang_tag = data[(first_null + 3)...second_null]
+
+          # Language tag can be empty
+          return true if lang_tag.empty?
+
+          # Must be ASCII (0-127)
+          lang_tag.bytes.each do |byte|
+            next unless byte > 127
+
+            add_error("iTXt language tag contains non-ASCII character " \
+                      "(0x#{byte.to_s(16)})")
+            return false
+          end
+
+          true
+        end
+
+        # Check UTF-8 validity of translated keyword and text
+        def check_utf8_fields
+          data = chunk.chunk_data
+          first_null = data.index("\0")
+          second_null = data.index("\0", first_null + 3)
+          third_null = data.index("\0", second_null + 1)
+
+          # Translated keyword
+          translated_keyword = data[(second_null + 1)...third_null]
+          unless valid_utf8?(translated_keyword)
+            add_error("iTXt translated keyword is not valid UTF-8")
+            return false
+          end
+
+          # Text field (may be compressed)
+          text_data = data[(third_null + 1)..] || ""
+          if !compressed? && !valid_utf8?(text_data)
+            add_error("iTXt text is not valid UTF-8")
+            return false
+          end
+
+          true
+        end
+
+        # Check that compressed data can be decompressed and is valid UTF-8
+        def check_decompression
+          data = chunk.chunk_data
+          first_null = data.index("\0")
+          third_null = data.index("\0", data.index("\0", first_null + 3) + 1)
+          compressed_data = data[(third_null + 1)..] || ""
+
+          # Try to decompress
+          begin
+            decompressed = Zlib::Inflate.inflate(compressed_data)
+            unless valid_utf8?(decompressed)
+              add_error("iTXt decompressed text is not valid UTF-8")
+              return false
+            end
+          rescue Zlib::Error => e
+            add_error("iTXt decompression failed: #{e.message}")
+            return false
+          end
+
+          true
+        end
+
+        # Check if compression is enabled
+        def compressed?
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          data[null_pos + 1].ord == COMPRESSED
+        end
+
+        # Validate UTF-8 encoding
+        def valid_utf8?(str)
+          str.force_encoding("UTF-8").valid_encoding?
+        end
+
+        # Store text information in context
+        def store_text_info
+          data = chunk.chunk_data
+          first_null = data.index("\0")
+          second_null = data.index("\0", first_null + 3)
+          third_null = data.index("\0", second_null + 1)
+
+          keyword = data[0, first_null]
+          lang_tag = data[(first_null + 3)...second_null]
+          translated_keyword = data[(second_null + 1)...third_null]
+          text_data = data[(third_null + 1)..] || ""
+
+          # Decompress if needed
+          if compressed?
+            text = Zlib::Inflate.inflate(text_data)
+            comp_info = " (compressed from #{text_data.length} bytes)"
+          else
+            text = text_data
+            comp_info = ""
+          end
+
+          # Force UTF-8 encoding
+          text.force_encoding("UTF-8")
+          translated_keyword.force_encoding("UTF-8")
+
+          # Store in context (allow multiple text chunks)
+          texts = context.retrieve(:text_chunks) || []
+          texts << {
+            keyword: keyword,
+            text: text,
+            compressed: compressed?,
+            language: lang_tag.empty? ? nil : lang_tag,
+            translated_keyword: translated_keyword.empty? ? nil : translated_keyword,
+          }
+          context.store(:text_chunks, texts)
+
+          # Add info about the text chunk
+          text_preview = text.length > 40 ? "#{text[0, 40]}..." : text
+          lang_info = lang_tag.empty? ? "" : " [#{lang_tag}]"
+          trans_info = translated_keyword.empty? ? "" : " (#{translated_keyword})"
+          add_info("iTXt: #{keyword}#{lang_info}#{trans_info} = " \
+                   "\"#{text_preview}\"#{comp_info}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for mDCv (Mastering Display Color Volume) chunk
+      #
+      # The mDCv chunk specifies the color volume of the mastering display
+      # used for content creation. Introduced in PNG 3rd edition for HDR support.
+      #
+      # Structure:
+      # - Display primaries (12 bytes): 6 x uint16 (x,y for R,G,B)
+      #   Each coordinate is in 0.00002 units (range 0-50000 = 0.0-1.0)
+      # - White point (4 bytes): 2 x uint16 (x,y)
+      #   Each coordinate is in 0.00002 units
+      # - Maximum luminance (4 bytes): uint32
+      #   In 0.0001 cd/m² units
+      # - Minimum luminance (4 bytes): uint32
+      #   In 0.0001 cd/m² units
+      #
+      # Total: 24 bytes
+      #
+      # Constraints:
+      # - Must contain exactly 24 bytes
+      # - Must appear before PLTE and IDAT
+      # - At most one mDCv chunk allowed
+      # - Coordinates must be in range 0-50000 (0.0-1.0 in CIE 1931)
+      # - Maximum luminance must be > minimum luminance
+      #
+      class MdcvValidator < BaseValidator
+        CHUNK_TYPE = "mDCV"
+
+        # Maximum coordinate value (0.00002 * 50000 = 1.0)
+        MAX_COORDINATE = 50_000
+
+        # Coordinate scale factor
+        COORDINATE_SCALE = 0.00002
+
+        # Luminance scale factor (cd/m²)
+        LUMINANCE_SCALE = 0.0001
+
+        def validate
+          check_chunk_length
+          check_uniqueness
+          check_position
+          validate_fields if chunk.chunk_data.bytesize == 24
+        end
+
+        private
+
+        def check_chunk_length
+          return if check_length(24)
+
+          add_error("invalid chunk length: #{chunk.chunk_data.bytesize} bytes")
+        end
+
+        def check_uniqueness
+          return unless context.seen?(CHUNK_TYPE)
+
+          add_error("duplicate mDCV chunk (only one allowed)")
+        end
+
+        def check_position
+          add_error("mDCv must appear before PLTE") if context.seen?("PLTE")
+
+          return unless context.seen?("IDAT")
+
+          add_error("mDCv must appear before IDAT")
+        end
+
+        def validate_fields
+          data = chunk.data
+
+          # Parse all uint16 and uint32 values
+          red_x = read_uint16(data, 0)
+          red_y = read_uint16(data, 2)
+          green_x = read_uint16(data, 4)
+          green_y = read_uint16(data, 6)
+          blue_x = read_uint16(data, 8)
+          blue_y = read_uint16(data, 10)
+          white_x = read_uint16(data, 12)
+          white_y = read_uint16(data, 14)
+          max_luminance = read_uint32(data, 16)
+          min_luminance = read_uint32(data, 20)
+
+          # Validate display primaries
+          validate_primary("red", red_x, red_y)
+          validate_primary("green", green_x, green_y)
+          validate_primary("blue", blue_x, blue_y)
+
+          # Validate white point
+          validate_white_point(white_x, white_y)
+
+          # Validate luminance values
+          validate_luminance(max_luminance, min_luminance)
+
+          # Add informational messages about decoded values
+          add_display_info(
+            red_x, red_y, green_x, green_y, blue_x, blue_y,
+            white_x, white_y, max_luminance, min_luminance
+          )
+        end
+
+        def validate_primary(color, x_value, y_value)
+          validate_coordinate("#{color} primary x", x_value)
+          validate_coordinate("#{color} primary y", y_value)
+
+          # Check that x + y <= 1.0 (sum <= 50000)
+          return unless x_value + y_value > MAX_COORDINATE
+
+          add_warning(
+            "#{color} primary coordinates sum > 1.0 " \
+            "(x=#{format_coordinate(x_value)}, " \
+            "y=#{format_coordinate(y_value)})",
+          )
+        end
+
+        def validate_white_point(x_value, y_value)
+          validate_coordinate("white point x", x_value)
+          validate_coordinate("white point y", y_value)
+
+          # Check that x + y <= 1.0
+          return unless x_value + y_value > MAX_COORDINATE
+
+          add_warning(
+            "white point coordinates sum > 1.0 " \
+            "(x=#{format_coordinate(x_value)}, " \
+            "y=#{format_coordinate(y_value)})",
+          )
+        end
+
+        def validate_coordinate(name, value)
+          return if check_range(value, 0, MAX_COORDINATE, name)
+
+          add_error(
+            "#{name} out of range: #{value} " \
+            "(must be 0-#{MAX_COORDINATE})",
+          )
+        end
+
+        def validate_luminance(max_lum, min_lum)
+          # Maximum luminance must be greater than minimum
+          if max_lum <= min_lum
+            add_error(
+              "maximum luminance (#{format_luminance(max_lum)}) must be > " \
+              "minimum luminance (#{format_luminance(min_lum)})",
+            )
+          end
+
+          # Check for reasonable luminance ranges
+          add_warning("maximum luminance is 0 cd/m²") if max_lum.zero?
+
+          return unless max_lum > 100_000_000 # 10,000 cd/m²
+
+          add_warning(
+            "maximum luminance very high: #{format_luminance(max_lum)} " \
+            "(> 10,000 cd/m²)",
+          )
+        end
+
+        def add_display_info(
+          red_x, red_y, green_x, green_y, blue_x, blue_y,
+          white_x, white_y, max_lum, min_lum
+        )
+          add_info(
+            "mastering display: " \
+            "R=(#{format_coordinate(red_x)},#{format_coordinate(red_y)}), " \
+            "G=(#{format_coordinate(green_x)},#{format_coordinate(green_y)}), " \
+            "B=(#{format_coordinate(blue_x)},#{format_coordinate(blue_y)})",
+          )
+
+          add_info(
+            "white point: " \
+            "(#{format_coordinate(white_x)},#{format_coordinate(white_y)})",
+          )
+
+          add_info(
+            "luminance range: " \
+            "#{format_luminance(min_lum)} - #{format_luminance(max_lum)} cd/m²",
+          )
+        end
+
+        def read_uint16(data, offset)
+          data[offset, 2].unpack1("n")
+        end
+
+        def read_uint32(data, offset)
+          data[offset, 4].unpack1("N")
+        end
+
+        def format_coordinate(value)
+          (value * COORDINATE_SCALE).round(5).to_s
+        end
+
+        def format_luminance(value)
+          (value * LUMINANCE_SCALE).round(4).to_s
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG oFFs (Image Offset) chunk
+      #
+      # oFFs specifies the offset of the image from a reference point:
+      # - X position (4 bytes, signed)
+      # - Y position (4 bytes, signed)
+      # - Unit specifier (1 byte)
+      #
+      # Validation rules from PNG spec:
+      # - Chunk must be exactly 9 bytes
+      # - Unit must be 0 (pixels) or 1 (micrometers)
+      # - Must appear before IDAT chunk
+      # - Only one oFFs chunk allowed
+      class OffsValidator < BaseValidator
+        # Expected chunk length
+        EXPECTED_LENGTH = 9
+
+        # Valid unit specifiers
+        UNIT_PIXELS = 0
+        UNIT_MICROMETERS = 1
+        VALID_UNITS = [UNIT_PIXELS, UNIT_MICROMETERS].freeze
+
+        # Unit names for display
+        UNIT_NAMES = {
+          UNIT_PIXELS => "pixels",
+          UNIT_MICROMETERS => "micrometers",
+        }.freeze
+
+        # Validate oFFs 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_length
+          return false unless check_unit
+
+          store_offset_info
+          true
+        end
+
+        private
+
+        # Check that only one oFFs chunk exists
+        def check_uniqueness
+          if context.retrieve(:has_offset)
+            add_error("Multiple oFFs chunks (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that oFFs appears before IDAT
+        def check_position
+          if context.seen?("IDAT")
+            add_error("oFFs chunk after IDAT chunk")
+            return false
+          end
+
+          true
+        end
+
+        # Check chunk length
+        def check_length
+          actual_length = chunk.chunk_data.length
+
+          unless actual_length == EXPECTED_LENGTH
+            add_error("oFFs chunk wrong length (#{actual_length} bytes, " \
+                      "expected #{EXPECTED_LENGTH})")
+            return false
+          end
+
+          true
+        end
+
+        # Check unit specifier
+        def check_unit
+          data = chunk.chunk_data
+          unit = data[8].ord
+
+          unless VALID_UNITS.include?(unit)
+            add_error("oFFs invalid unit specifier (#{unit}, " \
+                      "must be 0 or 1)")
+            return false
+          end
+
+          true
+        end
+
+        # Store offset information in context
+        def store_offset_info
+          data = chunk.chunk_data
+
+          # Parse X position (4 bytes, signed big-endian)
+          x_bytes = data[0, 4].bytes
+          x_pos = (x_bytes[0] << 24) | (x_bytes[1] << 16) |
+            (x_bytes[2] << 8) | x_bytes[3]
+          # Convert to signed
+          x_pos -= (1 << 32) if x_pos >= (1 << 31)
+
+          # Parse Y position (4 bytes, signed big-endian)
+          y_bytes = data[4, 4].bytes
+          y_pos = (y_bytes[0] << 24) | (y_bytes[1] << 16) |
+            (y_bytes[2] << 8) | y_bytes[3]
+          # Convert to signed
+          y_pos -= (1 << 32) if y_pos >= (1 << 31)
+
+          # Parse unit
+          unit = data[8].ord
+          unit_name = UNIT_NAMES[unit]
+
+          # Store in context
+          context.store(:has_offset, true)
+          context.store(:offset_x, x_pos)
+          context.store(:offset_y, y_pos)
+          context.store(:offset_unit, unit)
+
+          # Add info about the offset
+          add_info("oFFs: position (#{x_pos}, #{y_pos}) #{unit_name}")
+        end
+      end
+    end
+  end
+end