laser-cutter 1.0.5 → 2.0.1

data/lib/{laser-cutter → laser/cutter}/notching/edge.rb

@@ -1,49 +1,54 @@
+# frozen_string_literal: true
+
 module Laser
   module Cutter
     module Notching
       MINIMUM_NOTCHES_PER_SIDE = 3
+      # Decimal places kept of length / notch width before counting notches.
+      RATIO_DIGITS = 6
       # This class represents a single edge of one side: both inside
       # and outside edge of the material.  It's also responsible
       # for calculating the "perfect" notch width.
       class Edge
+        # Both ends of an edge: 1 for p1, 2 for p2.
+        ENDS = [1, 2].freeze
 
-        attr_accessor :outside, :inside
-        attr_accessor :notch_width
-        attr_accessor :thickness, :kerf
-        attr_accessor :center_out, :corners, :adjust_corners
-        attr_accessor :notch_count, :v1, :v2
+        attr_accessor :outside, :inside, :notch_width, :thickness, :kerf, :center_out, :corners, :adjust_corners, :notch_count, :v1, :v2
 
+        # @return [Array<Integer>] the ends that get a corner box when +corners+ is set: 1 for p1, 2 for p2
+        attr_accessor :corner_ends
 
         def initialize(outside, inside, options = {})
           self.outside = outside.clone
           self.inside = inside.clone
 
           # two vectors representing directions going from beginning of each inside line to the outside
-          self.v1 = [inside.p1.x - outside.p1.x, inside.p1.y - outside.p1.y].map{|e| -(e / e.abs).to_f }
-          self.v2 = [inside.p2.x - outside.p2.x, inside.p2.y - outside.p2.y].map{|e| -(e / e.abs).to_f }
+          self.v1 = [inside.p1.x - outside.p1.x, inside.p1.y - outside.p1.y].map{ |e| -(e / e.abs).to_f }
+          self.v2 = [inside.p2.x - outside.p2.x, inside.p2.y - outside.p2.y].map{ |e| -(e / e.abs).to_f }
 
-          self.v1 = Vector.[](*self.v1)
-          self.v2 = Vector.[](*self.v2)
+          self.v1 = Vector.[](*v1)
+          self.v2 = Vector.[](*v2)
 
           self.center_out = options[:center_out] || false
           self.thickness = options[:thickness]
           self.corners = options[:corners]
+          self.corner_ends = options[:corner_ends] || ENDS
           self.kerf = options[:kerf] || 0
           self.notch_width = options[:notch_width]
           self.adjust_corners = options[:adjust_corners]
 
-          calculate_notch_width!
           adjust_for_kerf!
+          calculate_notch_width!
         end
 
         def adjust_for_kerf!
-          if kerf?
-            self.inside  = move_line_for_kerf(inside)
-            self.outside = move_line_for_kerf(outside)
-          end
+          return unless kerf?
+
+          self.inside  = move_line_for_kerf(inside)
+          self.outside = move_line_for_kerf(outside)
         end
 
-        def move_line_for_kerf line
+        def move_line_for_kerf(line)
           k = kerf / 2.0
           p1 = line.p1.plus(v1 * k)
           p2 = line.p2.plus(v2 * k)
@@ -51,7 +56,15 @@ module Laser
         end
 
         def kerf?
-          self.kerf > 0.0
+          kerf > 0.0
+        end
+
+        # Whether this edge draws a corner box at the given end.
+        #
+        # @param end_index [Integer] 1 for p1, 2 for p2
+        # @return [Boolean]
+        def corner_at?(end_index)
+          corners ? corner_ends.include?(end_index) : false
         end
 
         # face_setting determines if we want that face to have center notch
@@ -65,17 +78,20 @@ module Laser
         def first_notch_out?
           add_across_line?(center_out)
         end
+
         private
 
         def calculate_notch_width!
-          count = ((self.inside.length) / notch_width).to_f.ceil + 1
+          length = kerf? ? inside.length - kerf : inside.length
+          # Rounded before #ceil: when the notch divides the side exactly,
+          # float noise in the coordinates would otherwise decide the count,
+          # and the two panels meeting at this joint would disagree.
+          count = (length / notch_width).to_f.round(RATIO_DIGITS).ceil + 1
           count = (count / 2 * 2) + 1 # make count always an odd number
           count = [MINIMUM_NOTCHES_PER_SIDE, count].max
-
-          self.notch_width = 1.0 * (self.inside.length) / count
+          self.notch_width = 1.0 * length / count
           self.notch_count = count
         end
-
       end
     end
   end

data/lib/laser/cutter/notching/infinite_iterator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module Notching
+      # Alternating iterator
+      InfiniteIterator = Struct.new(:array) do
+        attr_accessor :array, :next_index, :calls
+
+        def initialize(array)
+          self.array = array
+          self.calls = 0
+          self.next_index = 0
+        end
+
+        def next
+          item = array[next_index].clone
+          self.next_index += 1
+          self.next_index %= array.size
+          self.calls += 1
+          item = yield item, calls if block_given?
+          item
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/notching/path_generator.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module Notching
+      class PathGenerator
+        extend ::Forwardable
+
+        %i(center_out thickness corners kerf kerf? notch_width first_notch_out? adjust_corners corners).each do |method_name|
+          def_delegator :@edge, method_name, method_name
+        end
+
+        attr_accessor :edge
+
+        # This class generates lines that zigzag between two lines: the outside line, and the
+        # inside line of a single edge. Edge class encapsulates both of them with additional
+        # properties.
+        def initialize(edge)
+          @edge = edge
+        end
+
+        # Calculates a notched path that flows between the outer edge of the box
+        # (outside_line) and inner (inside_line).  Relative location of these lines
+        # also defines the direction and orientation of the box, and hence the notches.
+        #
+        # We always want to create a symmetric path that has a notch in the middle
+        # (for center_out = true) or dip in the middle (center_out = false)
+        def generate
+          lines = []
+          lines << corner_box_sides if corners
+          lines << notch_lines
+          lines.flatten
+        end
+
+        # The zigzag alone, without the corner boxes.
+        #
+        # @return [Array<Geometry::Line>]
+        def notch_lines
+          point = starting_point
+          vertices = [point]
+          adjust_for_kerf(vertices, -1) if adjust_end?(1)
+          define_shifts.each do |shift|
+            point = shift.next_point_after point
+            vertices << point
+          end
+          adjust_for_kerf(vertices, 1) if adjust_end?(2)
+          create_lines(vertices)
+        end
+
+        def adjust_for_kerf(vertices, direction)
+          return unless kerf?
+
+          point = vertices.pop
+          point = point.plus(2 * direction * shift_vector(1))
+          vertices << point
+        end
+
+        def corner_box_sides
+          ends = Edge::ENDS.select { |end_index| edge.corner_at?(end_index) }
+
+          # These boxes occupy the corners of the 3D box. They do not match
+          # in width to our notches because they are usually merged with them.
+          # It's just an aesthetic choice I guess.
+          boxes = ends.map { |end_index| Geometry::Rect[inside_point(end_index).clone, outside_point(end_index).clone] }
+          sides = boxes.map(&:relocate!).map(&:sides)
+          sides << ends.map { |end_index| kerf_strip(end_index) } if kerf? && adjust_corners
+          sides.flatten
+        end
+
+        # Widens the corner box at one end by the kerf, on the side where
+        # nothing is attached to it: along the edge when the first notch is a
+        # hole, across it when the first notch is a tab.
+        #
+        # @param end_index [Integer] 1 for p1, 2 for p2
+        # @return [Array<Geometry::Line>]
+        def kerf_strip(end_index)
+          inside = inside_point(end_index)
+          outside = outside_point(end_index)
+          along, across = first_notch_out? ? [outside, inside] : [inside, outside]
+          moved = inside.plus(-2 * shift_vector(end_index, first_notch_out? ? 1 : 0))
+
+          coords = []
+          coords[d_index_along] = along[d_index_along]
+          coords[d_index_across] = across[d_index_across]
+          Geometry::Rect[moved, Geometry::Point[*coords]].sides << Geometry::Line[moved, inside.clone]
+        end
+
+        def shift_vector(index, dim_shift = 0)
+          shift = []
+          shift[(d_index_across + dim_shift) % 2] = 0
+          shift[(d_index_along + dim_shift) % 2] = kerf / 2.0 * edge.send(:"v#{index}").[]((d_index_along + dim_shift) % 2)
+          Vector.[](*shift)
+        end
+
+        def starting_point
+          edge.inside.p1.clone # start
+        end
+
+        # 0 = X, 1 = Y
+        def d_index_along
+          edge.inside.p1.x == edge.inside.p2.x ? 1 : 0
+        end
+
+        def d_index_across
+          (d_index_along + 1) % 2
+        end
+
+        def direction_along
+          edge.inside.p1.coords.[](d_index_along) < edge.inside.p2.coords.[](d_index_along) ? 1 : -1
+        end
+
+        def direction_across
+          edge.inside.p1.coords.[](d_index_across) < edge.outside.p1.coords.[](d_index_across) ? 1 : -1
+        end
+
+        private
+
+        def inside_point(end_index)
+          edge.inside.public_send(:"p#{end_index}")
+        end
+
+        def outside_point(end_index)
+          edge.outside.public_send(:"p#{end_index}")
+        end
+
+        # A corner box next to a hole is widened by the kerf, so the hole starts that much later.
+        def adjust_end?(end_index)
+          adjust_corners && !first_notch_out? && edge.corner_at?(end_index)
+        end
+
+        # This method has the bulk of the logic: we create the list of path deltas
+        # to be applied when we walk the edge next.
+        # @param [Object] shift
+        def define_shifts
+          along_iter = create_iterator_along
+          across_iter = create_iterator_across
+
+          shifts = []
+          inner = true # false when we are drawing outer notch, true when inner
+
+          if first_notch_out?
+            shifts << across_iter.next
+            inner = !inner
+          end
+
+          (1..edge.notch_count).to_a.each do |notch_number|
+            shifts << along_iter.next do |shift, _index|
+              if inner && notch_number > 1 && notch_number < edge.notch_count
+                shift.delta -= kerf
+              elsif !inner
+                shift.delta += kerf
+              end
+              inner = !inner
+              shift
+            end
+            shifts << across_iter.next unless notch_number == edge.notch_count
+          end
+
+          shifts << across_iter.next if first_notch_out?
+          shifts
+        end
+
+        # As we draw notches, shifts define the 'delta' – movement from one point
+        # to the next.  This method defines three types of movements we'll be doing:
+        # one alongside the edge, and two across (towards the box and outward from the box)
+        def create_iterator_along
+          InfiniteIterator.new([Shift.new(notch_width, direction_along, d_index_along)])
+        end
+
+        def create_iterator_across
+          InfiniteIterator.new([Shift.new(thickness, direction_across, d_index_across),
+                                Shift.new(thickness, -direction_across, d_index_across)])
+        end
+
+        def create_lines(vertices)
+          lines = []
+          vertices.each_with_index do |v, i|
+            if v != vertices.last
+              lines << Geometry::Line.new(v, vertices[i + 1])
+            end
+          end
+          lines.flatten
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/notching/shift.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module Notching
+      Shift = Struct.new(:delta, :direction, :dim_index) do
+        def next_point_after(point)
+          p = point.clone
+          shift = []
+          shift[dim_index] = delta * direction
+          shift[(dim_index + 1) % 2] = 0
+          p.plus(*shift)
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/options.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    # Everything a box can be asked for, typed. This is what a Ruby program
+    # hands to {Laser::Cutter.render} or {Laser::Cutter.write}.
+    #
+    # Values are coerced, so the Strings of a web form will do, and an
+    # instance cannot be changed: #new(lid: :plain) returns a changed copy.
+    # Keys may be Strings or Symbols. A key it does not
+    # know, a value of the wrong type or a dimension left out all raise,
+    # at once, before anything is drawn.
+    #
+    # The distances left nil take the default for the units: a kerf of
+    # 0.0024in, a margin of 0.125in, a padding of 0.1in, a stroke of 0.001in,
+    # and a notch three times the thickness.
+    #
+    # @example A box in millimeters, with a plain lid, as an SVG
+    #   options = Laser::Cutter::Options.new(width: 70, height: 20, depth: 50, thickness: 4.3,
+    #                                        units: :mm, lid: :plain, format: :svg)
+    #   options.lid                 # => "plain"
+    #   Laser::Cutter.render(options) # => "<svg ..."
+    #
+    # @raise [MissingOption] when width, height, depth or thickness is left out
+    # @raise [InvalidOption] when a value cannot be used, or a key is not an option
+    class Options < Dry::Struct
+      # The dimensions a box cannot be drawn without.
+      REQUIRED = %i[width height depth thickness].freeze
+
+      # The longest list of allowed values an error spells out.
+      MAXIMUM_CHOICES = 5
+
+      transform_keys(&:to_sym)
+      schema schema.strict
+
+      # @!attribute [r] width
+      #   @return [Float] internal width of the box
+      attribute :width, Types::Length
+
+      # @!attribute [r] height
+      #   @return [Float] internal height of the box
+      attribute :height, Types::Length
+
+      # @!attribute [r] depth
+      #   @return [Float] internal depth of the box
+      attribute :depth, Types::Length
+
+      # @!attribute [r] thickness
+      #   @return [Float] thickness of the material
+      attribute :thickness, Types::Length
+
+      # @!attribute [r] notch
+      #   @return [Float, nil] notch length, a guide only; nil for three times the thickness
+      attribute? :notch, Types.optional(Types::Length)
+
+      # @!attribute [r] kerf
+      #   @return [Float, nil] width of the cut; nil for the default
+      attribute? :kerf, Types.optional(Types::Allowance)
+
+      # @!attribute [r] units
+      #   @return [String] "in" or "mm", the units of every distance here
+      attribute :units, Types::Units
+
+      # @!attribute [r] lid
+      #   @return [String] "full", "back" or "plain": notched on every side, into the back wall only, or on no side
+      attribute :lid, Types::Lid
+
+      # @!attribute [r] format
+      #   @return [String, nil] "pdf" or "svg"; nil for a PDF, or for what the extension of the file says
+      attribute? :format, Types.optional(Types::Format)
+
+      # @!attribute [r] file
+      #   @return [String, nil] the file {Laser::Cutter.write} writes
+      attribute? :file, Types.optional(Types::Coercible::String)
+
+      # @!attribute [r] margin
+      #   @return [Float, nil] margin from the edge of the page; nil for the default
+      attribute? :margin, Types.optional(Types::Allowance)
+
+      # @!attribute [r] padding
+      #   @return [Float, nil] space between the panels; nil for the default
+      attribute? :padding, Types.optional(Types::Allowance)
+
+      # @!attribute [r] stroke
+      #   @return [Float, nil] stroke width of the lines; nil for the default
+      attribute? :stroke, Types.optional(Types::Length)
+
+      # @!attribute [r] page_size
+      #   @return [String, nil] a page size such as "A4", for a PDF; nil to fit the box
+      attribute? :page_size, Types.optional(Types::PageSize)
+
+      # @!attribute [r] page_layout
+      #   @return [String] "portrait" or "landscape", for a PDF
+      attribute :page_layout, Types::PageLayout
+
+      # @!attribute [r] metadata
+      #   @return [Boolean] whether the settings of the box are printed on the page
+      attribute :metadata, Types::Params::Bool.default(true)
+
+      # @!attribute [r] inside_box
+      #   @return [Boolean] whether the box is also drawn without kerf, in red
+      attribute :inside_box, Types::Params::Bool.default(false)
+
+      class << self
+        # @param attributes [Hash, Options] the options, by name
+        # @return [Options]
+        # @raise [MissingOption, InvalidOption]
+        def new(attributes = {}, *)
+          return attributes if attributes.is_a?(self)
+
+          require_dimensions!(attributes) if attributes.respond_to?(:to_h)
+          super
+        rescue Dry::Struct::Error => e
+          raise InvalidOption, explain(e)
+        end
+
+        private
+
+        def require_dimensions!(attributes)
+          given = attributes.to_h.transform_keys(&:to_sym)
+          missing = REQUIRED.select { |name| Types.blank?(given[name]) }
+          return if missing.empty?
+
+          raise MissingOption, "#{missing.join(', ')} #{missing.size > 1 ? 'are' : 'is'} required, but missing."
+        end
+
+        # Says which option was refused, and what it may be when that is a short list.
+        def explain(error)
+          cause = error.cause
+          return error.message.sub(/\A\[.*?\] /, '') unless cause.respond_to?(:key) && cause.respond_to?(:value)
+
+          choices = choices_of(schema.key(cause.key).type)
+          allowed = choices && choices.size <= MAXIMUM_CHOICES ? ", but must be one of: #{choices.join(', ')}" : ''
+          "#{cause.key} cannot be #{cause.value.inspect}#{allowed}."
+        end
+
+        # The words an attribute may be, found under whatever wraps its type.
+        #
+        # @return [Array<String>, nil] nil when the attribute is not one of a list
+        def choices_of(type)
+          return type.values if type.respond_to?(:values)
+
+          inner = %i[right type].find { |name| type.respond_to?(name) }
+          choices_of(type.public_send(inner)) if inner
+        end
+      end
+
+      # @return [Configuration] the same settings, as the renderers take them
+      def to_configuration
+        Configuration.new(to_h.except(:format, :inside_box).merge(debug: inside_box))
+      end
+    end
+  end
+end

data/lib/laser/cutter/page_manager.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    class PageManager
+      SIZES = PDF::Core::PageGeometry::SIZES.clone.freeze
+
+      attr_reader :units
+
+      # @param units [String, Symbol] 'in' or 'mm'; the configuration's default is a Symbol
+      def initialize(units)
+        @units = units.to_s
+      end
+
+      def all_page_sizes
+        output = +""
+        page_size_values.each do |k|
+          output << sprintf("\t%10s:\t%6.1f x %6.1f\n", *k)
+        end
+        output
+      end
+
+      # if from_units is nil, we expect it to be in dots per inch (default
+      # measurements for Prawn
+      def value_from_units(value, from_units = nil)
+        multiplier = if from_units.nil?
+                       if units.eql?('in')
+                         1.0 / 72.0 # PDF units per inch
+                       else
+                         25.4 * 1.0 / 72.0
+                       end
+                     elsif units.eql?(from_units)
+                       1.0
+                     elsif units.eql?('in') && from_units.eql?('mm')
+                       (1.0 / 25.4)
+                     else
+                       25.4
+                     end
+        value.to_f * multiplier
+      end
+
+      def page_size_values
+        h = Hashie::Mash.new(SIZES)
+        h.keys.sort.map do |k|
+          [k, value_from_units(h[k][0].to_f), value_from_units(h[k][1].to_f)]
+        end
+      end
+    end
+  end
+end

data/lib/{laser-cutter → laser/cutter}/renderer/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Laser
   module Cutter
     module Renderer
@@ -16,15 +18,20 @@ module Laser
           self.page_manager = Laser::Cutter::PageManager.new(config.units)
         end
 
-        def render
+        # Writes the document to config.file, yielding after each line drawn.
+        def render(&)
+          File.binwrite(config.file, document(&))
+        end
+
+        # @return [String] the document, yielding after each line drawn
+        def document
           raise 'Abstract method'
         end
 
         def units
-          config.units.to_sym || :mm
+          config.units.to_sym
         end
       end
     end
   end
 end
-

data/lib/laser/cutter/renderer/box_renderer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module Renderer
+      class BoxRenderer < Base
+        alias_method :box, :subject
+
+        def initialize(config)
+          super
+          self.subject = Laser::Cutter::Box.new(config)
+        end
+
+        def ensure_space_for(rect)
+          coords = [rect.p2.x, rect.p2.y].map{ |a| page_manager.value_from_units(a) }
+          box.metadata = Geometry::Point.new(coords)
+        end
+
+        def enclosure
+          box.enclosure
+        end
+
+        # @return [Array<Geometry::Line>] every line to cut, computed once
+        def lines
+          @lines ||= box.generate_notches
+        end
+
+        # Draws the box, yielding after each line so a caller can count them.
+        def render(pdf = nil)
+          pdf.line_width = config.stroke.send(units)
+          pdf.stroke_color config[:color] || BLACK
+          lines.each do |line|
+            LineRenderer.new(config, line).render(pdf)
+            yield line if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/renderer/layout_renderer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module Renderer
+      # Writes the PDF: the box, its metadata block, and the unkerfed outline
+      # when asked for.
+      class LayoutRenderer < Base
+        UNKERFED_COLOR = 'DD2211'
+
+        def initialize(config)
+          self.config = config
+          super
+        end
+
+        # @return [Integer] how many lines {#render} draws, and yields
+        def total
+          box_renderers.sum { |renderer| renderer.lines.size }
+        end
+
+        # @return [String] the PDF, yielding after each line drawn
+        def document(&)
+          margin = config.margin.to_f.send(units)
+          pdf = Prawn::Document.new(margin:      margin,
+                                    page_size:   config.page_size || calculate_image_boundary(box_renderers.first, margin),
+                                    page_layout: config.page_layout.to_sym)
+
+          box_renderers.first.render(pdf, &)
+          meta_renderer&.render(pdf)
+          box_renderers.drop(1).each { |renderer| renderer.render(pdf, &) }
+          pdf.render
+        end
+
+        def calculate_image_boundary(box_renderer, margin)
+          box_renderer.enclosure.to_a[1].map do |c|
+            c.send(units) + (2 * margin)
+          end
+        end
+
+        private
+
+        def meta_renderer
+          @meta_renderer ||= MetaRenderer.new(config) if config.metadata
+        end
+
+        # The box, then the same box without kerf when config.debug is set.
+        def box_renderers
+          @box_renderers ||= begin
+            configs = [config]
+            configs << Configuration.new(config.to_hash).merge!(kerf: 0.0, color: UNKERFED_COLOR) if config.debug
+            configs.map do |box_config|
+              BoxRenderer.new(box_config).tap do |renderer|
+                renderer.ensure_space_for(meta_renderer.enclosure) if meta_renderer
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end