From 57fbda35e03aa3f1755797cefd7bf8f06b17f3ec Mon Sep 17 00:00:00 2001 From: Florian Festi Date: Fri, 7 Sep 2018 14:48:04 +0200 Subject: [PATCH] Extend docs by adding User Docs and and Introduction to the API --- documentation/src/apiintro.rst | 245 +++++++++++++++++++++++++++++++ documentation/src/index.rst | 2 + documentation/src/usermanual.rst | 145 ++++++++++++++++++ 3 files changed, 392 insertions(+) create mode 100644 documentation/src/apiintro.rst create mode 100644 documentation/src/usermanual.rst diff --git a/documentation/src/apiintro.rst b/documentation/src/apiintro.rst new file mode 100644 index 0000000..cea1d2a --- /dev/null +++ b/documentation/src/apiintro.rst @@ -0,0 +1,245 @@ +========================== +Using the Boxes.py library +========================== + +If there is no generator fitting your needs you can either adjust an +existing one (may be by copying it to another name first) or writing a +new one from scratch. + +Generators are found in ``boxes/generators/``. They are included into +the web UI and the CLI tool by the name of their class. So whenever +you copy either an existing generator or the sceleton in +``boxes/generators/_template.py`` you need to change the name of the +main class first. + +Generator Arguments +------------------- + +Boxes.py uses the ``argparse`` standard library for handling the +arguments for the generators. It is used directly for the ``boxes`` +command line tool. But it also handles -- with some additional code -- +the web interface and the Inkscape extensions. To make this work one +has to limit the kind of parameters used. Boxes.py supports the +following types: + + * ``int`` + * ``float`` + * ``str`` + * ``boxes.boolarg`` -- an alternative to ``bool`` that works with the + web interface + * ``boxes.argparseSections`` -- multiple lengths e.g. for dividing up + a box in one direction + +and + +.. autoclass:: boxes.ArgparseEdgeType + +For the standard types there is code to create HTML and Inkscape +extensions. The other types can have ``.html()`` and ``.inx()`` +methods. + +The argument parser need to be built in the ``.__init__()`` method +after calling the method of the super class. Have a look at + +.. automethod:: boxes.generators._template.BOX.__init__ + +As many arguments are used over and over there is a function that can +add the most common ones: + +.. automethod:: boxes.Boxes.buildArgParser + +Check the source for details about the single arguments. + +Other arguments can be added with the normal argparser API - namely + +.. automethod:: argparse.ArgumentParser.add_argument + +of the ``Boxes.argparser`` attribute. + +Edge style arguments +.................... + +Edges that work together share a Settings class (and object). These +classes can create ``argparse`` groups: + +.. automethod:: boxes.edges.Settings.parserArguments + +See + +.. automethod:: boxes.generators._template.BOX.__init__ + +for a list of possible edge settings. These regular settings are used +in the standard edge instances used everywhere. For special edge +instances you can call them with a ``prefix`` parameter. But you then +need to deal with the results on your own. + +Default Arguments +................. + +The :ref:`default-args` get added automatically by the super class's +constructor. + +Accessing the Arguments +....................... + +For convenience content of the arguments are written to attributes of +the Boxes instance before ``.render()`` is called. This is done by +``Boxes.parseArgs``. But most people won't need to care as this is +handled by the frame work. Be careful to **not overwrite important +methods or attributes by using conflicting argument names**. + +API Levels +---------- + +For actual drawing there are multiple levels of abscractions thta can +be used. From the simplest to the more powerful they are the following: + +Simple drawing commands +....................... + +These are simple drawing commands. Some of them get ``x``, ``y`` and +``angle`` parameters to draw somewhere specific. Some just draw right +at the current coordinate origin. Often these commands create holes or +hole patterns. + +Moving the coordinate system +............................ + +Boxes.py moves the coordinate system around a lot. You basically never have to +deal with the global position on the sheet but only with coordnates +relative to where you are. There are a few functions to move the +origin to a convenient position. + +Turtle graphics +............... + +To draw parts turtle graphic commands are used. The always start at +hthe current origin following the X axis. The move the origin with +them. The inside of the part is above the X axis and the outside +below. Corners with an positive angle (going counter clockwise) close +the part while negative angles (going clockwise) create protrusions. +This is inversed for holes which need to be drawn clockwise. + +Getting this directions right is important to make the burn correction +(aka kerf) work properly. The burn correction is implemented by +increasing the radius of positive corners and decresing the radius of +negative corners. (TODO: nice pictures) + +Edges +..... + +Edges are also turtle graphic commands. But they have been elevated to +proper Classes. + +Parts +..... + +There are a couple of standard parts that can be drawn with a single +command. Their typical params are explained in the API docs. + + +Part Callbacks +.............. + +Most parts support callbacks - either one in the middle for round +parts or one for each edge. They allow placing holes or other features +on the part. + + +How to get things done +---------------------- + +Decide whether you want to start from scratch or want to rework an +existing generator. + +You should go over the arguments first. Get at least the most basic +arguments done. For things you are still unsure you can just use a +attribute set in the .__init__() method and turn it into a proper +argument later on. + +Depending on what you want to do you can work on the different levels +of the API. You can either use what is there and combine it into +something new or you can implements new things in the appropriate level. + +Here are some examples: + +Housing for some electronics +............................ + +You can use the ElectronicsBox or the ClosedBox as a basis. Write some +callbacks to place holes in the walls to allow accessing the ports of +the electronics boards. Place some holes to screw spacers into the +bottom to mount the PBC on. + +NemaMount +......... + +This is a good non box example to look at. + +.. autoclass:: boxes.generators.nemamount.NemaMount + +Note that although it produces a cube like object it uses separate +variables (``x``, ``y``, ``h``) for the different axis. Probably +because it started as a copy of another generator like ``ClosedBox``. + +DisplayShelf +............ + +.. autoclass:: boxes.generators.displayshelf.DisplayShelf + +The DisplayShelf is completely made out of rectangularWalls(). It uses +a callback to place all the fingerHolesAt() right places on the sides. +While the use of the Boxes.py API is pretty straight forward the +calculations needed are a bit more tricky. You can use the ``debug`` +default param to check if you got things right when attempting +something like this yourself. + +Note that the front walls and the shelfs form a 90° angle so they work +with the default FingerJoints. + +BinTray +....... + +.. autoclass:: boxes.generators.bintray.BinTray + +The BinTray is based on the TypeTray generator: + +.. autoclass:: boxes.generators.typetray.TypeTray + +TypeTray is an already pretty complicated generator. + +BinTray replaces the now vertical front (former top) edges with a +special purpose one that does add the triangles: + +.. autoclass:: boxes.generators.bintray.BinFrontEdge + +The ``hi`` (height of inner walls) argument was removed although the +variable is still used internally - out of lazyness. + +To complete the bin the front walls are added. Follow up patches then +switched the slots between the vertical and horizontal walls to have +better support for the now bottoms of the bins. Another patch adds +angled finger joints for connecting the front walls with the bottoms +of the bins. + +The TrafficLight generator uses a similar technique implementing its +own Edge class. But it uses its own code to generate all the wall needed. + +Stachel +....... + +.. autoclass:: boxes.generators.stachel.Stachel + +Stachel allows mounting a monopod to a bass recorder. It is basically +just one part repeated with different parameters. It can't really make +use of much of the Boxes.py library. It implements this one part +including the ``move`` parameter and draws everything using the +``.polyline()`` method. This is pretty painful as lots of angles and +distances need to be calculated by hand. + +For symmetric sections it passes the parameters to ``.polyline`` twice +-- first in normal order and then reversed to get the mirrored section. + +This generator is beyond what Boxes.py is designed for. If you need +something similar you may want to use another tool like OpenScad or a +traditional CAD program. diff --git a/documentation/src/index.rst b/documentation/src/index.rst index 0155a75..9bae3d3 100644 --- a/documentation/src/index.rst +++ b/documentation/src/index.rst @@ -13,6 +13,8 @@ Contents: README install + usermanual + apiintro Boxes edges diff --git a/documentation/src/usermanual.rst b/documentation/src/usermanual.rst new file mode 100644 index 0000000..ac2d376 --- /dev/null +++ b/documentation/src/usermanual.rst @@ -0,0 +1,145 @@ +============== +Using Boxes.py +============== + +.. toctree:: + :maxdepth: 2 + +Boxes.py is made of a library that is not visible to the user and +multiple generators -- each having its own set of parameters and +creating a drawing for it own type of object. These generators are +divided up into different groups to make it easier to find them: + +* Boxes +* Boxes with flex +* Trays and Drawer Inserts +* Shelves +* Parts and Samples +* Misc +* Unstable + +The parameters for each generators also come in groups. + +Units of meassurement +--------------------- + +In general all measurements are in Millimeters (mm). There is no +option to change the units of measurement and there is no plan to add +such a option. + +A second way to define lengths is as multiple of the material +thickness which is one of the standard parameters described +below. This allows features to retain their proportions even if some +parts depend on the material thickness. + +The description texts should state the unit of each argument - +please open a ticket if the units are missing somewhere. + +.. _default-args: + +Default arguments +----------------- +In the web interface this is the bottom group right before the +``Render`` button. These are basically all technical settings that +have little to do with the object being rendered but more with the +material used and the way the drawing and the material is processed. + +The settings are + +thickness +......... + +The thickness of the material used. This value is used at many places +to define the sizes of features like finger joints, hinges, ... It is +very important to get the value right - especially if there are +fingers that need to fit into some holes. Be aware that many materials +may differ from their nominal value. You should **always measure the +thickness** for every sheet unless you have a very reliable supply +that is known to stick very closly to specifications. For (ply) wood +even a 100th of a milimeter makes a notable difference in how stiff +the fit is. Harder more brittle materials may be even more picky. + +burn +.... + +The burn correction aka kerf is the distance the laser has to keep +from the edge of the parts. If the laser would cut right on the edge +it would cut away the outside perimeter of the part. So the burn value is +basically the radius of the laser - or half the width of the laser cut. + +The value of the burn parameter depends on your laser cutter, the +material cut and the thickness of the material. In addition it depends +on whether you want the parts to be over or under sized. Materials +that are spongy like wood can be cut oversized (larger burn value) to +they can be press fitted with some force and may be assembled without +glue. Brittle materials (like Acrylic) need to be cut undersized to +leave a gap for glue. + +**Note:** The way the burn param works is a bit counter intuitive. Bigger +burn values make a tighter fit. Smaller values make a looser fit. + +Small changes in the burn param can make a notable difference. Typical +steps for adjustment are 0.01 or even 0.005mm to choose between +different amounts of force needed to press plywood together. + +format +...... + +Boxes.py is able to create multiple formats. For most of them it +requires ``ps2edit``. Unfortunately it is currently not available on +the server running the public web instance. Without it only ``SVG`` +and ``postscript`` (ps) is supported. With ``ps2edit`` you can also +select + +* ai +* dxf +* gcode +* pdf +* plt + +Other formats supported by ``ps2edit`` can be easily added. Please +open a ticket if you need one. + +tabs +.... + +Tabs are small bridges between the parts and surrounding material that +keep the part from falling out. In theory their width should be +affected by the burn parameter. But it is more practical to have both +be separate so you can tune them separately. Most parts and generators +support this features but there may be some that don't. + +For plywood values of 0.2 to 0.3mm still allow getting the parts out +by hand (Depending on you laser cutter and the exact material). With +little more you will need a knife to cut them loose. + +debug +..... + +Most regular users won't need this option. + +It adds some construction lines that are helpful for +developing new generators. Only few pieces actually support the +parameter. The most notable being finger holes that show the border of +the piece they belong to. This helps checking whether the finger holes +are placed correctly. + +reference +......... + +Converting vector graphics is error prone. Many formats have very +weird ideas how their internal units translates to real world +dimmensions. If reference is set to non zero Boxes.py renders a rectangle of +the given length. It can be used to check if the drawing is still at +the right scale or may give clues on how to scale it back to the right +proportions. + +Edge Type parameters +-------------------- + +All but the simplest edge types have a number of settings controlling +how exactly they should look. Generators are encouraged to offer these +settings to the user. In the web interface they are folded up. In the +command line interfacce they are grouped together. Users should be +aware that not all settings are practical to change. For now Boxes.py +does not allow hiding some settings.