57d06a3ba32a46f95b220f23e7db5979d01d23ea
[blender.git] / intern / iksolver / extern / IK_solver.h
1 /**
2  * $Id$
3  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License
7  * as published by the Free Software Foundation; either version 2
8  * of the License, or (at your option) any later version. The Blender
9  * Foundation also sells licenses for use in proprietary software under
10  * the Blender License.  See http://www.blender.org/BL/ for information
11  * about this.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
21  *
22  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
23  * All rights reserved.
24  *
25  * The Original Code is: all of this file.
26  *
27  * Contributor(s): none yet.
28  *
29  * ***** END GPL/BL DUAL LICENSE BLOCK *****
30  */
31
32 /**
33
34  * $Id$
35  * Copyright (C) 2001 NaN Technologies B.V.
36  *
37  * @author Laurence
38  * @mainpage IK - Blender inverse kinematics module.
39  *
40  * @section about About the IK module
41  *
42  * This module allows you to create segments and form them into 
43  * chains. You can then define a goal point that the end of the 
44  * chain should attempt to reach - an inverse kinematic problem.
45  * This module will then modify the segments in the chain in
46  * order to get the end of the chain as near as possible to the 
47  * goal. This solver uses an inverse jacobian method to find
48  * a solution.
49  * 
50  * @section issues Known issues with this IK solver.
51  *
52  * - The current solver works with only one type of segment. These
53  * segments always have 3 degress of freedom (DOF). i.e. the solver
54  * uses all these degrees to solve the IK problem. It would be 
55  * nice to allow the user to specify different segment types such
56  * as 1 DOF joints in a given plane. 2 DOF joints about given axis.
57  * - There is currently no support for joint constraints in the
58  * solver. This is within the realms of possibility - please ask
59  * if this functionality is required.
60  * - The solver is slow, inverse jacobian methods in general give
61  * 'smooth' solutions and the method is also very flexible, it 
62  * does not rely on specific angle parameterization and can be 
63  * extended to deal with different joint types and joint 
64  * constraints. However it is not suitable for real time use. 
65  * Other algorithms exist which are more suitable for real-time
66  * applications, please ask if this functionality is required.     
67  * 
68  * @section dependencies Dependencies
69  * 
70  * This module only depends on Moto.
71  */
72
73 #ifndef NAN_INCLUDED_IK_solver_h
74 #define NAN_INCLUDED_IK_solver_h
75
76
77
78
79 #ifdef __cplusplus
80 extern "C" {
81 #endif
82
83 /** 
84  * External segment structure
85  */
86
87
88 /**
89  * This structure defines a single segment of an IK chain. 
90  * - Individual segments are always defined in local coordinates.
91  * - The segment is assumed to be oriented in  the local 
92  * y-direction.
93  * - seg_start is the start of the segment relative to the end 
94  * of the parent segment.
95  * - basis is a column major matrix defining the rest position 
96  * of the bone.
97  * - length is the simply the length of the bone.  
98  * - basis_change is a 3x3 matrix representing the change 
99  * from the rest position of the segment to the solved position.
100  * In fact it is the transpose of this matrix because blender 
101  * does something weird with quaternion conversion. This is 
102  * strictly an ouput variable for returning the results of an
103  * an ik solve back to you.
104  * The local transformation specified as a column major matrix 
105  * of a segment is then defined as.
106  * translate(seg_start)*basis*transpose(basis_change)*translate(0,length,0) 
107  */
108
109 typedef struct IK_Segment_Extern {
110         float seg_start[3];
111         float basis[9];
112         float length;
113         float basis_change[9];
114 } IK_Segment_Extern;
115
116 typedef IK_Segment_Extern* IK_Segment_ExternPtr; 
117
118 /** 
119  * External chain structure.
120  * This structure is filled when you call IK_LoadChain.
121  * The first segment in the chain is the root segment.
122  * The end of the last segment is the end-effector of the chain 
123  * this is the point that tries to move to the goal in the ik 
124  * solver. 
125  * - num_segments is the number of segments in the array pointed
126  * to by the member segments.
127  * - chain_dof is the number of degrees of freedom of the chain
128  * that is the number of independent ways the chain can be changed
129  * to reach the goal. 
130  * - segments points to an array of IK_Segment_Extern structs
131  * containing the segments of this chain. 
132  * - intern is pointer used by the module to store information
133  * about the chain. Please do not touch the member in any way.   
134  */
135
136 typedef struct IK_Chain_Extern {
137         int num_segments;
138         int chain_dof;
139         IK_Segment_ExternPtr segments;
140         void * intern;
141 } IK_Chain_Extern; 
142
143 typedef IK_Chain_Extern* IK_Chain_ExternPtr;
144
145
146 /**
147  * Create a clean chain structure. 
148  * @return A IK_Chain_Extern structure allocated on the heap.
149  * Do not attempt to delete or free this memory yourself please 
150  * use the FreeChain(...) function for this.
151  */
152
153 extern IK_Chain_ExternPtr IK_CreateChain(void);
154
155 /**
156  * Copy segment information into the chain structure.
157  * @param chain A chain to load the segments into.
158  * @param segments a ptr to an array of IK_Input_Segment_Extern structures
159  * @param num_segs the number of segments to load into the chain
160  * @return 1 if the chain was correctly loaded into the structure. 
161  * @return 0 if an error occured loading the chain. This will normally
162  * occur when there is not enough memory to allocate internal chain data.
163  * In this case you should not use the chain structure and should call
164  * IK_FreeChain to free the memory associated with the chain.
165  */
166
167 extern int IK_LoadChain(IK_Chain_ExternPtr chain,IK_Segment_ExternPtr segments, int num_segs);
168
169 /**
170  * Compute the solution of an inverse kinematic problem.
171  * @param chain a ptr to an IK_Segment_Extern loaded with the segments
172  * to solve for.
173  * @param goal the goal of the IK problem
174  * @param tolerance .The distance to the solution within which the chain is deemed 
175  * to be solved.
176  * @param max_iterations. The maximum number of iterations to use in solving the 
177  * problem. 
178  * @param max_angle_change. The maximum allowed angular change. 0.1 is a good value here.
179  * @param output. Results of the solution are written to the segments pointed to by output.
180  * Only the basis and basis_change fields are written. You must make sure that you have
181  * allocated enough room for the output segments.
182  * @return 0 if the solved chain did not reach the goal. This occurs when the
183  * goal was unreachable by the chain end effector.
184  * @return 1 if the chain reached the goal.
185  */ 
186
187 extern int IK_SolveChain(
188         IK_Chain_ExternPtr chain,
189         float goal[3],
190         float tolerance,
191         int max_iterations,
192         float max_angle_change, 
193         IK_Segment_ExternPtr output
194 );
195
196 /** 
197  * Free a chain and all it's internal memory.
198  */
199
200 extern void IK_FreeChain(IK_Chain_ExternPtr);
201
202
203 #ifdef __cplusplus
204 }
205 #endif
206
207 #endif // NAN_INCLUDED_IK_solver_h