Pcbnew FP wizard: add docstring for parameters
Adds more verbose and complete explanations of the FootprintWizardBase and FootprintWizardDrawingAids functions.
This commit is contained in:
John Beard
Wayne Stambaugh
parent
137799165d
commit
5001b056ac
|
|
@ -19,9 +19,24 @@ import pcbnew
|
|||
import math
|
||||
|
||||
|
||||
# Base class for creating footprint wizards
|
||||
# Inherit this class to make a new wizard
|
||||
class FootprintWizard(pcbnew.FootprintWizardPlugin):
|
||||
"""!
|
||||
A class to simplify many aspects of footprint creation, leaving only
|
||||
the foot-print specific routines to the wizards themselves.
|
||||
|
||||
Inherit this class to make a new wizard.
|
||||
|
||||
Provides simplified access to helpers like drawing functions, a transform
|
||||
matrix stack and simple parameter checking.
|
||||
|
||||
Generally, you need to implement:
|
||||
GetValue()
|
||||
GenerateParameterList()
|
||||
CheckParameters()
|
||||
BuildThisFootprint()
|
||||
GetName()
|
||||
GetDescription()
|
||||
"""
|
||||
|
||||
# Copy units from pcbnew
|
||||
uMM = pcbnew.uMM
|
||||
|
|
@ -34,55 +49,42 @@ class FootprintWizard(pcbnew.FootprintWizardPlugin):
|
|||
uPercent = pcbnew.uPercent
|
||||
uString = pcbnew.uString
|
||||
|
||||
"""
|
||||
A class to simplify many aspects of footprint creation, leaving only
|
||||
the foot-print specific routines to the wizards themselves
|
||||
|
||||
Generally, you need to implement:
|
||||
GetValue()
|
||||
GenerateParameterList()
|
||||
CheckParameters()
|
||||
BuildThisFootprint()
|
||||
GetName()
|
||||
GetDescription()
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
pcbnew.FootprintWizardPlugin.__init__(self)
|
||||
self.GenerateParameterList()
|
||||
|
||||
def GetName(self):
|
||||
"""
|
||||
"""!
|
||||
Return the name of the footprint wizard
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def GetDescription(self):
|
||||
"""
|
||||
"""!
|
||||
Return the footprint wizard description
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def GetValue(self):
|
||||
"""
|
||||
"""!
|
||||
Return the value (name) of the generated footprint
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def GenerateParameterList(self):
|
||||
"""
|
||||
"""!
|
||||
Footprint parameter specification is done here
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def CheckParameters(self):
|
||||
"""
|
||||
"""!
|
||||
Any custom parameter checking should be performed here
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
def BuildThisFootprint(self):
|
||||
"""
|
||||
"""!
|
||||
Draw the footprint.
|
||||
|
||||
This is specific to each footprint class, you need to implement
|
||||
|
|
@ -92,7 +94,7 @@ class FootprintWizard(pcbnew.FootprintWizardPlugin):
|
|||
|
||||
# Do not override this method!
|
||||
def BuildFootprint(self):
|
||||
"""
|
||||
"""!
|
||||
Actually make the footprint. We defer all but the set-up to
|
||||
the implementing class
|
||||
"""
|
||||
|
|
@ -149,16 +151,21 @@ class FootprintWizard(pcbnew.FootprintWizardPlugin):
|
|||
return
|
||||
|
||||
def SetModule3DModel(self):
|
||||
"""!
|
||||
If your plug-in sets a 3D model, override this function
|
||||
"""
|
||||
pass
|
||||
|
||||
def GetTextSize(self):
|
||||
"""
|
||||
IPC nominal
|
||||
"""!
|
||||
Get the default text size for the footprint. Override to change it.
|
||||
|
||||
Defaults to IPC nominal of 1.0mm
|
||||
"""
|
||||
return pcbnew.FromMM(1.0)
|
||||
|
||||
def GetTextThickness(self):
|
||||
"""
|
||||
"""!
|
||||
Thicker than IPC guidelines (10% of text height = 0.12mm)
|
||||
as 5 wires/mm is a common silk screen limitation
|
||||
"""
|
||||
|
|
@ -166,12 +173,14 @@ class FootprintWizard(pcbnew.FootprintWizardPlugin):
|
|||
|
||||
|
||||
class FootprintWizardDrawingAids:
|
||||
"""
|
||||
"""!
|
||||
Collection of handy functions to simplify drawing shapes from within
|
||||
footprint wizards
|
||||
|
||||
A "drawing context" is provided which can be used to set and retain
|
||||
settings such as line thickness and layer
|
||||
settings such as line thickness and layer. The DC also contains a
|
||||
"transform stack", which allows easy positioning and transforming of
|
||||
drawn elements without lots of geometric book-keeping.
|
||||
"""
|
||||
|
||||
# directions (in degrees, compass-like)
|
||||
|
|
@ -184,7 +193,7 @@ class FootprintWizardDrawingAids:
|
|||
dirW = 270
|
||||
dirNW = 315
|
||||
|
||||
# flip constants
|
||||
# Flip constants
|
||||
flipNone = 0 # no flip transform
|
||||
flipX = 1 # flip X values, i.e. about the Y-axis
|
||||
flipY = 2 # flip Y values, i.e. about the X-axis
|
||||
|
|
@ -212,17 +221,22 @@ class FootprintWizardDrawingAids:
|
|||
}
|
||||
|
||||
def PushTransform(self, mat):
|
||||
"""
|
||||
"""!
|
||||
Add a transform to the top of the stack and recompute the
|
||||
overall transform
|
||||
|
||||
@param mat: the transform matrix to add to the stack
|
||||
"""
|
||||
self.dc['transforms'].append(mat)
|
||||
self.RecomputeTransforms()
|
||||
|
||||
def PopTransform(self, num=1):
|
||||
"""
|
||||
"""!
|
||||
Remove a transform from the top of the stack and recompute the
|
||||
overall transform
|
||||
|
||||
@param num: the number of transforms to pop from the stack.
|
||||
@return the last popped transform
|
||||
"""
|
||||
|
||||
for i in range(num):
|
||||
|
|
@ -231,16 +245,19 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def ResetTransform(self):
|
||||
"""
|
||||
Reset the transform stack to the identity matrix
|
||||
"""!
|
||||
Reset the transform stack to the identity matrix.
|
||||
"""
|
||||
self.dc['transforms'] = []
|
||||
self.RecomputeTransforms()
|
||||
|
||||
def _ComposeMatricesWithIdentity(self, mats):
|
||||
"""
|
||||
"""!
|
||||
Compose a sequence of matrices together by sequential
|
||||
pre-multiplication with the identity matrix
|
||||
pre-multiplication with the identity matrix.
|
||||
|
||||
@param mats: list of matrices to compose
|
||||
@return: the composed transform matrix
|
||||
"""
|
||||
|
||||
x = self.xfrmIDENTITY
|
||||
|
|
@ -258,7 +275,7 @@ class FootprintWizardDrawingAids:
|
|||
return x
|
||||
|
||||
def RecomputeTransforms(self):
|
||||
"""
|
||||
"""!
|
||||
Re-compute the transform stack into a single transform and
|
||||
store in the DC
|
||||
"""
|
||||
|
|
@ -266,12 +283,17 @@ class FootprintWizardDrawingAids:
|
|||
self.dc['transforms'])
|
||||
|
||||
def TransformTranslate(self, x, y, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a translation
|
||||
optionally pushing onto the stack
|
||||
|
||||
( 1 0 x )
|
||||
( 0 1 y )
|
||||
|
||||
@param x: translation in x-direction
|
||||
@param y: translation in y-direction
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
mat = [1, 0, x, 0, 1, y]
|
||||
|
||||
|
|
@ -280,9 +302,13 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformFlipOrigin(self, flip, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a horizontal,
|
||||
vertical or both flip about the origin
|
||||
|
||||
@param flip: one of flipNone, flipX, flipY, flipBoth
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
mat = None
|
||||
if flip == self.flipX:
|
||||
|
|
@ -301,12 +327,18 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformFlip(self, x, y, flip=flipNone, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a horizontal,
|
||||
vertical or both flip about a point (x,y)
|
||||
|
||||
This is performed by a translate-to-origin, flip, translate-
|
||||
back sequence
|
||||
back sequence.
|
||||
|
||||
@param x: the x co-ordinate of the flip point
|
||||
@param y: the y co-ordinate of the flip point
|
||||
@param flip: one of flipNone, flipX, flipY, flipBoth
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
mats = [self.TransformTranslate(x, y, push=False),
|
||||
self.TransformFlipOrigin(flip, push=False),
|
||||
|
|
@ -320,12 +352,16 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformRotationOrigin(self, rot, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a rotation
|
||||
about the origin, and optionally push onto the stack
|
||||
|
||||
( cos(t) -sin(t) 0 )
|
||||
( sin(t) cos(t) 0 )
|
||||
|
||||
@param rot: the rotation angle in degrees
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
rads = rot * math.pi / 180
|
||||
mat = [math.cos(rads), -math.sin(rads), 0,
|
||||
|
|
@ -336,12 +372,18 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformRotation(self, x, y, rot, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a rotation
|
||||
about the point (x,y), and optionally push onto the stack
|
||||
|
||||
This is performed by a translate-to-origin, rotate, translate-
|
||||
back sequence
|
||||
|
||||
@param x: the x co-ordinate of the rotation centre
|
||||
@param y: the y co-ordinate of the rotation centre
|
||||
@param rot: the rotation angle in degrees
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
|
||||
mats = [self.TransformTranslate(x, y, push=False),
|
||||
|
|
@ -356,12 +398,17 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformScaleOrigin(self, sx, sy=None, push=True):
|
||||
"""
|
||||
"""!
|
||||
Set up and return a transform matrix representing a scale about
|
||||
the origin, and optionally push onto the stack
|
||||
|
||||
( sx 0 0 )
|
||||
( 0 sy 0 )
|
||||
|
||||
@param sx: the scale factor in the x direction
|
||||
@param sy: the scale factor in the y direction
|
||||
@param push: add this transform to the current stack
|
||||
@return the generated transform matrix
|
||||
"""
|
||||
|
||||
if sy is None:
|
||||
|
|
@ -374,9 +421,14 @@ class FootprintWizardDrawingAids:
|
|||
return mat
|
||||
|
||||
def TransformPoint(self, x, y, mat=None):
|
||||
"""
|
||||
"""!
|
||||
Return a point (x, y) transformed by the given matrix, or if
|
||||
that is not given, the drawing context transform
|
||||
|
||||
@param x: the x co-ordinate of the point to transform
|
||||
@param y: the y co-ordinate of the point to transform
|
||||
@param mat: the transform matrix to use or None to use the current DC's
|
||||
@return: the transformed point as a wxPoint
|
||||
"""
|
||||
|
||||
if not mat:
|
||||
|
|
@ -386,43 +438,47 @@ class FootprintWizardDrawingAids:
|
|||
x * mat[3] + y * mat[4] + mat[5])
|
||||
|
||||
def SetLineThickness(self, lineThickness):
|
||||
"""
|
||||
"""!
|
||||
Set the current pen lineThickness used for subsequent drawing
|
||||
operations
|
||||
|
||||
@param lineThickness: the new line thickness to set
|
||||
"""
|
||||
self.dc['lineThickness'] = lineThickness
|
||||
|
||||
def SetLineTickness(self, lineThickness):
|
||||
"""
|
||||
"""!
|
||||
Old version of SetLineThickness.
|
||||
Does the same thing, but is is only here for compatibility with old
|
||||
scripts.
|
||||
Set the current pen lineThickness used for subsequent drawing
|
||||
operations
|
||||
|
||||
@param lineThickness: the new line thickness to set
|
||||
"""
|
||||
self.dc['lineThickness'] = lineThickness
|
||||
self.SetLineThickness(lineThickness)
|
||||
|
||||
def GetLineThickness(self):
|
||||
"""
|
||||
"""!
|
||||
Get the current drawing context line thickness
|
||||
"""
|
||||
return self.dc['lineThickness']
|
||||
|
||||
def SetLayer(self, layer):
|
||||
"""
|
||||
"""!
|
||||
Set the current drawing layer, used for subsequent drawing
|
||||
operations
|
||||
"""
|
||||
self.dc['layer'] = layer
|
||||
|
||||
def GetLayer(self):
|
||||
"""
|
||||
return the current drawing layer, used drawing operations
|
||||
"""!
|
||||
Return the current drawing layer, used for drawing operations
|
||||
"""
|
||||
return self.dc['layer']
|
||||
|
||||
def Line(self, x1, y1, x2, y2):
|
||||
"""
|
||||
"""!
|
||||
Draw a line from (x1, y1) to (x2, y2)
|
||||
"""
|
||||
outline = pcbnew.EDGE_MODULE(self.module)
|
||||
|
|
@ -435,10 +491,16 @@ class FootprintWizardDrawingAids:
|
|||
self.module.Add(outline)
|
||||
|
||||
def Circle(self, x, y, r, filled=False):
|
||||
"""
|
||||
"""!
|
||||
Draw a circle at (x,y) of radius r
|
||||
If filled is true, the thickness and radius of the line will be set
|
||||
such that the circle appears filled
|
||||
|
||||
@param x: the x co-ordinate of the arc centre
|
||||
@param y: the y co-ordinate of the arc centre
|
||||
@param r: the circle's radius
|
||||
@param filled: True to draw a filled circle, False to use the current
|
||||
DC line thickness
|
||||
"""
|
||||
|
||||
circle = pcbnew.EDGE_MODULE(self.module)
|
||||
|
|
@ -457,13 +519,19 @@ class FootprintWizardDrawingAids:
|
|||
self.module.Add(circle)
|
||||
|
||||
def Arc(self, cx, cy, sx, sy, a):
|
||||
"""
|
||||
"""!
|
||||
Draw an arc based on centre, start and angle
|
||||
|
||||
The transform matrix is applied
|
||||
|
||||
Note that this won't work properly if the result is not a
|
||||
circular arc (e.g. a horizontal scale)
|
||||
|
||||
@param cx: the x co-ordinate of the arc centre
|
||||
@param cy: the y co-ordinate of the arc centre
|
||||
@param sx: the x co-ordinate of the arc start point
|
||||
@param sy: the y co-ordinate of the arc start point
|
||||
@param a: the arc's central angle (in deci-degrees)
|
||||
"""
|
||||
circle = pcbnew.EDGE_MODULE(self.module)
|
||||
circle.SetWidth(self.dc['lineThickness'])
|
||||
|
|
@ -482,22 +550,33 @@ class FootprintWizardDrawingAids:
|
|||
circle.SetStartEnd(center, start)
|
||||
self.module.Add(circle)
|
||||
|
||||
# extends from (x1,y1) right
|
||||
def HLine(self, x, y, l):
|
||||
"""
|
||||
"""!
|
||||
Draw a horizontal line from (x,y), rightwards
|
||||
|
||||
@param x: line start x co-ordinate
|
||||
@param y: line start y co-ordinate
|
||||
@param l: line length
|
||||
"""
|
||||
self.Line(x, y, x + l, y)
|
||||
|
||||
def VLine(self, x, y, l):
|
||||
"""
|
||||
"""!
|
||||
Draw a vertical line from (x1,y1), downwards
|
||||
|
||||
@param x: line start x co-ordinate
|
||||
@param y: line start y co-ordinate
|
||||
@param l: line length
|
||||
"""
|
||||
self.Line(x, y, x, y + l)
|
||||
|
||||
def Polyline(self, pts, mirrorX=None, mirrorY=None):
|
||||
"""
|
||||
"""!
|
||||
Draw a polyline, optionally mirroring around the given points
|
||||
|
||||
@param pts: list of polyline vertices (list of (x, y))
|
||||
@param mirrorX: x co-ordinate of mirror point (None for no x-flip)
|
||||
@param mirrorY: y co-ordinate of mirror point (None for no y-flip)
|
||||
"""
|
||||
|
||||
def _PolyLineInternal(pts):
|
||||
|
|
@ -525,11 +604,16 @@ class FootprintWizardDrawingAids:
|
|||
self.PopTransform()
|
||||
|
||||
def Reference(self, x, y, size, orientation_degree=0):
|
||||
"""
|
||||
"""!
|
||||
Draw the module's reference as the given point.
|
||||
|
||||
The actual setting of the reference is not done in this drawing
|
||||
aid - that is up to the wizard
|
||||
|
||||
@param x: the x position of the reference
|
||||
@param y: the y position of the reference
|
||||
@param size: the text size (in both directions)
|
||||
@param orientation_degree: text orientation in degrees
|
||||
"""
|
||||
|
||||
text_size = pcbnew.wxSize(size, size)
|
||||
|
|
@ -542,8 +626,13 @@ class FootprintWizardDrawingAids:
|
|||
self.module.Reference().SetTextAngle(orientation_degree * 10)
|
||||
|
||||
def Value(self, x, y, size, orientation_degree=0):
|
||||
"""
|
||||
"""!
|
||||
As for references, draw the module's value
|
||||
|
||||
@param x: the x position of the value
|
||||
@param y: the y position of the value
|
||||
@param size: the text size (in both directions)
|
||||
@param orientation_degree: text orientation in degrees
|
||||
"""
|
||||
text_size = pcbnew.wxSize(size, size)
|
||||
|
||||
|
|
@ -555,9 +644,14 @@ class FootprintWizardDrawingAids:
|
|||
self.module.Value().SetTextAngle(orientation_degree * 10)
|
||||
|
||||
def Box(self, x, y, w, h):
|
||||
"""
|
||||
"""!
|
||||
Draw a rectangular box, centred at (x,y), with given width and
|
||||
height
|
||||
|
||||
@param x: the x co-ordinate of the box's centre
|
||||
@param y: the y co-ordinate of the box's centre
|
||||
@param w: the width of the box
|
||||
@param h: the height of the box
|
||||
"""
|
||||
|
||||
pts = [[x - w/2, y - h/2], # left
|
||||
|
|
@ -569,10 +663,17 @@ class FootprintWizardDrawingAids:
|
|||
self.Polyline(pts)
|
||||
|
||||
def NotchedCircle(self, x, y, r, notch_w, notch_h, rotate=0):
|
||||
"""
|
||||
"""!
|
||||
Circle radius r centred at (x, y) with a raised or depressed notch
|
||||
at the top
|
||||
Notch height is measured from the top of the circle radius
|
||||
|
||||
@param x: the x co-ordinate of the circle's centre
|
||||
@param y: the y co-ordinate of the circle's centre
|
||||
@param r: the radius of the circle
|
||||
@param notch_w: the width of the notch
|
||||
@param notch_h: the height of the notch
|
||||
@param rotate: the rotation of the whole figure, in degrees
|
||||
"""
|
||||
|
||||
self.TransformRotation(x, y, rotate)
|
||||
|
|
@ -598,8 +699,16 @@ class FootprintWizardDrawingAids:
|
|||
self.PopTransform()
|
||||
|
||||
def NotchedBox(self, x, y, w, h, notchW, notchH, rotate=0):
|
||||
"""
|
||||
Draw a box with a notch in the top edge
|
||||
"""!
|
||||
Draw a box with a notch in the centre of the top edge
|
||||
|
||||
@param x: the x co-ordinate of the circle's centre
|
||||
@param y: the y co-ordinate of the circle's centre
|
||||
@param w: the width of the box
|
||||
@param h: the height of the box
|
||||
@param notchW: the width of the notch
|
||||
@param notchH: the height of the notch
|
||||
@param rotate: the rotation of the whole figure, in degrees
|
||||
"""
|
||||
|
||||
self.TransformRotation(x, y, rotate)
|
||||
|
|
@ -625,8 +734,16 @@ class FootprintWizardDrawingAids:
|
|||
|
||||
def BoxWithDiagonalAtCorner(self, x, y, w, h,
|
||||
setback=pcbnew.FromMM(1.27), flip=flipNone):
|
||||
"""
|
||||
Draw a box with a diagonal at the top left corner
|
||||
"""!
|
||||
Draw a box with a diagonal at the top left corner.
|
||||
|
||||
@param x: the x co-ordinate of the circle's centre
|
||||
@param y: the y co-ordinate of the circle's centre
|
||||
@param w: the width of the box
|
||||
@param h: the height of the box
|
||||
@param setback: the set-back of the diagonal, in both x and y
|
||||
@param flip: one of flipNone, flipX, flipY or flipBoth to change the
|
||||
diagonal corner
|
||||
"""
|
||||
|
||||
self.TransformFlip(x, y, flip, push=True)
|
||||
|
|
@ -644,8 +761,16 @@ class FootprintWizardDrawingAids:
|
|||
|
||||
def BoxWithOpenCorner(self, x, y, w, h,
|
||||
setback=pcbnew.FromMM(1.27), flip=flipNone):
|
||||
"""
|
||||
"""!
|
||||
Draw a box with an opening at the top left corner
|
||||
|
||||
@param x: the x co-ordinate of the circle's centre
|
||||
@param y: the y co-ordinate of the circle's centre
|
||||
@param w: the width of the box
|
||||
@param h: the height of the box
|
||||
@param setback: the set-back of the opening, in both x and y
|
||||
@param flip: one of flipNone, flipX, flipY or flipBoth to change the
|
||||
open corner position
|
||||
"""
|
||||
|
||||
self.TransformTranslate(x, y)
|
||||
|
|
@ -662,11 +787,15 @@ class FootprintWizardDrawingAids:
|
|||
self.PopTransform(num=2)
|
||||
|
||||
def MarkerArrow(self, x, y, direction=dirN, width=pcbnew.FromMM(1)):
|
||||
"""
|
||||
"""!
|
||||
Draw a marker arrow facing in the given direction, with the
|
||||
point at (x,y)
|
||||
|
||||
Direction of 0 is north
|
||||
@param x: x position of the arrow tip
|
||||
@param y: y position of the arrow tip
|
||||
@param direction: arrow direction in degrees (0 is "north", can use
|
||||
dir* shorthands)
|
||||
@param width: arrow width
|
||||
"""
|
||||
|
||||
self.TransformTranslate(x, y)
|
||||
|
|
|
|||
Loading…
Reference in New Issue