1Spline
2======
3
4.. module:: ezdxf.entities
5    :noindex:
6
7SPLINE curve (`DXF Reference`_), all coordinates have to be 3D coordinates even
8the spline is only a 2D planar curve.
9
10The spline curve is defined by control points, knot values and weights. The
11control points establish the spline, the various types of knot vector determines
12the shape of the curve and the weights of rational splines define how
13strong a control point influences the shape.
14
15To create a :class:`Spline` curve you just need a bunch of fit points - knot
16values and weights are optional (tested with AutoCAD 2010). If you add
17additional data, be sure that you know what you do.
18
19.. versionadded:: 0.16
20
21    The function :func:`ezdxf.math.fit_points_to_cad_cv` calculates control
22    vertices from given fit points. This control vertices define a cubic
23    B-spline which matches visually the SPLINE entities created by BricsCAD and
24    AutoCAD from fit points.
25
26.. seealso::
27
28    - `Wikipedia`_ article about B_splines
29    - Department of Computer Science and Technology at the `Cambridge`_ University
30    - :ref:`tut_spline`
31
32
33======================== ==========================================
34Subclass of              :class:`ezdxf.entities.DXFGraphic`
35DXF type                 ``'SPLINE'``
36Factory function         see table below
37Inherited DXF attributes :ref:`Common graphical DXF attributes`
38Required DXF version     DXF R2000 (``'AC1015'``)
39======================== ==========================================
40
41Factory Functions
42-----------------
43
44=========================================== ==========================================
45Basic spline entity                         :meth:`~ezdxf.layouts.BaseLayout.add_spline`
46Spline control frame from fit points        :meth:`~ezdxf.layouts.BaseLayout.add_spline_control_frame`
47Open uniform spline                         :meth:`~ezdxf.layouts.BaseLayout.add_open_spline`
48Closed uniform spline                       :meth:`~ezdxf.layouts.BaseLayout.add_closed_spline`
49Open rational uniform spline                :meth:`~ezdxf.layouts.BaseLayout.add_rational_spline`
50Closed rational uniform spline              :meth:`~ezdxf.layouts.BaseLayout.add_closed_rational_spline`
51=========================================== ==========================================
52
53.. _DXF Reference: http://help.autodesk.com/view/OARX/2018/ENU/?guid=GUID-E1F884F8-AA90-4864-A215-3182D47A9C74
54
55.. class:: Spline
56
57    All points in :ref:`WCS` as (x, y, z) tuples
58
59    .. attribute:: dxf.degree
60
61        Degree of the spline curve (int).
62
63    .. attribute:: dxf.flags
64
65        Bit coded option flags, constants defined in :mod:`ezdxf.lldxf.const`:
66
67        =================== ======= ===========
68        dxf.flags           Value   Description
69        =================== ======= ===========
70        CLOSED_SPLINE       1       Spline is closed
71        PERIODIC_SPLINE     2
72        RATIONAL_SPLINE     4
73        PLANAR_SPLINE       8
74        LINEAR_SPLINE       16      planar bit is also set
75        =================== ======= ===========
76
77    .. attribute:: dxf.n_knots
78
79        Count of knot values (int), automatically set by `ezdxf` (read only)
80
81    .. attribute:: dxf.n_fit_points
82
83        Count of fit points (int), automatically set by ezdxf (read only)
84
85    .. attribute:: dxf.n_control_points
86
87        Count of control points (int), automatically set by ezdxf (read only)
88
89    .. attribute:: dxf.knot_tolerance
90
91        Knot tolerance (float); default = ``1e-10``
92
93    .. attribute:: dxf.fit_tolerance
94
95        Fit tolerance (float); default = ``1e-10``
96
97    .. attribute:: dxf.control_point_tolerance
98
99        Control point tolerance (float); default = ``1e-10``
100
101    .. attribute:: dxf.start_tangent
102
103        Start tangent vector as (3D vector in :ref:`WCS`)
104
105    .. attribute:: dxf.end_tangent
106
107        End tangent vector as (3D vector in :ref:`WCS`)
108
109    .. autoattribute:: closed
110
111    .. autoattribute:: control_points
112
113    .. autoattribute:: fit_points
114
115    .. autoattribute:: knots
116
117    .. autoattribute:: weights
118
119    .. automethod:: control_point_count
120
121    .. automethod:: fit_point_count
122
123    .. automethod:: knot_count
124
125    .. automethod:: construction_tool() -> BSpline
126
127    .. automethod:: apply_construction_tool(s: BSpline) -> Spline
128
129    .. automethod:: flattening(distance: float, segments: int = 4) -> Iterable[Vec3]
130
131    .. automethod:: set_open_uniform
132
133    .. automethod:: set_uniform
134
135    .. automethod:: set_closed
136
137    .. automethod:: set_open_rational
138
139    .. automethod:: set_uniform_rational
140
141    .. automethod:: set_closed_rational
142
143    .. automethod:: transform(m: Matrix44) -> Spline
144
145    .. automethod:: from_arc(entity: DXFGraphic) -> Spline
146
147.. _Cambridge: https://www.cl.cam.ac.uk/teaching/2000/AGraphHCI/SMEG/node4.html
148
149.. _Wikipedia: https://en.wikipedia.org/wiki/Spline_%28mathematics%29
150