fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variation/delta_parser.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Variation
+    # Parses variation deltas from gvar tuple data
+    #
+    # The gvar table stores deltas in various compression formats to minimize
+    # file size. This parser handles all delta formats and decompresses them
+    # into usable point delta arrays.
+    #
+    # Delta Formats:
+    # - DELTAS_ARE_ZERO: All deltas are zero (no data stored)
+    # - DELTAS_ARE_WORDS: Deltas stored as signed 16-bit words
+    # - DELTAS_ARE_BYTES: Deltas stored as signed 8-bit bytes
+    # - Point number runs: Compressed sequences of affected points
+    #
+    # Reference: OpenType specification, gvar table delta encoding
+    #
+    # @example Parsing delta data
+    #   parser = Fontisan::Variation::DeltaParser.new
+    #   deltas = parser.parse(tuple_data, point_count)
+    #   # Returns: [{ x: 10, y: 5 }, { x: -3, y: 2 }, ...]
+    class DeltaParser
+      # Delta format flags (from tuple variation header flags)
+      DELTAS_ARE_ZERO = 0x80
+      DELTAS_ARE_WORDS = 0x40
+
+      # Point number flags
+      POINTS_ARE_WORDS = 0x80
+      POINT_RUN_COUNT_MASK = 0x7F
+
+      # Parse delta data from tuple variation
+      #
+      # @param data [String] Binary delta data
+      # @param point_count [Integer] Total number of points in glyph
+      # @param private_points [Boolean] Whether tuple has private point numbers
+      # @param shared_points [Array<Integer>, nil] Shared point numbers if applicable
+      # @return [Array<Hash>] Array of point deltas { x:, y: }
+      # @raise [VariationDataCorruptedError] If delta data is corrupted or cannot be parsed
+      def parse(data, point_count, private_points: false, shared_points: nil)
+        return zero_deltas(point_count) if data.nil? || data.empty?
+
+        io = StringIO.new(data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Parse point numbers if present
+        points = if private_points
+                   parse_point_numbers(io)
+                 elsif shared_points
+                   shared_points
+                 else
+                   # All points affected
+                   (0...point_count).to_a
+                 end
+
+        # Determine delta format from first byte (if present)
+        format_byte = io.getbyte
+        return zero_deltas(point_count) if format_byte.nil?
+
+        io.pos -= 1 # Put byte back
+
+        # Parse X deltas
+        x_deltas = parse_delta_array(io, points.length)
+
+        # Parse Y deltas
+        y_deltas = parse_delta_array(io, points.length)
+
+        # Build full delta array (zero for untouched points)
+        build_full_deltas(points, x_deltas, y_deltas, point_count)
+      rescue StandardError => e
+        raise VariationDataCorruptedError.new(
+          message: "Failed to parse delta data: #{e.message}",
+          details: {
+            point_count: point_count,
+            private_points: private_points,
+            error_class: e.class.name,
+          },
+        )
+      end
+
+      # Parse delta data with explicit format flag
+      #
+      # @param data [String] Binary delta data
+      # @param point_count [Integer] Total number of points
+      # @param flags [Integer] Tuple variation flags
+      # @return [Array<Hash>] Array of point deltas
+      def parse_with_flags(data, point_count, flags)
+        if (flags & DELTAS_ARE_ZERO).zero?
+          parse(data, point_count)
+        else
+          zero_deltas(point_count)
+        end
+      end
+
+      private
+
+      # Parse point numbers from packed format
+      #
+      # Point numbers indicate which points have deltas. Uses run-length
+      # encoding to compress sequences of point numbers.
+      #
+      # @param io [StringIO] Input stream
+      # @return [Array<Integer>] Array of point numbers
+      def parse_point_numbers(io)
+        points = []
+        first_byte = io.getbyte
+        return points if first_byte.nil?
+
+        # First byte indicates total number of point numbers
+        total_points = first_byte
+
+        # Parse all point number runs
+        point_index = 0
+        remaining = total_points
+
+        while remaining.positive?
+          control = io.getbyte
+          return points if control.nil?
+
+          # Number of points in this run
+          run_count = (control & POINT_RUN_COUNT_MASK) + 1
+
+          # Limit run_count to remaining points
+          run_count = [run_count, remaining].min
+
+          if (control & POINTS_ARE_WORDS).zero?
+            # Points stored as 8-bit bytes (deltas from previous)
+            run_count.times do
+              byte = io.getbyte
+              return points if byte.nil?
+
+              point_index += byte
+              points << point_index
+              remaining -= 1
+            end
+          else
+            # Points stored as 16-bit words
+            run_count.times do
+              bytes = io.read(2)
+              return points if bytes.nil? || bytes.bytesize < 2
+
+              point = bytes.unpack1("n")
+              points << point
+              point_index = point
+              remaining -= 1
+            end
+          end
+        end
+
+        points
+      end
+
+      # Parse an array of delta values
+      #
+      # Deltas can be stored as bytes or words depending on value range.
+      # The format is determined by inspecting the first byte.
+      #
+      # @param io [StringIO] Input stream
+      # @param count [Integer] Number of deltas to parse
+      # @return [Array<Integer>] Array of delta values
+      def parse_delta_array(io, count)
+        return [] if count.zero?
+
+        deltas = []
+
+        # Read control byte to determine format
+        control = io.getbyte
+        return deltas if control.nil?
+
+        if (control & DELTAS_ARE_WORDS).zero?
+          # Deltas stored as 8-bit signed bytes
+          count.times do
+            byte = io.getbyte
+            return deltas if byte.nil?
+
+            signed = byte > 0x7F ? byte - 0x100 : byte
+            deltas << signed
+          end
+        else
+          # Deltas stored as 16-bit signed words
+          count.times do
+            bytes = io.read(2)
+            return deltas if bytes.nil? || bytes.bytesize < 2
+
+            value = bytes.unpack1("n")
+            signed = value > 0x7FFF ? value - 0x10000 : value
+            deltas << signed
+          end
+        end
+
+        deltas
+      end
+
+      # Build full delta array including untouched points
+      #
+      # @param points [Array<Integer>] Point numbers with deltas
+      # @param x_deltas [Array<Integer>] X deltas
+      # @param y_deltas [Array<Integer>] Y deltas
+      # @param point_count [Integer] Total points in glyph
+      # @return [Array<Hash>] Full delta array
+      def build_full_deltas(points, x_deltas, y_deltas, point_count)
+        full_deltas = Array.new(point_count) { { x: 0, y: 0 } }
+
+        points.each_with_index do |point_num, i|
+          next if point_num >= point_count
+          next if i >= x_deltas.length || i >= y_deltas.length
+
+          full_deltas[point_num] = {
+            x: x_deltas[i],
+            y: y_deltas[i],
+          }
+        end
+
+        full_deltas
+      end
+
+      # Create array of zero deltas
+      #
+      # @param count [Integer] Number of deltas
+      # @return [Array<Hash>] Array of zero deltas
+      def zero_deltas(count)
+        Array.new(count) { { x: 0, y: 0 } }
+      end
+    end
+  end
+end

data/lib/fontisan/variation/inspector.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require_relative "variation_context"
+
+module Fontisan
+  module Variation
+    # Inspects and analyzes variable font structure
+    #
+    # This class provides comprehensive analysis of variable font structure,
+    # including axes, instances, regions, and variation statistics. Results
+    # can be exported to JSON or YAML formats.
+    #
+    # @example Inspecting a variable font
+    #   inspector = Fontisan::Variation::Inspector.new(font)
+    #   info = inspector.inspect_variation
+    #   # => { axes: [...], instances: [...], regions: {...}, statistics: {...} }
+    #
+    # @example Exporting to JSON
+    #   inspector.export_json
+    #   # => "{ \"axes\": [...], ... }"
+    #
+    # @example Exporting to YAML
+    #   inspector.export_yaml
+    #   # => "---\naxes:\n  - ..."
+    class Inspector
+      # @return [TrueTypeFont, OpenTypeFont] Font to inspect
+      attr_reader :font
+
+      # @return [VariationContext] Variation context
+      attr_reader :context
+
+      # Initialize inspector
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font
+      def initialize(font)
+        @font = font
+        @context = VariationContext.new(font)
+      end
+
+      # Inspect complete variation structure
+      #
+      # Returns comprehensive information about font variation capabilities.
+      #
+      # @return [Hash] Complete variation information
+      def inspect_variation
+        {
+          axes: inspect_axes,
+          instances: inspect_instances,
+          regions: inspect_regions,
+          statistics: calculate_statistics,
+        }
+      end
+
+      # Export inspection results as JSON
+      #
+      # @return [String] JSON formatted output
+      def export_json
+        JSON.pretty_generate(inspect_variation)
+      end
+
+      # Export inspection results as YAML
+      #
+      # @return [String] YAML formatted output
+      def export_yaml
+        YAML.dump(inspect_variation)
+      end
+
+      # Check if font is a variable font
+      #
+      # @return [Boolean] True if font has variation tables
+      def variable_font?
+        @context.variable_font?
+      end
+
+      private
+
+      # Inspect variation axes
+      #
+      # @return [Array<Hash>] Array of axis information
+      def inspect_axes
+        return [] unless variable_font?
+        return [] unless @context.fvar
+
+        @context.axes.map do |axis|
+          {
+            tag: axis.axis_tag,
+            name: axis_name(axis.axis_name_id),
+            min: axis.min_value,
+            default: axis.default_value,
+            max: axis.max_value,
+            hidden: axis.flags & 0x0001 != 0,
+          }
+        end
+      end
+
+      # Inspect named instances
+      #
+      # @return [Array<Hash>] Array of instance information
+      def inspect_instances
+        return [] unless variable_font?
+        return [] unless @context.fvar
+
+        @context.fvar.instances.map.with_index do |instance, index|
+          {
+            index: index,
+            name: instance_name(instance[:subfamily_name_id]),
+            postscript_name: instance_name(instance[:postscript_name_id]),
+            coordinates: instance_coordinates(instance[:coordinates], @context.axes),
+          }
+        end
+      end
+
+      # Inspect variation regions
+      #
+      # @return [Hash] Region statistics and information
+      def inspect_regions
+        regions = {
+          gvar: nil,
+          hvar: nil,
+          vvar: nil,
+          mvar: nil,
+        }
+
+        if @font.has_table?("gvar")
+          regions[:gvar] = inspect_gvar_regions
+        end
+
+        if @font.has_table?("HVAR")
+          regions[:hvar] = inspect_hvar_regions
+        end
+
+        if @font.has_table?("VVAR")
+          regions[:vvar] = inspect_vvar_regions
+        end
+
+        if @font.has_table?("MVAR")
+          regions[:mvar] = inspect_mvar_regions
+        end
+
+        regions.compact
+      end
+
+      # Inspect gvar table regions
+      #
+      # @return [Hash] Gvar region information
+      def inspect_gvar_regions
+        gvar = @font.table("gvar")
+        return nil unless gvar
+
+        {
+          glyph_count: gvar.glyph_count,
+          axis_count: gvar.axis_count,
+          shared_tuples: gvar.shared_tuple_count || 0,
+          glyph_variation_data_present: gvar.glyph_count.positive?,
+        }
+      end
+
+      # Inspect HVAR table regions
+      #
+      # @return [Hash] HVAR region information
+      def inspect_hvar_regions
+        hvar = @font.table("HVAR")
+        return nil unless hvar
+
+        {
+          advance_width_mapping: hvar.advance_width_mapping ? true : false,
+          lsb_mapping: hvar.lsb_mapping ? true : false,
+          rsb_mapping: hvar.rsb_mapping ? true : false,
+        }
+      end
+
+      # Inspect VVAR table regions
+      #
+      # @return [Hash] VVAR region information
+      def inspect_vvar_regions
+        vvar = @font.table("VVAR")
+        return nil unless vvar
+
+        {
+          advance_height_mapping: vvar.advance_height_mapping ? true : false,
+          tsb_mapping: vvar.tsb_mapping ? true : false,
+          bsb_mapping: vvar.bsb_mapping ? true : false,
+        }
+      end
+
+      # Inspect MVAR table regions
+      #
+      # @return [Hash] MVAR region information
+      def inspect_mvar_regions
+        mvar = @font.table("MVAR")
+        return nil unless mvar
+
+        {
+          value_record_count: mvar.value_record_count || 0,
+          metrics_varied: mvar.value_records&.map { |r| r[:value_tag] } || [],
+        }
+      end
+
+      # Calculate variation statistics
+      #
+      # @return [Hash] Statistical information
+      def calculate_statistics
+        stats = {
+          is_variable: variable_font?,
+          axis_count: 0,
+          instance_count: 0,
+          has_glyph_variations: @context.has_glyph_variations?,
+          has_metrics_variations: @context.has_metrics_variations?,
+          variation_tables: [],
+        }
+
+        if variable_font?
+          stats[:axis_count] = @context.axis_count
+          stats[:instance_count] = @context.fvar.instance_count if @context.fvar
+        end
+
+        # List variation tables present
+        variation_table_tags = %w[fvar gvar cvar HVAR VVAR MVAR avar STAT]
+        stats[:variation_tables] = variation_table_tags.select do |tag|
+          @font.has_table?(tag)
+        end
+
+        # Calculate design space size
+        if stats[:axis_count].positive?
+          stats[:design_space_dimensions] = stats[:axis_count]
+        end
+
+        stats
+      end
+
+      # Get axis name from name table
+      #
+      # @param name_id [Integer] Name ID
+      # @return [String] Axis name
+      def axis_name(name_id)
+        return "Unknown" unless @font.has_table?("name")
+
+        name_table = @font.table("name")
+        record = name_table.names.find { |n| n[:name_id] == name_id }
+        record ? record[:string] : "Axis #{name_id}"
+      end
+
+      # Get instance name from name table
+      #
+      # @param name_id [Integer] Name ID
+      # @return [String, nil] Instance name
+      def instance_name(name_id)
+        return nil unless name_id
+        return nil unless @font.has_table?("name")
+
+        name_table = @font.table("name")
+        record = name_table.names.find { |n| n[:name_id] == name_id }
+        record ? record[:string] : "Instance #{name_id}"
+      end
+
+      # Build coordinates hash from instance
+      #
+      # @param coordinates [Array<Float>] Coordinate values
+      # @param axes [Array] Variation axes
+      # @return [Hash<String, Float>] Coordinates by axis tag
+      def instance_coordinates(coordinates, axes)
+        coords = {}
+        coordinates.each_with_index do |value, index|
+          break if index >= axes.length
+
+          axis = axes[index]
+          coords[axis.axis_tag] = value
+        end
+        coords
+      end
+    end
+  end
+end