laser-cutter 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cb71396bbb2f8c49f903912ebe28e43ccf2fa278f7fc390bb68f4002dd678a5
-  data.tar.gz: 51bee7e480b3fd7578a6668a9f9c82ef3894e2f388bc3db336b76eefcff89098
+  metadata.gz: 140ec85d7822779ce6cf52830e4d462252bda1d9b03f0f45c433a68c381e08ac
+  data.tar.gz: 6f103d783a2b0de67eeba6491fac047029e52fec5ffe824dd0508481d8fcd41a
 SHA512:
-  metadata.gz: a146752a70a7b9f73c6cf46c0472ec5a7456b50e2623188c7665e057c0cf98bd687d05946137c968995783b569a03fb7c99afca3528e084f712d46298e9ef261
-  data.tar.gz: e8b3eecd4f8fe18078599f989f3a14e94bb9c4df0ff6504619f196849b1c016ebbcb48dad5153465e810cbcce38566cf00d5e2c67ce9bb8fbfca9aa4d80b0455
+  metadata.gz: 1e465b0c64a35fbbc397e0d98fccb520ae1fb0e8bb6fc073be86cf4fa80b141461ee238f7dcd8d77e8380f9c4043ac86a86efbecf9a380a4b1db2bcd0a7a0fd5
+  data.tar.gz: 9946ba8635c743ca01a7d458d3622037ea7bf811631bcda87c96a8c94398941ff6931809a46ec57624eefd1d1827036fff50155b8dd8492d60b23265bb3f1376

data/.plans/002.00-lid-options/plan.md

@@ -0,0 +1,45 @@
+# 002.00 Lid options: notched on one side, or plain
+
+Branch `kig/add-lid-options`, off `master`; the PR targets `master`. Released as 2.0.1.
+
+## Goal
+
+A box whose lid lifts off. Today the lid (the `top` panel) is notched on all four sides and can only be glued shut.
+
+## Decisions
+
+Answered by Konstantin on 2026-09-30:
+
+- The lid rests on top of the walls. Where a lid edge is plain, the wall edge under it is straight at the inner height `H`, and the lid reaches the outer footprint.
+- The lid notched on one side joins the **back** wall, always.
+- The option is `--lid full|back|plain`, `-L`, `full` by default. `full` draws exactly what 2.0.0 drew.
+
+Decided without an answer (he had gone to bed), so worth a look in review:
+
+- In `back` and `plain` the lid owns all four top corner squares, so no wall rises above `H` at a corner. In `back` the lid's two back corners are the feet either side of its notched edge.
+- The internal height stays `H` in every mode: the underside of the lid is at `H`.
+- The layout does not move. A wall without its tabs leaves its old space unused.
+
+## Geometry
+
+Faces are laid out in a column (`top`, `front`, `bottom`, `back`) with `left` and `right` beside `front`. A `Rect`'s sides run 0 bottom, 1 right, 2 top, 3 left. The lid's joints:
+
+| Lid side | Wall    | Wall side |
+| :------- | :------ | :-------- |
+| 0        | `back`  | 2         |
+| 1        | `right` | 0         |
+| 2        | `front` | 0         |
+| 3        | `left`  | 0         |
+
+- A plain wall edge is the edge's **inside** line. The sides next to it lose the corner box, and its kerf fix-ups, at that end only.
+- A plain lid edge is the edge's **outside** line.
+- Kerf grows every outline by half the kerf, as it does for notches.
+
+## Work
+
+- [x] `Configuration`: `lid`, default `full`, rejected by `validate!` when unknown
+- [x] `Notching::Edge` and `PathGenerator`: a corner box per end, not per edge
+- [x] `Box`: per-face outlines; plain and back lids; straight wall edges
+- [x] `generate --lid`, README, CLAUDE.md
+- [x] Specs: each outline against an independent even-odd oracle, with and without kerf
+- [x] Version 2.0.1

data/.plans/003.00-ruby-api/plan.md

@@ -0,0 +1,37 @@
+# 003.00 A Ruby API for MakeABox.io
+
+Branch `kig/add-ruby-api-facade`, off `master` once 002.00 had merged; the API carries the lid that plan added.
+
+## Goal
+
+MakeABox.io, a Rails application, draws boxes in-process. It must not shell out to `laser-cutter`, and it must be able to ask for any lid.
+
+## What 2.0.0 already allowed
+
+`Configuration.new(hash)`, `validate!`, `Renderer::LayoutRenderer.new(config).render` and `PageManager#page_size_values` are what the website calls today against 1.0.3, and all still work. Two things were missing:
+
+- A renderer could only write to `config.file`. A controller wants the bytes.
+- `validate!` demanded `file`, so a caller with no file had to invent one.
+- `Configuration` is a Mash: it takes any key and any value, and says nothing until a renderer trips over it.
+
+## Decisions
+
+- Asked for by Konstantin mid-way: the facade takes every option as a **typed class**. That is `Laser::Cutter::Options`, a strict `Dry::Struct` with its types in `Laser::Cutter::Types`. dry-struct becomes a runtime dependency.
+- `Laser::Cutter.render(options)` returns the document as a String. No file is needed or written.
+- `Laser::Cutter.write(options)` writes it to `options.file`. Without a format, the extension of the file decides.
+- Both take an `Options`, or a Hash they turn into one, and pass a block through as the per-line callback.
+- `Options` coerces Strings, reads a blank String as left out, and refuses unknown keys. A missing dimension raises `MissingOption`, with the message `Configuration#validate!` gives, since the website rewrites that message. Anything else raises `InvalidOption`.
+- The `--box` shorthand is not an attribute: it is a way to type four options, not a fifth.
+- Renderers answer `document`, the String; `render` writes it to `config.file` as before.
+- `Configuration` also reads a blank lid as the default, for callers still building one by hand.
+- "The two lid types (or none)" is read as `back`, `plain`, or no lid setting at all, which is `full`. A box with no lid panel is not part of this.
+- Requiring the gem still loads dry-cli and the commands. Harmless in a Rails process; splitting the CLI out of the default require is left for later.
+- The command line keeps building a `Configuration` itself; it is not moved onto `Options` here.
+
+## Work
+
+- [x] `document` on both renderers
+- [x] `Types` and `Options`
+- [x] `Laser::Cutter.render` and `Laser::Cutter.write`
+- [x] Specs, including Strings from a form and the calls the website makes today
+- [x] README section, CLAUDE.md

data/CLAUDE.md

@@ -30,17 +30,25 @@ Everything lives under `Laser::Cutter`, in `lib/laser/cutter/`. `lib/laser/cutte
 
 Pipeline, from config to file:
 
-1. **`Configuration`** is a `Hashie::Mash` with symbolized keys. It parses the `--box WxHxD/T[/N]` shorthand, casts numeric strings to floats, and merges per-unit defaults for kerf, margin, padding and stroke. Notch defaults to `3 × thickness`. `validate!` raises `MissingOption` / `ZeroValueNotAllowed`. `units` defaults to the Symbol `:in`, and arrives as a String from the command line, so compare it with `to_s` or `to_sym`.
+1. **`Configuration`** is a `Hashie::Mash` with symbolized keys. It parses the `--box WxHxD/T[/N]` shorthand, casts numeric strings to floats, and merges per-unit defaults for kerf, margin, padding and stroke. Notch defaults to `3 × thickness`. `validate!` raises `MissingOption` / `ZeroValueNotAllowed`, and `InvalidOption` for a lid it does not know. `units` defaults to the Symbol `:in`, and arrives as a String from the command line, so compare it with `to_s` or `to_sym`.
 1. **`Renderer.for(format, config)`** picks `LayoutRenderer` (PDF, Prawn) or `SvgRenderer` (SVG, Victor). Both answer `total` (lines to draw) and `render { |line| }`, which yields after each line. That block drives the progress bar.
    - `LayoutRenderer` draws a `BoxRenderer`, a `MetaRenderer` when `config.metadata` is set, and a second red `BoxRenderer` without kerf when `config.debug` is set. It sizes the page from the box enclosure unless `page_size` is given.
    - `SvgRenderer` fits the page to the box, flips y (SVG counts down from the top), and writes the metadata as a `<desc>`.
 1. **`Box`** models the six faces as `Geometry::Rect`s. `position_faces!` lays them out in a cross (see the ASCII diagram in that method). `generate_notches` pairs each side of a face with the matching side of its outer bounding rect (face grown by `thickness`) as a **`Notching::Edge`**. The `conf` table sets per-face alignment: `valign`/`halign` decide whether a side's center notch points `:out` or `:in`. `corners` plus `pick_corners_face` decide which face fills the corner squares.
+   - `lid` (`full`, `back`, `plain`) sets how the `top` panel joins the walls. A plain lid edge is the edge's **outside** line, and the wall side under it (`LID_SIDES`) is the edge's **inside** line, so the lid lies on walls that end at the inner height. The lid then owns the corners above the walls: `corner_ends` strips the corner box from the wall sides that touch it.
+   - `outlines` holds the merged lines of each face by name; `notches` is all of them, flattened.
 1. **`Notching::Edge`** holds the inside and outside lines of one side, both shifted by `kerf / 2`. `calculate_notch_width!` forces an **odd** notch count of at least 3 and recomputes the real notch width, so the requested notch is only a guide. It rounds `length / notch` to `RATIO_DIGITS` before `ceil`: two panels meeting at a joint must get the same count, and float noise used to split them when the notch divided the side exactly.
-1. **`Notching::PathGenerator`** turns an `Edge` into `Geometry::Line`s. It zigzags between the inside and outside lines using `Shift` deltas from two alternating `InfiniteIterator`s. It widens or narrows notches by `kerf` and adds the corner boxes.
+1. **`Notching::PathGenerator`** turns an `Edge` into `Geometry::Line`s. It zigzags between the inside and outside lines using `Shift` deltas from two alternating `InfiniteIterator`s. It widens or narrows notches by `kerf` and adds the corner boxes, at the ends the edge names in `corner_ends`. Kerf grows every outline by half the kerf on every side; `spec/laser/cutter/box_lid_spec.rb` checks exactly that, point by point, through `spec/support/outline.rb`.
 1. **`Aggregator`** merges the lines of a face into the outline to cut. Neighbouring edges draw shared stretches twice, and a shared stretch runs through the material, so each collinear group is combined as a symmetric difference: a point is cut when an odd number of lines cover it. It groups lines by axis and offset and sweeps each group once, so a face takes n log n; the old pairwise version made a 100×80×60 box take 55 seconds.
 
 Geometry is unitless, in the config's units. Conversion to PDF points happens only at render time (`value.send(:in)` / `.send(:mm)`). `PageManager#value_from_units` converts PDF points back.
 
+### Ruby API
+
+- `Laser::Cutter.render(options)` returns the document as a String, and `Laser::Cutter.write(options)` writes it to `options.file`. Both live in `lib/laser/cutter.rb`, take an `Options` or a Hash, and pass a block through as the per-line callback. MakeABox.io calls these; keep them working without a file, a terminal or the CLI classes.
+- `Options` (`options.rb`) is a strict `Dry::Struct`, one attribute per `generate` option, with its types in `Types` (`types.rb`). It raises `MissingOption` for a missing dimension and `InvalidOption` for anything else, and turns into a `Configuration` with `to_configuration`. A new `generate` option needs an attribute here too.
+- Renderers answer `document`, the String. `Renderer::Base#render` writes it to `config.file`.
+
 ### Command line
 
 - `exe/laser-cutter` (and `exe/lc`) call `Laser::Cutter::Launcher.new(ARGV).execute!`. The Launcher takes argv, the three streams and `kernel`, and exits only through `kernel.exit`. Aruba runs it in-process (`spec/support/aruba.rb`), so commands must write to `out` and `err`, never to `$stdout`.
@@ -51,9 +59,14 @@ Geometry is unitless, in the config's units. Conversion to PDF points happens on
 
 ## Known gaps
 
+- `generate` declares defaults for `--units` and `--page-layout`, and they override what `-R` reads from a saved configuration. `--lid` has no dry-cli default for that reason.
+
 - `just build` is an empty recipe, so `just publish` builds nothing. `rake build` is the real build.
+
 - The `Rakefile` YARD title is copied from another project, and it references a `CHANGELOG.md` that does not exist.
+
 - The gemspec lists `tty-*` and `pastel` directly, though only dry-cli-ui uses them.
+
 - `Box` still carries the comment "badly needs refactoring and tests".
 
 ## Conventions

data/README.md

@@ -61,6 +61,7 @@ laser-cutter COMMAND [OPTIONS]
 | `-w`, `-H`, `-d`, `-t` | Width, height, depth and thickness, one at a time              |
 | `-n`, `--notch`        | Notch length, a guide only                                     |
 | `-k`, `--kerf`         | Kerf, the width of the cut                                     |
+| `-L`, `--lid`          | `full` (default), `back` or `plain`, see below                 |
 | `-u`, `--units`        | `in` (default) or `mm`                                         |
 | `-o`, `--file`         | File to write, required                                        |
 | `-f`, `--format`       | `pdf` (default) or `svg`, in either case                       |
@@ -77,6 +78,30 @@ 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
 ```
 
+A box with a lid that lifts off:
+
+```bash
+laser-cutter generate -b 3x2x2/0.125 --lid plain -o box.pdf
+```
+
+### The lid
+
+The lid is the top panel. `--lid` sets how it joins the walls:
+
+| `--lid` | The lid                              | The walls under it                                |
+| :------ | :----------------------------------- | :------------------------------------------------ |
+| `full`  | Notched on all four sides            | Notched; the box is glued shut                    |
+| `back`  | Notched where it meets the back wall | The back is notched, the other three are straight |
+| `plain` | A rectangle, no notches              | All four are straight                             |
+
+| `--lid full`                                            | `--lid back`                                                           | `--lid plain`                                             |
+| :------------------------------------------------------ | :--------------------------------------------------------------------- | :-------------------------------------------------------- |
+| ![A box with a full lid](docs/images/box-lid-full.avif) | ![A box with a lid notched at the back](docs/images/box-lid-back.avif) | ![A box with a plain lid](docs/images/box-lid-plain.avif) |
+
+Each is `laser-cutter generate -b 3x2x2/0.125 --lid …`. The lid is the panel at the bottom of the page, the back wall the one at the top.
+
+A lid edge without notches reaches the outside of the wall under it, and that wall ends at the internal height. So a `plain` lid is `W + 2T` by `D + 2T` and lies on top of the box, and the space inside is still `W` by `H` by `D`.
+
 The same box as an SVG:
 
 ```bash
@@ -103,6 +128,86 @@ laser-cutter generate -o box.pdf -R box-settings.json
 cat box-settings.json | laser-cutter generate -o box.pdf -R -
 ```
 
+### More boxes
+
+A shallow box in millimeters, glued shut:
+
+```bash
+laser-cutter generate -u mm -w 70 -H 20 -d 50 -t 4.3 -n 5 -f svg -o box.svg
+```
+
+![A 70 by 20 by 50 millimeter box](docs/images/box-metric.avif)
+
+A tray with a lid that lifts off, from 3mm material with wide notches:
+
+```bash
+laser-cutter generate -u mm -w 120 -H 25 -d 80 -t 3 -n 12 --lid plain -f svg -o tray.svg
+```
+
+![A 120 by 25 by 80 millimeter tray with a plain lid](docs/images/box-tray.avif)
+
+The pictures on this page are the SVG files themselves, drawn with a thicker stroke (`-s 0.5`) and converted:
+
+```bash
+magick -density 96 -background white box.svg -flatten box.avif
+```
+
+## Using it from Ruby
+
+A Ruby program draws a box in its own process; nothing runs the command line. It needs three things:
+
+| Call                            | What it does                                      |
+| :------------------------------ | :------------------------------------------------ |
+| `Laser::Cutter::Options.new`    | Every setting of a box, typed and checked         |
+| `Laser::Cutter.render(options)` | Returns the PDF or the SVG as a String            |
+| `Laser::Cutter.write(options)`  | Writes it to `options.file`, and returns the path |
+
+```ruby
+require "laser-cutter"
+
+options = Laser::Cutter::Options.new(
+  width: 70, height: 20, depth: 50, thickness: 4.3,
+  units: :mm, lid: :plain, format: :svg
+)
+
+svg = Laser::Cutter.render(options)                      # a String, no file written
+Laser::Cutter.write(options.new(file: "box.pdf", format: nil)) # the extension picks the format
+```
+
+`Options` has an attribute for each option of `generate`:
+
+| Attribute                               | Type                    | When left out                  |
+| :-------------------------------------- | :---------------------- | :----------------------------- |
+| `width`, `height`, `depth`, `thickness` | Float above zero        | `MissingOption` is raised      |
+| `notch`                                 | Float above zero        | Three times the thickness      |
+| `kerf`, `margin`, `padding`             | Float, zero or more     | The default for the units      |
+| `stroke`                                | Float above zero        | The default for the units      |
+| `units`                                 | `in` or `mm`            | `in`                           |
+| `lid`                                   | `full`, `back`, `plain` | `full`                         |
+| `format`                                | `pdf` or `svg`          | `pdf`, or the file's extension |
+| `file`                                  | String                  | Only `write` needs it          |
+| `page_size`                             | A name such as `A4`     | The page fits the box          |
+| `page_layout`                           | `portrait`, `landscape` | `portrait`                     |
+| `metadata`                              | Boolean                 | `true`                         |
+| `inside_box`                            | Boolean                 | `false`                        |
+
+- Values are coerced, so the Strings a web form sends will do, and a blank String counts as left out. Keys may be Strings or Symbols.
+- A value it cannot use, or a key that is not an option, raises `Laser::Cutter::InvalidOption` with a message such as `lid cannot be "sliding", but must be one of: full, back, plain.` Both errors descend from `Laser::Cutter::Error`.
+- An `Options` cannot be changed; `options.new(lid: :back)` returns a changed copy.
+
+In a Rails controller:
+
+```ruby
+def create
+  box = params.require(:box).permit(*Laser::Cutter::Options.attribute_names)
+  send_data Laser::Cutter.render(box.to_h), type: "application/pdf", filename: "box.pdf"
+rescue Laser::Cutter::Error => e
+  redirect_to new_box_path, alert: e.message
+end
+```
+
+`Laser::Cutter::Box::LIDS` lists the lids, for a select. `Configuration`, `Renderer::LayoutRenderer#render` and `PageManager#page_size_values`, which MakeABox.io called in 1.0.3, still work.
+
 ## Feature Wish List
 
 - Create T-style joins, using various standard sizes of nuts and bolts (such as common #4-40 and M2 sizes)
@@ -158,4 +263,4 @@ laser-cutter generate -b 1x1.5x2/0.125/0.125 -O -o box.pdf
 
 MIT License (MIT). Please see [LICENSE](LICENSE) for more information.
 
-Author: © 2015-2024 Konstantin Gredeskoul [@kigster](https://github.com/kigster)
+Author: © 2015-2024 Konstantin Gredeskoul [@kigster](https://github.com/kigster)

data/laser-cutter.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'dry-cli-autocomplete'
   spec.add_dependency 'dry-cli-help'
   spec.add_dependency 'dry-cli-ui'
+  spec.add_dependency 'dry-struct', '~> 1.6'
   spec.add_dependency 'hashie'
   spec.add_dependency 'matrix'
   spec.add_dependency 'pastel'

data/lib/laser/cutter/box.rb

@@ -5,10 +5,23 @@ module Laser
     # 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']
@@ -18,8 +31,10 @@ module Laser
         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]
 
@@ -54,31 +69,16 @@ module Laser
         position_faces!
         corner_face = pick_corners_face
         self.notches = []
+        self.outlines = {}
         faces.each_with_index do |face, face_index|
-          bound = face_bounding_rect(face)
-          edges = []
-          bound.sides.each_with_index do |bounding_side, side_index|
-            include_corners = conf[:corners][corner_face][face_index] == :yes && side_index.odd?
-            key = side_index.odd? ? :valign : :halign
-            center_out = (conf[key][face_index] == :out)
-            edges << Notching::Edge.new(bounding_side,
-                                        face.sides[side_index],
-                                        { notch_width: notch_width,
-                                          thickness:   thickness,
-                                          kerf:        kerf,
-                                          center_out:  center_out,
-                                          corners:     include_corners })
-          end
+          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
 
-          side_lines = edges.map do |edge|
-            Notching::PathGenerator.new(edge).generate
-          end
-
-          notches << Aggregator.new(side_lines.flatten).lines
+          outlines[face.name] = Aggregator.new(lines_of(face, edges)).lines
+          notches << outlines[face.name]
         end
         notches.flatten!
       end
@@ -97,6 +97,84 @@ module Laser
 
       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))

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

@@ -31,6 +31,11 @@ module Laser
 
                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(**)

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

@@ -24,6 +24,9 @@ module Laser
         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)'
@@ -45,6 +48,7 @@ module Laser
         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'
         ]
 
@@ -80,9 +84,10 @@ module Laser
           Configuration.new(settings.merge(debug: settings.delete(:inside_box)))
         end
 
-        # One line per dimension, aligned, in the units of the box.
+        # One line per dimension, aligned, in the units of the box, then the lid.
         def dimensions(config)
-          DIMENSIONS.map { |name| "#{"#{name.capitalize}:".ljust(11)} #{config[name]} #{config.units}" }.join("\n")
+          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

data/lib/laser/cutter/configuration.rb

@@ -30,6 +30,7 @@ module Laser
           defaults = Hashie::Mash.new({
                                         units:       :in,
                                         page_layout: 'portrait',
+                                        lid:         'full',
                                         metadata:    true,
                                         in:          {
                                           kerf:    0.0024, # smallest kerf for thin material, usually it's more than that.
@@ -50,6 +51,7 @@ module Laser
         ::Hashie::Extensions::SymbolizeKeys.symbolize_keys!(options)
 
         options.delete_if { |_k, v| v.nil? }
+        options.delete(:lid) if options[:lid].to_s.empty? # a blank form field
         if options[:units]
           unit = options[:units].to_sym
           unless self.class.defaults.key?(unit) || self.class.defaults.key?(unit.to_s)
@@ -79,6 +81,10 @@ module Laser
         zeros = []
         NON_ZERO.each { |k| zeros << k if self[k] == 0 }
         raise ZeroValueNotAllowed, "#{zeros.join(', ')} #{zeros.size > 1 ? 'are' : 'is'} required, but is zero." unless zeros.empty?
+
+        return if Box::LIDS.include?(lid.to_s.to_sym)
+
+        raise InvalidOption, "lid is #{lid.to_s.inspect}, but must be one of: #{Box::LIDS.join(', ')}."
       end
 
       def change_units(new_units)

data/lib/laser/cutter/invalid_option.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Laser
+  module Cutter
+    # An option has a value it cannot take.
+    class InvalidOption < Error; end
+  end
+end

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

@@ -10,8 +10,14 @@ module Laser
       # 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, :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
@@ -26,6 +32,7 @@ module Laser
           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]
@@ -52,6 +59,14 @@ module Laser
           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
         # facing out (for a hole, etc).  This works well when we have odd number
         # of notches, but