laser-cutter 1.0.5 → 2.0.1

data/lib/laser/cutter/aggregator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    # Merges the lines of one face into the outline to cut.
+    #
+    # Each edge draws its own notch path and its own corner boxes, so where
+    # two of them meet the same stretch is drawn twice, once from each side.
+    # That stretch runs through the material and must not be cut. So every
+    # collinear group of lines is combined as a symmetric difference: a point
+    # is cut when an odd number of lines cover it. Two identical lines cancel,
+    # two overlapping lines keep only the parts they do not share, and lines
+    # that touch or overlap end to end join into one.
+    #
+    # Lines are grouped by axis and offset, sorted, and swept once, so a face
+    # of n lines takes n log n. Lines on neither axis pass through untouched.
+    class Aggregator
+      # Coordinates this close together count as the same.
+      TOLERANCE = Math.sqrt(Geometry::Tuple::PRECISION)
+
+      # @return [Array<Geometry::Line>] the outline, sorted
+      attr_reader :lines
+
+      # @param lines [Array<Geometry::Line>]
+      def initialize(lines = [])
+        @lines = (sweep(lines, 0) + sweep(lines, 1) + skewed(lines)).sort
+      end
+
+      private
+
+      # Lines running along one axis: 0 for horizontal (constant y), 1 for vertical (constant x).
+      #
+      # @return [Array<Geometry::Line>]
+      def sweep(lines, axis)
+        across = (axis + 1) % 2
+        along = lines.select { |line| along?(line, axis) }
+        groups(along, across).flat_map { |offset, group| cut_intervals(group, axis, offset, across) }
+      end
+
+      def skewed(lines)
+        lines.reject { |line| along?(line, 0) || along?(line, 1) }
+      end
+
+      def along?(line, axis)
+        across = (axis + 1) % 2
+        (line.p1[across] - line.p2[across]).abs <= TOLERANCE && (line.p1[axis] - line.p2[axis]).abs > TOLERANCE
+      end
+
+      # Lines on the same row or column, keyed by the offset of the first one seen.
+      def groups(lines, across)
+        lines.sort_by { |line| line.p1[across] }.slice_when { |a, b| b.p1[across] - a.p1[across] > TOLERANCE }
+             .to_h { |group| [group.first.p1[across], group] }
+      end
+
+      # Sweeps the endpoints of one collinear group, keeping the stretches an
+      # odd number of lines cover.
+      def cut_intervals(group, axis, offset, across)
+        events = group.flat_map do |line|
+          from, to = [line.p1[axis], line.p2[axis]].sort
+          [[from, 1], [to, -1]]
+        end
+        events.sort_by! { |position, step| [position, step] }
+
+        intervals = []
+        covered = 0
+        started = nil
+        events.each do |position, step|
+          was = covered
+          covered += step
+          if was.even? && covered.odd?
+            started = position
+          elsif was.odd? && covered.even?
+            extend_or_add(intervals, started, position)
+          end
+        end
+        intervals.map { |from, to| line_between(from, to, axis, offset, across) }
+      end
+
+      # Joins an interval onto the last one when they touch, and drops one with no length.
+      def extend_or_add(intervals, from, to)
+        return if to - from <= TOLERANCE
+
+        last = intervals.last
+        if last && from - last[1] <= TOLERANCE
+          last[1] = to
+        else
+          intervals << [from, to]
+        end
+      end
+
+      def line_between(from, to, axis, offset, across)
+        a = []
+        b = []
+        a[axis] = from
+        b[axis] = to
+        a[across] = b[across] = offset
+        Geometry::Line.new(Geometry::Point[*a], Geometry::Point[*b])
+      end
+    end
+  end
+end

data/lib/laser/cutter/box.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    # Note: this class badly needs refactoring and tests.  Both are coming.
+
+    class Box
+      # How the lid, the top panel, joins the walls: notched on all four sides,
+      # on the side of the back wall only, or on none.
+      LIDS = %i[full back plain].freeze
+
+      # The side of each wall that meets the lid, as an index into Rect#sides.
+      LID_SIDES = { 'front' => 0, 'left' => 0, 'right' => 0, 'back' => 2 }.freeze
+
+      # Everything is in millimeters
+
+      attr_accessor :dim, :thickness, :notch_width, :kerf, :padding, :units, :inside_box, :front, :back, :top, :bottom, :left, :right, :faces, :bounds, :conf, :corner_face, :metadata, :notches
+
+      # @return [Symbol] one of LIDS
+      attr_accessor :lid
+
+      # @return [Hash{String => Array<Geometry::Line>}] the lines to cut for each face, by its name
+      attr_accessor :outlines
+
+      def initialize(config = {})
+        self.dim = Geometry::Dimensions.new(config['width'], config['height'], config['depth'])
+        self.thickness = config['thickness']
+
+        self.notch_width = config['notch'] || (1.0 * longest / 5.0)
+        self.kerf = config['kerf'] || 0.0
+        self.padding = config['padding']
+        self.units = config['units']
+        self.inside_box = config['inside_box']
+        self.lid = (config['lid'] || LIDS.first).to_sym
+
+        self.notches = []
+        self.outlines = {}
+
+        self.metadata = Geometry::Point[config['metadata_width'] || 0, config['metadata_height'] || 0]
+
+        create_faces! # generates dimensions for each side
+        self.faces = [top, front, bottom, back, left, right]
+
+        self.conf = {
+          valign:  [:out, :out, :out, :out, :in, :in],
+          halign:  [:in, :out, :in, :out, :in, :in],
+          corners: {
+            front: [:no, :yes, :no, :yes, :no, :no], # our default choice, but may not work
+            top:   [:yes, :no, :yes, :no, :no, :no] # 2nd choice, has to work if 1st doesn't
+          },
+        }
+      end
+
+      def enclosure
+        generate_notches if notches.empty?
+        p1 = notches.first.p1.to_a
+        p2 = notches.first.p2.to_a
+
+        notches.each do |notch|
+          n = notch.normalized
+          n.p1.to_a.each_with_index { |c, i| p1[i] = c if c < p1[i] }
+          n.p2.to_a.each_with_index { |c, i| p2[i] = c if c > p2[i] }
+        end
+
+        Geometry::Rect[Geometry::Point.new(p1), Geometry::Point.new(p2)]
+      end
+
+      def generate_notches
+        position_faces!
+        corner_face = pick_corners_face
+        self.notches = []
+        self.outlines = {}
+        faces.each_with_index do |face, face_index|
+          edges = edges_of(face, face_index, corner_face)
+
+          if edges.any?(&:corners) && !edges.all?(&:first_notch_out?)
+            edges.each { |e| e.adjust_corners = true }
+          end
+
+          outlines[face.name] = Aggregator.new(lines_of(face, edges)).lines
+          notches << outlines[face.name]
+        end
+        notches.flatten!
+      end
+
+      def w; dim.w; end
+      def h; dim.h; end
+      def d; dim.d; end
+
+      def longest
+        [w, h, d].max
+      end
+
+      def to_s
+        "Box:\nH:#{dim.h} W:#{dim.w} D:#{dim.d}\nThickness:#{thickness}, Notch:#{notch_width}"
+      end
+
+      private
+
+      # One edge for each side of a face, pairing the side with the matching
+      # side of the face grown by the thickness.
+      #
+      # @return [Array<Notching::Edge>]
+      def edges_of(face, face_index, corner_face)
+        bound = face_bounding_rect(face)
+        bound.sides.each_with_index.map do |bounding_side, side_index|
+          include_corners = conf[:corners][corner_face][face_index] == :yes && side_index.odd?
+          key = side_index.odd? ? :valign : :halign
+          Notching::Edge.new(bounding_side,
+                             face.sides[side_index],
+                             { notch_width: notch_width,
+                               thickness:   thickness,
+                               kerf:        kerf,
+                               center_out:  conf[key][face_index] == :out,
+                               corners:     include_corners,
+                               corner_ends: corner_ends(face, side_index) })
+        end
+      end
+
+      # A lid that lifts off covers the corners above the walls, so a wall
+      # keeps no corner box at the end of a side that touches the lid.
+      #
+      # @return [Array<Integer>] the ends of the side that may carry a corner box
+      def corner_ends(face, side_index)
+        lid_side = LID_SIDES[face.name]
+        return Notching::Edge::ENDS if lid == :full || lid_side.nil?
+
+        case (side_index - lid_side) % 4
+        when 1 then [2]
+        when 3 then [1]
+        else Notching::Edge::ENDS
+        end
+      end
+
+      # @return [Array<Geometry::Line>] the lines of a face before they are merged
+      def lines_of(face, edges)
+        return lid_lines(edges) if face.equal?(top)
+
+        edges.each_with_index.flat_map do |edge, side_index|
+          straight?(face, side_index) ? [edge.inside] : Notching::PathGenerator.new(edge).generate
+        end
+      end
+
+      # Whether a side of a wall lies under a lid edge that has no notches.
+      def straight?(face, side_index)
+        return false if lid == :full || (lid == :back && face.equal?(back))
+
+        LID_SIDES[face.name] == side_index
+      end
+
+      def lid_lines(edges)
+        case lid
+        when :plain then edges.map(&:outside)
+        when :back then back_lid_lines(edges)
+        else edges.flat_map { |edge| Notching::PathGenerator.new(edge).generate }
+        end
+      end
+
+      # The lid notched into the back wall only. Its other three edges are
+      # straight, along the outside of the walls. Either side of the notches
+      # it has a foot, the corner square above the side wall.
+      def back_lid_lines(edges)
+        joint = edges.first
+        joint.corners = true
+        joint.adjust_corners = true
+        path = Notching::PathGenerator.new(joint).notch_lines
+
+        path + foot(joint.outside.p1, path.first.p1) + foot(joint.outside.p2, path.last.p2) + edges.drop(1).map(&:outside)
+      end
+
+      # The two sides of a foot the notches do not draw: its bottom, from the
+      # outer corner of the lid, and the side that faces the first notch.
+      def foot(corner, notch)
+        turn = Geometry::Point[notch.x, corner.y]
+        [Geometry::Line[corner, turn], Geometry::Line[turn, notch]]
+      end
+
+      def face_bounding_rect(face)
+        b = face.clone
+        b.move_to(b.position.plus(-thickness, -thickness))
+        b.p2 = b.p2.plus(2 * thickness, 2 * thickness)
+        b.relocate!
+      end
+
+      # ___________________________________________________________________
+      #
+      #               +-----------------+
+      #               |                 |
+      #               | back:     W x H |
+      #               |                 |
+      #               +-----------------+
+      #               +-----------------+
+      #               | bottom:   W x D |
+      #               +-----------------+
+      #   +--------+  +-----------------+  +--------+
+      #   |        |  |                 |  |        |
+      #   | left   |  | front:    W x H |  | right  |
+      #   | D x H  |  |                 |  | D x H  |
+      #   +--------+  X-----------------+  +--------+
+      #               +-----------------+
+      #               | top   :   W x D |
+      #               +-----------------+
+      #
+      # 0,0
+      # ___________________________________________________________________
+
+      def position_faces!
+        offset_x = [padding + d + (3 * thickness), metadata.x + (2 * thickness) + padding].max
+        offset_y = [padding + d + (3 * thickness), metadata.y + (2 * thickness) + padding].max
+
+        # X Coordinate
+        left.x  = offset_x - d - (2 * thickness) - padding
+        right.x = offset_x + w + (2 * thickness) + padding
+
+        [bottom, front, top, back].each { |s| s.x = offset_x }
+
+        # Y Coordinate
+        top.y    = offset_y - d - (2 * thickness) - padding
+        bottom.y = offset_y + h + (2 * thickness) + padding
+        back.y   = bottom.y + d + (2 * thickness) + padding
+
+        [left, front, right].each { |s| s.y = offset_y }
+
+        faces.each(&:relocate!)
+      end
+
+      def create_faces!
+        zero = Geometry::Point.new(0, 0)
+        self.front = Geometry::Rect.create(zero, dim.w, dim.h, "front")
+        self.back = Geometry::Rect.create(zero, dim.w, dim.h, "back")
+
+        self.top = Geometry::Rect.create(zero, dim.w, dim.d, "top")
+        self.bottom = Geometry::Rect.create(zero, dim.w, dim.d, "bottom")
+
+        self.left = Geometry::Rect.create(zero, dim.d, dim.h, "left")
+        self.right = Geometry::Rect.create(zero, dim.d, dim.h, "right")
+      end
+
+      # Choose which face will be responsible for filling out the little square overlap
+      # in the corners. Only one of the 3 possible sides need to be picked.
+      def pick_corners_face
+        b = face_bounding_rect(front)
+        edges = []
+        front.sides[0..1].each_with_index do |face, index|
+          edges << Notching::Edge.new(b.sides[index], face, notch_width: notch_width, kerf: kerf )
+        end
+        edges.map(&:notch_count).all?{ |c| c % 4 == 3 } ? :top : :front
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/command.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      # What every command inherits: the ui helpers, and the flags they all share.
+      class Command < Dry::CLI::Command
+        include Dry::CLI::UI
+
+        # Cells in a progress bar.
+        BAR_WIDTH = 60
+
+        def self.inherited(subclass)
+          super
+          subclass.option :verbose, type: :boolean, default: false, aliases: ['-v'],
+                                    desc: 'Print the configuration, and the full backtrace on failure'
+        end
+
+        # Boxes are as wide as help is.
+        def ui
+          @ui ||= Dry::CLI::UI::Console.new(out: out, err: err, box_width: CLI.help_width)
+        end
+
+        # A green bar of BAR_WIDTH cells, or fewer when the terminal is narrower.
+        #
+        # @param label [String]
+        # @param total [Integer]
+        # @yieldparam bar [#advance]
+        def progress(label, total:, &)
+          Dry::CLI::UI::Console
+            .new(out: out, err: err, box_width: CLI.help_width, width: progress_width(label))
+            .progress(label, total: total, color: :green, &)
+        end
+
+        private
+
+        # dry-cli-ui sizes a bar as the terminal width less the label and the
+        # counters around it, so the bar is capped by capping that width.
+        def progress_width(label)
+          wanted = BAR_WIDTH + label.length + Dry::CLI::UI::Widgets::Progress::CHROME
+          err.respond_to?(:tty?) && err.tty? ? [wanted, TTY::Screen.width].min : wanted
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/completion.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      # Dry::CLI::Autocomplete::Command[] builds an anonymous subclass, which
+      # loses the description and the examples. This one states its own.
+      class Completion < Dry::CLI::Autocomplete::Command
+        @registry = CLI
+        @program_name = PROGRAM
+
+        desc 'Generates auto-complete for BASH or ZSH'
+
+        example [
+          "bash > /usr/local/etc/bash_completion.d/#{PROGRAM}",
+          "zsh  > \"${fpath[1]}/_#{PROGRAM}\""
+        ]
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/config_file.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      # A configuration saved as JSON. The path '-' stands for STDIN when
+      # reading, and for the command's own output when writing.
+      class ConfigFile
+        STDIO = '-'
+
+        # @param path [String]
+        def initialize(path)
+          @path = path
+        end
+
+        # @return [Hash{String => Object}]
+        # @raise [Error] when the file is missing, or is not JSON
+        def read
+          JSON.parse(@path == STDIO ? $stdin.read : File.read(@path))
+        rescue SystemCallError, JSON::ParserError => e
+          raise Error, "cannot read the configuration from #{@path}: #{e.message}"
+        end
+
+        # @param settings [Hash]
+        # @param out [IO] where '-' writes to
+        # @raise [Error] when the file cannot be written
+        def write(settings, out)
+          json = JSON.pretty_generate(settings)
+          @path == STDIO ? out.puts(json) : File.write(@path, "#{json}\n")
+        rescue SystemCallError => e
+          raise Error, "cannot write the configuration to #{@path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/examples.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      class Examples < Command
+        desc 'Show detailed usage examples'
+
+        TEXT = <<~EXAMPLES
+          1. A box in inches, with the kerf set to 0.008", opened once it is written:
+
+               laser-cutter generate -b 3x2x2/0.125 -k 0.008 -O -o box.pdf
+
+          2. A box in millimeters on a landscape A3 page, with a 0.5mm stroke:
+
+               laser-cutter generate -u mm -w 70 -H 20 -d 50 -t 4.3 -n 5 -i A3 -l landscape -s 0.5 -o box.pdf
+
+          3. The same box as an SVG:
+
+               laser-cutter generate -b 3x2x2/0.125 -f svg -o box.svg
+
+          4. Every page size, in millimeters:
+
+               laser-cutter page-sizes -u mm
+
+          5. A box whose settings are saved for later:
+
+               laser-cutter generate -b 1.1x2.5x1.5/0.125/0.125 -p 0.1 -o box.pdf -W box-settings.json
+
+          6. A box from settings saved earlier, from a file or from STDIN:
+
+               laser-cutter generate -o box.pdf -R box-settings.json
+               cat box-settings.json | laser-cutter generate -o box.pdf -R -
+
+          7. A box with a lid that lifts off: a plain rectangle, or one notched into the back wall only:
+
+               laser-cutter generate -b 3x2x2/0.125 --lid plain -o box.pdf
+               laser-cutter generate -b 3x2x2/0.125 --lid back -o box.pdf
+        EXAMPLES
+
+        def call(**)
+          out.puts TEXT
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/generate.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      class Generate < Command
+        desc 'Draw the panels of a box into a PDF or an SVG file'
+
+        BANNER = "Laser-Cutter (ruby gem) Version #{Laser::Cutter::VERSION}, © 2015-2026 Konstantin Gredeskoul".freeze
+
+        # Columns a box spends on its borders and padding.
+        BOX_CHROME = 6
+
+        # What the opening box reports, in this order.
+        DIMENSIONS = %i[width height depth thickness notch kerf].freeze
+
+        # Options that describe the run rather than the box, kept out of a saved configuration.
+        RUN_ONLY = %i[verbose read write open format args].freeze
+
+        option :box, aliases: ['-b'], desc: 'WxHxD/T[/N]: width, height, depth, thickness and optional notch, in one'
+        option :width, aliases: ['-w'], desc: 'Internal width of the box'
+        option :height, aliases: ['-H'], desc: 'Internal height of the box'
+        option :depth, aliases: ['-d'], desc: 'Internal depth of the box'
+        option :thickness, aliases: ['-t'], desc: 'Thickness of the material'
+        option :notch, aliases: ['-n'], desc: 'Notch length, a guide only (default: three times the thickness)'
+        option :kerf, aliases: ['-k'], desc: 'Kerf, the width of the cut (default: 0.0024in)'
+        # No default here: one would override the lid a saved configuration asks for.
+        option :lid, values: %w[full back plain], aliases: ['-L'],
+                     desc: 'Lid: notched on every side, into the back wall only, or on no side (default: full)'
+        option :units, default: 'in', values: %w[in mm], aliases: ['-u'], desc: 'Units every dimension is in'
+
+        option :file, aliases: ['-o'], desc: 'File to write (required)'
+        option :format, default: 'pdf', aliases: ['-f'], desc: 'Output format: pdf or svg, in either case'
+
+        option :margin, aliases: ['-m'], desc: 'Margin from the edge of the page'
+        option :padding, aliases: ['-p'], desc: 'Space between the panels'
+        option :stroke, aliases: ['-s'], desc: 'Stroke width of the lines'
+        option :page_size, aliases: ['-i'], desc: 'Page size, such as LETTER or A3 (default: fit the box; PDF only)'
+        option :page_layout, default: 'portrait', values: %w[portrait landscape], aliases: ['-l'], desc: 'Page layout (PDF only)'
+
+        option :metadata, type: :boolean, default: true, aliases: ['-M'], desc: 'Print the settings of the box on the page'
+        option :inside_box, type: :boolean, default: false, aliases: ['-B'],
+                            desc: 'Also draw the box without kerf, in red, to check the kerf'
+        option :open, type: :boolean, default: false, aliases: ['-O'], desc: 'Open the file once it is written'
+        option :write, aliases: ['-W'], desc: "Save the configuration to a file, or to STDOUT with '-'"
+        option :read, aliases: ['-R'], desc: "Read the configuration from a file, or from STDIN with '-'"
+
+        example [
+          '-b 3x2x2/0.125 -o box.pdf # a box in inches',
+          '-b 3x2x2/0.125 -f svg -o box.svg # as an SVG',
+          '-b 3x2x2/0.125 --lid plain -o box.pdf # with a lid that lifts off',
+          '-u mm -w 70 -H 20 -d 50 -t 4.3 -o box.pdf'
+        ]
+
+        def call(format:, verbose:, **options)
+          config = configuration(options)
+          ui.debug('Configuration:', JSON.pretty_generate(config.to_hash)) if verbose
+          config.validate!
+          renderer = Renderer.for(format, config)
+          ui.info(BANNER, dimensions(config), "Format: #{format.upcase}")
+          ConfigFile.new(options[:write]).write(config.to_hash, out) if options[:write]
+
+          progress("Drawing #{File.basename(config.file)}", total: renderer.total) do |bar|
+            renderer.render { bar.advance }
+          end
+
+          report(format, File.expand_path(config.file))
+          system('open', config.file) if options[:open]
+        end
+
+        private
+
+        # A box wraps in the middle of a word, which would break a path nobody
+        # could then copy, so this one widens to fit a path longer than it.
+        def report(format, path)
+          ui.success("Generated #{format.upcase} file:", path, width: [CLI.help_width, path.length + BOX_CHROME].max)
+        end
+
+        # What was read from a file, overridden by what the command line gave.
+        def configuration(options)
+          given = options.except(*RUN_ONLY).compact
+          saved = options[:read] ? ConfigFile.new(options[:read]).read : {}
+          settings = saved.transform_keys(&:to_sym).merge(given)
+          Configuration.new(settings.merge(debug: settings.delete(:inside_box)))
+        end
+
+        # One line per dimension, aligned, in the units of the box, then the lid.
+        def dimensions(config)
+          rows = DIMENSIONS.map { |name| [name, "#{config[name]} #{config.units}"] } << [:lid, config.lid]
+          rows.map { |name, value| "#{"#{name.capitalize}:".ljust(11)} #{value}" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/help.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      class Help < Command
+        desc 'Show help, for the program or for one command'
+
+        argument :command, required: false, desc: 'The command to explain'
+
+        example ['', 'generate']
+
+        # Asks dry-cli for the help it prints on --help, which exits by itself.
+        def call(command: nil, **)
+          Dry::CLI.new(CLI).call(arguments: [command, '--help'].compact, out: out, err: err)
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/page_sizes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      class PageSizes < Command
+        desc 'List every page size, with its dimensions'
+
+        option :units, default: 'in', values: %w[in mm], aliases: ['-u'], desc: 'Units to print the dimensions in'
+
+        example ['', '--units mm']
+
+        def call(units:, **)
+          out.puts PageManager.new(units).all_page_sizes
+        end
+      end
+    end
+  end
+end

data/lib/laser/cutter/cli/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    module CLI
+      class Version < Command
+        desc 'Print the version'
+
+        def call(**)
+          out.puts Laser::Cutter::VERSION
+        end
+      end
+    end
+  end
+end