2 * $Id: IK_solver.h 5229 2005-08-31 22:09:44Z blendix $
3 * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
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
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.
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.
22 * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
23 * All rights reserved.
25 * The Original Code is: all of this file.
27 * Original author: Laurence
28 * Contributor(s): Brecht
30 * ***** END GPL/BL DUAL LICENSE BLOCK *****
35 * $Id: IK_solver.h 5229 2005-08-31 22:09:44Z blendix $
36 * Copyright (C) 2001 NaN Technologies B.V.
38 * @author Laurence, Brecht
39 * @mainpage IK - Blender inverse kinematics module.
41 * @section about About the IK module
43 * This module allows you to create segments and form them into
44 * tree. You can then define a goal points that the end of a given
45 * segment should attempt to reach - an inverse kinematic problem.
46 * This module will then modify the segments in the tree in order
47 * to get the as near as possible to the goal. This solver uses an
48 * inverse jacobian method to find a solution.
50 * @section issues Known issues with this IK solver.
52 * - There is currently no support for joint constraints in the
53 * solver. This is within the realms of possibility - please ask
54 * if this functionality is required.
55 * - The solver is slow, inverse jacobian methods in general give
56 * 'smooth' solutions and the method is also very flexible, it
57 * does not rely on specific angle parameterization and can be
58 * extended to deal with different joint types and joint
59 * constraints. However it is not suitable for real time use.
60 * Other algorithms exist which are more suitable for real-time
61 * applications, please ask if this functionality is required.
63 * @section dependencies Dependencies
65 * This module only depends on Moto.
68 #ifndef NAN_INCLUDED_IK_solver_h
69 #define NAN_INCLUDED_IK_solver_h
76 * Typical order of calls for solving an IK problem:
78 * - create number of IK_Segment's and set their parents and transforms
79 * - create an IK_Solver
80 * - set a number of goals for the IK_Solver to solve
82 * - free the IK_Solver
83 * - get basis and translation changes from segments
88 * IK_Segment defines a single segment of an IK tree.
89 * - Individual segments are always defined in local coordinates.
90 * - The segment is assumed to be oriented in the local
92 * - start is the start of the segment relative to the end
93 * of the parent segment.
94 * - rest_basis is a column major matrix defineding the rest
95 * position (w.r.t. which the limits are defined), must
97 * - basis is a column major matrix defining the current change
98 * from the rest basis, must be a pure rotation
99 * - length is the length of the bone.
101 * - basis_change and translation_change respectively define
102 * the change in rotation or translation. basis_change is a
103 * column major 3x3 matrix.
105 * The local transformation is then defined as:
106 * start * rest_basis * basis * basis_change * translation_change * translate(0,length,0)
110 typedef void IK_Segment
;
112 enum IK_SegmentFlag
{
121 typedef enum IK_SegmentAxis
{
130 extern IK_Segment
*IK_CreateSegment(int flag
);
131 extern void IK_FreeSegment(IK_Segment
*seg
);
133 extern void IK_SetParent(IK_Segment
*seg
, IK_Segment
*parent
);
134 extern void IK_SetTransform(IK_Segment
*seg
, float start
[3], float rest_basis
[][3], float basis
[][3], float length
);
135 extern void IK_SetLimit(IK_Segment
*seg
, IK_SegmentAxis axis
, float lmin
, float lmax
);
136 extern void IK_SetStiffness(IK_Segment
*seg
, IK_SegmentAxis axis
, float stiffness
);
138 extern void IK_GetBasisChange(IK_Segment
*seg
, float basis_change
[][3]);
139 extern void IK_GetTranslationChange(IK_Segment
*seg
, float *translation_change
);
142 * An IK_Solver must be created to be able to execute the solver.
144 * An arbitray number of goals can be created, stating that a given
145 * end effector must have a given position or rotation. If multiple
146 * goals are specified, they can be weighted (range 0..1) to get
147 * some control over their importance.
149 * IK_Solve will execute the solver, that will run until either the
150 * system converges, or a maximum number of iterations is reached.
151 * It returns 1 if the system converged, 0 otherwise.
154 typedef void IK_Solver
;
156 IK_Solver
*IK_CreateSolver(IK_Segment
*root
);
157 void IK_FreeSolver(IK_Solver
*solver
);
159 void IK_SolverAddGoal(IK_Solver
*solver
, IK_Segment
*tip
, float goal
[3], float weight
);
160 void IK_SolverAddGoalOrientation(IK_Solver
*solver
, IK_Segment
*tip
, float goal
[][3], float weight
);
162 int IK_Solve(IK_Solver
*solver
, float tolerance
, int max_iterations
);
169 #endif // NAN_INCLUDED_IK_solver_h