logosoup 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4398d59376687e027112633787c08a5d3237ccd9faedf078c8dc59b484903fcd
+  data.tar.gz: 143a9f9a2f55465c6ed3c49cce265529208b2e5957ace137e8688f46afd2fa9e
+SHA512:
+  metadata.gz: 438698259b4c3baf2494e7d58f32e47a6acb1149879ce37403287306fd490e2dbb6a293cd88343b7fc8ea56a6dc33f9fe5163f6f4e0364f27a15934c64d4f7fd
+  data.tar.gz: 50dfd2923054f75a6d4e5b1edd95c531d3add224dfb772c61c11c05ad52baad346bfa706e43cf3082d095e3d4de26d843d2c0b263ea8b5bd3d5676c1b1fe0c8e

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial gem scaffold
+- `LogoSoup.style` supports SVG strings and raster image paths

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codeminer42
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# LogoSoup
+
+[![Version](https://img.shields.io/badge/version-0.1.0-blue)](CHANGELOG.md)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
+[![Coverage](https://img.shields.io/badge/coverage-86.14%25-brightgreen)](coverage/index.html)
+
+Framework-agnostic Ruby gem for **normalizing logo rendering**.
+
+Given an input logo (SVG or raster), LogoSoup returns an **inline CSS style string** that you can apply to an `<img>` (or equivalent) so different logos render with a consistent perceived size, with optional visual-center alignment.
+
+This gem is inspired by the original Logo Soup project for React ([auroris/logo-soup](https://github.com/auroris/logo-soup)) developed by [Rostislav Melkumyan](https://www.sanity.io/blog/the-logo-soup-problem).
+
+## Why
+
+Logos often have different intrinsic sizes, padding, and visual weight. If you render them at the same width/height, they still *look* inconsistent.
+
+LogoSoup aims to:
+
+- Normalize sizing so logos look consistent at a given `base_size`.
+- Optionally align by visual center (e.g., Y axis) for better baseline alignment.
+- Stay framework-agnostic (no Rails dependencies).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'logosoup'
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+Or, with Bundler:
+
+```sh
+bundle add logosoup
+```
+
+## Requirements
+
+- Ruby: `>= 2.7`, `< 4.0`
+- System dependency: **libvips** (required for raster analysis)
+
+### Installing libvips
+
+- macOS (Homebrew):
+
+```sh
+brew install vips
+```
+
+- Ubuntu/Debian:
+
+```sh
+sudo apt-get update && sudo apt-get install -y libvips
+```
+
+## Usage
+
+LogoSoup exposes a single entrypoint: `LogoSoup.style`.
+
+### SVG (string)
+
+```ruby
+style = LogoSoup.style(
+
+  svg: File.read('logo.svg'),
+  base_size: 48
+)
+
+# => "width: 48px; height: 48px; object-fit: contain; display: block; transform: translate(0px, 0px);"
+```
+
+### Raster image (file path)
+
+```ruby
+style = LogoSoup.style(
+  image_path: 'logo.png',
+  base_size: 48
+)
+```
+
+### Bytes (IO/String)
+
+```ruby
+bytes = File.binread('logo.webp')
+
+style = LogoSoup.style(
+  image_bytes: bytes,
+  content_type: 'image/webp',
+  base_size: 48
+)
+```
+
+If `content_type` includes `svg` (e.g. `image/svg+xml`), `image_bytes:` is treated as SVG and handled by the SVG pipeline.
+
+## API
+
+### `LogoSoup.style`
+
+```ruby
+LogoSoup.style(
+  svg: nil,
+  image_path: nil,
+  image_bytes: nil,
+  content_type: nil,
+  base_size:,
+  on_error: nil,
+  **options
+)
+```
+
+#### Inputs (choose one)
+
+- `svg:` String containing SVG XML
+- `image_path:` filesystem path to an image (PNG/JPG/WebP/GIF/TIFF, etc.)
+- `image_bytes:` String/IO of image bytes
+
+#### Required
+
+- `base_size:` Integer (pixels). Used as the normalization target and also as fallback width/height.
+
+#### Error handling
+
+- `on_error: nil` (default): return a fallback style (`width/height = base_size`, no transform)
+- `on_error: :raise`: re-raise the original exception
+
+#### Options (with defaults)
+
+These map directly to `LogoSoup::Style::DEFAULTS`:
+
+- `scale_factor:` `0.5`
+- `density_aware:` `true`
+- `density_factor:` `0.5`
+- `contrast_threshold:` `10`
+- `align_by:` `'visual-center-y'`
+- `pixel_budget:` `2048`
+
+Notes:
+
+- Raster images are analyzed with libvips to estimate features (e.g. pixel density / content box / visual center offsets) that inform sizing and transforms.
+- For SVG input, LogoSoup currently uses intrinsic SVG dimensions and skips raster feature measurement.
+
+## Output
+
+The return value is a single inline CSS string including (at least):
+
+- `width: ...px;`
+- `height: ...px;`
+- `object-fit: contain;`
+- `display: block;`
+- `transform: ...` (only when alignment produces a non-nil transform)
+
+This is designed to be applied directly to an `<img>` tag or any element that supports these properties.
+
+## Testing
+
+Run the test suite:
+
+```sh
+bundle exec rake spec
+```
+
+### Coverage
+
+Generate a local coverage report:
+
+```sh
+bundle exec rake spec:coverage
+```
+
+This writes HTML reports to `coverage/index.html`.
+
+The badge at the top of this README reflects the last recorded SimpleCov result in `coverage/.last_run.json` (current line coverage: **86.14%**; branch coverage in that file: **53.17%**).
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+- Keep changes focused and add specs where it makes sense.
+- If you change behavior, update `CHANGELOG.md`
+
+## License
+
+Released under the MIT License. See `LICENSE.txt`.

data/lib/logo_soup/core/background_detector.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module LogoSoup
+  module Core
+    # Detects whether background should be treated as transparent and estimates
+    # background RGB from the image perimeter.
+    class BackgroundDetector
+      QUANTIZATION_SHIFT = 5
+      ALPHA_TRANSPARENCY_THRESHOLD = 128
+      TRANSPARENT_PERIMETER_RATIO_THRESHOLD = 0.1
+
+      # @param bytes [Array<Integer>] RGBA bytes
+      # @param width [Integer]
+      # @param height [Integer]
+      # @return [Array(Boolean, Integer, Integer, Integer)] [alpha_only, bg_r, bg_g, bg_b]
+      def self.call(bytes, width, height)
+        levels = 1 << (8 - QUANTIZATION_SHIFT)
+        bucket_count = levels * levels * levels
+
+        bucket_counts = Array.new(bucket_count, 0)
+        bucket_r = Array.new(bucket_count, 0)
+        bucket_g = Array.new(bucket_count, 0)
+        bucket_b = Array.new(bucket_count, 0)
+
+        opaque_count = 0
+        transparent_count = 0
+
+        sample = lambda do |x, y|
+          idx = ((y * width) + x) * 4
+          a = bytes[idx + 3]
+          return if a.nil?
+
+          if a < ALPHA_TRANSPARENCY_THRESHOLD
+            transparent_count += 1
+            return
+          end
+
+          opaque_count += 1
+          r = bytes[idx]
+          g = bytes[idx + 1]
+          b = bytes[idx + 2]
+
+          key = ((((r >> QUANTIZATION_SHIFT) * levels) + (g >> QUANTIZATION_SHIFT)) * levels) + (b >> QUANTIZATION_SHIFT)
+          bucket_counts[key] += 1
+          bucket_r[key] += r
+          bucket_g[key] += g
+          bucket_b[key] += b
+        end
+
+        width.times do |x|
+          sample.call(x, 0)
+          sample.call(x, height - 1) if height > 1
+        end
+
+        (1...(height - 1)).each do |y|
+          sample.call(0, y)
+          sample.call(width - 1, y) if width > 1
+        end
+
+        total_perimeter = opaque_count + transparent_count
+        transparent = total_perimeter.positive? && transparent_count > total_perimeter * TRANSPARENT_PERIMETER_RATIO_THRESHOLD
+        return [true, 0, 0, 0] if transparent
+
+        best_idx = 0
+        best_count = 0
+        bucket_counts.each_with_index do |count, i|
+          next unless count > best_count
+
+          best_count = count
+          best_idx = i
+        end
+
+        if best_count.positive?
+          bg_r = (bucket_r[best_idx].to_f / best_count).round
+          bg_g = (bucket_g[best_idx].to_f / best_count).round
+          bg_b = (bucket_b[best_idx].to_f / best_count).round
+          [false, bg_r, bg_g, bg_b]
+        else
+          [false, 255, 255, 255]
+        end
+      end
+    end
+  end
+end

data/lib/logo_soup/core/css.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LogoSoup
+  module Core
+    # CSS utilities.
+    module Css
+      module_function
+
+      # Formats a numeric value rounded to 1 decimal place.
+      #
+      # @param value [Numeric]
+      # @return [String]
+      def fmt_tenth_px(value)
+        rounded = (value.to_f * 10).round / 10.0
+        rounded = 0.0 if rounded.abs < 1e-9
+        rounded.to_i == rounded ? rounded.to_i.to_s : rounded.to_s
+      end
+
+      # Builds an inline style string from a hash.
+      #
+      # @param styles [Hash{Symbol=>String,nil}]
+      # @return [String]
+      def style_string(styles)
+        styles.compact.map { |key, val| "#{key.to_s.tr('_', '-')}: #{val};" }.join(" ")
+      end
+    end
+  end
+end

data/lib/logo_soup/core/dimension_calculator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LogoSoup
+  module Core
+    # Computes normalized render dimensions from intrinsic dimensions.
+    class DimensionCalculator
+      REFERENCE_DENSITY = 0.35
+      MIN_DENSITY_SCALE = 0.5
+      MAX_DENSITY_SCALE = 2.0
+
+      # @param width [Numeric]
+      # @param height [Numeric]
+      # @param base_size [Numeric]
+      # @param scale_factor [Numeric]
+      # @param density_factor [Numeric]
+      # @param pixel_density [Float, nil]
+      # @return [Array(Integer, Integer)]
+      def self.call(width:, height:, base_size:, scale_factor:, density_factor: 0.0, pixel_density: nil)
+        w = width.to_f
+        h = height.to_f
+        base = base_size.to_f
+
+        return [base.round, base.round] if w <= 0 || h <= 0
+
+        aspect_ratio = w / h
+        normalized_width = (aspect_ratio**scale_factor.to_f) * base
+        normalized_height = normalized_width / aspect_ratio
+
+        df = density_factor.to_f
+        if df.positive? && pixel_density
+          density_ratio = pixel_density.to_f / REFERENCE_DENSITY
+          if density_ratio.positive?
+            density_scale = (1.0 / density_ratio)**(df * 0.5)
+            clamped_scale = [[density_scale, MAX_DENSITY_SCALE].min, MIN_DENSITY_SCALE].max
+            normalized_width *= clamped_scale
+            normalized_height *= clamped_scale
+          end
+        end
+
+        [normalized_width.round, normalized_height.round]
+      end
+    end
+  end
+end

data/lib/logo_soup/core/feature_measurer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "image_loader"
+require_relative "background_detector"
+require_relative "pixel_analyzer"
+
+module LogoSoup
+  module Core
+    # Measures raster features (density, content box, visual center offsets).
+    class FeatureMeasurer
+      DEFAULT_PIXEL_BUDGET = 2_048
+
+      # @param path [String]
+      # @param contrast_threshold [Integer]
+      # @param pixel_budget [Integer]
+      # @param on_error [:raise, nil]
+      # @return [Hash]
+      def self.call(path:, contrast_threshold:, pixel_budget: DEFAULT_PIXEL_BUDGET, on_error: nil)
+        payload = ImageLoader.call(path: path, pixel_budget: pixel_budget, on_error: on_error)
+        bytes = payload.fetch(:bytes)
+        sample_width = payload.fetch(:sample_width)
+        sample_height = payload.fetch(:sample_height)
+        original_width = payload.fetch(:original_width)
+        original_height = payload.fetch(:original_height)
+
+        alpha_only, bg_r, bg_g, bg_b = BackgroundDetector.call(bytes, sample_width, sample_height)
+
+        measured = PixelAnalyzer.call(
+          bytes: bytes,
+          sample_width: sample_width,
+          sample_height: sample_height,
+          original_width: original_width,
+          original_height: original_height,
+          contrast_threshold: contrast_threshold,
+          alpha_only: alpha_only,
+          bg_r: bg_r,
+          bg_g: bg_g,
+          bg_b: bg_b
+        )
+
+        measured || default_features(original_width, original_height)
+      end
+
+      def self.default_features(w, h)
+        {
+          pixel_density: 0.5,
+          content_box_width: w,
+          content_box_height: h,
+          visual_center_offset_x: 0.0,
+          visual_center_offset_y: 0.0
+        }
+      end
+
+      private_class_method :default_features
+    end
+  end
+end

data/lib/logo_soup/core/image_loader.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "vips"
+
+module LogoSoup
+  module Core
+    # Loads an image from disk and returns sampled RGBA bytes.
+    class ImageLoader
+      RGBA_CHANNELS = 4
+
+      # @param path [String]
+      # @param pixel_budget [Integer]
+      # @param on_error [:raise, nil]
+      # @return [Hash]
+      def self.call(path:, pixel_budget:, on_error: nil)
+        image = Vips::Image.new_from_file(path, access: :sequential)
+        original_width = image.width
+        original_height = image.height
+
+        sample_width, sample_height, image_small = downsample(image, pixel_budget: pixel_budget)
+        rgba = ensure_rgba_uchar(image_small, on_error: on_error)
+
+        bytes = rgba.write_to_memory.bytes
+        raise "Empty image bytes" if bytes.empty?
+
+        {
+          bytes: bytes,
+          original_width: original_width,
+          original_height: original_height,
+          sample_width: sample_width,
+          sample_height: sample_height
+        }
+      end
+
+      def self.downsample(image, pixel_budget:)
+        w = image.width
+        h = image.height
+        return [1, 1, image] if w <= 0 || h <= 0
+
+        total_pixels = w * h
+        ratio = total_pixels > pixel_budget ? Math.sqrt(pixel_budget.to_f / total_pixels) : 1.0
+        ratio = 1.0 if ratio.nan? || ratio.infinite? || ratio <= 0
+
+        sw = [1, (w * ratio).round].max
+        sh = [1, (h * ratio).round].max
+
+        small = ratio == 1.0 ? image : image.resize(ratio)
+        if small.width != sw || small.height != sh
+          hscale = sw.to_f / small.width
+          vscale = sh.to_f / small.height
+          small = small.resize(hscale, vscale: vscale)
+        end
+
+        [sw, sh, small]
+      end
+
+      def self.ensure_rgba_uchar(image, on_error: nil)
+        img = begin
+          image.colourspace("srgb")
+        rescue StandardError => e
+          raise e if on_error == :raise
+          raise unless vips_error?(e)
+          image
+        end
+
+        img = img.cast("uchar")
+
+        if img.bands > RGBA_CHANNELS
+          img = img.extract_band(0, n: RGBA_CHANNELS)
+        elsif img.bands == 3
+          img = img.bandjoin(255)
+        elsif img.bands == 2
+          gray = img.extract_band(0)
+          alpha = img.extract_band(1)
+          rgb = gray.bandjoin(gray).bandjoin(gray)
+          img = rgb.bandjoin(alpha)
+        elsif img.bands == 1
+          gray = img
+          rgb = gray.bandjoin(gray).bandjoin(gray)
+          img = rgb.bandjoin(255)
+        end
+
+        img
+      end
+
+      def self.vips_error?(error)
+        error.class.name.start_with?("Vips::")
+      end
+
+      private_class_method :downsample, :ensure_rgba_uchar, :vips_error?
+    end
+  end
+end

data/lib/logo_soup/core/pixel_analyzer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module LogoSoup
+  module Core
+    # Measures visual features from sampled RGBA pixels.
+    class PixelAnalyzer
+      # @return [Hash, nil]
+      def self.call(
+        bytes:,
+        sample_width:,
+        sample_height:,
+        original_width:,
+        original_height:,
+        contrast_threshold:,
+        alpha_only:,
+        bg_r:,
+        bg_g:,
+        bg_b:
+      )
+        sw = sample_width
+        sh = sample_height
+        w = original_width
+        h = original_height
+
+        contrast_distance_sq = contrast_threshold.to_f * contrast_threshold.to_f * 3
+        min_x = sw
+        min_y = sh
+        max_x = 0
+        max_y = 0
+
+        total_weight = 0.0
+        weighted_x = 0.0
+        weighted_y = 0.0
+
+        filled_pixels = 0
+        total_weighted_opacity = 0.0
+
+        pixel_count = sw * sh
+        pixel_count.times do |i|
+          base = i * 4
+          r = bytes[base]
+          g = bytes[base + 1]
+          b = bytes[base + 2]
+          a = bytes[base + 3]
+          next if a.nil? || a <= contrast_threshold
+
+          if alpha_only
+            weight = a * a
+            opacity = a
+          else
+            dr = r - bg_r
+            dg = g - bg_g
+            db = b - bg_b
+            dist_sq = (dr * dr) + (dg * dg) + (db * db)
+            next if dist_sq < contrast_distance_sq
+
+            weight = dist_sq * a
+            opacity = [a, Math.sqrt(dist_sq)].min
+          end
+
+          x = i % sw
+          y = (i - x) / sw
+
+          min_x = x if x < min_x
+          max_x = x if x > max_x
+          min_y = y if y < min_y
+          max_y = y if y > max_y
+
+          total_weight += weight
+          weighted_x += (x + 0.5) * weight
+          weighted_y += (y + 0.5) * weight
+
+          filled_pixels += 1
+          total_weighted_opacity += opacity
+        end
+
+        return nil if min_x > max_x || min_y > max_y
+
+        scan_area = (max_x - min_x + 1) * (max_y - min_y + 1)
+        return nil if scan_area <= 0
+
+        coverage_ratio = filled_pixels.to_f / scan_area
+        average_opacity = filled_pixels.positive? ? (total_weighted_opacity / 255.0 / filled_pixels) : 0.0
+        pixel_density = coverage_ratio * average_opacity
+
+        scale_x = w.to_f / sw
+        scale_y = h.to_f / sh
+
+        cb_x = (min_x * scale_x).floor
+        cb_y = (min_y * scale_y).floor
+        cb_right = [[((max_x + 1) * scale_x).ceil.to_i, w].min, 0].max
+        cb_bottom = [[((max_y + 1) * scale_y).ceil.to_i, h].min, 0].max
+        content_box_width = [[cb_right - cb_x, 1].max, w].min
+        content_box_height = [[cb_bottom - cb_y, 1].max, h].min
+
+        if total_weight <= 0
+          offset_x = 0.0
+          offset_y = 0.0
+        else
+          global_center_x = (weighted_x / total_weight) * scale_x
+          global_center_y = (weighted_y / total_weight) * scale_y
+          local_center_x = global_center_x - cb_x
+          local_center_y = global_center_y - cb_y
+
+          geometric_center_x = content_box_width.to_f / 2
+          geometric_center_y = content_box_height.to_f / 2
+
+          offset_x = local_center_x - geometric_center_x
+          offset_y = local_center_y - geometric_center_y
+        end
+
+        {
+          pixel_density: pixel_density,
+          content_box_width: content_box_width,
+          content_box_height: content_box_height,
+          visual_center_offset_x: offset_x,
+          visual_center_offset_y: offset_y
+        }
+      end
+    end
+  end
+end

data/lib/logo_soup/core/svg_dimensions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module LogoSoup
+  module Core
+    # Extracts width/height from SVG XML.
+    class SvgDimensions
+      # @param svg_string [String]
+      # @param on_error [:raise, nil]
+      # @return [Array(Float, Float), nil]
+      def self.call(svg_string, on_error: nil)
+        raw = svg_string.to_s
+        return nil if raw.empty?
+
+        doc = Nokogiri::XML(raw) { |cfg| cfg.nonet }
+        svg = doc.at_xpath("//*[local-name()='svg']")
+        return nil unless svg
+
+        view_box = svg["viewBox"] || svg["viewbox"]
+        if view_box
+          parts = view_box.split(/[\s,]+/).filter_map do |p|
+            Float(p)
+          rescue ArgumentError, TypeError, RangeError => e
+            handle_error(e, on_error: on_error)
+            nil
+          end
+          return [parts[2], parts[3]] if parts.length == 4
+        end
+
+        w = numeric_dimension(svg["width"], on_error: on_error)
+        h = numeric_dimension(svg["height"], on_error: on_error)
+        return nil unless w && h
+
+        [w, h]
+      end
+
+      def self.numeric_dimension(value, on_error: nil)
+        return nil if value.nil?
+
+        num = value.to_s.strip[/[-+]?\d*\.?\d+/, 0]
+        return nil if num.blank?
+
+        Float(num)
+      rescue ArgumentError, RangeError => e
+        handle_error(e, on_error: on_error)
+        nil
+      end
+
+      def self.handle_error(error, on_error:)
+        raise error if on_error == :raise
+      end
+
+      private_class_method :numeric_dimension, :handle_error
+    end
+  end
+end

data/lib/logo_soup/core/visual_center_transform.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "css"
+
+module LogoSoup
+  module Core
+    # Computes a CSS translate() transform to align by visual center.
+    class VisualCenterTransform
+      # @param features [Hash]
+      # @param normalized_width [Numeric]
+      # @param normalized_height [Numeric]
+      # @param align_by [String, Symbol]
+      # @param intrinsic_width [Numeric]
+      # @param intrinsic_height [Numeric]
+      # @return [String, nil]
+      def self.call(features:, normalized_width:, normalized_height:, align_by:, intrinsic_width:, intrinsic_height:)
+        mode = align_by.to_s.strip
+        return nil if mode.empty? || mode == "bounds"
+
+        offset_x = features[:visual_center_offset_x]
+        offset_y = features[:visual_center_offset_y]
+        return nil unless offset_x.is_a?(Numeric) && offset_y.is_a?(Numeric)
+
+        content_w = features[:content_box_width].to_f
+        content_h = features[:content_box_height].to_f
+        content_w = intrinsic_width.to_f if content_w <= 0
+        content_h = intrinsic_height.to_f if content_h <= 0
+        return nil if content_w <= 0 || content_h <= 0
+
+        scale_x = normalized_width.to_f / content_w
+        scale_y = normalized_height.to_f / content_h
+
+        dx = %w[visual-center visual-center-x].include?(mode) ? (-offset_x.to_f * scale_x) : 0.0
+        dy = %w[visual-center visual-center-y].include?(mode) ? (-offset_y.to_f * scale_y) : 0.0
+
+        dx_fmt = Css.fmt_tenth_px(dx)
+        dy_fmt = Css.fmt_tenth_px(dy)
+        return nil if dx_fmt == "0" && dy_fmt == "0"
+
+        "translate(#{dx_fmt}px, #{dy_fmt}px)"
+      end
+    end
+  end
+end

data/lib/logo_soup/style.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "vips"
+
+module LogoSoup
+  # Composes the core logic into a single style string.
+  class Style
+    DEFAULTS = {
+      scale_factor: 0.5,
+      density_aware: true,
+      density_factor: 0.5,
+      contrast_threshold: 10,
+      align_by: "visual-center-y",
+      pixel_budget: 2_048
+    }.freeze
+
+    # @param on_error [:raise, nil] error handling strategy
+    #   - nil (default): return fallback style
+    #   - :raise: re-raise the original exception
+    # @return [String] inline CSS style
+    def self.call(base_size:, svg: nil, image_path: nil, image_bytes: nil, content_type: nil, on_error: nil, **options)
+      opts = DEFAULTS.merge(options).merge(base_size: base_size)
+
+      if svg
+        handle_svg(svg, opts: opts, on_error: on_error)
+      elsif image_path
+        handle_image_path(image_path, opts: opts, on_error: on_error)
+      elsif image_bytes
+        handle_image_bytes(image_bytes, content_type: content_type, opts: opts, on_error: on_error)
+      else
+        fallback_style(opts)
+      end
+    rescue StandardError => e
+      handle_error(e, opts: opts, on_error: on_error)
+    end
+
+    def self.handle_svg(svg_string, opts:, on_error:)
+      intrinsic_w, intrinsic_h = Core::SvgDimensions.call(svg_string, on_error: on_error) || [0.0, 0.0]
+
+      features =
+        if wants_visual_center?(opts.fetch(:align_by, nil))
+          measure_svg_features(svg_string, intrinsic_width: intrinsic_w, intrinsic_height: intrinsic_h, opts: opts, on_error: on_error)
+        else
+          empty_features
+        end
+
+      build_style(
+        intrinsic_width: intrinsic_w,
+        intrinsic_height: intrinsic_h,
+        features: features,
+        **opts
+      )
+    end
+
+    def self.handle_image_path(image_path, opts:, on_error:)
+      # Raster analysis is required; libvips must be installed.
+      image = Vips::Image.new_from_file(image_path, access: :sequential)
+      intrinsic_w = image.width
+      intrinsic_h = image.height
+
+      features = Core::FeatureMeasurer.call(
+        path: image_path,
+        contrast_threshold: opts.fetch(:contrast_threshold).to_i,
+        pixel_budget: opts.fetch(:pixel_budget).to_i,
+        on_error: on_error
+      )
+
+      build_style(
+        intrinsic_width: intrinsic_w,
+        intrinsic_height: intrinsic_h,
+        features: features,
+        **opts
+      )
+    end
+
+    def self.handle_image_bytes(image_bytes, content_type:, opts:, on_error:)
+      bytes = image_bytes.respond_to?(:read) ? image_bytes.read : image_bytes
+      bytes = bytes.to_s
+
+      if content_type.to_s.include?("svg")
+        svg_string = bytes.dup.force_encoding("UTF-8")
+        return handle_svg(svg_string, opts: opts, on_error: on_error)
+      end
+
+      file = nil
+      ext = file_extension_for(content_type)
+      file = Tempfile.new(["logo_soup", ext])
+      file.binmode
+      file.write(bytes)
+      file.flush
+      file.close
+
+      handle_image_path(file.path, opts: opts, on_error: on_error)
+    ensure
+      file.unlink if file
+    end
+
+    def self.handle_error(error, opts:, on_error:)
+      case on_error
+      when :raise
+        raise error
+      else
+        fallback_style(opts)
+      end
+    end
+
+    def self.wants_visual_center?(align_by)
+      mode = align_by.to_s.strip
+      %w[visual-center visual-center-x visual-center-y].include?(mode)
+    end
+
+    def self.measure_svg_features(svg_string, intrinsic_width:, intrinsic_height:, opts:, on_error:)
+      return empty_features if intrinsic_width.to_f <= 0 || intrinsic_height.to_f <= 0
+
+      file = Tempfile.new(["logo_soup", ".svg"])
+      file.binmode
+      file.write(svg_string.to_s)
+      file.flush
+      file.close
+
+      rendered = Vips::Image.new_from_file(file.path, access: :sequential)
+      rendered_w = rendered.width.to_f
+      rendered_h = rendered.height.to_f
+      return empty_features if rendered_w <= 0 || rendered_h <= 0
+
+      measured = Core::FeatureMeasurer.call(
+        path: file.path,
+        contrast_threshold: opts.fetch(:contrast_threshold).to_i,
+        pixel_budget: opts.fetch(:pixel_budget).to_i,
+        on_error: on_error
+      )
+
+      scale_x = intrinsic_width.to_f / rendered_w
+      scale_y = intrinsic_height.to_f / rendered_h
+
+      scaled = measured.dup
+      scaled[:content_box_width] = scaled[:content_box_width].to_f * scale_x if scaled[:content_box_width].is_a?(Numeric)
+      scaled[:content_box_height] = scaled[:content_box_height].to_f * scale_y if scaled[:content_box_height].is_a?(Numeric)
+      scaled[:visual_center_offset_x] = scaled[:visual_center_offset_x].to_f * scale_x if scaled[:visual_center_offset_x].is_a?(Numeric)
+      scaled[:visual_center_offset_y] = scaled[:visual_center_offset_y].to_f * scale_y if scaled[:visual_center_offset_y].is_a?(Numeric)
+      scaled
+    rescue StandardError => e
+      raise e if on_error == :raise
+
+      empty_features
+    ensure
+      file.unlink if file
+    end
+
+    def self.file_extension_for(content_type)
+      case content_type.to_s
+      when "image/png" then ".png"
+      when "image/jpeg", "image/jpg" then ".jpg"
+      when "image/webp" then ".webp"
+      when "image/gif" then ".gif"
+      when "image/tiff" then ".tif"
+      else
+        ".img"
+      end
+    end
+
+    def self.build_style(
+      intrinsic_width:,
+      intrinsic_height:,
+      features:,
+      base_size:,
+      scale_factor:,
+      density_aware:,
+      density_factor:,
+      align_by:,
+      **_unused
+    )
+      pixel_density = density_aware ? features[:pixel_density] : nil
+      effective_density_factor = density_aware ? density_factor.to_f : 0.0
+
+      normalized_w, normalized_h = Core::DimensionCalculator.call(
+        width: intrinsic_width,
+        height: intrinsic_height,
+        base_size: base_size,
+        scale_factor: scale_factor,
+        density_factor: effective_density_factor,
+        pixel_density: pixel_density
+      )
+
+      transform = Core::VisualCenterTransform.call(
+        features: features,
+        normalized_width: normalized_w,
+        normalized_height: normalized_h,
+        align_by: align_by,
+        intrinsic_width: intrinsic_width,
+        intrinsic_height: intrinsic_height
+      )
+
+      Core::Css.style_string(
+        width: "#{normalized_w}px",
+        height: "#{normalized_h}px",
+        object_fit: "contain",
+        display: "block",
+        transform: transform
+      )
+    end
+
+    def self.fallback_style(opts)
+      base = opts.fetch(:base_size).to_i
+      Core::Css.style_string(
+        width: "#{base}px",
+        height: "#{base}px",
+        object_fit: "contain",
+        display: "block",
+        transform: nil
+      )
+    end
+
+    def self.empty_features
+      {
+        pixel_density: nil,
+        content_box_width: nil,
+        content_box_height: nil,
+        visual_center_offset_x: nil,
+        visual_center_offset_y: nil
+      }
+    end
+
+    private_class_method :build_style,
+                         :fallback_style,
+                         :empty_features,
+                         :file_extension_for,
+                         :handle_error,
+                         :handle_svg,
+                         :handle_image_path,
+                         :handle_image_bytes,
+                         :measure_svg_features,
+                         :wants_visual_center?
+  end
+end

data/lib/logo_soup/version.rb

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

data/lib/logo_soup.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "logo_soup/version"
+
+require_relative "logo_soup/core/css"
+require_relative "logo_soup/core/svg_dimensions"
+require_relative "logo_soup/core/dimension_calculator"
+require_relative "logo_soup/core/visual_center_transform"
+
+require_relative "logo_soup/core/image_loader"
+require_relative "logo_soup/core/background_detector"
+require_relative "logo_soup/core/pixel_analyzer"
+require_relative "logo_soup/core/feature_measurer"
+
+require_relative "logo_soup/style"
+
+module LogoSoup
+  class Error < StandardError; end
+
+  # Public API.
+  #
+  # @return [String] inline CSS style string
+  def self.style(**kwargs)
+    Style.call(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,265 @@
+--- !ruby/object:Gem::Specification
+name: logosoup
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexandre Camillo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rubocop-github
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Compute CSS sizing/alignment styles for SVG and raster logos with consistent
+  perceived rendering.
+email:
+- alexandre.camillo@codeminer42.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/logo_soup.rb
+- lib/logo_soup/core/background_detector.rb
+- lib/logo_soup/core/css.rb
+- lib/logo_soup/core/dimension_calculator.rb
+- lib/logo_soup/core/feature_measurer.rb
+- lib/logo_soup/core/image_loader.rb
+- lib/logo_soup/core/pixel_analyzer.rb
+- lib/logo_soup/core/svg_dimensions.rb
+- lib/logo_soup/core/visual_center_transform.rb
+- lib/logo_soup/style.rb
+- lib/logo_soup/version.rb
+homepage: https://example.com/logosoup
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Framework-agnostic logo normalization (CSS style output)
+test_files: []