About Boxes.py
==============

+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+
| .. image:: static/samples/NotesHolder.jpg    | .. image:: static/samples/OttoBody.jpg       | .. image:: static/samples/PaintStorage.jpg   | .. image:: static/samples/ShutterBox.jpg     | .. image:: static/samples/TwoPiece.jpg       |
+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+----------------------------------------------+

* Boxes.py is an online box generator

  * https://boxes.hackerspace-bamberg.de/

* Boxes.py is an Inkscape plug-in
* Boxes.py is library to write your own
* Boxes.py is free software licensed under GPL v3+
* Boxes.py is written in Python and runs with Python 3

Boxes.py comes with a growing set of ready-to-use, fully parametrized
generators. See https://florianfesti.github.io/boxes/html/generators.html for the full list.

+----------------------------------------------+----------------------------------------------+----------------------------------------------+
| .. image:: static/samples/AngledBox.jpg      | .. image:: static/samples/FlexBox2.jpg       | .. image:: static/samples/HingeBox.jpg       |
+----------------------------------------------+----------------------------------------------+----------------------------------------------+

Features
--------

Boxes.py generates SVG images that can be viewed directly in a web browser but also
postscript and - with pstoedit as external helper - other vector formats
including dxf, plt (aka hpgl) and gcode.

Of course the library and the generators allow selecting the "thickness"
of the material used and automatically adjusts lengths and width of
joining fingers and other elements.

The "burn" parameter compensates for the material removed by the laser. This
allows fine tuning the gaps between joins up to the point where plywood
can be press fitted even without any glue.

Finger Joints are the work horse of the library. They allow 90° edges
and T connections. Their size is scaled up with the material
"thickness" to maintain the same appearance. The library also allows
putting holes and slots for screws (bed bolts) into finger joints,
although this is currently not supported for the included generators.

Dovetail joints can be used to join pieces in the same plane.

Flex cuts allows bending and stretching the material in one direction. This
is used for rounded edges and living hinges.

+----------------------------------------------+----------------------------------------------+----------------------------------------------+
|   .. image:: static/samples/TypeTray.jpg     |     .. image:: static/samples/BinTray.jpg    | .. image:: static/samples/DisplayShelf.jpg   |
+----------------------------------------------+----------------------------------------------+----------------------------------------------+
| .. image:: static/samples/AgricolaInsert.jpg | .. image:: static/samples/HeartBox.jpg       | .. image:: static/samples/Atreus21.jpg       |
+----------------------------------------------+----------------------------------------------+----------------------------------------------+

Static web app
--------------

Boxes.py also runs fully in the browser with Pyodide. The web app needs no
backend, any static file server can host it. It shows the settings and a live
preview side by side.

Build it with the Python environment that has Boxes.py and its dependencies
installed. The first build downloads a pinned Pyodide release into
``build/cache/`` and checks its sha256, later builds work offline::

    python scripts/build_web

Try it locally (opening the files with ``file://`` does not work)::

    python -m http.server -d build/web

Then open http://localhost:8000/.

To build and serve it in a container instead, without a local Python
environment, run this in the repo root::

    podman build -f scripts/Dockerfile.web -t boxes-web .
    podman run --rm -p 8080:8080 boxes-web

Then open http://localhost:8080/. The image builds from the files in your
checkout, so it includes your local changes.

To publish it, copy ``build/web/`` to a static host. The host must serve
``.wasm`` as ``application/wasm`` and ``.mjs`` as ``application/javascript``,
and should compress ``.wasm``, ``.js`` and ``.json``. Pyodide is about 9.6 MB
uncompressed and 4 MB with gzip. ``scripts/nginx-web.conf`` is the nginx
config the container uses, take it as an example. Its ``types`` block
replaces the inherited MIME types, so keep it inside ``location /pyodide/``,
where all ``.mjs`` and ``.wasm`` files are.

The settings are part of the URL, for example ``#ABox?x=150``. The part after
``?`` uses the same format as the server, so ``/ABox?x=150`` on the server
becomes ``#ABox?x=150`` in the web app. Only changed values are kept.

The web app offers the formats svg, svg_Ponoko, ps and lbrn2. Formats that
need pstoedit or ps2pdf, like dxf, pdf, gcode and plt, are only available
with the command line and the server.

Documentation
-------------

Boxes.py comes with Sphinx based documentation for usage, installation
and development.

The rendered version can be viewed at <https://florianfesti.github.io/boxes/html/index.html>.