From 5d09b9b8f585c5de80fd54d04173625aa87bb49d Mon Sep 17 00:00:00 2001 From: looooo Date: Thu, 4 Jan 2024 23:37:57 +0100 Subject: [PATCH] add some docs --- freecad/gears/basegear.py | 14 ++- freecad/gears/crowngear.py | 12 ++- pygears/_functions.py | 191 ++++++++++++++++++++++++++++--------- 3 files changed, 166 insertions(+), 51 deletions(-) diff --git a/freecad/gears/basegear.py b/freecad/gears/basegear.py index 9c02174..ec2803b 100644 --- a/freecad/gears/basegear.py +++ b/freecad/gears/basegear.py @@ -18,24 +18,32 @@ import os import sys +import numpy as np from freecad import app from freecad import part -import numpy as np - from pygears import __version__ from pygears._functions import arc_from_points_and_center def fcvec(x): + """tranforms a list or numpy array to a FreeCAD Vector which is + always 3d + + Args: + x (iterable): either a 2d or 3d vector + + Returns: + freecad.app.Vector: _description_ + """ if len(x) == 2: return app.Vector(x[0], x[1], 0) else: return app.Vector(x[0], x[1], x[2]) -class ViewProviderGear(object): +class ViewProviderGear(): """ The base Viewprovider for the gears """ diff --git a/freecad/gears/crowngear.py b/freecad/gears/crowngear.py index 7dca84c..048f735 100644 --- a/freecad/gears/crowngear.py +++ b/freecad/gears/crowngear.py @@ -16,18 +16,22 @@ # * * # *************************************************************************** -import os -import sys + +import numpy as np from freecad import app from freecad import part -import numpy as np - from .basegear import BaseGear, fcvec class CrownGear(BaseGear): + """ + A crown gear (also known as a face gear or a contrate gear) is a gear + which has teeth that project at right angles to the face of the wheel. + In particular, a crown gear is a type of bevel gear where the pitch cone + angle is 90 degrees. https://en.wikipedia.org/wiki/Crown_gear + """ def __init__(self, obj): super(CrownGear, self).__init__(obj) obj.addProperty("App::PropertyInteger", "teeth", "base", "number of teeth") diff --git a/pygears/_functions.py b/pygears/_functions.py index 59f1e03..d6abb54 100644 --- a/pygears/_functions.py +++ b/pygears/_functions.py @@ -21,17 +21,34 @@ from numpy.linalg import solve, norm def reflection(angle): + """A 2d reflection- / mirror- transformation + + Args: + angle (float): the angle of the line which mirrors the points. + + Returns: + function(points): the function can be used to transform an array of points (2d) + """ mat = array([[cos(2 * angle), -sin(2 * angle)], [-sin(2 * angle), -cos(2 * angle)]]) - def func(x): + def _func(x): # we do not use matrix-multiplication here because this is meant to work # on an array of points return dot(x, mat) - return func + return _func def reflection3D(angle): + """A 3d reflection- / mirror- transformation + + Args: + angle (float): the angle of the line which mirrors the points. The transformation + happens in xy-plane. + + Returns: + function(points): the function can be used to transform an array of points (3d) + """ mat = array( [ [cos(2 * angle), -sin(2 * angle), 0.0], @@ -40,47 +57,85 @@ def reflection3D(angle): ] ) - def func(x): - return dot(x, mat) + def _func(points): + return dot(points, mat) - return func + return _func -def rotation(angle, midpoint=None): - midpoint = midpoint or [0.0, 0.0] +def rotation(angle, center=None): + """A 2d rotation - transformation + + Args: + angle (float): the angle of the rotation. + center (2d array): + + Returns: + function(points): the function can be used to transform an array of points (3d) + """ + center = center or [0.0, 0.0] mat = array([[cos(angle), sin(angle)], [-sin(angle), cos(angle)]]) - midpoint = array(midpoint) - vec = midpoint - dot(midpoint, mat) + center = array(center) + vec = center - dot(center, mat) trans = translation(vec) - def func(xx): - return trans(dot(xx, mat)) + def _func(points): + return trans(dot(points, mat)) - return func + return _func def rotation3D(angle): + """A 3d rotation - transformation + + Args: + angle (float): the angle of the line which mirrors the points. The transformation + happens in xy-plane. + + Returns: + function(points): the function can be used to transform an array of points (3d) + """ mat = array( [[cos(angle), sin(angle), 0.0], [-sin(angle), cos(angle), 0.0], [0.0, 0.0, 1.0]] ) - def func(xx): - return dot(xx, mat) + def _func(points): + return dot(points, mat) - return func + return _func -def translation(vec): - def trans(x): - return [x[0] + vec[0], x[1] + vec[1]] +def translation(vector): + """A 2d translation - transformation - def func(x): - return array(list(map(trans, x))) + Args: + angle (float): the angle of the line which mirrors the points. The transformation + happens in xy-plane. - return func + Returns: + function(points): the function can be used to transform an array of points (3d) + """ + def _trans(point): + return [point[0] + vector[0], point[1] + vector[1]] + + def _func(points): + return array(list(map(_trans, points))) + + return _func def trim(p1, p2, p3, p4): + """ a trim function, needs to be documented + + Args: + p1 (array or list of length 2): _description_ + p2 (array or list of length 2): _description_ + p3 (array or list of length 2): _description_ + p4 (array or list of length 2): _description_ + + Returns: + _type_: _description_ + """ a1 = array(p1) a2 = array(p2) a3 = array(p3) @@ -115,6 +170,16 @@ def trim(p1, p2, p3, p4): def trimfunc(l1, l2): + """seems like a trimm function, but I don't have any clue what it does, + sry ;) + + Args: + l1 (_type_): _description_ + l2 (_type_): _description_ + + Returns: + _type_: _description_ + """ ik = 0 i0 = array(l1[0]) for i in array(l1[1:]): @@ -139,19 +204,36 @@ def trimfunc(l1, l2): return False -def diff_norm(vec1, vec2): - vec = array(vec2) - array(vec1) - return norm(vec) +def diff_norm(vector_1, vector_2): + """_summary_ + + Args: + vector_1 (np.array or list): the first vector + vector_2 (np.array or list): the second vector + + Returns: + float: the length of the distance between the two vectors + """ + return norm(array(vector_2) - array(vector_1)) -def nearestpts(evolv, underc): +def nearestpts(involute, undercut): + """finds the closest points of a involute and an undercutut + + Args: + involute (array or list of 2d points ?): the involute section of the tooth + undercut (array or list of 2d points ?): the undercut section of the tooth + + Returns: + list of arrays: ???? + """ ik = 0 iout = 0 jout = 0 outmin = 1000.0 - for i in array(evolv[1:]): + for i in array(involute[1:]): jk = 0 - for j in array(underc[1:]): + for j in array(undercut[1:]): l = diff_norm(i, j) if l < outmin: re = diff_norm(i, [0, 0]) @@ -161,25 +243,46 @@ def nearestpts(evolv, underc): iout, jout = [ik, jk] jk += 1 ik += 1 - return [vstack([underc[:jout], evolv[iout]]), evolv[iout:]] + return [vstack([undercut[:jout], involute[iout]]), involute[iout:]] -def intersection_line_circle(p1, p2, r): - """return the intersection point of a line from p1 to p2 and a sphere of radius 1 and - midpoint 0,0,0""" - d = p2 - p1 - d /= norm(d) - p_half = d.dot(p1) - q = p1.dot(p1) - r**2 - t = -p_half + sqrt(p_half**2 - q) - return p1 + d * t +def intersection_line_circle(point_1, point_2, radius): + """return the intersection point of a line from point_1 to point_2 and a sphere of radius 1 and + midpoint 0,0,0 + + Args: + point_1 (_type_): start of line + point_2 (_type_): end of line + radius (float): the radius of the sphere + + Returns: + _type_: _description_ + """ + diff = point_2 - point_1 + diff /= norm(diff) + p_half = diff.dot(point_1) + q = point_1.dot(point_1) - radius ** 2 + t = -p_half + sqrt(p_half ** 2 - q) + return point_1 + diff * t -def arc_from_points_and_center(p_1, p_2, m): - """return 3 points (x1, x12, x2) which can be used to create the arc""" - r = (norm(p_1 - m) + norm(p_2 - m)) / 2 - p_12l = (p_1 + p_2) / 2 - v = p_12l - m +def arc_from_points_and_center(point_1, point_2, center): + """ + returns 3 points (point_1, point_12, point_2) which are on the arc with + given center + + Args: + point_1 (np.array with length 2): the start point of the arc + point_2 (np.array with length 2): the end point of the arc + center (np.array with length 2): the center of the arc + + Returns: + [point_1, point_12, point_2]: returns the input points + the computed point + which is on the arc and between the input points + """ + r = (norm(point_1 - center) + norm(point_2 - center)) / 2 + p_12l = (point_1 + point_2) / 2 + v = p_12l - center v /= norm(v) - p_12 = m + v * r - return (p_1, p_12, p_2) + p_12 = center + v * r + return (point_1, p_12, point_2)