png_conform 0.1.1 → 0.1.2

data/benchmarks/lib/report_generator.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require "json"
+require "csv"
+
+# Generates benchmark reports in multiple formats.
+#
+# Supports text, JSON, CSV, and Markdown output formats with
+# detailed performance comparisons and statistics.
+class ReportGenerator
+  attr_reader :metrics_collector, :config
+
+  def initialize(metrics_collector, config = {})
+    @metrics_collector = metrics_collector
+    @config = config
+  end
+
+  # Generate report in specified format.
+  #
+  # @param format [String] Output format: text, json, csv, markdown
+  # @return [String] Formatted report
+  def generate(format = "text")
+    case format.to_s.downcase
+    when "json"
+      generate_json
+    when "csv"
+      generate_csv
+    when "markdown", "md"
+      generate_markdown
+    else
+      generate_text
+    end
+  end
+
+  private
+
+  # Generate text report with tables and colors.
+  def generate_text
+    summary = metrics_collector.summary
+    tools = summary[:tools]
+
+    return "No benchmark data available.\n" if tools.empty?
+
+    output = []
+    output << "=" * 80
+    output << "PNG Validation Tool Benchmark Comparison"
+    output << "=" * 80
+    output << ""
+    output << "Configuration:"
+    output << "  Files tested:     #{summary[:files_tested]} PNG files"
+    output << "  Total runs:       #{summary[:total_runs]}"
+    output << ""
+
+    # Tool availability
+    output << "Tools:"
+    tools.each do |tool|
+      stats = metrics_collector.calculate_statistics(tool)
+      output << "  #{tool}: #{stats[:successful_runs]}/#{stats[:total_runs]} successful"
+    end
+    output << ""
+
+    # Performance comparison (if we have 2 tools)
+    if tools.size == 2
+      comparison = metrics_collector.compare_tools(tools[0], tools[1])
+      output << "-" * 80
+      output << "PERFORMANCE SUMMARY"
+      output << "-" * 80
+      output << ""
+      output << format_comparison_table(comparison)
+      output << ""
+      output << format_winner_summary(comparison)
+      output << ""
+    end
+
+    # Detailed statistics per tool
+    output << "-" * 80
+    output << "DETAILED STATISTICS"
+    output << "-" * 80
+    output << ""
+
+    tools.each do |tool|
+      stats = metrics_collector.calculate_statistics(tool)
+      output << format_tool_statistics(stats)
+      output << ""
+    end
+
+    output.join("\n")
+  end
+
+  # Generate JSON report.
+  def generate_json
+    summary = metrics_collector.summary
+    tools = summary[:tools]
+
+    data = {
+      benchmark_info: {
+        timestamp: Time.now.iso8601,
+        files_tested: summary[:files_tested],
+        total_runs: summary[:total_runs],
+        tools: tools,
+      },
+      tool_statistics: summary[:tool_statistics],
+      raw_data: config[:include_raw_data] ? metrics_collector.export_raw_data : nil,
+    }.compact
+
+    # Add comparison if we have 2 tools
+    if tools.size == 2
+      data[:comparison] = metrics_collector.compare_tools(tools[0], tools[1])
+    end
+
+    JSON.pretty_generate(data)
+  end
+
+  # Generate CSV report.
+  def generate_csv
+    runs = metrics_collector.export_raw_data
+
+    CSV.generate do |csv|
+      csv << ["Tool", "File", "Execution Time (ms)", "Peak Memory (MB)",
+              "Success", "Exit Code", "Timed Out", "Timestamp"]
+
+      runs.each do |run|
+        csv << [
+          run[:tool],
+          run[:file],
+          run[:execution_time],
+          run[:peak_memory],
+          run[:success],
+          run[:exit_code],
+          run[:timed_out],
+          run[:timestamp].iso8601,
+        ]
+      end
+    end
+  end
+
+  # Generate Markdown report.
+  def generate_markdown
+    summary = metrics_collector.summary
+    tools = summary[:tools]
+
+    return "# No benchmark data available\n" if tools.empty?
+
+    output = []
+    output << "# PNG Validation Tool Benchmark Comparison"
+    output << ""
+    output << "## Configuration"
+    output << ""
+    output << "- **Files tested**: #{summary[:files_tested]} PNG files"
+    output << "- **Total runs**: #{summary[:total_runs]}"
+    output << "- **Tools**: #{tools.join(', ')}"
+    output << ""
+
+    # Performance comparison
+    if tools.size == 2
+      comparison = metrics_collector.compare_tools(tools[0], tools[1])
+      output << "## Performance Summary"
+      output << ""
+      output << format_markdown_comparison(comparison)
+      output << ""
+    end
+
+    # Statistics per tool
+    output << "## Detailed Statistics"
+    output << ""
+
+    tools.each do |tool|
+      stats = metrics_collector.calculate_statistics(tool)
+      output << format_markdown_statistics(stats)
+      output << ""
+    end
+
+    output.join("\n")
+  end
+
+  # Format comparison table for text output.
+  def format_comparison_table(comparison)
+    lines = []
+    lines << sprintf("%-15s %12s %12s %12s %8s",
+                     "Tool", "Avg Time", "Files/sec", "Peak Memory", "Winner")
+    lines << "-" * 80
+
+    [comparison[:tool1], comparison[:tool2]].each do |tool|
+      stats = comparison[:stats][tool]
+      is_winner = tool == comparison[:faster_tool]
+
+      # Handle nil throughput gracefully
+      files_per_sec = stats[:throughput]&.[](:files_per_second) || 0.0
+
+      lines << sprintf("%-15s %10.1fms %10.1f/s %10.1f MB %8s",
+                       tool,
+                       stats[:execution_time][:mean],
+                       files_per_sec,
+                       stats[:memory][:mean],
+                       is_winner ? "✓" : "")
+    end
+
+    lines.join("\n")
+  end
+
+  # Format winner summary.
+  def format_winner_summary(comparison)
+    lines = []
+    lines << "Performance Difference:"
+    lines << "  #{comparison[:faster_tool]} is #{comparison[:time_multiplier]}x faster " \
+             "(#{comparison[:time_difference_percent]}% faster)"
+    lines << "  #{comparison[:memory_efficient_tool]} uses #{comparison[:memory_multiplier]}x less memory " \
+             "(#{comparison[:memory_difference_percent]}% less)"
+    lines.join("\n")
+  end
+
+  # Format tool statistics for text output.
+  def format_tool_statistics(stats)
+    lines = []
+    lines << "#{stats[:tool]}:"
+    lines << "  Runs:        #{stats[:successful_runs]}/#{stats[:total_runs]} successful"
+    lines << "  Timeouts:    #{stats[:timeouts]}" if stats[:timeouts].positive?
+    lines << ""
+    lines << "  Execution Time:"
+    lines << "    Mean:      #{stats[:execution_time][:mean]}ms"
+    lines << "    Median:    #{stats[:execution_time][:median]}ms"
+    lines << "    Std Dev:   #{stats[:execution_time][:std_dev]}ms"
+    lines << "    Min:       #{stats[:execution_time][:min]}ms"
+    lines << "    Max:       #{stats[:execution_time][:max]}ms"
+    lines << ""
+    lines << "  Memory Usage:"
+    lines << "    Mean:      #{stats[:memory][:mean]} MB"
+    lines << "    Median:    #{stats[:memory][:median]} MB"
+    lines << "    Min:       #{stats[:memory][:min]} MB"
+    lines << "    Max:       #{stats[:memory][:max]} MB"
+
+    # Handle nil throughput gracefully
+    if stats[:throughput]
+      lines << ""
+      lines << "  Throughput:"
+      lines << "    Files/sec: #{stats[:throughput][:files_per_second]}"
+      lines << "    Time/file: #{stats[:throughput][:avg_time_per_file]}ms"
+    end
+
+    lines.join("\n")
+  end
+
+  # Format comparison for markdown.
+  def format_markdown_comparison(comparison)
+    lines = []
+    lines << "| Metric | #{comparison[:tool1]} | #{comparison[:tool2]} | Winner |"
+    lines << "|--------|----------|----------|--------|"
+
+    stats1 = comparison[:stats][comparison[:tool1]]
+    stats2 = comparison[:stats][comparison[:tool2]]
+
+    # Handle nil throughput gracefully
+    fps1 = stats1[:throughput]&.[](:files_per_second) || "N/A"
+    fps2 = stats2[:throughput]&.[](:files_per_second) || "N/A"
+
+    lines << "| Avg Time | #{stats1[:execution_time][:mean]}ms | " \
+             "#{stats2[:execution_time][:mean]}ms | " \
+             "#{comparison[:faster_tool]} |"
+    lines << "| Files/sec | #{fps1} | #{fps2} | " \
+             "#{comparison[:faster_tool]} |"
+    lines << "| Peak Memory | #{stats1[:memory][:mean]} MB | " \
+             "#{stats2[:memory][:mean]} MB | " \
+             "#{comparison[:memory_efficient_tool]} |"
+    lines << ""
+    lines << "**Performance:** #{comparison[:faster_tool]} is " \
+             "#{comparison[:time_multiplier]}x faster " \
+             "(#{comparison[:time_difference_percent]}% improvement)"
+    lines << ""
+    lines << "**Memory:** #{comparison[:memory_efficient_tool]} uses " \
+             "#{comparison[:memory_multiplier]}x less memory " \
+             "(#{comparison[:memory_difference_percent]}% improvement)"
+
+    lines.join("\n")
+  end
+
+  # Format statistics for markdown.
+  def format_markdown_statistics(stats)
+    lines = []
+    lines << "### #{stats[:tool]}"
+    lines << ""
+    lines << "- **Successful runs**: #{stats[:successful_runs]}/#{stats[:total_runs]}"
+    lines << "- **Timeouts**: #{stats[:timeouts]}" if stats[:timeouts].positive?
+    lines << ""
+    lines << "**Execution Time:**"
+    lines << "- Mean: #{stats[:execution_time][:mean]}ms"
+    lines << "- Median: #{stats[:execution_time][:median]}ms"
+    lines << "- Range: #{stats[:execution_time][:min]}ms - #{stats[:execution_time][:max]}ms"
+    lines << ""
+    lines << "**Memory Usage:**"
+    lines << "- Mean: #{stats[:memory][:mean]} MB"
+    lines << "- Range: #{stats[:memory][:min]} MB - #{stats[:memory][:max]} MB"
+
+    # Handle nil throughput gracefully
+    if stats[:throughput]
+      lines << ""
+      lines << "**Throughput:** #{stats[:throughput][:files_per_second]} files/sec"
+    end
+
+    lines.join("\n")
+  end
+end

data/benchmarks/lib/tool_runner.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Base class for running validation tools and measuring their performance.
+#
+# Provides a common interface for executing different PNG validation tools
+# (png_conform, pngcheck) and collecting performance metrics.
+class ToolRunner
+  attr_reader :name, :command, :options
+
+  # @param name [String] The name of the tool
+  # @param command [String] The command to execute
+  # @param options [Hash] Tool-specific options
+  def initialize(name, command, options = {})
+    @name = name
+    @command = command
+    @options = options
+  end
+
+  # Check if the tool is available on the system.
+  #
+  # @return [Boolean] True if tool is available
+  def available?
+    system("which #{command} > /dev/null 2>&1")
+  end
+
+  # Run the tool on a single file and measure performance.
+  #
+  # @param file_path [String] Path to the PNG file
+  # @return [Hash] Performance metrics and results
+  def run(file_path)
+    raise NotImplementedError, "Subclasses must implement #run"
+  end
+
+  # Run the tool on multiple files.
+  #
+  # @param file_paths [Array<String>] Paths to PNG files
+  # @return [Array<Hash>] Array of performance metrics
+  def run_batch(file_paths)
+    file_paths.map { |path| run(path) }
+  end
+
+  protected
+
+  # Measure execution time and memory usage.
+  #
+  # @yield Block to measure
+  # @return [Hash] Performance metrics
+  def measure_performance
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    start_memory = get_memory_usage
+
+    result = yield
+
+    end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end_memory = get_memory_usage
+
+    {
+      execution_time: ((end_time - start_time) * 1000).round(3), # milliseconds
+      memory_used: end_memory - start_memory,
+      peak_memory: end_memory,
+      result: result,
+    }
+  end
+
+  # Get current memory usage in MB.
+  #
+  # @return [Float] Memory usage in megabytes
+  def get_memory_usage
+    # Get RSS (Resident Set Size) in KB, convert to MB
+    rss_kb = `ps -o rss= -p #{Process.pid}`.strip.to_i
+    (rss_kb / 1024.0).round(2)
+  end
+
+  # Execute a command and capture output.
+  #
+  # @param cmd [String] Command to execute
+  # @param timeout [Integer] Timeout in seconds
+  # @return [Hash] Command result with stdout, stderr, and exit status
+  def execute_command(cmd, timeout: 30)
+    require "open3"
+    require "timeout"
+
+    stdout, stderr, status = nil
+    begin
+      Timeout.timeout(timeout) do
+        stdout, stderr, status = Open3.capture3(cmd)
+      end
+    rescue Timeout::Error
+      return {
+        stdout: "",
+        stderr: "Command timed out after #{timeout} seconds",
+        exit_code: -1,
+        timed_out: true,
+      }
+    end
+
+    {
+      stdout: stdout,
+      stderr: stderr,
+      exit_code: status.exitstatus,
+      timed_out: false,
+    }
+  end
+end

data/benchmarks/profile_loading.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ruby-prof"
+
+# Profile just the loading of png_conform
+result = RubyProf::Profile.profile do
+  require_relative "../lib/png_conform"
+end
+
+printer = RubyProf::FlatPrinter.new(result)
+printer.print($stdout, min_percent: 2)

data/benchmarks/profile_validation.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ruby-prof"
+require_relative "../lib/png_conform"
+
+# Pre-load everything
+PngConform::Services::ValidationService
+
+# Now profile just the validation work
+file = ARGV[0] || "spec/fixtures/pngsuite/compression/z00n2c08.png"
+
+result = RubyProf.profile do
+  PngConform::Services::ValidationService.validate_file(file)
+end
+
+printer = RubyProf::FlatPrinter.new(result)
+printer.print($stdout, min_percent: 1)

data/benchmarks/run_benchmark.rb

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+require_relative "lib/benchmark_runner"
+
+# Parse command-line options
+options = {
+  config_file: nil,
+  pattern: nil,
+  format: nil,
+  output: nil,
+  iterations: nil,
+  warmup: nil,
+  limit: nil,
+  tools: [],
+  verbose: true,
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: run_benchmark.rb [options]"
+
+  opts.separator ""
+  opts.separator "Configuration:"
+
+  opts.on("-c", "--config FILE", "Load configuration from YAML file") do |file|
+    options[:config_file] = file
+  end
+
+  opts.separator ""
+  opts.separator "File Selection:"
+
+  opts.on("-p", "--pattern PATTERN",
+          "File pattern (e.g., 'spec/fixtures/**/*.png')") do |pattern|
+    options[:pattern] = pattern
+  end
+
+  opts.on("-l", "--limit N", Integer, "Limit number of files to test") do |n|
+    options[:limit] = n
+  end
+
+  opts.separator ""
+  opts.separator "Execution:"
+
+  opts.on("-i", "--iterations N", Integer,
+          "Number of iterations per file (default: 3)") do |n|
+    options[:iterations] = n
+  end
+
+  opts.on("-w", "--warmup N", Integer,
+          "Number of warmup runs (default: 1)") do |n|
+    options[:warmup] = n
+  end
+
+  opts.on("-t", "--tool TOOL",
+          "Enable specific tool (png_conform, pngcheck)") do |tool|
+    options[:tools] << tool.to_sym
+  end
+
+  opts.separator ""
+  opts.separator "Output:"
+
+  opts.on("-f", "--format FORMAT",
+          "Output format: text, json, csv, markdown (default: text)") do |format|
+    options[:format] = format
+  end
+
+  opts.on("-o", "--output FILE",
+          "Write report to file instead of stdout") do |file|
+    options[:output] = file
+  end
+
+  opts.on("-q", "--quiet", "Suppress progress output") do
+    options[:verbose] = false
+  end
+
+  opts.separator ""
+  opts.separator "Other:"
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "PNG Benchmark Runner v1.0.0"
+    exit
+  end
+end.parse!
+
+# Load configuration
+config = {}
+
+if options[:config_file]
+  unless File.exist?(options[:config_file])
+    puts "Error: Configuration file not found: #{options[:config_file]}"
+    exit 1
+  end
+
+  config = YAML.load_file(options[:config_file], symbolize_names: true)
+end
+
+# Apply command-line overrides
+if options[:pattern]
+  config[:test_files] ||= {}
+  config[:test_files][:pattern] = options[:pattern]
+end
+
+if options[:limit]
+  config[:test_files] ||= {}
+  config[:test_files][:limit] = options[:limit]
+end
+
+config[:iterations] = options[:iterations] if options[:iterations]
+config[:warmup_runs] = options[:warmup] if options[:warmup]
+
+if options[:format]
+  config[:output] ||= {}
+  config[:output][:format] = options[:format]
+end
+
+if options[:output]
+  config[:output] ||= {}
+  config[:output][:file] = options[:output]
+end
+
+config[:output] ||= {}
+config[:output][:verbose] = options[:verbose]
+
+# Configure tools if specified
+if options[:tools].any?
+  config[:tools] ||= {}
+
+  # Disable all tools by default if specific tools are requested
+  config[:tools][:png_conform] = { enabled: false, options: {} }
+  config[:tools][:pngcheck] = { enabled: false, options: {} }
+
+  # Enable requested tools
+  options[:tools].each do |tool|
+    if config[:tools].key?(tool)
+      config[:tools][tool][:enabled] = true
+    else
+      puts "Warning: Unknown tool '#{tool}', ignoring"
+    end
+  end
+end
+
+# Run the benchmark
+begin
+  runner = BenchmarkRunner.new(config)
+  runner.run
+
+  exit 0
+rescue StandardError => e
+  puts "\nError: #{e.message}"
+  puts e.backtrace.join("\n") if ENV["DEBUG"]
+  exit 1
+end

data/docs/CHUNK_TYPES.adoc

@@ -240,6 +240,48 @@ Complete reference of all PNG, MNG, JNG, and APNG chunk types validated by PngCo
 **Size**: 1 byte
 **Values**: 0=cross-fuse, 1=diverging-fuse
 
+== Apple Extensions
+
+=== iDOT (Apple Display Optimization)
+
+**Purpose**: Apple-specific display optimization data for Retina displays
+**Size**: 28 bytes
+**Optional**: Only present in screenshots and images saved from macOS/iOS devices
+
+**Contents**:
+
+* Display scale factor (4 bytes, little-endian)
+* Pixel format information (4 bytes, little-endian)
+* Color space information (4 bytes, little-endian)
+* Backing scale factor (4 bytes, little-endian)
+* Flags (4 bytes, little-endian)
+* Reserved field 1 (4 bytes, little-endian)
+* Reserved field 2 (4 bytes, little-endian)
+
+**Validation**:
+
+* Chunk must be exactly 28 bytes
+* Only one iDOT chunk allowed per file
+* Must appear before IDAT chunk
+* CRC must be valid
+
+**Usage**:
+
+The iDOT chunk is automatically added by macOS and iOS when saving screenshots or images through system APIs. It contains display optimization data for:
+
+* Retina display rendering
+* Multi-core decoding performance
+* Display color space information
+* Backing store scale factors
+
+This chunk is safe to ignore for standard PNG decoders, as it follows the ancillary chunk naming convention (lowercase first letter).
+
+**References**:
+
+* Apple proprietary format
+* Found in PNG files generated by macOS 10.7+ and iOS 5+
+* Commonly seen in screenshot files
+
 == APNG (Animated PNG) Chunks
 
 === acTL (Animation Control)