From fa0181311ed98f751bfe00d2d2acb29ff05df942 Mon Sep 17 00:00:00 2001 From: Florian Festi Date: Mon, 4 Apr 2016 01:28:02 +0200 Subject: [PATCH] Add to the documentation Move content of API.txt into the docs Rename TODO.txt and add it to the docs --- boxes/edges.py | 62 +++++++++++-- documentation/API.txt | 91 ------------------- documentation/Boxes.rst | 129 ++++++++++++++++++++++++++- documentation/{TODO.txt => TODO.rst} | 16 +++- documentation/edges.rst | 91 ++++++++++++++++++- documentation/index.rst | 1 + 6 files changed, 281 insertions(+), 109 deletions(-) delete mode 100644 documentation/API.txt rename documentation/{TODO.txt => TODO.rst} (72%) diff --git a/boxes/edges.py b/boxes/edges.py index 6e4cbd5..d880360 100644 --- a/boxes/edges.py +++ b/boxes/edges.py @@ -19,6 +19,7 @@ import math class BoltPolicy: """Abstract class + Distributes (bed) bolts on a number of segments (fingers of a finger joint) @@ -97,8 +98,12 @@ class Settings: """Generic Settings class Used by different other classes to store messurements and details. - Supports absolutevalues and settings that grow with the thinckness + Supports absolute values and settings that grow with the thickness of the material used. + + Overload the absolute_params and relative_params class attributes with + the suported keys and default values. The values are available via + attribute access. """ absolute_params = { } relative_params = { } @@ -118,8 +123,8 @@ class Settings: Set values :param thickness: thickness of the material used - :param relative: (Default value = True) Do scale by thinckness - :param **kw: parameters to set + :param relative: (Default value = True) Do scale by thickness + :param \*\*kw: parameters to set """ factor = 1.0 @@ -156,6 +161,7 @@ class Edge: return getattr(self.boxes, name) def __call__(self, length, **kw): + """Draw edge of length mm""" self.ctx.move_to(0,0) self.ctx.line_to(length, 0) self.ctx.translate(*self.ctx.get_current_point()) @@ -252,9 +258,23 @@ class SlottedEdge(Edge): self.edge(self.sections[-1]) class FingerJointSettings(Settings): - """Setting for all different finger joint components + """Settings for finger joints - Both sides should use the same instance to ensure they match""" +Values: + +* absolute + + * surroundingspaces : 2 : maximum space at the start and end in multiple + of normal spaces + +* relative (in multiples of thickness) + + * space : 1.0 : space between fingers + * finger : 1.0 : width of the fingers + * height : 1.0 : length of the fingers + * width : 1.0 : width of finger holes + +""" absolute_params = { "surroundingspaces" : 2, @@ -350,7 +370,7 @@ class FingerHoleEdge(Edge): return (self.fingerHoleEdgeWidth+1) * self.thickness class FingerHoles: - """Hole mathcing a finger joint edge""" + """Hole matching a finger joint edge""" def __init__(self, boxes, settings): self.boxes = boxes self.ctx = boxes.ctx @@ -392,7 +412,19 @@ class CrossingFingerHoleEdge(Edge): class DoveTailSettings(Settings): """Settings used for dove tail joints - Both sides should use the same instance to ensure they match""" +Values: + +* absolute + + * angle : 50 : how much should fingers widen (-80 to 80) + +* relative (in multiples of thickness) + + * size : 3 : from one middle of a dove tail to another + * depth : 1.5 : how far the dove tails stick out of/into the edge + * radius : 0.2 : radius used on all four corners + +""" absolute_params = { "angle" : 50, } @@ -454,7 +486,21 @@ class DoveTailJointCounterPart(DoveTailJoint): return self.boxes.spacing class FlexSettings(Settings): - """Settings for one directional flex cuts""" + """Settings for one directional flex cuts + +Values: + +* absolute + + * stretch : 1.05 : Hint of how much the flex part should be shortend + +* relative (in multiples of thickness) + + * distance : 0.5 : width of the pattern perpendicular to the cuts + * connection : 1.0 : width of the gaps in the cuts + * width" : 5.0 : width of the pattern in direction of the cuts + +""" relative_params = { "distance" : 0.5, "connection" : 1.0, diff --git a/documentation/API.txt b/documentation/API.txt deleted file mode 100644 index 37a74cc..0000000 --- a/documentation/API.txt +++ /dev/null @@ -1,91 +0,0 @@ -Basic Concepts -============== - -There is basically only one class that takes care of everything. You -are supposed to sub class it and implement the render() method -(actually just any method that does anything). This Boxes class keeps -a cairo canvas object (self.ctx) that all drawing is made on. In -addition it keeps a couple of global settings used for various drawing -operations. See the __init__ method for the details. - -Building blocks and coordinates -------------------------------- - -To avoid too much coordinate calculations the coordinate system is -continuously moved to the current point. The most basic functions just -do drawings relative to the current coordinate system - without -changing the coordinate system. Those are found in the Builing Blocks section. - -Turtle graphics commands ------------------------- - -These start at the current positions and move the coordinate system to -their end. It is assumed that you are (roughly) drawing into the -direction of the x axis, with the inside of the part being above the -line. You need to turn counter clockwise (mathematically positive) to -get a closed shape. These commands typically produce some sort of edges. - -Finger joints -............. - -Finger joints are a simple way of joining two sheets of plywood. They -work best at an 90° angle. There are two different sides matching each -other. As a third alternative there are holes that the fingers of one -sheet can plug into. This allows stable T connections especially -useful for inner walls. - -Dovetail joints -............... - -Dovetails joints can only be used to join two pieces flatly. This -limits their use to closing some round form created with flex areas or -for joining several parts to a bigger one. For this use case they are -much stronger than simple finger joints and can also bare pulling forces. - - -Whole parts -=========== - -A couple of command can create whole parts like walls. Typically the -sizes given are the inner dimmensions not including additional space -needed for burn compensation or joints. - -Currently there are only three such parts: - -Boxes.rectangularWall() for generic walls and -Boxes.roundedPlate() and Boxes.surroundingWall() for a wall with -rounded corners and fitting wall with flex for the rounded edges and -dove tail joints for closing the loop. - -Callback parameter -.................. - -The callback parameter can take on of the following forms: - - * A function (or bound method) that expects one parameter: the number - of the side the callback is currently called for. - * A dict with some of the numbers of the sides as keys and functions - without parameters as values. - * A list of functions without parameters. The list may contain None - as place holder and be shorter than the number of sides. - -The callback functions are called with the side of the part at the -positive x and y axis. If the edge uses up space this space is below -the x axis. You do not have to restore the coordinate settings in the -callback. - -Instead of functions it can be handy to use a lambda expression -calling the one building block funtion you need (e.g. fingerHolesAt). - -Edge description -................ - -Some part building functions take a edges param or have other params -describing some edges. These descriptions are one or several character -strings. With the following meanings: - - e : straight edge - E : as above but extended outside by one thickness - f, F : finger joints - h : edge with holes for finger joints - d, D : dove tail joints diff --git a/documentation/Boxes.rst b/documentation/Boxes.rst index b165338..5a54dd8 100644 --- a/documentation/Boxes.rst +++ b/documentation/Boxes.rst @@ -1,6 +1,4 @@ - - ========================== The boxes.Boxes main class ========================== @@ -8,8 +6,17 @@ The boxes.Boxes main class .. toctree:: :maxdepth: 2 +There is basically one class that takes care of everything. You are +supposed to sub class it and implement the ``.__init__()`` and +``.render()`` method. This Boxes class keeps a cairo canvas object +(self.ctx) that all drawing is made on. In addition it keeps a couple +of global settings used for various drawing operations. See the +``.__init__()`` method for the details. + .. autoclass:: boxes.Boxes +And easier way to get started is using the +``boxes/generators/_template.py`` as a basis for your own generators. Basic operation --------------- @@ -38,13 +45,131 @@ Currently there are only three such parts: The callback parameter ...................... +The callback parameter can take on of the following forms: + +* A function (or bound method) that expects one parameter: the number of the side the callback is currently called for. +* A dict with some of the numbers of the sides as keys and functions without parameters as values. +* A list of functions without parameters. The list may contain None as place holder and be shorter than the number of sides. + +The callback functions are called with the side of the part at the +positive x and y axis. If the edge uses up space this space is below +the x axis. You do not have to restore the coordinate settings in the +callback. + +Instead of functions it can be handy to use a lambda expression +calling the one building block funtion you need (e.g. fingerHolesAt). + +For your own parts you can use this helper function: + .. automethod:: boxes.Boxes.cc + +For finding the right piece to the *callback* parameter this function is used: + .. automethod:: boxes.Boxes.getEntry + The move parameter .................. +For placing the parts the ``move`` parameter can be used. It is string +with space separated words - at most one of each of those options: + +* left / right +* up / down +* only + +If "only" is given the part is not drawn but only the move is +done. This can be useful to go in one direction after having placed +multiple parts in the other and have returned with ``.ctx.restore()``. + +For implementing parts the following helper function can be used to +implement a ``move`` parameter: + .. automethod:: boxes.Boxes.move +It needs to be called before and after drawing the actual part with +the proper ``before`` paramter set. + The edges parameter ................... + +The ``edges`` parameter needs to be an iterable of Edge instances to be +used as edges of the part. Instead of instances it is possible to pass +a single character that is looked up in the ``.edges`` dict. This +allows to pass a string with the desired characters per edge. By +default the following character are supported: + +* e : straight edge +* E : as above but extended outside by one thickness +* f, F : finger joints +* h : edge with holes for finger joints +* d, D : dove tail joints + +Generators can register their own Edges by putting them into the +``.edges`` dictionary. + +Same applies to the parameters of ``.surroundingWall`` although they +denominate single edge (types) only. + +Navigation +---------- +.. automethod:: boxes.Boxes.moveTo +.. automethod:: boxes.Boxes.continueDirection + +Boxes.ctx.save() +Boxes.ctx.restore() + +Turtle Graphics commands +------------------------ + +These commands all move the coordinate system with them. + +.. automethod:: boxes.Boxes.edge +.. automethod:: boxes.Boxes.corner +.. automethod:: boxes.Boxes.curveTo +.. automethod:: boxes.Boxes.polyline + +Special Functions +................. + +.. automethod:: boxes.Boxes.bedBoltHole + +Latch and Grip +.............. + +These should probably be Edge classes. But right now they are still functions. + +.. automethod:: boxes.Boxes.grip +.. automethod:: boxes.Boxes.latch +.. automethod:: boxes.Boxes.handle + +Draw Commands +------------- + +These commands do not change the coordinate system but get the +coordinates passed as parameters. All of them are either som sort of +hole or text. These artefacts are placed somewhere independently of +some continuous outline of the part their on. + +.. automethod:: boxes.Boxes.fingerHolesAt +.. automethod:: boxes.Boxes.hole +.. automethod:: boxes.Boxes.rectangularHole +.. automethod:: boxes.Boxes.text +.. automethod:: boxes.Boxes.NEMA + +Hexagonal Hole patterns +....................... + +Hexagonal hole patters are one way to have some ventilation for +housings maded with Boxes.py. Right now both ``.rectangularWall()`` +and ``.roundedPlate()`` do supports this pattern directly by passing +the parameters to the calls. For other use cases these more low level +methods can be used. + +For now this is the only supported pattern for ventilation slots. More +may be added in the future. + +.. automethod:: boxes.Boxes.hexHolesRectangle +.. automethod:: boxes.Boxes.hexHolesCircle +.. automethod:: boxes.Boxes.hexHolesPlate +.. automethod:: boxes.Boxes.hexHolesHex diff --git a/documentation/TODO.txt b/documentation/TODO.rst similarity index 72% rename from documentation/TODO.txt rename to documentation/TODO.rst index c200f38..e98d7c3 100644 --- a/documentation/TODO.txt +++ b/documentation/TODO.rst @@ -1,12 +1,18 @@ +===== +To Do +===== + Infrastructure .............. * Make outer edge continuous even if other parts are drawn intermediately. * Check burn compensation for building blocks -* Fix hexHoles* (leftoover, grow to space, ...) +* Fix hexHoles\* (leftoover, grow to space, ...) * Add other ventilation patterns than hex holes * Make settings nicer - * Offer a collection of different settings + + * Offer a collection of different settings + * Use stretch setting in flexboxes * Add CLI params for finger joint settings * Add CLI params for flex settings @@ -15,8 +21,10 @@ Generators .......... * Fix traylayout - * Inner corners of the floor - * Bottom edges of walls without floor underneeth + + * Inner corners of the floor + * Bottom edges of walls without floor underneeth + * Finish lamp * Make bolts configurable (e.g. box2.py) * Treasure Chest with rounded lid and living hinge diff --git a/documentation/edges.rst b/documentation/edges.rst index f21d20a..5ce71d3 100644 --- a/documentation/edges.rst +++ b/documentation/edges.rst @@ -2,22 +2,105 @@ Edges ===== As edges started out as methods of the main Boxes class they still are -callables and they are still available as both attributes of the Boxes -instance and also via the **.edges** attribute. +callables. A set of instances are kept the ``.edges`` attribute of the +``Boxes`` class. It is a dict with strings of length one as keys: -The default edges have a one character short name that can be used at -various places to quickly decide which type of edge to use. +* e : Edge +* E : OutSetEdge +* f : FingerJointEdge +* F : FingerJointEdgeCounterPart +* h : FingerHoleEdge +* d : DoveTailJoint +* D : DoveTailJointCounterPart + +Edges of the same type share a settings instance to make sure both +sides match (when the same length is given). + +Edge base class +--------------- + +.. autoclass:: boxes.edges.Edge + :members: + +.. automethod:: boxes.edges.Edge.__call__ + +Settings Class +-------------- + +.. autoclass:: boxes.edges.Settings + :members: + + +Straight Edges +-------------- .. autoclass:: boxes.edges.Edge .. autoclass:: boxes.edges.OutSetEdge + +Finger joints +------------- + +Finger joints are a simple way of joining two sheets (e.g. of plywood). They +work best at an 90° angle. There are two different sides matching each +other. As a third alternative there are holes that the fingers of one +sheet can plug into. This allows stable T connections especially +useful for inner walls. + .. autoclass:: boxes.edges.FingerJointEdge .. autoclass:: boxes.edges.FingerJointEdgeCounterPart .. autoclass:: boxes.edges.FingerHoleEdge .. autoclass:: boxes.edges.CrossingFingerHoleEdge + +In addition there is + +.. automethod:: boxes.Boxes.fingerHolesAt + +which is no Edge but fits ``FingerJointEdge``. + +Finger Joint Settings +..................... + +.. autoclass:: boxes.edges.FingerJointSettings + :members: + +Bed Bolts +......... + +.. autoclass:: boxes.edges.BoltPolicy + +.. autoclass:: boxes.edges.Bolts + +Dove Tail Joints +---------------- +Dovetails joints can only be used to join two pieces flatly. This +limits their use to closing some round form created with flex areas or +for joining several parts to a bigger one. For this use case they are +much stronger than simple finger joints and can also bare pulling forces. + .. autoclass:: boxes.edges.DoveTailJoint .. autoclass:: boxes.edges.DoveTailJointCounterPart + +Dove Tail Settings +.................. + +.. autoclass:: boxes.edges.DoveTailSettings + :members: + +Flex +---- .. autoclass:: boxes.edges.FlexEdge + +Flex Settings +............. + +.. autoclass:: boxes.edges.FlexSettings + +Slots +----- .. autoclass:: boxes.edges.Slot .. autoclass:: boxes.edges.SlottedEdge + +CompoundEdge +------------ .. autoclass:: boxes.edges.CompoundEdge diff --git a/documentation/index.rst b/documentation/index.rst index 3185402..285f266 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -13,6 +13,7 @@ Contents: Boxes edges + TODO .. include:: ../README.rst