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 circular Array objects."""
24
## @package make_circulararray
25
# \ingroup draftmake
26
# \brief Provides functions to create circular Array objects.
27

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

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

37

38
def make_circular_array(base_object,
39
                        r_distance=100, tan_distance=50,
40
                        number=3, symmetry=1,
41
                        axis=App.Vector(0, 0, 1), center=App.Vector(0, 0, 0),
42
                        use_link=True):
43
    """Create a circular array from the given object.
44

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

54
    r_distance: float, optional
55
        It defaults to `100`.
56
        Radial distance to the next ring of circular arrays.
57

58
    tan_distance: float, optional
59
        It defaults to `50`.
60
        The tangential distance between two elements located
61
        in the same circular ring.
62
        The tangential distance together with the radial distance
63
        determine how many copies are created.
64

65
    number: int, optional
66
        It defaults to 3.
67
        The number of layers or rings of repeated objects.
68
        The original object stays at the center, and is counted
69
        as a layer itself. So, if you want at least one layer of circular
70
        copies, this number must be at least 2.
71

72
    symmetry: int, optional
73
        It defaults to 1.
74
        It indicates how many lines of symmetry the entire circular pattern
75
        has. That is, with 1, the array is symmetric only after a full
76
        360 degrees rotation.
77

78
        When it is 2, the array is symmetric at 0 and 180 degrees.
79
        When it is 3, the array is symmetric at 0, 120, and 240 degrees.
80
        When it is 4, the array is symmetric at 0, 90, 180, and 270 degrees.
81
        Et cetera.
82

83
    axis: Base::Vector3, optional
84
        It defaults to `App.Vector(0, 0, 1)` or the `+Z` axis.
85
        The unit vector indicating the axis of rotation.
86

87
    center: Base::Vector3, optional
88
        It defaults to `App.Vector(0, 0, 0)` or the global origin.
89
        The point through which the `axis` passes to define
90
        the axis of rotation.
91

92
    use_link: bool, optional
93
        It defaults to `True`.
94
        If it is `True` the produced copies are not `Part::TopoShape` copies,
95
        but rather `App::Link` objects.
96
        The Links repeat the shape of the original `base_object` exactly,
97
        and therefore the resulting array is more memory efficient.
98

99
        Also, when `use_link` is `True`, the `Fuse` property
100
        of the resulting array does not work; the array doesn't
101
        contain separate shapes, it only has the original shape repeated
102
        many times, so there is nothing to fuse together.
103

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

108
    Returns
109
    -------
110
    Part::FeaturePython
111
        A scripted object of type `'Array'`.
112
        Its `Shape` is a compound of the copies of the original object.
113

114
    None
115
        If there is a problem it will return `None`.
116

117
    See Also
118
    --------
119
    make_ortho_array, make_polar_array, make_path_array, make_point_array
120
    """
121
    _name = "make_circular_array"
122

123
    found, base_object = utils.find_object(base_object, doc=App.activeDocument())
124
    if not found:
125
        _err(translate("draft","Wrong input: base_object not in document."))
126
        return None
127

128
    try:
129
        utils.type_check([(r_distance, (int, float, App.Units.Quantity)),
130
                          (tan_distance, (int, float, App.Units.Quantity))],
131
                         name=_name)
132
    except TypeError:
133
        _err(translate("draft","Wrong input: must be a number or quantity."))
134
        return None
135

136
    try:
137
        utils.type_check([(number, int),
138
                          (symmetry, int)], name=_name)
139
    except TypeError:
140
        _err(translate("draft","Wrong input: must be an integer number."))
141
        return None
142

143
    try:
144
        utils.type_check([(axis, App.Vector),
145
                          (center, App.Vector)], name=_name)
146
    except TypeError:
147
        _err(translate("draft","Wrong input: must be a vector."))
148
        return None
149

150
    use_link = bool(use_link)
151

152
    new_obj = make_array.make_array(base_object,
153
                                    arg1=r_distance, arg2=tan_distance,
154
                                    arg3=axis, arg4=center,
155
                                    arg5=number, arg6=symmetry,
156
                                    use_link=use_link)
157
    return new_obj
158

159
## @}
160