diff --git a/BOXMAKER.md b/BOXMAKER.md new file mode 100644 index 0000000..b3c5542 --- /dev/null +++ b/BOXMAKER.md @@ -0,0 +1,51 @@ +# LaserCutter versus BoxMaker + +Another developer [Rahulbot](https://github.com/rahulbot/) created a similar app [BoxMaker](https://github.com/rahulbot/boxmaker/) in Java, which was an inspiration to LaserCutter. + +Laser-Cutter library attempts to further advance the concept of programmatically creating +laser-cut box designs, provides additional fine tuning, many more options, strategies and most +importantly – extensibility. + +Unlike `BoxMaker` this gem has a suit of automated tests (rspecs) around the core functionality. +In addition, new feature contributions are highly encouraged, and in that +regard having existing test suit offers confidence against regressions, and thus welcomes colaboration. + +Finally, BoxMaker's notch-drawing algorithm generates non-symmetric and sometimes purely broken designs +(see picture below). + +`laser-cutter`'s algorithm will create a _symmetric design for most panels_, but it might sacrifice +identical notch length. Depending on the box dimensions you may end up with a slightly different notch +length on each side of the box. + +The choice ultimately comes down to the preference and feature set, so here I show you two boxes made with +each program, so you can pick what you prefer. + +### Example Outputs + +Below are two examples of boxes with identical dimensions produced with `laser-cutter` and `boxmaker`: + +This is how you would make a box with Adam Phelp's fork of BoxMaker (which adds flags and a lot of +niceties): + +```bash +git clone https://github.com/aphelps/boxmaker && cd boxmaker && ant +java -cp BOX.jar com.rahulbotics.boxmaker.BoxMaker \ + -W 1 -H 2 -D 1.5 -T 0.125 -n 0.125 -o box.pdf +``` + +And laser-cutter: + +```bash +gem install laser-cutter +laser-cutter -z 1x1.5x2/0.125/0.125 -O -o box.pdf +``` + +![LaserCutter Comparison](doc/comparison.jpg). + +## Contributing + +1. Fork it ( https://github.com/kigster/laser-cutter/fork ) +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create a new Pull Request diff --git a/README.md b/README.md index 43bf4ab..5cc9bb3 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,23 @@ [![Code Climate](https://codeclimate.com/github/kigster/laser-cutter.png)](https://codeclimate.com/github/kigster/laser-cutter) [![Test Coverage](https://codeclimate.com/github/kigster/laser-cutter/badges/coverage.svg)](https://codeclimate.com/github/kigster/laser-cutter) +![Maintained](https://img.shields.io/maintenance/yes/2017.svg) +[![Join the chat at https://gitter.im/kigster/laser-cutter](https://badges.gitter.im/kigster/laser-cutter.svg)](https://gitter.im/kigster/laser-cutter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + [![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FSFYYNEQ8RKWU) ## LaserCutter and Make-A-Box.io -[![Join the chat at https://gitter.im/kigster/laser-cutter](https://badges.gitter.im/kigster/laser-cutter.svg)](https://gitter.im/kigster/laser-cutter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -```laser-cutter``` is a ruby library for generating PDF designs for boxes of -custom dimensions that suit your project, that can be cut from wood or acrylic -using a laser-cutter. The sides of the box snap together using alternating notches, -that are deliberately layed out in a symmetric form. +**LaserCutter** is a ruby library for generating PDF designs for boxes of custom dimensions that suit your project, that can be cut from wood or acrylic using a laser-cutter. The sides of the box snap together using alternating notches, that are deliberately layed out in a symmetric form. -To use ```laser-cutter``` you need to have a recent version of ruby interpreter, -install it as a gem, and use command line to generate PDFs. +To use `laser-cutter` you need to have a recent version of ruby interpreter, install it as a gem, and use command line to generate PDFs. -[Make-A-Box](http://makeabox.io) is a online web application that uses ```laser-cutter``` library -and provides a straight-forward user interface for generating PDF designs without the need to install -the gem or use command line. +[Make-A-Box](http://makeabox.io) is a online web application that uses `laser-cutter` library and provides a straight-forward user interface for generating PDF designs without the need to install the gem or use command line. Use whatever suites you better. -### Design Goals - -One of the design goals of this project is to provide a highly extensible platform for creating -laser-cut designs, where alternative strategies can be added over time, and supported by various -command line options, and perhaps a light weight web application. If you are interested in -contributing to the project, please see [contributing](CONTRIBUTING.md) for more details. +> NOTE: Please read our [feature comparison guide](BOXMAKER.md) of LaserCutter against an older tool called [BoxMaker](https://github.com/rahulbot/boxmaker). -```laser-cutter``` supports many flexible command line options that allow setting dimensions, -stroke width, page size, layout, margins, padding (spacing between the boxes), and many more. - ## Dependencies The gem depends primarily on [Prawn](http://prawnpdf.org) – a fantastic PDF generation library. @@ -47,12 +34,49 @@ And then execute: $ bundle -Or install it yourself as: +Or install it manually: $ gem install laser-cutter ## Usage +We'll start with some examples: + +### Examples + +Create a box defined in inches, with kerf (cut width) set to `0.005in`, and open PDF in preview right after: + +```bash + laser-cutter -z 3x2x2/0.125 -k 0.005 -O -o box.pdf +``` + +Create a box defined in millimeters, print verbose info, and set page size to A3, and layout to landscape, and stroke width to `1/2mm`: + +```bash + laser-cutter -u mm -w70 -h20 -d50 -t4.3 -n5 -iA3 -l landscape -s0.5 -v -O -o box.pdf +``` + +List all possible page sizes in metric system: + +```bash + laser-cutter -L -u mm +``` + +Create a box with provided dimensions, and save the config to a file for later use: + +```bash + laser-cutter -z 1.1x2.5x1.5/0.125/0.125 -p 0.1 -O -o box.pdf -W box-settings.json +``` + +Read settings from a previously saved file: + +```bash + laser-cutter -O -o box.pdf -R box-settings.json + cat box-settings.json | laser-cutter -O -o box.pdf -R - +``` + +### Complete Help + ```bash Usage: laser-cutter [options] -o filename.pdf @@ -94,41 +118,7 @@ Common Options: -u, --units UNITS Either 'in' for inches (default) or 'mm' ``` -### Examples - -Create a box defined in inches, with kerf (cut width) set to 0.005in, and open PDF in preview right after: - -```bash - laser-cutter -z 3x2x2/0.125 -k 0.005 -O -o box.pdf -``` - -Create a box defined in millimeters, print verbose info, and set -page size to A3, and layout to landscape, and stroke width to 1/2mm: - -```bash - laser-cutter -u mm -w70 -h20 -d50 -t4.3 -n5 -iA3 -l landscape -s0.5 -v -O -o box.pdf -``` - -List all possible page sizes in metric system: - -```bash - laser-cutter -L -u mm -``` - -Create a box with provided dimensions, and save the config to a file for later use: - -```bash - laser-cutter -z 1.1x2.5x1.5/0.125/0.125 -p 0.1 -O -o box.pdf -W box-settings.json -``` - -Read settings from a previously saved file: - -```bash - laser-cutter -O -o box.pdf -R box-settings.json - cat box-settings.json | laser-cutter -O -o box.pdf -R - -``` - -## Feature Wish List +## Wish List * Create T-style joins, using various standard sizes of nuts and bolts (such as common #4-40 and M2 sizes) * Extensibility with various layout strategies, notch drawing strategies, basically plug and play @@ -137,56 +127,9 @@ Read settings from a previously saved file: * Supporting lids and front panels, that are larger than the box itself and have holes for notches. * Your brilliant idea can be here too! Please see [contributing](CONTRIBUTING.md) for more info. -## LaserCutter vs BoxMaker - -[Rahulbot](https://github.com/rahulbot/)-made [BoxMaker](https://github.com/rahulbot/boxmaker/) is a -functional generator of notched designs, similar to ```laser-cutter```, and generously open sourced -by the author, and so in no way this project disputes BoxMaker's viability. In fact BoxMaker was an -inspiration for this project. - -Laser-Cutter library attempts to further advance the concept of programmatically creating -laser-cut box designs, provides additional fine tuning, many more options, strategies and most -importantly – extensibility. - -Unlike ```BoxMaker```, this gem has a suit of automated tests (rspecs) around the core functionality. -In addition, new feature contributions are highly encouraged, and in that -regard having existing test suit offers confidence against regressions, and thus welcomes colaboration. - -Finally, BoxMaker's notch-drawing algorithm generates non-symmetric and sometimes purely broken designs -(see picture below). - -```laser-cutter```'s algorithm will create a _symmetric design for most panels_, but it might sacrifice -identical notch length. Depending on the box dimensions you may end up with a slightly different notch -length on each side of the box. - -The choice ultimately comes down to the preference and feature set, so here I show you two boxes made with -each program, so you can pick what you prefer. - -### Example Outputs - -Below are two examples of boxes with identical dimensions produced with ```laser-cutter``` and ```boxmaker```: - -This is how you would make a box with Adam Phelp's fork of BoxMaker (which adds flags and a lot of -niceties): - -```bash -git clone https://github.com/aphelps/boxmaker && cd boxmaker && ant -java -cp BOX.jar com.rahulbotics.boxmaker.BoxMaker \ - -W 1 -H 2 -D 1.5 -T 0.125 -n 0.125 -o box.pdf -``` - -And laser-cutter: - -```bash -gem install laser-cutter -laser-cutter -z 1x1.5x2/0.125/0.125 -O -o box.pdf -``` - -![LaserCutter Comparison](doc/comparison.jpg). - ## Contributing -1. Fork it ( https://github.com/[my-github-username]/laser-cutter/fork ) +1. Fork it ( https://github.com/kigster/laser-cutter/fork ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`)