haskal
/
kicad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2018-06-01 13:11:03 +01:00 committed by Wayne Stambaugh
parent 137799165d
commit 5001b056ac
1 changed files with 197 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
pcbnew/python/plugins/FootprintWizardBase.py
View File

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