yarn_skein 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2efd2c01dfa8a4654b1f110487399eb0111dba77daf030e7d3826d3514531a75
-  data.tar.gz: ea44d7874a49e18995a51e9ca09a04c787bf43db2f49a79281213f4679db14bb
+  metadata.gz: 6e58123240286568c5799c6ee0d7ed8572de554f44c4e2cbf653e178be29a181
+  data.tar.gz: bd9aba63f86efb708f7156575d7136d91cd660f05bc857b5a0cb50b8087586b7
 SHA512:
-  metadata.gz: 737cb9cedba8020ac8d5050d771a3051f43fa56a1a55c634120dbb77d1a977e22e0affb71d5b4746fa106c488468a19a737a4723319eb71e85a06722ab2d07fa
-  data.tar.gz: e52704d9b994e919071302371e97c0d7d56fe0b72e64c26c01d71015211e520566a6406d1de8c259c5826b10614d2a748c69d0852f9f62c09c275c2a50c23a76
+  metadata.gz: 7a13f3cde5def54d9bdd85026f2d143a9e3d0e9ca4b76023573839c8fc6f6d1b224580e62eb19907b6559a08391103470efb71fb7e6dba428d1364f64d4ea165
+  data.tar.gz: 398c7cfaa30a61beb4839fda0bc96737023b03df676b1fb85cae9e8854e4d7119e2f32be1de5fe2a86d402ea365450a0547b8749938395f68cb18644b61d5567

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-28
+
+### Added
+- `YarnSkein::ColorworkEstimator` for estimating per-color yarn yardage in stranded and intarsia colorwork
+- Supports float overhead calculation for stranded colorwork (default 20%)
+- Per-color breakdown with optional skein calculations when yarn is provided
+- Configurable safety margin (default 10%) consistent with `YardageEstimator`
+
 ## [0.3.0] - 2026-03-26
 
 ### Added

data/lib/yarn_skein/colorwork_estimator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module YarnSkein
+  # Estimates per-color yarn yardage for colorwork techniques.
+  #
+  # Supports stranded (Fair Isle) and intarsia colorwork. Stranded colorwork
+  # adds a float overhead factor because unused colors are carried across the
+  # back of the fabric. Intarsia uses separate yarn sections with no floats.
+  #
+  # @example Stranded colorwork
+  #   estimator = YarnSkein::ColorworkEstimator.new(
+  #     gauge: gauge,
+  #     technique: :stranded
+  #   )
+  #   estimator.estimate(
+  #     width: 40.inches, height: 24.inches,
+  #     colors: { main: 0.60, contrast: 0.40 },
+  #     yarn: yarn
+  #   )
+  #
+  # @example Intarsia colorwork
+  #   estimator = YarnSkein::ColorworkEstimator.new(
+  #     gauge: gauge,
+  #     technique: :intarsia
+  #   )
+  #   estimator.estimate(
+  #     width: 40.inches, height: 24.inches,
+  #     colors: { left: 0.50, right: 0.50 },
+  #     yarn: yarn
+  #   )
+  class ColorworkEstimator
+    TECHNIQUES = %i[stranded intarsia].freeze
+
+    # Default float overhead for stranded colorwork (20%).
+    DEFAULT_FLOAT_OVERHEAD = 0.20
+
+    # Default safety margin (10%), consistent with YardageEstimator.
+    DEFAULT_MARGIN = 0.10
+
+    # @return [FiberGauge::Gauge]
+    attr_reader :gauge
+
+    # @return [Symbol] :stranded or :intarsia
+    attr_reader :technique
+
+    # @param gauge [FiberGauge::Gauge] gauge swatch data
+    # @param technique [Symbol] :stranded or :intarsia
+    def initialize(gauge:, technique:)
+      unless TECHNIQUES.include?(technique)
+        raise ArgumentError, "technique must be one of: #{TECHNIQUES.join(", ")}"
+      end
+
+      @gauge = gauge
+      @technique = technique
+    end
+
+    # Estimates per-color yardage for a colorwork piece.
+    #
+    # @param width [FiberUnits::Length] finished width
+    # @param height [FiberUnits::Length] finished height
+    # @param colors [Hash<Symbol, Float>] color name => proportion (must sum to 1.0)
+    # @param yarn [YarnSkein::Yarn, nil] yarn for skein calculations
+    # @param margin [Float] safety margin (default 10%)
+    # @param float_overhead [Float] extra yarn for floats in stranded work (default 20%)
+    # @return [Hash] per-color breakdown and total
+    def estimate(width:, height:, colors:, yarn: nil, margin: DEFAULT_MARGIN, float_overhead: DEFAULT_FLOAT_OVERHEAD)
+      validate_colors!(colors)
+
+      base_yardage = base_yardage_for(width, height, margin: 0.0)
+      result = {}
+      total_yards = 0.0
+
+      colors.each do |color_name, proportion|
+        color_yards = base_yardage * proportion
+        color_yards *= (1.0 + float_overhead) if technique == :stranded
+        color_yards *= (1.0 + margin)
+        total_yards += color_yards
+
+        entry = {yardage: color_yards.yards}
+        entry[:skeins] = yarn.skeins_required(color_yards.yards) if yarn
+        result[color_name] = entry
+      end
+
+      result[:total] = {yardage: total_yards.yards}
+      result
+    end
+
+    private
+
+    # Compute raw yardage (in float yards) for a rectangle with no margin.
+    def base_yardage_for(width, height, margin:)
+      stitches = gauge.required_stitches(width)
+      rows = gauge.required_rows(height)
+      total_stitches = stitches.value * rows.value
+
+      total_stitches * yards_per_stitch
+    end
+
+    # Yards of yarn consumed per stitch, using the geometric U-loop model.
+    def yards_per_stitch
+      stitch_width_in = 1.0 / gauge.spi
+      stitch_height_in = 1.0 / gauge.rpi
+      (stitch_width_in + (2.0 * stitch_height_in)) / 36.0
+    end
+
+    def validate_colors!(colors)
+      raise ArgumentError, "colors must be a non-empty Hash" unless colors.is_a?(Hash) && !colors.empty?
+
+      total = colors.values.sum
+      unless (total - 1.0).abs < 0.001
+        raise ArgumentError, "color proportions must sum to 1.0 (got #{total})"
+      end
+
+      colors.each do |name, proportion|
+        unless proportion.is_a?(Numeric) && proportion > 0
+          raise ArgumentError, "proportion for #{name} must be a positive number"
+        end
+      end
+    end
+  end
+end

data/lib/yarn_skein/version.rb

@@ -3,6 +3,6 @@
 # :nocov:
 module YarnSkein
   # Current gem version.
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end
 # :nocov:

data/lib/yarn_skein.rb

@@ -8,6 +8,7 @@ require_relative "yarn_skein/fiber_blend"
 require_relative "yarn_skein/yarn"
 require_relative "yarn_skein/substitution"
 require_relative "yarn_skein/yardage_estimator"
+require_relative "yarn_skein/colorwork_estimator"
 require_relative "yarn_skein/catalog"
 
 # Domain objects for describing yarn skeins, fiber blends, and weight classes.

data/test/colorwork_estimator_test.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinColorworkEstimatorTest < Minitest::Test
+  def gauge
+    FiberGauge::Gauge.new(
+      stitches: 18.stitches,
+      rows: 24.rows,
+      width: 4.inches,
+      height: 4.inches
+    )
+  end
+
+  def yarn
+    YarnSkein::Yarn.new(
+      brand: "Malabrigo",
+      line: "Rios",
+      yardage: 210.yards,
+      skein_weight: 100.grams
+    )
+  end
+
+  def stranded_estimator
+    YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :stranded)
+  end
+
+  def intarsia_estimator
+    YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :intarsia)
+  end
+
+  # ----------------------------
+  # initialization
+  # ----------------------------
+
+  def test_rejects_invalid_technique
+    assert_raises(ArgumentError) do
+      YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :mosaic)
+    end
+  end
+
+  def test_accepts_stranded_technique
+    est = YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :stranded)
+    assert_equal :stranded, est.technique
+  end
+
+  def test_accepts_intarsia_technique
+    est = YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :intarsia)
+    assert_equal :intarsia, est.technique
+  end
+
+  # ----------------------------
+  # color validation
+  # ----------------------------
+
+  def test_rejects_empty_colors
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(width: 20.inches, height: 20.inches, colors: {})
+    end
+  end
+
+  def test_rejects_non_hash_colors
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(width: 20.inches, height: 20.inches, colors: [0.5, 0.5])
+    end
+  end
+
+  def test_rejects_proportions_not_summing_to_one
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(
+        width: 20.inches, height: 20.inches,
+        colors: {main: 0.60, contrast: 0.30}
+      )
+    end
+  end
+
+  def test_rejects_zero_proportion
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(
+        width: 20.inches, height: 20.inches,
+        colors: {main: 1.0, contrast: 0.0}
+      )
+    end
+  end
+
+  # ----------------------------
+  # stranded estimation
+  # ----------------------------
+
+  def test_stranded_returns_per_color_yardage
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40}
+    )
+
+    assert result.key?(:main)
+    assert result.key?(:contrast)
+    assert result.key?(:total)
+    assert_instance_of FiberUnits::Length, result[:main][:yardage]
+    assert_instance_of FiberUnits::Length, result[:contrast][:yardage]
+    assert_instance_of FiberUnits::Length, result[:total][:yardage]
+  end
+
+  def test_stranded_includes_float_overhead
+    stranded = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.20
+    )
+
+    intarsia = intarsia_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0
+    )
+
+    # Stranded total should be 20% more than intarsia (due to float overhead)
+    stranded_total = stranded[:total][:yardage].to(:yards).value
+    intarsia_total = intarsia[:total][:yardage].to(:yards).value
+
+    assert_in_delta intarsia_total * 1.20, stranded_total, 0.01
+  end
+
+  def test_stranded_custom_float_overhead
+    low_overhead = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.15
+    )
+
+    high_overhead = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.25
+    )
+
+    assert high_overhead[:total][:yardage].to(:yards).value >
+           low_overhead[:total][:yardage].to(:yards).value
+  end
+
+  def test_stranded_proportions_affect_distribution
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.70, contrast: 0.30},
+      margin: 0.0
+    )
+
+    main_yards = result[:main][:yardage].to(:yards).value
+    contrast_yards = result[:contrast][:yardage].to(:yards).value
+
+    assert_in_delta 7.0 / 3.0, main_yards / contrast_yards, 0.01
+  end
+
+  # ----------------------------
+  # intarsia estimation
+  # ----------------------------
+
+  def test_intarsia_no_float_overhead
+    intarsia = intarsia_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {left: 0.50, right: 0.50},
+      margin: 0.0
+    )
+
+    # For intarsia, each half should get half the base yardage
+    left_yards = intarsia[:left][:yardage].to(:yards).value
+    right_yards = intarsia[:right][:yardage].to(:yards).value
+
+    assert_in_delta left_yards, right_yards, 0.01
+  end
+
+  def test_intarsia_total_matches_base_yardage
+    intarsia = intarsia_estimator.estimate(
+      width: 20.inches, height: 30.inches,
+      colors: {left: 0.50, right: 0.50},
+      margin: 0.0
+    )
+
+    # Total intarsia yardage should match a plain YardageEstimator (no margin)
+    base = YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+    base_result = base.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+
+    assert_in_delta(
+      base_result[:yardage].to(:yards).value,
+      intarsia[:total][:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # ----------------------------
+  # skein calculations
+  # ----------------------------
+
+  def test_includes_skeins_when_yarn_provided
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      yarn: yarn
+    )
+
+    assert result[:main].key?(:skeins)
+    assert result[:contrast].key?(:skeins)
+    assert_instance_of Integer, result[:main][:skeins]
+    assert_instance_of Integer, result[:contrast][:skeins]
+  end
+
+  def test_omits_skeins_when_no_yarn
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40}
+    )
+
+    refute result[:main].key?(:skeins)
+    refute result[:contrast].key?(:skeins)
+  end
+
+  # ----------------------------
+  # margin
+  # ----------------------------
+
+  def test_default_margin_applied
+    no_margin = intarsia_estimator.estimate(
+      width: 20.inches, height: 20.inches,
+      colors: {main: 1.0},
+      margin: 0.0
+    )
+
+    with_margin = intarsia_estimator.estimate(
+      width: 20.inches, height: 20.inches,
+      colors: {main: 1.0}
+    )
+
+    assert_in_delta(
+      no_margin[:main][:yardage].to(:yards).value * 1.10,
+      with_margin[:main][:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # ----------------------------
+  # multi-color
+  # ----------------------------
+
+  def test_three_color_stranded
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.50, contrast_a: 0.30, contrast_b: 0.20},
+      margin: 0.0
+    )
+
+    assert result.key?(:main)
+    assert result.key?(:contrast_a)
+    assert result.key?(:contrast_b)
+    assert result.key?(:total)
+
+    total = result[:main][:yardage].to(:yards).value +
+            result[:contrast_a][:yardage].to(:yards).value +
+            result[:contrast_b][:yardage].to(:yards).value
+
+    assert_in_delta total, result[:total][:yardage].to(:yards).value, 0.01
+  end
+
+  # ----------------------------
+  # realistic scenario
+  # ----------------------------
+
+  def test_fair_isle_yoke_estimate_is_reasonable
+    # A Fair Isle yoke ~20" wide, 12" tall in worsted weight
+    result = stranded_estimator.estimate(
+      width: 20.inches, height: 12.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      yarn: yarn
+    )
+
+    main_yards = result[:main][:yardage].to(:yards).value
+    contrast_yards = result[:contrast][:yardage].to(:yards).value
+    total_yards = result[:total][:yardage].to(:yards).value
+
+    assert total_yards > 50, "total #{total_yards} seems too low"
+    assert total_yards < 500, "total #{total_yards} seems too high"
+    assert main_yards > contrast_yards, "main color should use more yarn"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yarn_skein
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Meagan Waller
@@ -66,6 +66,7 @@ files:
 - Rakefile
 - lib/yarn_skein.rb
 - lib/yarn_skein/catalog.rb
+- lib/yarn_skein/colorwork_estimator.rb
 - lib/yarn_skein/fiber_blend.rb
 - lib/yarn_skein/substitution.rb
 - lib/yarn_skein/version.rb
@@ -74,6 +75,7 @@ files:
 - lib/yarn_skein/yarn.rb
 - sig/yarn_skein.rbs
 - test/catalog_test.rb
+- test/colorwork_estimator_test.rb
 - test/fiber_blend_test.rb
 - test/substitution_test.rb
 - test/test_helper.rb