fontisan 0.1.0 → 0.2.0

data/lib/fontisan/svg/view_box_calculator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Svg
+    # Calculates SVG viewBox and handles coordinate transformations
+    #
+    # [`ViewBoxCalculator`](lib/fontisan/svg/view_box_calculator.rb) manages
+    # the coordinate system transformation between font space and SVG space.
+    # Font coordinates use a Y-up system (ascender is positive), while SVG
+    # uses Y-down (origin at top-left).
+    #
+    # Responsibilities:
+    # - Calculate appropriate viewBox for glyphs
+    # - Transform Y-coordinates (flip Y-axis)
+    # - Scale coordinates based on units-per-em
+    # - Provide consistent coordinate mapping
+    #
+    # This is a pure utility class with no state or side effects.
+    #
+    # @example Transform a Y coordinate
+    #   calculator = ViewBoxCalculator.new(units_per_em: 1000, ascent: 800, descent: -200)
+    #   svg_y = calculator.transform_y(700)  # Font Y to SVG Y
+    #
+    # @example Calculate viewBox for a glyph
+    #   viewbox = calculator.calculate_viewbox(x_min: 100, y_min: 0, x_max: 600, y_max: 700)
+    #   # => "100 100 500 700"
+    class ViewBoxCalculator
+      # @return [Integer] Units per em from font
+      attr_reader :units_per_em
+
+      # @return [Integer] Font ascent
+      attr_reader :ascent
+
+      # @return [Integer] Font descent (typically negative)
+      attr_reader :descent
+
+      # Initialize calculator with font metrics
+      #
+      # @param units_per_em [Integer] Units per em from font head table
+      # @param ascent [Integer] Font ascent from hhea table
+      # @param descent [Integer] Font descent from hhea table (typically negative)
+      # @raise [ArgumentError] If parameters are invalid
+      def initialize(units_per_em:, ascent:, descent:)
+        validate_parameters!(units_per_em, ascent, descent)
+
+        @units_per_em = units_per_em
+        @ascent = ascent
+        @descent = descent
+      end
+
+      # Transform Y coordinate from font space to SVG space
+      #
+      # Font space: Y-up (ascender positive, descender negative)
+      # SVG space: Y-down (origin at top)
+      #
+      # Transformation: svg_y = ascent - font_y
+      #
+      # @param font_y [Numeric] Y coordinate in font space
+      # @return [Numeric] Y coordinate in SVG space
+      def transform_y(font_y)
+        ascent - font_y
+      end
+
+      # Transform point from font space to SVG space
+      #
+      # @param font_x [Numeric] X coordinate in font space
+      # @param font_y [Numeric] Y coordinate in font space
+      # @return [Array<Numeric>] [svg_x, svg_y]
+      def transform_point(font_x, font_y)
+        [font_x, transform_y(font_y)]
+      end
+
+      # Calculate viewBox string for SVG
+      #
+      # @param x_min [Numeric] Minimum X coordinate
+      # @param y_min [Numeric] Minimum Y coordinate
+      # @param x_max [Numeric] Maximum X coordinate
+      # @param y_max [Numeric] Maximum Y coordinate
+      # @return [String] ViewBox string "x y width height"
+      def calculate_viewbox(x_min:, y_min:, x_max:, y_max:)
+        # Transform bounding box to SVG space
+        svg_y_min = transform_y(y_max) # Y is flipped
+        svg_y_max = transform_y(y_min)
+
+        width = x_max - x_min
+        height = svg_y_max - svg_y_min
+
+        "#{x_min} #{svg_y_min} #{width} #{height}"
+      end
+
+      # Calculate font-level viewBox
+      #
+      # Uses font metrics to create a viewBox covering the entire font space
+      #
+      # @return [String] ViewBox string for entire font
+      def font_viewbox
+        # Typical font viewBox covers descent to ascent
+        # Width is units_per_em
+        height = ascent - descent
+        "0 0 #{units_per_em} #{height}"
+      end
+
+      # Get scale factor for coordinate precision
+      #
+      # @param target_units [Integer] Target units per em (default 1000)
+      # @return [Float] Scale factor
+      def scale_factor(target_units: 1000)
+        target_units.to_f / units_per_em
+      end
+
+      private
+
+      # Validate initialization parameters
+      #
+      # @param units_per_em [Integer] Units per em
+      # @param ascent [Integer] Font ascent
+      # @param descent [Integer] Font descent
+      # @raise [ArgumentError] If validation fails
+      def validate_parameters!(units_per_em, ascent, descent)
+        unless units_per_em.is_a?(Integer) && units_per_em.positive?
+          raise ArgumentError,
+                "units_per_em must be a positive Integer, got: #{units_per_em.inspect}"
+        end
+
+        unless ascent.is_a?(Integer)
+          raise ArgumentError,
+                "ascent must be an Integer, got: #{ascent.inspect}"
+        end
+
+        unless descent.is_a?(Integer)
+          raise ArgumentError,
+                "descent must be an Integer, got: #{descent.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff/cff_glyph.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff
+      # Wrapper class for CFF glyph data
+      #
+      # [`CFFGlyph`](lib/fontisan/tables/cff/cff_glyph.rb) provides a unified
+      # interface for CFF glyphs that matches the API of TrueType glyphs
+      # ([`SimpleGlyph`](lib/fontisan/tables/glyf/simple_glyph.rb) and
+      # [`CompoundGlyph`](lib/fontisan/tables/glyf/compound_glyph.rb)).
+      #
+      # This allows [`GlyphAccessor`](lib/fontisan/glyph_accessor.rb) to work
+      # transparently with both TrueType (glyf) and OpenType/CFF fonts.
+      #
+      # CFF Glyph Characteristics:
+      # - Always "simple" (no composite structure like TrueType compound glyphs)
+      # - Outline data stored as Type 2 CharString programs
+      # - Width information embedded in CharString
+      # - Glyph names from Charset
+      #
+      # @example Accessing a CFF glyph
+      #   cff = font.table("CFF ")
+      #   charstring = cff.charstring_for_glyph(42)
+      #   glyph = CFFGlyph.new(42, charstring, cff.charset, cff.encoding)
+      #
+      #   puts glyph.name           # => "A"
+      #   puts glyph.width          # => 500
+      #   puts glyph.bounding_box   # => [10, 0, 490, 700]
+      #   puts glyph.simple?        # => true
+      #   puts glyph.compound?      # => false
+      #
+      # Reference: [`docs/ttfunk-feature-analysis.md:541-575`](docs/ttfunk-feature-analysis.md:541)
+      class CFFGlyph
+        # @return [Integer] Glyph ID (GID)
+        attr_reader :glyph_id
+
+        # @return [CharString] Interpreted CharString with path data
+        attr_reader :charstring
+
+        # Initialize a CFF glyph wrapper
+        #
+        # @param glyph_id [Integer] Glyph ID (0-based, 0 is .notdef)
+        # @param charstring [CharString] Interpreted CharString object
+        # @param charset [Charset] Charset for name lookup
+        # @param encoding [Encoding, nil] Encoding (optional, for character code
+        #   mapping)
+        def initialize(glyph_id, charstring, charset, encoding = nil)
+          @glyph_id = glyph_id
+          @charstring = charstring
+          @charset = charset
+          @encoding = encoding
+        end
+
+        # Check if this is a simple glyph
+        #
+        # CFF glyphs are conceptually "simple" - they don't have the composite
+        # structure that TrueType compound glyphs have. While CFF CharStrings
+        # can call subroutines, these are code reuse mechanisms, not glyph
+        # composition.
+        #
+        # @return [Boolean] Always true for CFF glyphs
+        def simple?
+          true
+        end
+
+        # Check if this is a compound glyph
+        #
+        # CFF glyphs don't have components like TrueType compound glyphs.
+        #
+        # @return [Boolean] Always false for CFF glyphs
+        def compound?
+          false
+        end
+
+        # Check if this glyph has no outline data
+        #
+        # A glyph is empty if its CharString path is empty (e.g., space
+        # character)
+        #
+        # @return [Boolean] True if glyph has no path data
+        def empty?
+          return true unless @charstring
+
+          @charstring.path.empty?
+        end
+
+        # Get the bounding box for this glyph
+        #
+        # Returns the glyph's bounding box in font units as calculated from
+        # the CharString path.
+        #
+        # @return [Array<Float>, nil] [xMin, yMin, xMax, yMax] or nil if empty
+        def bounding_box
+          return nil unless @charstring
+
+          @charstring.bounding_box
+        end
+
+        # Get the advance width for this glyph
+        #
+        # Returns the glyph's advance width from the CharString.
+        #
+        # @return [Integer, nil] Advance width in font units, or nil if not
+        #   available
+        def width
+          return nil unless @charstring
+
+          @charstring.width
+        end
+
+        # Get the PostScript glyph name
+        #
+        # Looks up the glyph name from the Charset using the glyph ID.
+        #
+        # @return [String] Glyph name (e.g., "A", "Aacute", ".notdef")
+        def name
+          return ".notdef" unless @charset
+
+          @charset.glyph_name(@glyph_id) || ".notdef"
+        end
+
+        # Convert the glyph outline to drawing commands
+        #
+        # Returns an array of drawing commands that can be used to render
+        # the glyph outline.
+        #
+        # @return [Array<Array>] Array of command arrays:
+        #   - [:move_to, x, y]
+        #   - [:line_to, x, y]
+        #   - [:curve_to, x1, y1, x2, y2, x, y]
+        #
+        # @example Rendering a glyph
+        #   glyph.to_commands.each do |cmd|
+        #     case cmd[0]
+        #     when :move_to
+        #       canvas.move_to(cmd[1], cmd[2])
+        #     when :line_to
+        #       canvas.line_to(cmd[1], cmd[2])
+        #     when :curve_to
+        #       canvas.curve_to(cmd[1], cmd[2], cmd[3], cmd[4], cmd[5], cmd[6])
+        #     end
+        #   end
+        def to_commands
+          return [] unless @charstring
+
+          @charstring.to_commands
+        end
+
+        # Get the raw path data
+        #
+        # Returns the raw path array from the CharString for advanced use cases.
+        #
+        # @return [Array<Hash>] Array of path command hashes with keys:
+        #   - :type (:move_to, :line_to, :curve_to)
+        #   - :x, :y (coordinates)
+        #   - :x1, :y1, :x2, :y2 (control points for curves)
+        def path
+          return [] unless @charstring
+
+          @charstring.path
+        end
+
+        # String representation for debugging
+        #
+        # @return [String] Human-readable representation
+        def to_s
+          "#<#{self.class.name} gid=#{@glyph_id} name=#{name.inspect} " \
+            "width=#{width} bbox=#{bounding_box.inspect}>"
+        end
+
+        alias inspect to_s
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff/charset.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../../binary/base_record"
+
+module Fontisan
+  module Tables
+    class Cff
+      # CFF Charset structure
+      #
+      # Charset maps glyph IDs (GIDs) to glyph names via String IDs (SIDs).
+      # GID 0 is always `.notdef` and is not included in the Charset data.
+      #
+      # Three formats:
+      # - Format 0: Array of SIDs, one per glyph (except .notdef)
+      # - Format 1: Ranges with 8-bit nLeft counts
+      # - Format 2: Ranges with 16-bit nLeft counts
+      #
+      # Predefined charsets:
+      # - 0: ISOAdobe charset (SIDs 0-228)
+      # - 1: Expert charset
+      # - 2: Expert Subset charset
+      #
+      # Reference: CFF specification section 13 "Charsets"
+      # https://adobe-type-tools.github.io/font-tech-notes/pdfs/5176.CFF.pdf
+      #
+      # @example Reading a Charset
+      #   charset = Fontisan::Tables::Cff::Charset.new(
+      #     data, num_glyphs, cff_table
+      #   )
+      #   puts charset.glyph_name(5)  # => "A"
+      #   puts charset.glyph_id("A")  # => 5
+      class Charset
+        # Format identifiers
+        FORMATS = {
+          0 => :array,
+          1 => :range_8,
+          2 => :range_16,
+        }.freeze
+
+        # Predefined charset identifiers
+        PREDEFINED = {
+          0 => :iso_adobe,
+          1 => :expert,
+          2 => :expert_subset,
+        }.freeze
+
+        # @return [Integer] Charset format (0, 1, or 2)
+        attr_reader :format_type
+
+        # @return [Array<String>] Glyph names indexed by GID
+        attr_reader :glyph_names
+
+        # Initialize a Charset
+        #
+        # @param data [String, Integer] Binary data or predefined charset ID
+        # @param num_glyphs [Integer] Number of glyphs in the font
+        # @param cff_table [Cff] Parent CFF table for string lookup
+        def initialize(data, num_glyphs, cff_table)
+          @num_glyphs = num_glyphs
+          @cff_table = cff_table
+          @glyph_names = [".notdef"] # GID 0 is always .notdef
+          @glyph_name_to_id = { ".notdef" => 0 }
+
+          if data.is_a?(Integer) && PREDEFINED.key?(data)
+            load_predefined_charset(data)
+          else
+            @data = data
+            parse!
+          end
+        end
+
+        # Get glyph name for a GID
+        #
+        # @param gid [Integer] Glyph ID
+        # @return [String, nil] Glyph name or nil if invalid GID
+        def glyph_name(gid)
+          return nil if gid.negative? || gid >= @glyph_names.size
+
+          @glyph_names[gid]
+        end
+
+        # Get GID for a glyph name
+        #
+        # @param name [String] Glyph name
+        # @return [Integer, nil] Glyph ID or nil if not found
+        def glyph_id(name)
+          @glyph_name_to_id[name]
+        end
+
+        # Get the format symbol
+        #
+        # @return [Symbol] Format identifier (:array, :range_8, :range_16, or
+        #   :predefined)
+        def format
+          @format_type ? FORMATS[@format_type] : :predefined
+        end
+
+        private
+
+        # Parse the Charset from binary data
+        def parse!
+          io = StringIO.new(@data)
+          @format_type = read_uint8(io)
+
+          case @format_type
+          when 0
+            parse_format_0(io)
+          when 1
+            parse_format_1(io)
+          when 2
+            parse_format_2(io)
+          else
+            raise CorruptedTableError,
+                  "Invalid Charset format: #{@format_type}"
+          end
+
+          build_name_to_id_map
+        rescue StandardError => e
+          raise CorruptedTableError,
+                "Failed to parse Charset: #{e.message}"
+        end
+
+        # Parse Format 0: Array of SIDs
+        #
+        # Format 0 directly lists SIDs for each glyph (except .notdef at GID 0)
+        #
+        # @param io [StringIO] Input stream positioned after format byte
+        def parse_format_0(io)
+          # Read one SID per glyph (num_glyphs - 1, excluding .notdef)
+          (@num_glyphs - 1).times do
+            sid = read_uint16(io)
+            glyph_name = sid_to_glyph_name(sid)
+            @glyph_names << glyph_name
+          end
+        end
+
+        # Parse Format 1: Ranges with 8-bit counts
+        #
+        # Format 1 uses ranges: first SID, nLeft (number of consecutive SIDs)
+        #
+        # @param io [StringIO] Input stream positioned after format byte
+        def parse_format_1(io)
+          glyph_count = 1 # Start at 1 (we already have .notdef at 0)
+
+          while glyph_count < @num_glyphs
+            first_sid = read_uint16(io)
+            n_left = read_uint8(io)
+
+            # Add glyphs for this range
+            (n_left + 1).times do |i|
+              sid = first_sid + i
+              glyph_name = sid_to_glyph_name(sid)
+              @glyph_names << glyph_name
+              glyph_count += 1
+              break if glyph_count >= @num_glyphs
+            end
+          end
+        end
+
+        # Parse Format 2: Ranges with 16-bit counts
+        #
+        # Format 2 is like Format 1 but with 16-bit nLeft values
+        #
+        # @param io [StringIO] Input stream positioned after format byte
+        def parse_format_2(io)
+          glyph_count = 1 # Start at 1 (we already have .notdef at 0)
+
+          while glyph_count < @num_glyphs
+            first_sid = read_uint16(io)
+            n_left = read_uint16(io)
+
+            # Add glyphs for this range
+            (n_left + 1).times do |i|
+              sid = first_sid + i
+              glyph_name = sid_to_glyph_name(sid)
+              @glyph_names << glyph_name
+              glyph_count += 1
+              break if glyph_count >= @num_glyphs
+            end
+          end
+        end
+
+        # Load a predefined charset
+        #
+        # @param charset_id [Integer] Predefined charset ID (0, 1, or 2)
+        def load_predefined_charset(charset_id)
+          @format_type = nil # Predefined charsets don't have a format
+
+          case charset_id
+          when 0
+            load_iso_adobe_charset
+          when 1
+            load_expert_charset
+          when 2
+            load_expert_subset_charset
+          end
+
+          build_name_to_id_map
+        end
+
+        # Load ISOAdobe charset (SIDs 0-228)
+        #
+        # This is the standard charset containing common Latin glyphs
+        def load_iso_adobe_charset
+          # ISOAdobe charset contains SIDs 0-228
+          # For a full implementation, we would need all 229 glyphs
+          # Here we generate them from SIDs
+          (@num_glyphs - 1).times do |i|
+            sid = i + 1 # Skip 0 (.notdef)
+            break if sid > 228
+
+            @glyph_names << sid_to_glyph_name(sid)
+          end
+        end
+
+        # Load Expert charset
+        #
+        # This is a special charset for expert fonts with additional glyphs
+        def load_expert_charset
+          # Expert charset contains specific SIDs for expert glyphs
+          # This is a placeholder - a full implementation would include the
+          # complete expert charset SID list from the CFF specification
+          (@num_glyphs - 1).times do |i|
+            @glyph_names << sid_to_glyph_name(i + 1)
+          end
+        end
+
+        # Load Expert Subset charset
+        #
+        # This is a subset of the Expert charset
+        def load_expert_subset_charset
+          # Expert Subset contains a subset of expert glyphs
+          # This is a placeholder - a full implementation would include the
+          # complete expert subset charset SID list from the CFF specification
+          (@num_glyphs - 1).times do |i|
+            @glyph_names << sid_to_glyph_name(i + 1)
+          end
+        end
+
+        # Convert SID to glyph name
+        #
+        # @param sid [Integer] String ID
+        # @return [String] Glyph name
+        def sid_to_glyph_name(sid)
+          @cff_table.string_for_sid(sid) || ".notdef"
+        end
+
+        # Build the name-to-ID lookup map
+        def build_name_to_id_map
+          @glyph_names.each_with_index do |name, gid|
+            @glyph_name_to_id[name] = gid
+          end
+        end
+
+        # Read an unsigned 8-bit integer
+        #
+        # @param io [StringIO] Input stream
+        # @return [Integer] The value
+        def read_uint8(io)
+          byte = io.read(1)
+          raise CorruptedTableError, "Unexpected end of Charset data" if
+            byte.nil?
+
+          byte.unpack1("C")
+        end
+
+        # Read an unsigned 16-bit integer (big-endian)
+        #
+        # @param io [StringIO] Input stream
+        # @return [Integer] The value
+        def read_uint16(io)
+          bytes = io.read(2)
+          raise CorruptedTableError, "Unexpected end of Charset data" if
+            bytes.nil? || bytes.bytesize < 2
+
+          bytes.unpack1("n") # Big-endian unsigned 16-bit
+        end
+      end
+    end
+  end
+end