png_conform 0.1.0

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

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG pCAL (Pixel Calibration) chunk
+      #
+      # pCAL maps pixel values to physical values:
+      # - Calibration name (1-79 bytes, Latin-1)
+      # - Null separator (1 byte)
+      # - Original zero (4 bytes, signed)
+      # - Original max (4 bytes, signed)
+      # - Equation type (1 byte, 0-3)
+      # - Number of parameters (1 byte)
+      # - Unit name (null-terminated Latin-1)
+      # - Parameters (null-terminated ASCII floating point strings)
+      #
+      # Validation rules from PNG spec:
+      # - Calibration name must be 1-79 characters, Latin-1 printable
+      # - Calibration name must not have leading/trailing/consecutive spaces
+      # - Equation type must be 0-3
+      # - Number of parameters must match equation type requirements
+      # - Parameters must be valid ASCII floating point numbers
+      # - Must appear before IDAT chunk
+      # - Only one pCAL chunk allowed
+      class PcalValidator < BaseValidator
+        # Maximum calibration name length
+        MAX_CALIBRATION_NAME_LENGTH = 79
+
+        # Latin-1 printable characters (space to tilde + high ASCII)
+        PRINTABLE_LATIN1 = (32..126).to_a + (161..255).to_a
+
+        # Valid equation types and required parameter counts
+        EQUATION_LINEAR = 0            # p0 + p1*x (2 params)
+        EQUATION_BASE_E = 1            # p0 + p1*e^(p2*x) (3 params)
+        EQUATION_BASE_10 = 2           # p0 + p1*10^(p2*x) (3 params)
+        EQUATION_ARBITRARY = 3         # p0 + p1*n^(p2*x) (4 params)
+
+        EQUATION_PARAM_COUNTS = {
+          EQUATION_LINEAR => 2,
+          EQUATION_BASE_E => 3,
+          EQUATION_BASE_10 => 3,
+          EQUATION_ARBITRARY => 4,
+        }.freeze
+
+        # ASCII floating point regex
+        FLOAT_REGEX = /\A[+-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\z/
+
+        # Validate pCAL 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_calibration_name
+          return false unless check_equation_type
+          return false unless check_parameters
+
+          store_calibration_info
+          true
+        end
+
+        private
+
+        # Check that only one pCAL chunk exists
+        def check_uniqueness
+          if context.retrieve(:has_calibration)
+            add_error("duplicate pCAL chunk (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that pCAL appears before IDAT
+        def check_position
+          if context.seen?("IDAT")
+            add_error("pCAL chunk after IDAT chunk")
+            return false
+          end
+
+          true
+        end
+
+        # Check pCAL chunk structure
+        def check_structure
+          data = chunk.chunk_data
+
+          # Must contain at least name + nulls + int fields + equation type + param count
+          if data.length < 12
+            add_error("pCAL chunk too short (minimum 12 bytes)")
+            return false
+          end
+
+          # Must contain null separator after name
+          null_pos = data.index("\0")
+          unless null_pos
+            add_error("pCAL chunk missing null separator")
+            return false
+          end
+
+          true
+        end
+
+        # Check calibration name validity
+        def check_calibration_name
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          cal_name = data[0, null_pos]
+
+          # Check calibration name length
+          if cal_name.empty?
+            add_error("pCAL chunk has empty calibration name")
+            return false
+          end
+
+          if cal_name.length > MAX_CALIBRATION_NAME_LENGTH
+            add_error("pCAL calibration name too long " \
+                      "(#{cal_name.length}, max #{MAX_CALIBRATION_NAME_LENGTH})")
+            return false
+          end
+
+          # Check for Latin-1 printable characters
+          cal_name.bytes.each do |byte|
+            next if PRINTABLE_LATIN1.include?(byte)
+
+            add_error("pCAL calibration name contains non-printable " \
+                      "character (0x#{byte.to_s(16)})")
+            return false
+          end
+
+          # Check for leading/trailing spaces
+          if cal_name.start_with?(" ")
+            add_error("pCAL calibration name has leading space")
+            return false
+          end
+
+          if cal_name.end_with?(" ")
+            add_error("pCAL calibration name has trailing space")
+            return false
+          end
+
+          # Check for consecutive spaces
+          if cal_name.include?("  ")
+            add_error("pCAL calibration name has consecutive spaces")
+            return false
+          end
+
+          true
+        end
+
+        # Check equation type
+        def check_equation_type
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          equation_type = data[null_pos + 9].ord
+
+          unless EQUATION_PARAM_COUNTS.key?(equation_type)
+            add_error("pCAL invalid equation type (#{equation_type}, " \
+                      "must be 0-3)")
+            return false
+          end
+
+          true
+        end
+
+        # Check parameters
+        def check_parameters
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          equation_type = data[null_pos + 9].ord
+          num_params = data[null_pos + 10].ord
+
+          expected_params = EQUATION_PARAM_COUNTS[equation_type]
+          unless num_params == expected_params
+            add_error("pCAL parameter count mismatch (#{num_params}, " \
+                      "expected #{expected_params} for equation type #{equation_type})")
+            return false
+          end
+
+          # Find unit name and parameters
+          unit_start = null_pos + 11
+          unit_null = data.index("\0", unit_start)
+          unless unit_null
+            add_error("pCAL missing unit name null terminator")
+            return false
+          end
+
+          # Parse parameters
+          param_start = unit_null + 1
+          params_found = 0
+          pos = param_start
+
+          while params_found < num_params && pos < data.length
+            param_end = data.index("\0", pos)
+            unless param_end
+              add_error("pCAL missing parameter #{params_found + 1} " \
+                        "null terminator")
+              return false
+            end
+
+            param_str = data[pos, param_end - pos]
+            unless valid_float_string?(param_str)
+              add_error("pCAL invalid parameter #{params_found + 1} " \
+                        "format: '#{param_str}'")
+              return false
+            end
+
+            params_found += 1
+            pos = param_end + 1
+          end
+
+          unless params_found == num_params
+            add_error("pCAL found #{params_found} parameters, " \
+                      "expected #{num_params}")
+            return false
+          end
+
+          true
+        end
+
+        # Validate floating point string format
+        def valid_float_string?(str)
+          return false if str.empty?
+
+          str.match?(FLOAT_REGEX)
+        end
+
+        # Store calibration information in context
+        def store_calibration_info
+          data = chunk.chunk_data
+          null_pos = data.index("\0")
+          cal_name = data[0, null_pos]
+
+          # Parse original zero and max (signed 32-bit big-endian)
+          orig_zero_bytes = data[null_pos + 1, 4].bytes
+          orig_zero = (orig_zero_bytes[0] << 24) |
+            (orig_zero_bytes[1] << 16) |
+            (orig_zero_bytes[2] << 8) |
+            orig_zero_bytes[3]
+          orig_zero -= (1 << 32) if orig_zero >= (1 << 31)
+
+          orig_max_bytes = data[null_pos + 5, 4].bytes
+          orig_max = (orig_max_bytes[0] << 24) |
+            (orig_max_bytes[1] << 16) |
+            (orig_max_bytes[2] << 8) |
+            orig_max_bytes[3]
+          orig_max -= (1 << 32) if orig_max >= (1 << 31)
+
+          equation_type = data[null_pos + 9].ord
+          num_params = data[null_pos + 10].ord
+
+          # Parse unit name
+          unit_start = null_pos + 11
+          unit_null = data.index("\0", unit_start)
+          unit_name = data[unit_start, unit_null - unit_start]
+
+          # Parse parameters
+          params = []
+          pos = unit_null + 1
+          num_params.times do
+            param_end = data.index("\0", pos)
+            param_str = data[pos, param_end - pos]
+            params << param_str.to_f
+            pos = param_end + 1
+          end
+
+          # Store in context
+          context.store(:has_calibration, true)
+          context.store(:calibration_name, cal_name)
+          context.store(:calibration_equation_type, equation_type)
+          context.store(:calibration_parameters, params)
+
+          # Add info about the calibration
+          eq_type_name = %w[linear base-e base-10
+                            arbitrary][equation_type]
+          add_info("pCAL: \"#{cal_name}\" #{eq_type_name} equation, " \
+                   "range #{orig_zero}..#{orig_max}, " \
+                   "unit \"#{unit_name}\", " \
+                   "params: #{params.join(', ')}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG pHYs (Physical Pixel Dimensions) chunk
+      #
+      # pHYs specifies the intended pixel size or aspect ratio:
+      # - Pixels per unit, X axis (4 bytes)
+      # - Pixels per unit, Y axis (4 bytes)
+      # - Unit specifier (1 byte): 0 = unknown, 1 = meters
+      #
+      # Validation rules from PNG spec:
+      # - Must be exactly 9 bytes
+      # - Must appear before IDAT
+      # - Only one pHYs chunk allowed
+      # - Unit specifier must be 0 or 1
+      class PhysValidator < BaseValidator
+        # Unit specifiers
+        UNIT_UNKNOWN = 0
+        UNIT_METER = 1
+
+        # Common DPI values (pixels per inch)
+        DPI_72 = 2835   # 72 DPI in pixels per meter
+        DPI_96 = 3780   # 96 DPI in pixels per meter
+        DPI_150 = 5906  # 150 DPI in pixels per meter
+        DPI_300 = 11_811 # 300 DPI in pixels per meter
+
+        # Validate pHYs chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_length(9)
+          return false unless check_position
+          return false unless check_uniqueness
+          return false unless check_unit
+
+          store_phys_info
+          true
+        end
+
+        private
+
+        # Check pHYs position relative to other chunks
+        def check_position
+          # pHYs should appear before IDAT
+          if context.seen?("IDAT")
+            add_error("pHYs chunk after IDAT (must be before)")
+            return false
+          end
+          true
+        end
+
+        # Check that only one pHYs chunk is present
+        def check_uniqueness
+          if context.seen?("pHYs")
+            add_error("duplicate pHYs chunk")
+            return false
+          end
+          true
+        end
+
+        # Check unit specifier
+        def check_unit
+          data = chunk.chunk_data
+          unit = data[8].unpack1("C")
+
+          check_enum(unit, [UNIT_UNKNOWN, UNIT_METER], "unit specifier")
+        end
+
+        # Store physical dimensions in context
+        def store_phys_info
+          data = chunk.chunk_data
+          pixels_per_unit_x = data[0, 4].unpack1("N")
+          pixels_per_unit_y = data[4, 4].unpack1("N")
+          unit = data[8].unpack1("C")
+
+          context.store(:phys_x, pixels_per_unit_x)
+          context.store(:phys_y, pixels_per_unit_y)
+          context.store(:phys_unit, unit)
+
+          # Calculate aspect ratio
+          if pixels_per_unit_x.positive? && pixels_per_unit_y.positive?
+            aspect = pixels_per_unit_x.to_f / pixels_per_unit_y
+            context.store(:pixel_aspect_ratio, aspect)
+
+            if (aspect - 1.0).abs > 0.01
+              add_info("pHYs: non-square pixels " \
+                       "(aspect ratio #{format('%.3f', aspect)})")
+            end
+          end
+
+          # Provide DPI information if unit is meters
+          unless unit == UNIT_METER && pixels_per_unit_x == pixels_per_unit_y
+            return
+          end
+
+          dpi = (pixels_per_unit_x * 0.0254).round
+          add_info("pHYs: #{dpi} DPI")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG sBIT (Significant Bits) chunk
+      #
+      # sBIT indicates the number of significant bits in the original image:
+      # - For grayscale: 1 byte (significant grayscale bits)
+      # - For truecolor: 3 bytes (R, G, B significant bits)
+      # - For indexed-color: 3 bytes (R, G, B significant bits)
+      # - For grayscale+alpha: 2 bytes (gray, alpha significant bits)
+      # - For truecolor+alpha: 4 bytes (R, G, B, alpha significant bits)
+      #
+      # Validation rules from PNG spec:
+      # - Length depends on color type
+      # - Must appear before PLTE and IDAT
+      # - Only one sBIT chunk allowed
+      # - Each value must be > 0 and <= sample depth
+      class SbitValidator < BaseValidator
+        # Validate sBIT chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_position
+          return false unless check_uniqueness
+          return false unless check_length_for_color_type
+          return false unless check_values
+
+          store_sbit_info
+          true
+        end
+
+        private
+
+        # Check sBIT position relative to other chunks
+        def check_position
+          valid = true
+
+          # sBIT should appear before PLTE and IDAT
+          if context.seen?("PLTE")
+            add_warning("sBIT chunk after PLTE (should be before)")
+          end
+
+          if context.seen?("IDAT")
+            add_error("sBIT chunk after IDAT (must be before)")
+            valid = false
+          end
+
+          valid
+        end
+
+        # Check that only one sBIT chunk is present
+        def check_uniqueness
+          if context.seen?("sBIT")
+            add_error("duplicate sBIT chunk")
+            return false
+          end
+          true
+        end
+
+        # Check sBIT length for color type
+        def check_length_for_color_type
+          color_type = context.retrieve(:color_type)
+          return true unless color_type
+
+          expected_length = case color_type
+                            when 0 then 1  # Grayscale
+                            when 2 then 3  # Truecolor
+                            when 3 then 3  # Indexed-color
+                            when 4 then 2  # Grayscale + alpha
+                            when 6 then 4  # Truecolor + alpha
+                            else
+                              return true
+                            end
+
+          check_length(expected_length)
+        end
+
+        # Check significant bit values
+        def check_values
+          color_type = context.retrieve(:color_type)
+          bit_depth = context.retrieve(:bit_depth)
+          return true unless color_type && bit_depth
+
+          data = chunk.chunk_data
+          valid = true
+
+          case color_type
+          when 0
+            # Grayscale
+            gray_bits = data[0].unpack1("C")
+            valid &= check_sbit_value(gray_bits, bit_depth, "gray")
+          when 2
+            # Truecolor
+            red, green, blue = data.unpack("CCC")
+            valid &= check_sbit_value(red, bit_depth, "red")
+            valid &= check_sbit_value(green, bit_depth, "green")
+            valid &= check_sbit_value(blue, bit_depth, "blue")
+          when 3
+            # Indexed-color (refers to palette sample depth, which is always 8)
+            red, green, blue = data.unpack("CCC")
+            valid &= check_sbit_value(red, 8, "red")
+            valid &= check_sbit_value(green, 8, "green")
+            valid &= check_sbit_value(blue, 8, "blue")
+          when 4
+            # Grayscale + alpha
+            gray, alpha = data.unpack("CC")
+            valid &= check_sbit_value(gray, bit_depth, "gray")
+            valid &= check_sbit_value(alpha, bit_depth, "alpha")
+          when 6
+            # Truecolor + alpha
+            red, green, blue, alpha = data.unpack("CCCC")
+            valid &= check_sbit_value(red, bit_depth, "red")
+            valid &= check_sbit_value(green, bit_depth, "green")
+            valid &= check_sbit_value(blue, bit_depth, "blue")
+            valid &= check_sbit_value(alpha, bit_depth, "alpha")
+          end
+
+          valid
+        end
+
+        # Check individual significant bit value
+        def check_sbit_value(value, max_depth, name)
+          if value.zero?
+            add_error("#{name} significant bits cannot be 0")
+            return false
+          end
+
+          if value > max_depth
+            add_error("#{name} significant bits (#{value}) exceeds " \
+                      "sample depth (#{max_depth})")
+            return false
+          end
+
+          true
+        end
+
+        # Store significant bit information in context
+        def store_sbit_info
+          color_type = context.retrieve(:color_type)
+          data = chunk.chunk_data
+
+          case color_type
+          when 0
+            gray = data[0].unpack1("C")
+            context.store(:significant_bits, { gray: gray })
+            add_info("sBIT: gray=#{gray}")
+          when 2
+            red, green, blue = data.unpack("CCC")
+            context.store(:significant_bits,
+                          { red: red, green: green, blue: blue })
+            add_info("sBIT: R=#{red}, G=#{green}, B=#{blue}")
+          when 3
+            red, green, blue = data.unpack("CCC")
+            context.store(:significant_bits,
+                          { red: red, green: green, blue: blue })
+            add_info("sBIT: R=#{red}, G=#{green}, B=#{blue}")
+          when 4
+            gray, alpha = data.unpack("CC")
+            context.store(:significant_bits, { gray: gray, alpha: alpha })
+            add_info("sBIT: gray=#{gray}, alpha=#{alpha}")
+          when 6
+            red, green, blue, alpha = data.unpack("CCCC")
+            context.store(:significant_bits,
+                          { red: red, green: green, blue: blue, alpha: alpha })
+            add_info("sBIT: R=#{red}, G=#{green}, B=#{blue}, A=#{alpha}")
+          end
+        end
+      end
+    end
+  end
+end