FreeCAD

1
# ***************************************************************************
2
# *   (c) 2019 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 polar Array objects."""
24
## @package make_polararray
25
# \ingroup draftmake
26
# \brief Provides functions to create polar Array objects.
27

28
## \addtogroup draftmake
29
# @{
30
import FreeCAD as App
31
import draftutils.utils as utils
32
import draftmake.make_array as make_array
33

34
from draftutils.messages import _err
35
from draftutils.translate import translate
36

37

38
def make_polar_array(base_object,
39
                     number=5, angle=360, center=App.Vector(0, 0, 0),
40
                     use_link=True):
41
    """Create a polar array from the given object.
42

43
    Parameters
44
    ----------
45
    base_object: Part::Feature or str
46
        Any of object that has a `Part::TopoShape` that can be duplicated.
47
        This means most 2D and 3D objects produced with any workbench.
48
        If it is a string, it must be the `Label` of that object.
49
        Since a label is not guaranteed to be unique in a document,
50
        it will use the first object found with this label.
51

52
    number: int, optional
53
        It defaults to 5.
54
        The number of copies produced in the polar pattern.
55

56
    angle: float, optional
57
        It defaults to 360.
58
        The magnitude in degrees swept by the polar pattern.
59

60
    center: Base::Vector3, optional
61
        It defaults to the origin `App.Vector(0, 0, 0)`.
62
        The vector indicating the center of rotation of the array.
63

64
    use_link: bool, optional
65
        It defaults to `True`.
66
        If it is `True` the produced copies are not `Part::TopoShape` copies,
67
        but rather `App::Link` objects.
68
        The Links repeat the shape of the original `obj` exactly,
69
        and therefore the resulting array is more memory efficient.
70

71
        Also, when `use_link` is `True`, the `Fuse` property
72
        of the resulting array does not work; the array doesn't
73
        contain separate shapes, it only has the original shape repeated
74
        many times, so there is nothing to fuse together.
75

76
        If `use_link` is `False` the original shape is copied many times.
77
        In this case the `Fuse` property is able to fuse
78
        all copies into a single object, if they touch each other.
79

80
    Returns
81
    -------
82
    Part::FeaturePython
83
        A scripted object of type `'Array'`.
84
        Its `Shape` is a compound of the copies of the original object.
85

86
    None
87
        If there is a problem it will return `None`.
88

89
    See Also
90
    --------
91
    make_ortho_array, make_circular_array, make_path_array, make_point_array
92
    """
93
    _name = "make_polar_array"
94

95
    found, base_object = utils.find_object(base_object, doc=App.activeDocument())
96
    if not found:
97
        _err(translate("draft","Wrong input: base_object not in document."))
98
        return None
99

100
    try:
101
        utils.type_check([(number, int)], name=_name)
102
    except TypeError:
103
        _err(translate("draft","Wrong input: must be an integer number."))
104
        return None
105

106
    try:
107
        utils.type_check([(angle, (int, float))], name=_name)
108
    except TypeError:
109
        _err(translate("draft","Wrong input: must be a number."))
110
        return None
111

112
    try:
113
        utils.type_check([(center, App.Vector)], name=_name)
114
    except TypeError:
115
        _err(translate("draft","Wrong input: must be a vector."))
116
        return None
117

118
    use_link = bool(use_link)
119
    new_obj = make_array.make_array(base_object,
120
                                    arg1=center, arg2=angle, arg3=number,
121
                                    use_link=use_link)
122
    return new_obj
123

124
## @}
125