fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variation/region_matcher.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Variation
+    # Region matcher for variable fonts
+    #
+    # This class matches design space coordinates to variation regions/tuples,
+    # determining which regions contribute to the final interpolated value
+    # and calculating their contribution scalars.
+    #
+    # A variation region defines a sub-space within the design space where
+    # a particular set of deltas applies. Regions are defined by start, peak,
+    # and end coordinates on each axis.
+    #
+    # Matching Process:
+    # 1. For each region, check if current coordinates fall within the region
+    # 2. Calculate the scalar (contribution factor) for each matching region
+    # 3. Return only non-zero contributions
+    #
+    # Reference: OpenType Font Variations specification, gvar table
+    #
+    # @example Matching coordinates to regions
+    #   matcher = RegionMatcher.new(axes)
+    #   matches = matcher.match_regions(
+    #     coordinates: { "wght" => 600.0 },
+    #     regions: [region1, region2, region3]
+    #   )
+    #   # => [{ region_index: 0, scalar: 0.5 }, { region_index: 1, scalar: 0.8 }]
+    class RegionMatcher
+      # @return [Array<VariationAxisRecord>] Variation axes
+      attr_reader :axes
+
+      # @return [Interpolator] Coordinate interpolator
+      attr_reader :interpolator
+
+      # Initialize region matcher
+      #
+      # @param axes [Array<VariationAxisRecord>] Variation axes from fvar table
+      def initialize(axes)
+        @axes = axes || []
+        @interpolator = Interpolator.new(@axes)
+      end
+
+      # Match coordinates to variation regions
+      #
+      # Returns all regions that contribute (have non-zero scalar) at the
+      # given coordinates, along with their contribution scalars.
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param regions [Array<Hash>] Array of region definitions
+      # @return [Array<Hash>] Matches with :region_index and :scalar
+      def match_regions(coordinates:, regions:)
+        # Normalize coordinates
+        normalized = @interpolator.normalize_coordinates(coordinates)
+
+        # Find matching regions
+        matches = []
+        regions.each_with_index do |region, index|
+          scalar = @interpolator.calculate_region_scalar(normalized, region)
+
+          # Only include non-zero contributions
+          matches << { region_index: index, scalar: scalar } if scalar > 0.0
+        end
+
+        matches
+      end
+
+      # Match coordinates to gvar tuple variations
+      #
+      # Converts gvar tuple data to regions and matches them.
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param tuples [Array<Hash>] Tuple variation data from gvar
+      # @return [Array<Hash>] Matches with :tuple_index and :scalar
+      def match_tuples(coordinates:, tuples:)
+        # Convert tuples to regions
+        regions = tuples.map do |tuple|
+          @interpolator.build_region_from_tuple(tuple)
+        end
+
+        # Match regions
+        match_regions(coordinates: coordinates, regions: regions)
+      end
+
+      # Check if coordinates are within a region
+      #
+      # @param coordinates [Hash<String, Float>] Normalized coordinates
+      # @param region [Hash<String, Hash>] Region definition per axis
+      # @return [Boolean] True if within region
+      def within_region?(coordinates, region)
+        region.all? do |axis_tag, axis_region|
+          coord = coordinates[axis_tag] || 0.0
+          start_val = axis_region[:start] || -1.0
+          end_val = axis_region[:end] || 1.0
+
+          coord >= start_val && coord <= end_val
+        end
+      end
+
+      # Get active regions at coordinates
+      #
+      # Returns the subset of regions that are active (non-zero contribution)
+      # at the given coordinates.
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param regions [Array<Hash>] All regions
+      # @return [Array<Integer>] Indices of active regions
+      def active_region_indices(coordinates, regions)
+        matches = match_regions(coordinates: coordinates, regions: regions)
+        matches.map { |m| m[:region_index] }
+      end
+
+      # Calculate contribution percentages for all regions
+      #
+      # Returns the percentage contribution of each region at the given
+      # coordinates. All percentages sum to 100% (or less if some regions
+      # are inactive).
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param regions [Array<Hash>] All regions
+      # @return [Array<Float>] Contribution percentages (0.0 to 1.0)
+      def contribution_percentages(coordinates, regions)
+        matches = match_regions(coordinates: coordinates, regions: regions)
+
+        # Calculate total scalar
+        total_scalar = matches.sum { |m| m[:scalar] }
+        return Array.new(regions.size, 0.0) if total_scalar.zero?
+
+        # Build percentage array
+        percentages = Array.new(regions.size, 0.0)
+        matches.each do |match|
+          percentages[match[:region_index]] = match[:scalar] / total_scalar
+        end
+
+        percentages
+      end
+
+      # Find the dominant region at coordinates
+      #
+      # Returns the region with the highest contribution scalar.
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param regions [Array<Hash>] All regions
+      # @return [Hash, nil] Match with highest scalar or nil
+      def dominant_region(coordinates, regions)
+        matches = match_regions(coordinates: coordinates, regions: regions)
+        return nil if matches.empty?
+
+        matches.max_by { |m| m[:scalar] }
+      end
+
+      # Build region from peak coordinates
+      #
+      # Creates a simple region definition from peak coordinates only,
+      # using ±1.0 for start/end on each axis.
+      #
+      # @param peaks [Hash<String, Float>] Peak coordinates per axis
+      # @return [Hash<String, Hash>] Region definition
+      def build_region_from_peaks(peaks)
+        region = {}
+
+        @axes.each do |axis|
+          tag = axis.axis_tag
+          peak = peaks[tag] || 0.0
+
+          region[tag] = {
+            start: peak.negative? ? -1.0 : 0.0,
+            peak: peak,
+            end: peak.positive? ? 1.0 : 0.0,
+          }
+        end
+
+        region
+      end
+
+      # Build region from start, peak, end arrays
+      #
+      # Converts array-based region data (as in gvar) to hash-based format.
+      #
+      # @param start_arr [Array<Float>] Start coordinates (one per axis)
+      # @param peak_arr [Array<Float>] Peak coordinates (one per axis)
+      # @param end_arr [Array<Float>] End coordinates (one per axis)
+      # @return [Hash<String, Hash>] Region definition
+      def build_region_from_arrays(start_arr, peak_arr, end_arr)
+        region = {}
+
+        @axes.each_with_index do |axis, index|
+          region[axis.axis_tag] = {
+            start: start_arr[index] || -1.0,
+            peak: peak_arr[index] || 0.0,
+            end: end_arr[index] || 1.0,
+          }
+        end
+
+        region
+      end
+
+      # Validate region definition
+      #
+      # Checks if a region is well-formed.
+      #
+      # @param region [Hash<String, Hash>] Region definition
+      # @return [Boolean] True if valid
+      def valid_region?(region)
+        return false unless region.is_a?(Hash)
+
+        region.all? do |_axis_tag, axis_region|
+          next false unless axis_region.is_a?(Hash)
+          next false unless axis_region.key?(:peak)
+
+          start_val = axis_region[:start] || -1.0
+          peak = axis_region[:peak]
+          end_val = axis_region[:end] || 1.0
+
+          # Validate ordering: start <= peak <= end
+          start_val <= peak && peak <= end_val
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/variation/subsetter.rb

@@ -0,0 +1,463 @@
+# frozen_string_literal: true
+
+require_relative "validator"
+require_relative "optimizer"
+require_relative "table_accessor"
+
+module Fontisan
+  module Variation
+    # Subset variable fonts while preserving variation
+    #
+    # This class enables subsetting operations on variable fonts while
+    # maintaining variation capabilities. It can subset by glyphs, axes,
+    # or both, and includes validation to ensure the resulting subset
+    # remains a valid variable font.
+    #
+    # Subsetting operations:
+    # 1. Glyph subsetting - Keep only specified glyphs with their variations
+    # 2. Axis subsetting - Keep only specified axes
+    # 3. Region simplification - Deduplicate and merge similar regions
+    # 4. Validation - Ensure subset integrity
+    #
+    # @example Subset to specific glyphs
+    #   subsetter = Fontisan::Variation::Subsetter.new(font)
+    #   result = subsetter.subset_glyphs([0, 1, 2, 3])
+    #
+    # @example Subset to specific axes
+    #   subsetter = Fontisan::Variation::Subsetter.new(font)
+    #   result = subsetter.subset_axes(["wght", "wdth"])
+    class Subsetter
+      include TableAccessor
+
+      # @return [TrueTypeFont, OpenTypeFont] Font being subset
+      attr_reader :font
+
+      # @return [Validator] Validation utility
+      attr_reader :validator
+
+      # @return [Hash] Subsetter options
+      attr_reader :options
+
+      # @return [Hash] Last operation report
+      attr_reader :report
+
+      # Initialize subsetter
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font to subset
+      # @param options [Hash] Subsetter options
+      # @option options [Boolean] :validate Validate before/after subsetting (default: true)
+      # @option options [Boolean] :optimize Optimize after subsetting (default: true)
+      # @option options [Float] :region_threshold Region similarity threshold (default: 0.01)
+      def initialize(font, options = {})
+        @font = font
+        @validator = Validator.new(font)
+        @options = {
+          validate: true,
+          optimize: true,
+          region_threshold: 0.01,
+        }.merge(options)
+        @report = {}
+        @variation_tables = {}
+      end
+
+      # Subset glyphs while preserving variation
+      #
+      # Filters variation data to keep only specified glyphs.
+      #
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      # @return [Hash] Subset result with :tables and :report
+      def subset_glyphs(glyph_ids)
+        validate_input if @options[:validate]
+
+        @report = {
+          operation: :subset_glyphs,
+          original_glyph_count: get_glyph_count,
+          subset_glyph_count: glyph_ids.length,
+          glyphs_removed: get_glyph_count - glyph_ids.length,
+        }
+
+        # Start with all tables
+        tables = @font.table_data.dup
+
+        # Subset gvar if present
+        if has_variation_table?("gvar")
+          subset_gvar_table(tables, glyph_ids)
+          @report[:gvar_updated] = true
+        end
+
+        # Subset CFF2 if present
+        if has_variation_table?("CFF2")
+          subset_cff2_table(tables, glyph_ids)
+          @report[:cff2_updated] = true
+        end
+
+        # Subset metrics variations
+        subset_metrics_variations(tables, glyph_ids)
+
+        # Update non-variation tables
+        update_glyph_tables(tables, glyph_ids)
+
+        validate_output(tables) if @options[:validate]
+
+        { tables: tables, report: @report }
+      end
+
+      # Filter to specific axes
+      #
+      # Removes unused axes and updates all variation tables.
+      #
+      # @param axis_tags [Array<String>] Axis tags to keep (e.g., ["wght", "wdth"])
+      # @return [Hash] Subset result with :tables and :report
+      def subset_axes(axis_tags)
+        validate_input if @options[:validate]
+
+        fvar = variation_table("fvar")
+        return { tables: @font.table_data.dup, report: { error: "No fvar table" } } unless fvar
+
+        # Find axes to keep
+        all_axes = fvar.axes
+        keep_axes = all_axes.select { |axis| axis_tags.include?(axis.axis_tag) }
+        keep_indices = keep_axes.map { |axis| all_axes.index(axis) }
+
+        @report = {
+          operation: :subset_axes,
+          original_axis_count: all_axes.length,
+          subset_axis_count: keep_axes.length,
+          axes_removed: all_axes.length - keep_axes.length,
+          removed_axes: (all_axes.map(&:axis_tag) - axis_tags),
+        }
+
+        # Start with all tables
+        tables = @font.table_data.dup
+
+        # Update fvar table
+        subset_fvar_table(tables, keep_axes, keep_indices)
+
+        # Update gvar if present
+        if has_variation_table?("gvar")
+          subset_gvar_axes(tables, keep_indices)
+          @report[:gvar_updated] = true
+        end
+
+        # Update CFF2 if present
+        if has_variation_table?("CFF2")
+          subset_cff2_axes(tables, keep_indices)
+          @report[:cff2_updated] = true
+        end
+
+        # Update metrics variation tables
+        subset_metrics_axes(tables, keep_indices)
+
+        validate_output(tables) if @options[:validate]
+
+        { tables: tables, report: @report }
+      end
+
+      # Simplify regions within threshold
+      #
+      # Uses VariationOptimizer to deduplicate regions.
+      #
+      # @param threshold [Float] Similarity threshold (default: from options)
+      # @return [Hash] Simplification result with :tables and :report
+      def simplify_regions(threshold: nil)
+        threshold ||= @options[:region_threshold]
+
+        @report = {
+          operation: :simplify_regions,
+          threshold: threshold,
+        }
+
+        tables = @font.table_data.dup
+
+        # Optimize CFF2 if present
+        if has_variation_table?("CFF2")
+          cff2 = variation_table("CFF2")
+          optimizer = Optimizer.new(cff2, region_threshold: threshold)
+          optimizer.optimize
+
+          @report[:regions_deduplicated] = optimizer.stats[:regions_deduplicated]
+          @report[:cff2_optimized] = true
+        end
+
+        # Simplify metrics table regions
+        simplify_metrics_regions(tables, threshold)
+
+        validate_output(tables) if @options[:validate]
+
+        { tables: tables, report: @report }
+      end
+
+      # Combined subset operation
+      #
+      # Performs multiple subsetting operations in sequence.
+      #
+      # @param glyphs [Array<Integer>, nil] Glyph IDs to keep (nil = all)
+      # @param axes [Array<String>, nil] Axis tags to keep (nil = all)
+      # @param simplify [Boolean] Simplify regions after subsetting
+      # @return [Hash] Combined result with :tables and :report
+      def subset(glyphs: nil, axes: nil, simplify: true)
+        # Don't validate input here - let sub-methods handle it
+        # to avoid multiple validations
+
+        steps = []
+        tables = @font.table_data.dup
+
+        # Step 1: Subset glyphs if specified
+        if glyphs
+          subsetter = Subsetter.new(@font, @options)
+          glyph_result = subsetter.subset_glyphs(glyphs)
+          tables = glyph_result[:tables]
+          steps << { step: :subset_glyphs, report: glyph_result[:report] }
+        end
+
+        # Step 2: Subset axes if specified
+        if axes
+          # Create temporary font wrapper with subset tables
+          temp_font = create_temp_font(tables)
+          axis_subsetter = Subsetter.new(temp_font, @options)
+          axis_result = axis_subsetter.subset_axes(axes)
+          tables = axis_result[:tables]
+          steps << { step: :subset_axes, report: axis_result[:report] }
+        end
+
+        # Step 3: Simplify regions if requested
+        if simplify && @options[:optimize]
+          temp_font = create_temp_font(tables)
+          region_subsetter = Subsetter.new(temp_font, @options)
+          simplify_result = region_subsetter.simplify_regions
+          tables = simplify_result[:tables]
+          steps << { step: :simplify_regions, report: simplify_result[:report] }
+        end
+
+        # Create combined report
+        @report = {
+          operation: :combined_subset,
+          steps: steps,
+        }
+
+        # Validate final output if requested
+        if @options[:validate]
+          validate_output(tables)
+        end
+
+        { tables: tables, report: @report }
+      end
+
+      private
+
+      # Validate input font
+      # @raise [InvalidVariationDataError] If font is invalid
+      def validate_input
+        result = @validator.validate
+        return if result[:valid]
+
+        errors = result[:errors].join(", ")
+        raise InvalidVariationDataError.new(
+          message: "Invalid input font: #{errors}",
+          details: { validation_errors: result[:errors] },
+        )
+      end
+
+      # Validate output tables
+      #
+      # @param tables [Hash] Output tables
+      def validate_output(tables)
+        temp_font = create_temp_font(tables)
+        validator = Validator.new(temp_font)
+        result = validator.validate
+
+        @report[:validation] = result
+
+        unless result[:valid]
+          @report[:validation_errors] = result[:errors]
+        end
+      end
+
+      # Get glyph count from maxp table
+      #
+      # @return [Integer] Glyph count
+      def get_glyph_count
+        maxp = variation_table("maxp")
+        maxp ? maxp.num_glyphs : 0
+      end
+
+      # Subset gvar table to specific glyphs
+      #
+      # @param tables [Hash] Font tables
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      def subset_gvar_table(_tables, _glyph_ids)
+        # This is a placeholder - full implementation would:
+        # 1. Read gvar table
+        # 2. Extract variation data for keep glyphs
+        # 3. Rebuild glyph variation data array with new offsets
+        # 4. Update glyph_count
+        # 5. Serialize back to binary
+
+        @report[:gvar_note] = "gvar subsetting not yet implemented"
+      end
+
+      # Subset CFF2 table to specific glyphs
+      #
+      # @param tables [Hash] Font tables
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      def subset_cff2_table(_tables, _glyph_ids)
+        # This is a placeholder - full implementation would:
+        # 1. Read CFF2 table
+        # 2. Extract CharStrings for keep glyphs
+        # 3. Rebuild CharString INDEX
+        # 4. Update FDSelect if present
+        # 5. Serialize back to binary
+
+        @report[:cff2_note] = "CFF2 subsetting not yet implemented"
+      end
+
+      # Subset metrics variation tables
+      #
+      # @param tables [Hash] Font tables
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      def subset_metrics_variations(tables, glyph_ids)
+        subset_metrics_table(tables, "HVAR", glyph_ids) if has_variation_table?("HVAR")
+        subset_metrics_table(tables, "VVAR", glyph_ids) if has_variation_table?("VVAR")
+        # MVAR is font-wide, no glyph subsetting needed
+      end
+
+      # Subset a single metrics table
+      #
+      # @param tables [Hash] Font tables
+      # @param table_tag [String] Table tag
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      def subset_metrics_table(_tables, table_tag, _glyph_ids)
+        # This is a placeholder - full implementation would:
+        # 1. Read metrics table
+        # 2. Filter DeltaSetIndexMap to keep glyphs
+        # 3. Remove unused ItemVariationData
+        # 4. Rebuild and serialize
+
+        @report[:"#{table_tag.downcase}_note"] = "#{table_tag} subsetting not yet implemented"
+      end
+
+      # Update non-variation glyph tables
+      #
+      # @param tables [Hash] Font tables
+      # @param glyph_ids [Array<Integer>] Glyph IDs to keep
+      def update_glyph_tables(_tables, _glyph_ids)
+        # Update maxp
+        # Update glyf/loca or CFF
+        # Update cmap
+        # etc.
+
+        @report[:glyph_tables_note] = "Glyph table updates not yet implemented"
+      end
+
+      # Subset fvar table
+      #
+      # @param tables [Hash] Font tables
+      # @param keep_axes [Array] Axes to keep
+      # @param keep_indices [Array<Integer>] Axis indices to keep
+      def subset_fvar_table(_tables, _keep_axes, _keep_indices)
+        # This is a placeholder - full implementation would:
+        # 1. Rebuild fvar with subset axes
+        # 2. Update instances to remove coordinates for removed axes
+        # 3. Serialize back to binary
+
+        @report[:fvar_note] = "fvar subsetting not yet implemented"
+      end
+
+      # Subset gvar axes
+      #
+      # @param tables [Hash] Font tables
+      # @param keep_indices [Array<Integer>] Axis indices to keep
+      def subset_gvar_axes(_tables, _keep_indices)
+        # This is a placeholder - full implementation would:
+        # 1. Update axis_count
+        # 2. Filter shared tuples to keep indices
+        # 3. Filter tuple variations to keep indices
+        # 4. Serialize back to binary
+
+        @report[:gvar_axes_note] = "gvar axis subsetting not yet implemented"
+      end
+
+      # Subset CFF2 axes
+      #
+      # @param tables [Hash] Font tables
+      # @param keep_indices [Array<Integer>] Axis indices to keep
+      def subset_cff2_axes(_tables, _keep_indices)
+        # This is a placeholder - full implementation would:
+        # 1. Update num_axes in CFF2
+        # 2. Filter blend operands to keep indices
+        # 3. Update ItemVariationStore regions
+        # 4. Serialize back to binary
+
+        @report[:cff2_axes_note] = "CFF2 axis subsetting not yet implemented"
+      end
+
+      # Subset metrics table axes
+      #
+      # @param tables [Hash] Font tables
+      # @param keep_indices [Array<Integer>] Axis indices to keep
+      def subset_metrics_axes(tables, keep_indices)
+        subset_metrics_table_axes(tables, "HVAR", keep_indices) if has_variation_table?("HVAR")
+        subset_metrics_table_axes(tables, "VVAR", keep_indices) if has_variation_table?("VVAR")
+        subset_metrics_table_axes(tables, "MVAR", keep_indices) if has_variation_table?("MVAR")
+      end
+
+      # Subset a single metrics table's axes
+      #
+      # @param tables [Hash] Font tables
+      # @param table_tag [String] Table tag
+      # @param keep_indices [Array<Integer>] Axis indices to keep
+      def subset_metrics_table_axes(_tables, table_tag, _keep_indices)
+        # This is a placeholder - full implementation would:
+        # 1. Read metrics table
+        # 2. Filter ItemVariationStore regions to keep axis indices
+        # 3. Rebuild and serialize
+
+        @report[:"#{table_tag.downcase}_axes_note"] = "#{table_tag} axis subsetting not yet implemented"
+      end
+
+      # Simplify metrics table regions
+      #
+      # @param tables [Hash] Font tables
+      # @param threshold [Float] Similarity threshold
+      def simplify_metrics_regions(_tables, _threshold)
+        # This is a placeholder - full implementation would:
+        # 1. Load each metrics table
+        # 2. Deduplicate regions in ItemVariationStore
+        # 3. Update delta set indices
+        # 4. Serialize back to binary
+
+        @report[:metrics_simplify_note] = "Metrics region simplification not yet implemented"
+      end
+
+      # Create temporary font wrapper for validation
+      #
+      # @param tables [Hash] Table data
+      # @return [Object] Temporary font wrapper
+      def create_temp_font(tables)
+        # This is a simplified wrapper for validation
+        # In production, would create proper font object
+        Class.new do
+          attr_reader :table_data
+
+          def initialize(tables)
+            @table_data = tables
+            @parsed_tables = {}
+          end
+
+          def has_table?(tag)
+            @table_data.key?(tag)
+          end
+
+          def table(tag)
+            return @parsed_tables[tag] if @parsed_tables.key?(tag)
+            return nil unless has_table?(tag)
+
+            # Parse table on demand
+            # This is simplified - real implementation would use proper parsers
+            @parsed_tables[tag] = nil
+          end
+        end.new(tables)
+      end
+    end
+  end
+end