Curve Fitting: expose function for fitting a single curve
[blender-staging.git] / extern / curve_fit_nd / curve_fit_nd.h
1 /*
2  * Copyright (c) 2016, DWANGO Co., Ltd.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of the <organization> nor the
13  *       names of its contributors may be used to endorse or promote products
14  *       derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27
28 #ifndef __SPLINE_FIT__
29 #define __SPLINE_FIT__
30
31 /** \file curve_fit_nd.h
32  *  \ingroup curve_fit
33  */
34
35
36 /* curve_fit_cubic.c */
37
38 /**
39  * Takes a flat array of points and evalues that to calculate a bezier spline.
40  *
41  * \param points, points_len: The array of points to calculate a cubics from.
42  * \param dims: The number of dimensions for for each element in \a points.
43  * \param error_threshold: the error threshold to allow for,
44  * the curve will be within this distance from \a points.
45  * \param corners, corners_len: indices for points which will not have aligned tangents (optional).
46  * This can use the output of #curve_fit_corners_detect_db which has been included
47  * to evaluate a line to detect corner indices.
48  *
49  * \param r_cubic_array, r_cubic_array_len: Resulting array of tangents and knots, formatted as follows:
50  * ``r_cubic_array[r_cubic_array_len][3][dims]``,
51  * where each point has 0 and 2 for the tangents and the middle index 1 for the knot.
52  * The size of the *flat* array will be ``r_cubic_array_len * 3 * dims``.
53  * \param r_corner_index_array, r_corner_index_len: Corner indices in in \a r_cubic_array (optional).
54  * This allows you to access corners on the resulting curve.
55  *
56  * \returns zero on success, nonzero is reserved for error values.
57  */
58 int curve_fit_cubic_to_points_db(
59         const double       *points,
60         const unsigned int  points_len,
61         const unsigned int  dims,
62         const double        error_threshold,
63         const unsigned int *corners,
64         unsigned int        corners_len,
65
66         double **r_cubic_array, unsigned int *r_cubic_array_len,
67         unsigned int **r_cubic_orig_index,
68         unsigned int **r_corner_index_array, unsigned int *r_corner_index_len);
69
70 int curve_fit_cubic_to_points_fl(
71         const float        *points,
72         const unsigned int  points_len,
73         const unsigned int  dims,
74         const float         error_threshold,
75         const unsigned int *corners,
76         const unsigned int  corners_len,
77
78         float **r_cubic_array, unsigned int *r_cubic_array_len,
79         unsigned int **r_cubic_orig_index,
80         unsigned int **r_corners_index_array, unsigned int *r_corners_index_len);
81
82 /**
83  * Takes a flat array of points and evalues that to calculate handle lengths.
84  *
85  * \param points, points_len: The array of points to calculate a cubics from.
86  * \param dims: The number of dimensions for for each element in \a points.
87  * \param error_threshold: the error threshold to allow for,
88  * \param tan_l, tan_r: Normalized tangents the handles will be aligned to.
89  * Note that tangents must both point along the direction of the \a points,
90  * so \a tan_l points in the same direction of the resulting handle,
91  * where \a tan_r will point the opposite direction of its handle.
92  *
93  * \param r_handle_l, r_handle_r: Resulting calculated handles.
94  * \param r_error_sq: The maximum distance  (squared) this curve diverges from \a points.
95  */
96 int curve_fit_cubic_to_points_single_db(
97         const double *points,
98         const uint    points_len,
99         const uint    dims,
100         const double  error_threshold,
101         const double tan_l[],
102         const double tan_r[],
103
104         double  r_handle_l[],
105         double  r_handle_r[],
106         double *r_error_sq);
107
108 int curve_fit_cubic_to_points_single_fl(
109         const float  *points,
110         const uint    points_len,
111         const uint    dims,
112         const float   error_threshold,
113         const float   tan_l[],
114         const float   tan_r[],
115
116         float   r_handle_l[],
117         float   r_handle_r[],
118         float  *r_error_sq);
119
120 /* curve_fit_corners_detect.c */
121
122 /**
123  * A helper function that takes a line and outputs its corner indices.
124  *
125  * \param points, points_len: Curve to evaluate.
126  * \param dims: The number of dimensions for for each element in \a points.
127  * \param radius_min: Corners on the curve between points below this radius are ignored.
128  * \param radius_max: Corners on the curve above this radius are ignored.
129  * \param samples_max: Prevent testing corners beyond this many points
130  * (prevents a large radius taking excessive time to compute).
131  * \param angle_threshold: Angles above this value are considered corners
132  * (higher value for fewer corners).
133  *
134  * \param r_corners, r_corners_len: Resulting array of corners.
135  *
136  * \returns zero on success, nonzero is reserved for error values.
137  */
138 int curve_fit_corners_detect_db(
139         const double      *points,
140         const unsigned int points_len,
141         const unsigned int dims,
142         const double       radius_min,
143         const double       radius_max,
144         const unsigned int samples_max,
145         const double       angle_threshold,
146
147         unsigned int **r_corners,
148         unsigned int  *r_corners_len);
149
150 int curve_fit_corners_detect_fl(
151         const float       *points,
152         const unsigned int points_len,
153         const unsigned int dims,
154         const float        radius_min,
155         const float        radius_max,
156         const unsigned int samples_max,
157         const float        angle_threshold,
158
159         unsigned int **r_corners,
160         unsigned int  *r_corners_len);
161
162 #endif  /* __SPLINE_FIT__ */