]> git.mxchange.org Git - flightgear.git/blob - src/FDM/JSBSim/FGForce.h
Connect the FlightGear /environment/turbulence-norm property to the
[flightgear.git] / src / FDM / JSBSim / FGForce.h
1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3  Header:       FGForce.h
4  Author:       Tony Peden
5  Date started: 5/20/00
6
7  ------------- Copyright (C) 1999  Anthony K. Peden (apeden@earthlink.net) -------------
8
9  This program is free software; you can redistribute it and/or modify it under
10  the terms of the GNU General Public License as published by the Free Software
11  Foundation; either version 2 of the License, or (at your option) any later
12  version.
13
14  This program is distributed in the hope that it will be useful, but WITHOUT
15  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
17  details.
18
19  You should have received a copy of the GNU General Public License along with
20  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21  Place - Suite 330, Boston, MA  02111-1307, USA.
22
23  Further information about the GNU General Public License can also be found on
24  the world wide web at http://www.gnu.org.
25
26
27  HISTORY
28 --------------------------------------------------------------------------------
29 5/20/00  TP   Created
30
31
32 FUNCTIONAL DESCRIPTION
33 --------------------------------------------------------------------------------
34
35 The purpose of this class is to provide storage for computed forces and
36 encapsulate all the functionality associated with transforming those
37 forces from their native coord system to the body system.  This includes
38 computing the moments due to the difference between the point of application
39 and the cg.
40
41 CAVEAT:  if the custom transform is used for wind-to-body transforms then the
42          user *must* always pass this class the negative of beta. This is true
43          because sideslip angle does not follow the right hand rule i.e. it is
44          positive for aircraft nose left sideslip.  Note that use of the custom
45          transform for this purpose shouldn't be necessary as it is already
46          provided by SetTransform(tWindBody) and is not subject to the same
47          restriction.
48
49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
50 SENTRY
51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
52
53 #ifndef FGFORCE_H
54 #define FGFORCE_H
55
56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57 INCLUDES
58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
59
60 #define ID_FORCE "$Id$"
61
62 #include "FGFDMExec.h"
63 #include "FGJSBBase.h"
64 #include "FGMatrix33.h"
65 #include "FGColumnVector3.h"
66 #include "FGColumnVector4.h"
67
68 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 COMMENTS, REFERENCES, and NOTES [use "class documentation" below for API docs]
70 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
71
72 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
73 CLASS DOCUMENTATION
74 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
75
76 /** Utility class that aids in the conversion of forces between coordinate systems
77     and calculation of moments.
78 <br><h3>Resolution of Applied Forces into Moments and Body Axes Components</h3>
79 <br><p>
80 All forces acting on the aircraft that cannot be considered a change in weight
81 need to be resolved into body axis components so that the aircraft acceleration
82 vectors, both translational and rotational, can be computed. Furthermore, the
83 moments produced by each force that does not act at a location corresponding to
84 the center of gravity also need to be computed. Unfortunately, the math required
85 to do this can be a bit messy and errors are easily introduced so the class
86 FGForce was created to provide these services in a consistent and reusable
87 manner.<br><br></p>
88
89 <h4>Basic usage</h4>
90
91 <p>FGForce requires that its users supply it with the location of the applied
92 force vector in JSBSim structural coordinates, the sense of each axis in that
93 coordinate system relative to the body system, the orientation of the vector
94 also relative to body coordinates and, of course, the force vector itself. With
95 this information it will compute both the body axis force components and the
96 resulting moments. Any moments inherently produced by the native system can be
97 supplied as well and they will be summed with those computed.</p>
98
99 <p>A good example for demonstrating the use of this class are the aerodynamic
100 forces: lift, drag, and side force and the aerodynamic moments about the pitch,
101 roll and yaw axes. These "native" forces and moments are computed and stored
102 in the FGColumnVector objects vFs and vMoments. Their native coordinate system
103 is often referred to as the wind system and is defined as a right-handed system
104 having its x-axis aligned with the relative velocity vector and pointing towards
105 the rear of the aircraft , the y-axis extending out the right wing, and the
106 z-axis directed upwards. This is different than body axes; they are defined such
107 that the x-axis is lies on the aircraft's roll axis and positive forward, the
108 y-axis is positive out the right wing, and the z-axis is positive downwards. In
109 this instance, JSBSim already provides the needed transform and FGForce can make
110 use of it by calling SetTransformType() once an object is created:</p>
111
112 <p><tt>FGForce fgf(FDMExec);</tt><br>
113 <tt>fgf.SetTransformType(tWindBody);</tt><br><br>
114
115 This call need only be made once for each object. The available transforms are
116 defined in the enumerated type TransformType and are tWindBody, tLocalBody,
117 tCustom, and tNone. The local-to-body transform, like the wind-to-body, also
118 makes use of that already available in JSBSim. tNone sets FGForce to do no
119 angular transform at all, and tCustom allows for modeling force vectors at
120 arbitrary angles relative to the body system such as that produced by propulsion
121 systems. Setting up and using a custom transform is covered in more detail below.
122 Continuing with the example, the point of application of the aerodynamic forces,
123 the aerodynamic reference point in JSBSim, also needs to be set:</p>
124 <p><tt>
125 fgf.SetLocation(x, y, z)</tt></p>
126
127 <p>where x, y, and z are in JSBSim structural coordinates.</p>
128
129 <p>Initialization is complete and the FGForce object is ready to do its job. As
130 stated above, the lift, drag, and side force are computed and stored in the
131 vector vFs and need to be passed to FGForce:</p>
132
133 <p><tt>fgf.SetNativeForces(vFs);</tt> </p>
134
135 <p>The same applies to the aerodynamic pitching, rolling and yawing moments:</p>
136
137 <p><tt>fgf.SetNativeMoments(vMoments);</tt></p>
138
139 <p>Note that storing the native forces and moments outside of this class is not
140 strictly necessary, overloaded SetNativeForces() and SetNativeMoments() methods
141 which each accept three doubles (rather than a vector) are provided and can be
142 repeatedly called without incurring undue overhead. The body axes force vector
143 can now be retrieved by calling:</p>
144
145 <p><tt>vFb=fgf.GetBodyForces();</tt></p>
146
147 <p>This method is where the bulk of the work gets done so calling it more than
148 once for the same set of native forces and moments should probably be avoided.
149 Note that the moment calculations are done here as well so they should not be
150 retrieved after calling the GetBodyForces() method:</p>
151
152 <p><tt>vM=fgf.GetMoments();</tt> </p>
153
154 <p>As an aside, the native moments are not needed to perform the computations
155 correctly so, if the FGForce object is not being used to store them then an
156 alternate approach is to avoid the SetNativeMoments call and perform the sum</p>
157
158 <p><tt>vMoments+=fgf.GetMoments();</tt> <br><br>
159
160 after the forces have been retrieved. </p>
161
162 <h4>Use of the Custom Transform Type</h4>
163
164 <p>In cases where the native force vector is not aligned with the body, wind, or
165 local coordinate systems a custom transform type is provided. A vectorable engine
166 nozzle will be used to demonstrate its usage. Initialization is much the same:</p>
167
168 <p><tt>FGForce fgf(FDMExec);</tt> <br>
169 <tt>fgf.SetTransformType(tCustom);</tt> <br>
170 <tt>fgf.SetLocation(x,y,z);</tt> </p>
171
172 <p>Except that here the tCustom transform type is specified and the location of
173 the thrust vector is used rather than the aerodynamic reference point. Thrust is
174 typically considered to be positive when directed aft while the body x-axis is
175 positive forward and, if the native system is right handed, the z-axis will be
176 reversed as well. These differences in sense need to be specified using by the
177 call: </p>
178
179 <p><tt>fgf.SetSense(-1,1,-1);</tt></p>
180
181 <p>The angles are specified by calling the method: </p>
182
183 <p><tt>fgf.SetAnglesToBody(pitch, roll, yaw);</tt> </p>
184
185 <p>in which the transform matrix is computed. Note that these angles should be
186 taken relative to the body system and not the local as the names might suggest.
187 For an aircraft with vectorable thrust, this method will need to be called
188 every time the nozzle angle changes, a fixed engine/nozzle installation, on the
189 other hand, will require it to be be called only once.</p>
190
191 <p>Retrieval of the computed forces and moments is done as detailed above.</p>
192 <br>
193 <blockquote>
194     <p><i>CAVEAT: If the custom system is used to compute
195     the wind-to-body transform, then the sign of the sideslip
196     angle must be reversed when calling SetAnglesToBody().
197     This is true because sideslip angle does not follow the right
198     hand rule. Using the custom transform type this way
199     should not be necessary, as it is already provided as a built
200     in type (and the sign differences are correctly accounted for).</i>
201     <br></p>
202 </blockquote>
203
204 <h4>Use as a Base Type</h4>
205
206 <p>For use as a base type, the native force and moment vector data members are
207 defined as protected. In this case the SetNativeForces() and SetNativeMoments()
208 methods need not be used and, instead, the assignments to vFn, the force vector,
209 and vMn, the moments, can be made directly. Otherwise, the usage is similar.<br>
210 <br><br></p>
211
212     @author Tony Peden
213     @version $Id$
214 */
215
216 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
217 CLASS DECLARATION
218 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
219
220 namespace JSBSim {
221
222 class FGForce : public FGJSBBase
223 {
224 public:
225   /// Constructor
226   FGForce(FGFDMExec *FDMExec);
227   /// Destructor
228   ~FGForce();
229
230   enum TransformType { tNone, tWindBody, tLocalBody, tCustom } ttype;
231
232   inline void SetNativeForces(double Fnx, double Fny, double Fnz) {
233     vFn(1)=Fnx;
234     vFn(2)=Fny;
235     vFn(3)=Fnz;
236   }
237   inline void SetNativeForces(FGColumnVector3 vv) { vFn = vv; };
238
239   inline void SetNativeMoments(double Ln,double Mn, double Nn) {
240     vMn(1)=Ln;
241     vMn(2)=Mn;
242     vMn(3)=Nn;
243   }
244   inline void SetNativeMoments(FGColumnVector3 vv) { vMn = vv; }
245
246   inline FGColumnVector3& GetNativeForces(void) { return vFn; }
247   inline FGColumnVector3& GetNativeMoments(void) { return vMn; }
248
249   FGColumnVector3& GetBodyForces(void);
250
251   inline FGColumnVector3& GetMoments(void) { return vM; }
252
253   // Normal point of application, JSBsim structural coords
254   // (inches, x +back, y +right, z +up)
255   inline void SetLocation(double x, double y, double z) {
256     vXYZn(eX) = x;
257     vXYZn(eY) = y;
258     vXYZn(eZ) = z;
259     SetActingLocation(x, y, z);
260   }
261   
262   /** Acting point of application.
263       JSBsim structural coords used (inches, x +back, y +right, z +up).
264       This function sets the point at which the force acts - this may
265       not be the same as where the object resides. One area where this
266       is true is P-Factor modeling.
267       @param x acting location of force
268       @param y acting location of force
269       @param z acting location of force    */
270   inline void SetActingLocation(double x, double y, double z) {
271     vActingXYZn(eX) = x;
272     vActingXYZn(eY) = y;
273     vActingXYZn(eZ) = z;
274   }
275   inline void SetLocationX(double x) {vXYZn(eX) = x; vActingXYZn(eX) = x;}
276   inline void SetLocationY(double y) {vXYZn(eY) = y; vActingXYZn(eY) = y;}
277   inline void SetLocationZ(double z) {vXYZn(eZ) = z; vActingXYZn(eZ) = z;}
278   inline double SetActingLocationX(double x) {vActingXYZn(eX) = x; return x;}
279   inline double SetActingLocationY(double y) {vActingXYZn(eY) = y; return y;}
280   inline double SetActingLocationZ(double z) {vActingXYZn(eZ) = z; return z;}
281   inline void SetLocation(FGColumnVector3 vv) { vXYZn = vv; SetActingLocation(vv);}
282   inline void SetActingLocation(FGColumnVector3 vv) { vActingXYZn = vv; }
283   
284   inline double GetLocationX( void ) { return vXYZn(eX);}
285   inline double GetLocationY( void ) { return vXYZn(eY);}
286   inline double GetLocationZ( void ) { return vXYZn(eZ);}
287   inline double GetActingLocationX( void ) { return vActingXYZn(eX);}
288   inline double GetActingLocationY( void ) { return vActingXYZn(eY);}
289   inline double GetActingLocationZ( void ) { return vActingXYZn(eZ);}
290   FGColumnVector3& GetLocation(void) { return vXYZn; }
291   FGColumnVector3& GetActingLocation(void) { return vActingXYZn; }
292
293   //these angles are relative to body axes, not earth!!!!!
294   //I'm using these because pitch, roll, and yaw are easy to visualize,
295   //there's no equivalent to roll in wind axes i.e. alpha, ? , beta
296   //making up new names or using these is a toss-up: either way people
297   //are going to get confused.
298   //They are in radians.
299
300   void SetAnglesToBody(double broll, double bpitch, double byaw);
301   inline void  SetAnglesToBody(FGColumnVector3 vv) {
302     SetAnglesToBody(vv(eRoll), vv(ePitch), vv(eYaw));
303   }
304
305   inline void SetSense(double x, double y, double z) { vSense(eX)=x, vSense(eY)=y, vSense(eZ)=z; }
306   inline void SetSense(FGColumnVector3 vv) { vSense=vv; }
307
308   inline FGColumnVector3& GetSense(void) { return vSense; }
309
310   inline void SetTransformType(TransformType ii) { ttype=ii; }
311   inline TransformType GetTransformType(void) { return ttype; }
312
313   FGMatrix33 Transform(void);
314
315 protected:
316   FGFDMExec *fdmex;
317   FGColumnVector3 vFn;
318   FGColumnVector3 vMn;
319   FGColumnVector3 vH;
320   
321 private:
322   FGColumnVector3 vFb;
323   FGColumnVector3 vM;
324   FGColumnVector3 vXYZn;
325   FGColumnVector3 vActingXYZn;
326   FGColumnVector3 vDXYZ;
327   FGColumnVector3 vSense;
328
329   FGMatrix33 mT;
330
331   virtual void Debug(int from);
332 };
333 }
334 #endif
335