FreeCAD

1
# ***************************************************************************
2
# *   (c) 2020 Eliud Cabrera Castillo <e.cabrera-castillo@tum.de>           *
3
# *                                                                         *
4
# *   This file is part of the FreeCAD CAx development system.              *
5
# *                                                                         *
6
# *   This program is free software; you can redistribute it and/or modify  *
7
# *   it under the terms of the GNU Lesser General Public License (LGPL)    *
8
# *   as published by the Free Software Foundation; either version 2 of     *
9
# *   the License, or (at your option) any later version.                   *
10
# *   for detail see the LICENCE text file.                                 *
11
# *                                                                         *
12
# *   FreeCAD is distributed in the hope that it will be useful,            *
13
# *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
14
# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
15
# *   GNU Library General Public License for more details.                  *
16
# *                                                                         *
17
# *   You should have received a copy of the GNU Library General Public     *
18
# *   License along with FreeCAD; if not, write to the Free Software        *
19
# *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
20
# *   USA                                                                   *
21
# *                                                                         *
22
# ***************************************************************************
23
"""Provides functions to create Arc objects by using 3 points."""
24
## @package make_arc_3points
25
# \ingroup draftmake
26
# \brief Provides functions to create Arc objects by using 3 points.
27

28
## \addtogroup draftmake
29
# @{
30
import math
31

32
import FreeCAD as App
33
import Part
34
import Draft
35
import draftutils.utils as utils
36
from draftutils.messages import _err
37
from draftutils.translate import translate
38

39
import draftutils.gui_utils as gui_utils
40

41

42
def make_arc_3points(points, placement=None, face=False,
43
                     support=None, map_mode="Deactivated",
44
                     primitive=False):
45
    """Draw a circular arc defined by three points in the circumference.
46

47
    Parameters
48
    ----------
49
    points: list of Base::Vector3
50
        A list that must be three points.
51

52
    placement: Base::Placement, optional
53
        It defaults to `None`.
54
        It is a placement, comprised of a `Base` (`Base::Vector3`),
55
        and a `Rotation` (`Base::Rotation`).
56
        If it exists it moves the center of the new object to the point
57
        indicated by `placement.Base`, while `placement.Rotation`
58
        is ignored so that the arc keeps the same orientation
59
        with which it was created.
60

61
        If both `support` and `placement` are given,
62
        `placement.Base` is used for the `AttachmentOffset.Base`,
63
        and again `placement.Rotation` is ignored.
64

65
    face: bool, optional
66
        It defaults to `False`.
67
        If it is `True` it will create a face in the closed arc.
68
        Otherwise only the circumference edge will be shown.
69

70
    support: App::PropertyLinkSubList, optional
71
        It defaults to `None`.
72
        It is a list containing tuples to define the attachment
73
        of the new object.
74

75
        A tuple in the list needs two elements;
76
        the first is an external object, and the second is another tuple
77
        with the names of sub-elements on that external object
78
        likes vertices or faces.
79
        ::
80
            support = [(obj, ("Face1"))]
81
            support = [(obj, ("Vertex1", "Vertex5", "Vertex8"))]
82

83
        This parameter sets the `Support` property but it only really affects
84
        the position of the new object when the `map_mode`
85
        is set to other than `'Deactivated'`.
86

87
    map_mode: str, optional
88
        It defaults to `'Deactivated'`.
89
        It defines the type of `'MapMode'` of the new object.
90
        This parameter only works when a `support` is also provided.
91

92
        Example: place the new object on a face or another object.
93
        ::
94
            support = [(obj, ("Face1"))]
95
            map_mode = 'FlatFace'
96

97
        Example: place the new object on a plane created by three vertices
98
        of an object.
99
        ::
100
            support = [(obj, ("Vertex1", "Vertex5", "Vertex8"))]
101
            map_mode = 'ThreePointsPlane'
102

103
    primitive: bool, optional
104
        It defaults to `False`. If it is `True`, it will create a Part
105
        primitive instead of a Draft object.
106
        In this case, `placement`, `face`, `support`, and `map_mode`
107
        are ignored.
108

109
    Returns
110
    -------
111
    Part::Part2DObject or Part::Feature
112
        The new arc object.
113
        Normally it returns a parametric Draft object (`Part::Part2DObject`).
114
        If `primitive` is `True`, it returns a basic `Part::Feature`.
115

116
    None
117
        Returns `None` if there is a problem and the object cannot be created.
118
    """
119
    _name = "make_arc_3points"
120

121
    try:
122
        utils.type_check([(points, (list, tuple))], name=_name)
123
    except TypeError:
124
        _err(translate("draft","Points:") + " {}".format(points))
125
        _err(translate("draft","Wrong input: must be list or tuple of three points exactly."))
126
        return None
127

128
    if len(points) != 3:
129
        _err(translate("draft","Points:") + " {}".format(points))
130
        _err(translate("draft","Wrong input: must be list or tuple of three points exactly."))
131
        return None
132

133
    if placement is not None:
134
        try:
135
            utils.type_check([(placement, App.Placement)], name=_name)
136
        except TypeError:
137
            _err(translate("draft","Placement:") + " {}".format(placement))
138
            _err(translate("draft","Wrong input: incorrect type of placement."))
139
            return None
140

141
    p1, p2, p3 = points
142

143
    try:
144
        utils.type_check([(p1, App.Vector),
145
                          (p2, App.Vector),
146
                          (p3, App.Vector)], name=_name)
147
    except TypeError:
148
        _err(translate("draft","Wrong input: incorrect type of points."))
149
        return None
150

151
    try:
152
        _edge = Part.Arc(p1, p2, p3)
153
    except Part.OCCError as error:
154
        _err(translate("draft","Cannot generate shape:") + " " + "{}".format(error))
155
        return None
156

157
    edge = _edge.toShape()
158
    radius = edge.Curve.Radius
159
    center = edge.Curve.Center
160

161
    if primitive:
162
        obj = App.ActiveDocument.addObject("Part::Feature", "Arc")
163
        obj.Shape = edge
164
        return obj
165

166
    rot = App.Rotation(edge.Curve.XAxis,
167
                       edge.Curve.YAxis,
168
                       edge.Curve.Axis, "ZXY")
169
    _placement = App.Placement(center, rot)
170
    start = edge.FirstParameter
171
    end = math.degrees(edge.LastParameter)
172
    obj = Draft.make_circle(radius,
173
                            placement=_placement, face=face,
174
                            startangle=start, endangle=end,
175
                            support=support)
176

177
    original_placement = obj.Placement
178

179
    if placement and not support:
180
        obj.Placement.Base = placement.Base
181
    if support:
182
        obj.MapMode = map_mode
183
        if placement:
184
            obj.AttachmentOffset.Base = placement.Base
185
            obj.AttachmentOffset.Rotation = original_placement.Rotation
186

187
    return obj
188

189
## @}
190