From 8482d2865e2c5d8ce12e151ff504261ab13bed99 Mon Sep 17 00:00:00 2001 From: crobarcro Date: Tue, 30 May 2017 15:20:23 +0100 Subject: [PATCH] TopoShapeEdgePy.xml: improved docstrings Corrected docstrings for *At methods (valueAt, tangentAt etc.) to explain parameter position meaning Improved docstrings for FirstParameter, LastParameter, Length and getParameterByLength --- src/Mod/Part/App/TopoShapeEdgePy.xml | 306 +++++++++++++++++++++++++-- 1 file changed, 291 insertions(+), 15 deletions(-) diff --git a/src/Mod/Part/App/TopoShapeEdgePy.xml b/src/Mod/Part/App/TopoShapeEdgePy.xml index ea149baa5c..7683fced33 100644 --- a/src/Mod/Part/App/TopoShapeEdgePy.xml +++ b/src/Mod/Part/App/TopoShapeEdgePy.xml @@ -16,17 +16,102 @@ - float = getParameterByLength(float) - Return parameter [First,Last]. Input value must be of [0|Length] + paramval = getParameterByLength(pos) +Get the value of the primary parameter at the given distance along the cartesian +length of the curve. + +Args: + pos (float or int): The distance along the length of the curve at which to + determine the primary parameter value. See help for the FirstParameter or + LastParameter properties for more information on the primary parameter. + +Returns: + + paramval (float): the value of the primary parameter defining the curve at the + given position along its cartesian length. + - Vector = tangentAt(pos) - Get the tangent at the given parameter [First|Last] if defined + Vector = tangentAt(paramval) +Get the tangent direction at the given primary parameter value along the Edge +if it is defined + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the tangent direction e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.tangentAt(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is the Vector (-0.7071067811865475, 0.7071067811865476, 0.0) + + Values with magnitude greater than the Edge length return + values of the tangent on the curve extrapolated beyond its + length. This may not be valid for all Edges. Negative values + similarly return a tangent on the curve extrapolated backwards + (before the start point of the Edge). For example, using the + same shape as above: + + >>> x.tangentAt(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865477, 0.7071067811865474, 0.0) + + Which gives the same result as + + >>> x.tangentAt(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865475, 0.7071067811865476, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the tangent to the Edge at the given + location along its length (or extrapolated length) + - Vector = valueAt(pos) - Get the point at the given parameter [First|Last] if defined + Vector = valueAt(paramval) +Get the value of the cartesian parameter value at the given parameter value along +the Edge + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the value in terms of the main parameter defining + the edge, what the parameter value is depends on the type of + edge. See e.g: + + For a circle value + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.valueAt(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is theVector (0.7071067811865476, 0.7071067811865475, 0.0) + + Values with magnitude greater than the Edge length return + values on the curve extrapolated beyond its length. This may + not be valid for all Edges. Negative values similarly return + a parameter value on the curve extrapolated backwards (before the + start point of the Edge). For example, using the same shape + as above: + + >>> x.valueAt(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865474, -0.7071067811865477, 0.0) + + Which gives the same result as + + >>> x.valueAt(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865476, -0.7071067811865475, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the cartesian location on the Edge at the given + distance along its length (or extrapolated length) + @@ -36,27 +121,163 @@ - Vector = normalAt(pos) - Get the normal vector at the given parameter [First|Last] if defined + Vector = normalAt(paramval) +Get the normal direction at the given parameter value along the Edge if it +is defined + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the normal direction e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.normalAt(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is the Vector (-0.7071067811865476, -0.7071067811865475, 0.0) + + Values with magnitude greater than the Edge length return + values of the normal on the curve extrapolated beyond its + length. This may not be valid for all Edges. Negative values + similarly return a normal on the curve extrapolated backwards + (before the start point of the Edge). For example, using the + same shape as above: + + >>> x.normalAt(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865474, 0.7071067811865477, 0.0) + + Which gives the same result as + + >>> x.normalAt(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865476, 0.7071067811865475, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the normal to the Edge at the given + location along its length (or extrapolated length) + - Vector = d1At(pos) - Get the first derivative at the given parameter [First|Last] if defined + Vector = derivative1At(paramval) +Get the first derivative at the given parameter value along the Edge if it +is defined + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the first derivative e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.derivative1At(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is the Vector (-0.7071067811865475, 0.7071067811865476, 0.0) + + Values with magnitude greater than the Edge length return + values of the first derivative on the curve extrapolated + beyond its length. This may not be valid for all Edges. + Negative values similarly return a first derivative on the + curve extrapolated backwards (before the start point of the + Edge). For example, using the same shape as above: + + >>> x.derivative1At(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865477, 0.7071067811865474, 0.0) + + Which gives the same result as + + >>> x.derivative1At(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (0.7071067811865475, 0.7071067811865476, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the first derivative to the Edge at the + given location along its length (or extrapolated length) + - Vector = d2At(pos) - Get the second derivative at the given parameter [First|Last] if defined + Vector = derivative2At(paramval) +Get the second derivative at the given parameter value along the Edge if it +is defined + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the second derivative e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.derivative2At(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is the Vector (-0.7071067811865476, -0.7071067811865475, 0.0) + + Values with magnitude greater than the Edge length return + values of the second derivative on the curve extrapolated + beyond its length. This may not be valid for all Edges. + Negative values similarly return a second derivative on the + curve extrapolated backwards (before the start point of the + Edge). For example, using the same shape as above: + + >>> x.derivative2At(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865474, 0.7071067811865477, 0.0) + + Which gives the same result as + + >>> x.derivative2At(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865476, 0.7071067811865475, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the second derivative to the Edge at the + given location along its length (or extrapolated length) + - Vector = d3At(pos) - Get the third derivative at the given parameter [First|Last] if defined + Vector = derivative3At(paramval) +Get the third derivative at the given parameter value along the Edge if it +is defined + +Args: + paramval (float or int): The parameter value along the Edge at which to + determine the third derivative e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.derivative3At(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + + y is the Vector (0.7071067811865475, -0.7071067811865476, -0.0) + + Values with magnitude greater than the Edge length return + values of the third derivative on the curve extrapolated + beyond its length. This may not be valid for all Edges. + Negative values similarly return a third derivative on the + curve extrapolated backwards (before the start point of the + Edge). For example, using the same shape as above: + + >>> x.derivative3At(x.FirstParameter + 3.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865477, -0.7071067811865474, 0.0) + + Which gives the same result as + + >>> x.derivative3At(x.FirstParameter -0.5*(x.LastParameter - x.FirstParameter)) + Vector (-0.7071067811865475, -0.7071067811865476, 0.0) + + Since it is a circle + +Returns: + + Vector: representing the third derivative to the Edge at the + given location along its length (or extrapolated length) + - Float = curvatureAt(pos) - Get the curvature at the given parameter [First|Last] if defined + Float = curvatureAt(paramval) - Get the curvature at the given parameter [First|Last] if defined @@ -124,7 +345,20 @@ Part.show(s) - Splits the edge at the given parameter values and builds a wire out of it + Wire = split(paramval) +Splits the edge at the given parameter values and builds a wire out of it + +Args: + paramval (float or int): The parameter value along the Edge at which to + split it e.g: + + x = Part.makeCircle(1, FreeCAD.Vector(0,0,0), FreeCAD.Vector(0,0,1), 0, 90) + y = x.derivative3At(x.FirstParameter + 0.5 * (x.LastParameter - x.FirstParameter)) + +Returns: + + Wire: wire made up of two Edges + @@ -140,25 +374,67 @@ Part.show(s) - Returns the length of the edge + Returns the cartesian length of the curve - Returns a 2 tuple with the parameter range + +Returns a 2 tuple with the range of the primary parameter +defining the curve. This is the same as would be returned by +the FirstParameter and LastParameter properties, i.e. + +(LastParameter,FirstParameter) + +What the parameter is depends on what type of edge it is. For a +Line the parameter is simply its cartesian length. Some other +examples are shown below: + +Type Parameter +--------------------------------------------------------------- +Circle Angle swept by circle (or arc) in radians +BezierCurve Unitless number in the range 0.0 to 1.0 +Helix Angle swept by helical turns in radians + - Returns the start value of the parameter range + +Returns the start value of the range of the primary parameter +defining the curve. + +What the parameter is depends on what type of edge it is. For a +Line the parameter is simply its cartesian length. Some other +examples are shown below: + +Type Parameter +----------------------------------------------------------- +Circle Angle swept by circle (or arc) in radians +BezierCurve Unitless number in the range 0.0 to 1.0 +Helix Angle swept by helical turns in radians + - Returns the end value of the parameter range + +Returns the end value of the range of the primary parameter +defining the curve. + +What the parameter is depends on what type of edge it is. For a +Line the parameter is simply its cartesian length. Some other +examples are shown below: + +Type Parameter +----------------------------------------------------------- +Circle Angle swept by circle (or arc) in radians +BezierCurve Unitless number in the range 0.0 to 1.0 +Helix Angle swept by helical turns in radians + @@ -170,13 +446,13 @@ Part.show(s) - Returns true of the edge is closed + Returns true if the edge is closed - Returns true of the edge is degenerated + Returns true if the edge is degenerated