png_conform 0.1.0

data/lib/png_conform/analyzers/optimization_analyzer.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Analyzers
+    # Analyzes PNG files for optimization opportunities
+    class OptimizationAnalyzer
+      # Chunks that are often unnecessary for web/mobile use
+      UNNECESSARY_FOR_WEB = %w[tIME pHYs oFFs pCAL sCAL sTER].freeze
+
+      # Text chunk types
+      TEXT_CHUNKS = %w[tEXt zTXt iTXt].freeze
+
+      # Metadata chunk types
+      METADATA_CHUNKS = %w[tEXt zTXt iTXt tIME pHYs].freeze
+
+      def initialize(result)
+        @result = result
+        @suggestions = []
+      end
+
+      def analyze
+        check_unnecessary_chunks
+        check_color_depth
+        check_palette_opportunity
+        check_interlacing
+        check_text_chunks
+        check_metadata_size
+
+        {
+          suggestions: @suggestions,
+          potential_savings_bytes: calculate_total_savings,
+          potential_savings_percent: calculate_savings_percentage,
+        }
+      end
+
+      private
+
+      def check_unnecessary_chunks
+        unnecessary = @result.chunks.select do |c|
+          UNNECESSARY_FOR_WEB.include?(c.type)
+        end
+        return if unnecessary.empty?
+
+        # Each chunk has: 4 bytes length + 4 bytes type + data + 4 bytes CRC
+        savings = unnecessary.sum { |c| c.length + 12 }
+        @suggestions << {
+          type: :remove_chunks,
+          priority: :medium,
+          savings_bytes: savings,
+          description: "Remove #{unnecessary.count} unnecessary chunks " \
+                      "(#{unnecessary.map(&:type).join(', ')})",
+          chunks: unnecessary.map(&:type),
+        }
+      end
+
+      def check_color_depth
+        # Get bit depth from IHDR chunk
+        ihdr = @result.ihdr_chunk
+        return unless ihdr && get_bit_depth(ihdr) == 16
+
+        # Estimate if 8-bit would be sufficient
+        if could_use_8_bit?
+          current_size = @result.file_size
+          estimated_savings = (current_size * 0.45).to_i # ~45% reduction
+
+          @suggestions << {
+            type: :reduce_bit_depth,
+            priority: :high,
+            savings_bytes: estimated_savings,
+            description: "Convert from 16-bit to 8-bit depth " \
+                        "(estimated ~45% file size reduction)",
+            current: "16-bit",
+            recommended: "8-bit",
+          }
+        end
+      end
+
+      def check_palette_opportunity
+        # Get color type from IHDR
+        ihdr = @result.ihdr_chunk
+        return unless ihdr && get_color_type(ihdr) == 2 # RGB
+        return if @result.file_size < 10_000 # Skip small files
+
+        # If it's RGB but could be palette
+        @suggestions << {
+          type: :convert_to_palette,
+          priority: :medium,
+          savings_bytes: (@result.file_size * 0.30).to_i,
+          description: "Consider converting to palette mode if using limited colors " \
+                      "(potential ~30% reduction)",
+          current: "RGB (Truecolor)",
+          recommended: "Indexed (Palette)",
+        }
+      end
+
+      def check_interlacing
+        # Get interlace method from IHDR
+        ihdr = @result.ihdr_chunk
+        return unless ihdr && get_interlace_method(ihdr) == 1
+
+        # Interlaced PNGs are larger
+        savings = (@result.file_size * 0.15).to_i
+
+        @suggestions << {
+          type: :remove_interlacing,
+          priority: :low,
+          savings_bytes: savings,
+          description: "Remove interlacing for smaller file size " \
+                      "(~15% reduction, but slower initial display)",
+          current: "Adam7 interlaced",
+          recommended: "Non-interlaced",
+        }
+      end
+
+      def check_text_chunks
+        text_chunks = @result.chunks.select { |c| TEXT_CHUNKS.include?(c.type) }
+        return if text_chunks.empty?
+
+        total_text_size = text_chunks.sum { |c| c.length + 12 }
+        return if total_text_size < 500 # Ignore small metadata
+
+        @suggestions << {
+          type: :reduce_metadata,
+          priority: :low,
+          savings_bytes: total_text_size,
+          description: "#{text_chunks.count} text chunks using #{total_text_size} bytes " \
+                      "(consider removing non-essential metadata)",
+          chunks: text_chunks.map(&:type),
+        }
+      end
+
+      def check_metadata_size
+        metadata_chunks = @result.chunks.select do |c|
+          METADATA_CHUNKS.include?(c.type)
+        end
+
+        total_metadata = metadata_chunks.sum { |c| c.length + 12 }
+        file_size = @result.file_size
+
+        # If metadata is more than 10% of file size
+        return unless total_metadata > file_size * 0.1
+
+        @suggestions << {
+          type: :excessive_metadata,
+          priority: :medium,
+          savings_bytes: total_metadata,
+          description: "Metadata comprises #{(total_metadata.to_f / file_size * 100).round(1)}% " \
+                      "of file size (#{total_metadata} bytes)",
+          recommendation: "Review if all metadata is necessary",
+        }
+      end
+
+      # Helper methods to extract IHDR data
+      def get_bit_depth(ihdr_chunk)
+        # IHDR data: width(4) + height(4) + bit_depth(1) + ...
+        return nil unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 9
+
+        ihdr_chunk.data.bytes[8]
+      end
+
+      def get_color_type(ihdr_chunk)
+        return nil unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 10
+
+        ihdr_chunk.data.bytes[9]
+      end
+
+      def get_interlace_method(ihdr_chunk)
+        return nil unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 13
+
+        ihdr_chunk.data.bytes[12]
+      end
+
+      def could_use_8_bit?
+        # Conservative heuristic: suggest 8-bit for smaller files
+        # Without pixel analysis, we're conservative
+        @result.file_size < 100_000
+      end
+
+      def calculate_total_savings
+        @suggestions.sum { |s| s[:savings_bytes] || 0 }
+      end
+
+      def calculate_savings_percentage
+        return 0 if @result.file_size.zero?
+
+        (calculate_total_savings.to_f / @result.file_size * 100).round(1)
+      end
+    end
+  end
+end

data/lib/png_conform/analyzers/resolution_analyzer.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Analyzers
+    # Analyzes PNG resolution and DPI for various use cases
+    class ResolutionAnalyzer
+      # Standard DPI values
+      SCREEN_DPI = 72
+      PRINT_DPI_LOW = 150
+      PRINT_DPI_STANDARD = 300
+      PRINT_DPI_HIGH = 600
+
+      # Retina display densities
+      RETINA_1X = 1.0
+      RETINA_2X = 2.0
+      RETINA_3X = 3.0
+
+      def initialize(result)
+        @result = result
+        ihdr = result.ihdr_chunk
+        @width = ihdr ? get_width(ihdr) : 0
+        @height = ihdr ? get_height(ihdr) : 0
+        @dpi = extract_dpi
+      end
+
+      def analyze
+        {
+          resolution: resolution_info,
+          retina: retina_analysis,
+          print: print_analysis,
+          web: web_analysis,
+          recommendations: generate_recommendations,
+        }
+      end
+
+      private
+
+      # Extract data from IHDR chunk
+      def get_width(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 4
+
+        ihdr_chunk.data.bytes[0..3].pack("C*").unpack1("N")
+      end
+
+      def get_height(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 8
+
+        ihdr_chunk.data.bytes[4..7].pack("C*").unpack1("N")
+      end
+
+      def resolution_info
+        {
+          width_px: @width,
+          height_px: @height,
+          dimensions: "#{@width}x#{@height}",
+          total_pixels: @width * @height,
+          megapixels: (@width * @height / 1_000_000.0).round(2),
+          dpi: @dpi,
+          has_dpi_metadata: !@dpi.nil?,
+        }
+      end
+
+      def retina_analysis
+        analysis = {
+          is_retina_ready: check_retina_ready,
+          at_1x: calculate_physical_size(RETINA_1X),
+          at_2x: calculate_physical_size(RETINA_2X),
+          at_3x: calculate_physical_size(RETINA_3X),
+        }
+
+        analysis[:recommended_density] = recommend_density
+        analysis[:ios_asset_catalog] = ios_asset_suggestions
+        analysis[:android_density] = android_density_bucket
+
+        analysis
+      end
+
+      def print_analysis
+        return { capable: false, reason: "No DPI metadata" } unless @dpi
+
+        width_inches = @width.to_f / @dpi
+        height_inches = @height.to_f / @dpi
+
+        {
+          capable: @dpi >= PRINT_DPI_LOW,
+          dpi: @dpi,
+          physical_size: {
+            width_inches: width_inches.round(2),
+            height_inches: height_inches.round(2),
+            width_cm: (width_inches * 2.54).round(2),
+            height_cm: (height_inches * 2.54).round(2),
+          },
+          quality: print_quality_assessment,
+          suitable_for: suitable_print_sizes,
+        }
+      end
+
+      def web_analysis
+        {
+          suitable_for_web: @width <= 4096 && @height <= 4096,
+          typical_screen_size: calculate_screen_coverage,
+          mobile_friendly: @width <= 1920 && @height <= 1920,
+          retina_optimized: @width >= 1000 && @height >= 1000,
+          load_time_estimate: estimate_load_time,
+        }
+      end
+
+      def extract_dpi
+        # Look for pHYs chunk
+        phys_chunk = @result.chunks_by_type("pHYs").first
+        return nil unless phys_chunk&.data && phys_chunk.data.bytesize >= 9
+
+        # pHYs: pixels_per_unit_x(4) + pixels_per_unit_y(4) + unit_specifier(1)
+        unit = phys_chunk.data.bytes[8]
+        return nil unless unit == 1 # 1 = meters
+
+        pixels_per_meter = phys_chunk.data.bytes[0..3].pack("C*").unpack1("N")
+        (pixels_per_meter * 0.0254).round # Convert to DPI
+      end
+
+      def check_retina_ready
+        @width >= 88 && @height >= 88
+      end
+
+      def calculate_physical_size(density)
+        css_reference_dpi = 163
+        effective_dpi = css_reference_dpi * density
+
+        width_points = (@width.to_f / effective_dpi * 72).round(1)
+        height_points = (@height.to_f / effective_dpi * 72).round(1)
+
+        {
+          width_points: width_points,
+          height_points: height_points,
+          dimensions_pt: "#{width_points}x#{height_points}pt",
+          suitable_for: suitable_element_sizes(width_points, height_points),
+        }
+      end
+
+      def recommend_density
+        pixels = @width * @height
+        case pixels
+        when 0..10_000 then "@1x (too small for higher densities)"
+        when 10_001..100_000 then "@1x or @2x"
+        when 100_001..500_000 then "@2x"
+        when 500_001..2_000_000 then "@2x or @3x"
+        else "@3x"
+        end
+      end
+
+      def ios_asset_suggestions
+        suggestions = []
+
+        if @width == @height
+          case @width
+          when 20 then suggestions << "Icon 20pt @1x (Settings)"
+          when 40 then suggestions << "Icon 20pt @2x (Settings)"
+          when 60 then suggestions << "Icon 20pt @3x or 60pt @1x"
+          when 29 then suggestions << "Icon 29pt @1x"
+          when 58 then suggestions << "Icon 29pt @2x"
+          when 87 then suggestions << "Icon 29pt @3x"
+          when 1024 then suggestions << "App Store Icon (1024x1024)"
+          end
+        end
+
+        suggestions.empty? ? ["Custom size"] : suggestions
+      end
+
+      def android_density_bucket
+        case @width
+        when 0..120 then "ldpi or mdpi"
+        when 121..240 then "mdpi or hdpi"
+        when 241..480 then "hdpi or xhdpi"
+        when 481..720 then "xhdpi or xxhdpi"
+        when 721..960 then "xxhdpi or xxxhdpi"
+        else "xxxhdpi or custom"
+        end
+      end
+
+      def print_quality_assessment
+        return "Unknown" unless @dpi
+
+        case @dpi
+        when 0...PRINT_DPI_LOW then "Not suitable"
+        when PRINT_DPI_LOW...PRINT_DPI_STANDARD then "Acceptable"
+        when PRINT_DPI_STANDARD...PRINT_DPI_HIGH then "Good"
+        else "Excellent"
+        end
+      end
+
+      def suitable_print_sizes
+        return [] unless @dpi && @dpi >= PRINT_DPI_LOW
+
+        width_in = @width.to_f / @dpi
+        height_in = @height.to_f / @dpi
+
+        sizes = []
+        sizes << "4x6\"" if width_in >= 4 && height_in >= 6
+        sizes << "5x7\"" if width_in >= 5 && height_in >= 7
+        sizes << "8x10\"" if width_in >= 8 && height_in >= 10
+
+        sizes.empty? ? ["Small prints only"] : sizes
+      end
+
+      def calculate_screen_coverage
+        screens = {
+          "Mobile (375x667)" => { w: 375, h: 667 },
+          "Desktop (1920x1080)" => { w: 1920, h: 1080 },
+        }
+
+        screens.transform_values do |screen|
+          w_pct = (@width.to_f / screen[:w] * 100).round(1)
+          h_pct = (@height.to_f / screen[:h] * 100).round(1)
+          "#{w_pct}% x #{h_pct}%"
+        end
+      end
+
+      def suitable_element_sizes(width_pt, height_pt)
+        elements = []
+        elements << "Small icon" if width_pt < 32 && height_pt < 32
+        elements << "Standard icon" if width_pt.between?(32, 64)
+        elements << "Large icon" if width_pt.between?(64, 128)
+        elements << "Banner" if width_pt > 300
+
+        elements.empty? ? ["Custom"] : elements
+      end
+
+      def estimate_load_time
+        file_size = @result.file_size
+        mbps = 5
+        bytes_per_second = (mbps * 1_000_000 / 8).to_i
+        seconds = file_size.to_f / bytes_per_second
+
+        if seconds < 0.1
+          "< 0.1s"
+        elsif seconds < 1
+          "#{(seconds * 1000).round}ms"
+        else
+          "#{seconds.round(1)}s"
+        end
+      end
+
+      def generate_recommendations
+        recs = []
+
+        if @width < 100 && @height < 100
+          recs << {
+            category: :retina,
+            priority: :high,
+            message: "Image is too small for Retina displays - consider @2x/@3x versions",
+          }
+        end
+
+        unless @dpi
+          recs << {
+            category: :metadata,
+            priority: :medium,
+            message: "Add pHYs chunk with DPI information for print compatibility",
+          }
+        end
+
+        if @width > 3000 || @height > 3000
+          recs << {
+            category: :web,
+            priority: :high,
+            message: "Image is very large for web - consider reducing dimensions",
+          }
+        end
+
+        recs
+      end
+    end
+  end
+end

data/lib/png_conform/bindata/chunk_structure.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module PngConform
+  module BinData
+    # Base structure for PNG chunks
+    #
+    # PNG chunk format (from PNG spec):
+    #   Length: 4 bytes (big-endian unsigned integer)
+    #   Type:   4 bytes (4 ASCII characters)
+    #   Data:   variable length (specified by Length field)
+    #   CRC:    4 bytes (CRC-32 of Type and Data)
+    #
+    # @example Reading a chunk
+    #   chunk = ChunkStructure.read(io)
+    #   puts chunk.type        # => "IHDR"
+    #   puts chunk.length      # => 13
+    #   puts chunk.data.length # => 13
+    #   puts chunk.crc         # => 0x9a76a1ae
+    #
+    class ChunkStructure < ::BinData::Record
+      endian :big
+
+      # Length of the data field (4 bytes, big-endian)
+      uint32 :data_length
+
+      # Chunk type code (4 bytes, ASCII)
+      string :chunk_type, length: 4
+
+      # Chunk data (variable length, specified by data_length field)
+      string :chunk_data, read_length: :data_length
+
+      # CRC-32 checksum (4 bytes, big-endian)
+      # CRC is calculated over the Type and Data fields
+      uint32 :crc
+
+      # Convenience accessor for chunk type
+      #
+      # @return [String] chunk type code
+      def type
+        chunk_type
+      end
+
+      # Convenience accessor for chunk data
+      #
+      # @return [String] chunk data
+      def data
+        chunk_data
+      end
+
+      # Convenience accessor for data length
+      #
+      # @return [Integer] data length
+      def length
+        data_length
+      end
+
+      # Calculate the expected CRC-32 value
+      #
+      # The CRC is calculated over the chunk type and data fields.
+      # This uses the standard CRC-32 algorithm as specified in PNG spec.
+      #
+      # @return [Integer] the calculated CRC-32 value
+      def calculated_crc
+        require "zlib"
+        ::Zlib.crc32(chunk_type + chunk_data)
+      end
+
+      # Check if the stored CRC matches the calculated CRC
+      #
+      # @return [Boolean] true if CRC is valid, false otherwise
+      def crc_valid?
+        crc == calculated_crc
+      end
+
+      # Get chunk type as a symbol for easier matching
+      #
+      # @return [Symbol] chunk type as symbol (e.g., :IHDR)
+      def type_symbol
+        chunk_type.to_sym
+      end
+
+      # Check if this is a critical chunk
+      #
+      # Critical chunks have uppercase first letter in type code.
+      # From PNG spec: bit 5 of first byte is 0 for critical chunks.
+      #
+      # @return [Boolean] true if critical chunk
+      def critical?
+        (chunk_type[0].ord & 0x20).zero?
+      end
+
+      # Check if this is an ancillary chunk
+      #
+      # Ancillary chunks have lowercase first letter in type code.
+      #
+      # @return [Boolean] true if ancillary chunk
+      def ancillary?
+        !critical?
+      end
+
+      # Check if this chunk is safe to copy
+      #
+      # Safe-to-copy chunks have lowercase fourth letter.
+      # From PNG spec: bit 5 of fourth byte is 1 for safe-to-copy.
+      #
+      # @return [Boolean] true if safe to copy
+      def safe_to_copy?
+        chunk_type[3].ord & 0x20 != 0
+      end
+
+      # Check if this is a private chunk
+      #
+      # Private chunks have lowercase second letter.
+      # From PNG spec: bit 5 of second byte is 1 for private chunks.
+      #
+      # @return [Boolean] true if private chunk
+      def private?
+        chunk_type[1].ord & 0x20 != 0
+      end
+
+      # Get human-readable chunk information
+      #
+      # @return [String] formatted chunk information
+      def to_s
+        format(
+          "%s: %d bytes (CRC: 0x%08x %s)",
+          chunk_type,
+          data_length,
+          crc,
+          crc_valid? ? "OK" : "INVALID",
+        )
+      end
+
+      # Get detailed chunk information for debugging
+      #
+      # @return [Hash] chunk details
+      def inspect_details
+        {
+          type: chunk_type,
+          length: data_length,
+          data_size: chunk_data.length,
+          crc: format("0x%08x", crc),
+          crc_valid: crc_valid?,
+          critical: critical?,
+          private: private?,
+          safe_to_copy: safe_to_copy?,
+        }
+      end
+    end
+  end
+end

data/lib/png_conform/bindata/jng_file.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module PngConform
+  module BinData
+    # JNG (JPEG Network Graphics) file structure
+    # A JNG file consists of:
+    # - 8-byte signature: 139 74 78 71 13 10 26 10
+    # - JHDR chunk (must be first)
+    # - JDAT chunks (JPEG data)
+    # - Optional IDAT chunks (PNG alpha channel)
+    # - IEND chunk (must be last)
+    class JngFile < ::BinData::Record
+      # JNG signature (magic number)
+      JNG_SIGNATURE = [139, 74, 78, 71, 13, 10, 26, 10].pack("C*").freeze
+
+      string :signature, length: 8
+      array :chunks, type: :chunk_structure, read_until: :eof
+
+      # Validate JNG signature
+      def valid_signature?
+        signature == JNG_SIGNATURE
+      end
+
+      # Get signature as hex string for display
+      def signature_hex
+        signature.unpack1("H*")
+      end
+
+      # Find chunks by type
+      def chunks_by_type(type)
+        chunks.select { |chunk| chunk.type == type }
+      end
+
+      # Get JHDR chunk (must be first chunk)
+      def jhdr_chunk
+        chunks.first if chunks.first&.type == "JHDR"
+      end
+
+      # Get IEND chunk (must be last chunk)
+      def iend_chunk
+        chunks.last if chunks.last&.type == "IEND"
+      end
+
+      # Get all JDAT chunks (JPEG image data)
+      def jdat_chunks
+        chunks_by_type("JDAT")
+      end
+
+      # Get all IDAT chunks (PNG alpha channel data)
+      def idat_chunks
+        chunks_by_type("IDAT")
+      end
+
+      # Get JSEP chunk (8/12-bit separator, if present)
+      def jsep_chunk
+        chunks_by_type("JSEP").first
+      end
+
+      # Check if JNG has alpha channel
+      def has_alpha?
+        !idat_chunks.empty?
+      end
+
+      # Check if file has proper chunk ordering
+      def proper_chunk_order?
+        return false unless jhdr_chunk
+        return false unless iend_chunk
+        return false if jdat_chunks.empty?
+
+        true
+      end
+
+      # Get total file size
+      def total_size
+        8 + chunks.sum(&:total_size)
+      end
+    end
+  end
+end