alhena 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35e4670f6299d744074cb8bc0c64eba91b2f0691d07f1034b9a5ae7423c9dffa
-  data.tar.gz: 0df90b79072d3f967af91362b80b4cd7ba3c78dcf72a8e3e61d7227c1933ec91
+  metadata.gz: f4c0b230268d5ea31a81de61c2921d5e4935867b6404f5cce8b1845f72e684fd
+  data.tar.gz: 50efd3bdb4e99ae0cab4af5de6ef774475bce172f393acdae2331a46d50025f2
 SHA512:
-  metadata.gz: 4fd434b589dc0feb1c2e71ab0553b3b8059e11613ffa6cbeae33550456c10a2547e811b61fd94a6310e5f53248459967ff2ecc634fc9eda389e2876d62554bd3
-  data.tar.gz: 2b80e1d2e093842035364cecc9ad4a5be2389dcdfbd4589ebc776c99f95be3149451fd9977c2455bba5c5da824d4601cc0d1059ff68357487ba7a28eb66bb991
+  metadata.gz: 90ffa83e7e39302c55686750ef08230df82f825c05b7a7f00802825475b57876abbd37e7fc8d96296c8d51bc9380fa1ac5bdd11a3aef5a799a5ae80dbab32a57
+  data.tar.gz: c9956c2c6c282c20dbd7b304ebb548e04029a57dafe6a87b2888d868477ce85ee971e0ae1ffc1c2f1e9b1eabc62170102c42f2bf5ad5d389f1c0611f4a26abb6

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 — 2026-09-15
+
+- Added text advance and line metric measurement without rasterization.
+- Added low-resolution outline rendering for minimap-style ink distribution.
+- Added an asserted 10,000-row downsampling performance budget.
+
 ## 0.1.0 — 2026-09-11
 
 - Initial release.

data/README.md

@@ -16,18 +16,20 @@
   <a href="#quick-start">Quick Start</a> ·
   <a href="#usage">Usage</a> ·
   <a href="#supported-formats">Supported Formats</a> ·
-  <a href="#development">Development</a>
+  <a href="#performance">Performance</a>
 </p>
 
 ---
 
-Alhena reads TrueType, OpenType, and TTC fonts, extracts their outlines, and rasterizes antialiased grayscale, LCD, and color glyph bitmaps. It requires Ruby 3.1+ and has no runtime gem dependencies or native extensions.
+Alhena reads TrueType, OpenType, and TTC fonts, extracts their outlines, and rasterizes antialiased grayscale, LCD, and color glyph bitmaps. It has no runtime gem dependencies or native extensions.
 
 ## Features
 
 - TrueType, OpenType CFF1/CFF2, and TTC font parsing
 - Analytic grayscale and LCD rasterization with subpixel positioning
 - Variable font axes, outlines, and metrics
+- Fast text advance measurement without rasterization
+- Low-resolution ink distribution rendering for minimaps
 - COLR/CPAL, sbix, and CBDT/CBLC color glyphs
 - Entry- and byte-bounded LRU glyph cache
 - Lazy, bounds-checked table parsing
@@ -53,6 +55,10 @@ Or install it directly:
 gem install alhena
 ```
 
+### Requirements
+
+- Ruby 3.1 or later
+
 ## Quick Start
 
 ```ruby
@@ -72,6 +78,18 @@ puts bitmap.to_ascii
 advance = font.advance(glyph, size: 24)
 ```
 
+Measure a UTF-8 string without rasterizing its glyphs:
+
+```ruby
+metrics = font.measure("Inline hint", size: 14)
+width = font.advance_width("Inline hint".codepoints, size: 14)
+```
+
+`Metrics` contains the scaled `width`, `ascent`, `descent`, and `line_gap`;
+`descent` retains the font's signed value (normally negative).
+OpenType shaping is outside Alhena's scope, so non-empty `features:` values raise
+`Alhena::UnsupportedFont`.
+
 ## Usage
 
 ### Fonts and metrics
@@ -93,6 +111,14 @@ bitmap = Alhena::Rasterizer.new(width: 100, height: 100).fill(path)
 
 `Outline` supports lines, quadratic and cubic curves, transforms, bounds, appending, and cubic-to-quadratic conversion. `Rasterizer#fill` uses pixel coordinates with Y down and implicitly closes open subpaths.
 
+For minimaps, combine already-positioned outlines into a low-resolution coverage
+bitmap without rasterizing each glyph separately:
+
+```ruby
+mini = Alhena::Rasterizer.new(width: 1, height: 1)
+  .fill_downsampled(outlines, scale: 0.05, width: 120, height: 2)
+```
+
 `Font#rasterize` and `Rasterizer#fill` accept `gamma:`, `darkening:`, and `lcd: :rgb` or `:bgr`. Use grayscale when the display subpixel order is unknown.
 
 ### Glyph cache
@@ -149,6 +175,7 @@ Measurements below are medians of five batches on Ruby 4.0.0 with YJIT on arm64-
 | A at 14px, cache hit | 0.48 µs | 5 µs |
 | ASCII 95 glyph prewarm | 4.79 ms | 60 ms |
 | 鬱 at 48px, uncached | 0.47 ms | 3 ms |
+| 10,000 downsampled rows | 100.37 ms | 200 ms |
 
 Cache glyphs in interactive applications so each glyph is normally rasterized once per size and position. These measurements are local evidence, not universal guarantees.
 

data/lib/alhena/font.rb

@@ -126,6 +126,31 @@ module Alhena
       cached_metric(glyph, vertical: vertical)[0] * scale_factor(size)
     end
 
+    def advance_width(codepoints, size:, features: [])
+      validate_features(features)
+      raise ArgumentError, "codepoints must be an Array" unless codepoints.is_a?(Array)
+
+      factor = scale_factor(size)
+      units = codepoints.each_with_index.sum do |codepoint, index|
+        next 0 if variation_selector?(codepoint)
+
+        selector = codepoints[index + 1]
+        glyph = glyph_id(codepoint, variation_selector: variation_selector?(selector) ? selector : nil)
+        glyph = glyph_id(codepoint) if glyph.zero? && variation_selector?(selector)
+        cached_metric(glyph, vertical: false)[0]
+      end
+      units * factor
+    end
+
+    def measure(text, size:, features: [])
+      valid_text = text.is_a?(String) && text.encoding == Encoding::UTF_8 && text.valid_encoding?
+      raise ArgumentError, "text must be a valid UTF-8 String" unless valid_text
+
+      factor = scale_factor(size)
+      Metrics.new(width: advance_width(text.codepoints, size: size, features: features),
+        ascent: ascent * factor, descent: descent * factor, line_gap: line_gap * factor).freeze
+    end
+
     def bearing(glyph, size: units_per_em, vertical: false)
       cached_metric(glyph, vertical: vertical)[1] * scale_factor(size)
     end
@@ -166,10 +191,21 @@ module Alhena
     private
 
     def scale_factor(size)
-      raise ArgumentError, "size must be positive and finite" unless size.is_a?(Numeric) && size.finite? && size > 0
+      valid = size.is_a?(Numeric) && size.real? && size.finite? && size > 0
+      raise ArgumentError, "size must be positive and finite" unless valid
+
       size.to_f / units_per_em
     end
 
+    def validate_features(features)
+      raise ArgumentError, "features must be an Array" unless features.is_a?(Array)
+      raise UnsupportedFont, "OpenType layout features are not supported" unless features.empty?
+    end
+
+    def variation_selector?(codepoint)
+      codepoint.is_a?(Integer) && (codepoint.between?(0xfe00, 0xfe0f) || codepoint.between?(0xe0100, 0xe01ef))
+    end
+
     def validate_glyph(glyph)
       raise ArgumentError, "glyph ID out of range" unless glyph.is_a?(Integer) && glyph >= 0 && glyph < glyph_count
     end

data/lib/alhena/rasterizer.rb

@@ -31,6 +31,22 @@ module Alhena
       @area = nil
     end
 
+    def fill_downsampled(outlines, scale:, width:, height:)
+      valid_scale = scale.is_a?(Numeric) && scale.real? && scale.finite? && scale > 0
+      raise ArgumentError, "scale must be positive and finite" unless valid_scale
+      raise ArgumentError, "outlines must be enumerable" unless outlines.respond_to?(:each)
+
+      target = self.class.new(width: width, height: height, tolerance: @tolerance)
+      combined = Outline.new
+      outlines.each do |outline|
+        raise ArgumentError, "outlines must contain Outline values" unless outline.is_a?(Outline)
+
+        combined.append(outline)
+      end
+      combined.coordinates.map! { |coordinate| coordinate * scale } unless scale == 1
+      target.fill(combined)
+    end
+
     private
 
     def lcd_bitmap(outline, left:, top:, gamma:, darkening:, order:)

data/lib/alhena/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Alhena
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/alhena.rb

@@ -7,6 +7,7 @@ module Alhena
   class Error < StandardError; end
   class InvalidFont < Error; end
   class UnsupportedFont < Error; end
+  Metrics = Struct.new(:width, :ascent, :descent, :line_gap, keyword_init: true)
 end
 
 require_relative "alhena/bitmap"

data/sig/alhena.rbs

@@ -1,4 +1,11 @@
 module Alhena
+  class Metrics < Struct[untyped]
+    attr_accessor width: Float
+    attr_accessor ascent: Float
+    attr_accessor descent: Float
+    attr_accessor line_gap: Float
+    def initialize: (?width: Float, ?ascent: Float, ?descent: Float, ?line_gap: Float) -> void
+  end
   VERSION: String
   type matrix = Array[Numeric]
   class Error < StandardError
@@ -70,6 +77,8 @@ module Alhena
     def post: () -> Hash[Symbol, Numeric | bool]
     def glyph_id: (String | Integer character, ?variation_selector: String | Integer | nil) -> Integer
     def advance: (Integer glyph, ?size: Numeric, ?vertical: bool) -> Float
+    def advance_width: (Array[Integer] codepoints, size: Numeric, ?features: Array[String | Symbol]) -> Float
+    def measure: (String text, size: Numeric, ?features: Array[String | Symbol]) -> Metrics
     def bearing: (Integer glyph, ?size: Numeric, ?vertical: bool) -> Float
     def outline: (Integer glyph) -> Outline
     def axes: () -> Hash[String, Hash[Symbol, Numeric | bool | String | nil]]
@@ -104,6 +113,7 @@ module Alhena
     MAX_PIXELS: Integer
     def initialize: (width: Integer, height: Integer, ?tolerance: Numeric) -> void
     def fill: (Outline, ?transform: matrix?, ?left: Integer, ?top: Integer, ?gamma: Numeric, ?darkening: Numeric, ?lcd: :rgb | :bgr | nil) -> Bitmap
+    def fill_downsampled: (Enumerable[Outline] outlines, scale: Numeric, width: Integer, height: Integer) -> Bitmap
   end
   class Cache
     attr_reader capacity: Integer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alhena
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -9,8 +9,8 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Read sfnt and TTC fonts, extract outlines, and produce antialiased grayscale
-  or LCD glyph bitmaps without native dependencies.
+description: Read sfnt and TTC fonts, measure text, extract outlines, and produce
+  antialiased or downsampled glyph bitmaps without native dependencies.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -58,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Pure Ruby TrueType and CFF font rasterization
+summary: Pure Ruby font rasterization and measurement
 test_files: []