—— Vector3 ]; — ts [0 — onst s n t e n n e c mp o nts( compon ents[1]; o C t i). ; e . n ] p r o S 2 e [ / p = s h / t le ¡ – com ponent g . r — n e a — oth r.com — 0 ¡= — e e — g h ot ran 0). —— ){ , s n — = a ¿ na —— r3 & q q (radi i s — e to — d (); ecaus h t —— nst Vec this an g n pi (b e L o y c n 2] M e 0 to [ le( etwee (q); t s . t e e n c r .G one spa p gle botVecto tor(q)) ; //rang e D l m ng c (co in 3 s r b o //A – = D rossVe a, cosa) a f ect = v ¡ C — n ( i s ) i s ] — th — { po a = atan2( ts[0 o t n — m e o r t n c s( po —— l()cons dicula b a= a m — f o ; n ¡= —— Norma perpe bs(c nts[1]) ) ] a f 1 — fa; [ && mpone ents —— bitrary that is ) n ] — o 1 ts[ ], -co mp n o —— rateAr vector e c ( n 2 — s [ po nents — ne unit fab s[0]); m e o G & c : o bs( comp ) & onent ] or3: bitrary a f 0 [ s r ent , comp ) ¡= ts(0.0, ] n 0 o [ an amm; s p nt en om [2], 0.0 c ( ); s or3 ompone ompon 0 s b . t a 0 f n , e C c ¡= ontypeset s[0] ) p t ] abs( mm.Set Professionally n 1 m [ e on p ents ents(-colevel. n Advanced m o -co mp mpon , ] o c 1 al [ ( s s t o m b r n Hundreds of live crossreferences C a o e on if(f m.Set p e aryN s m l r nt t e o e m i c n b ( o r Live Index s eA mp ent t o n a c r o . e p en mTable - uu o Live of Contents G ] C } / 1 t / [ Se – nts e — n else{ mm.Live Bibliography o p —— nst{ m (); o t — i c n eU Internet links —— uu)co ents[0], rM Live — e } .Mak ; —— ctor3 & ompon perato m — m — code m urn mLive C++ .c //o – Ve documentation u — t u s — t — re — r-(con ts[0] — — — n Professional C++ code included o — —— perat pone — — m o — } —— ctor3:: or3(co —— — — t e — c // or3 V rn Ve —— t — ro c u e — Z Ve e ret { —— Zero() eM k — a //M – —— akeMe 0.0; st{ uu — n * o = } — ] — c M — [0] 3:: .0; ts[1 com —— 3 & uu) n e — //— Vector ponents [1] = 0 .0; n — ctor po s[1] * s d — 0 m t i m o n e o o v c —— onst V + c onent one ts[2] = ] p — 0 [ m — tor(c ts comp co ponen n — e n po s[0] + —— ossVec tor c com m e — o c V t oss —— ubleCr u). uu. ponen r * — C ] e ubl ——or3::Do e X u nents[0 ] * com o } — D / m t — o 0
RIGID BODY KINEMATICS AND C++ CODE
Sergio Pissanetzky
Rigid Body Kinematics and C++ Code
Sergio Pissanetzky
2005
c 2005 by Sergio Pissanetzky and SciControls.com. All rights reserved. No Copyright part of the contents of this book can be reproduced without the written permission of the publisher. Professionally typeset by LATEX. This work is in compliance with the mathematical typesetting conventions established by the International Organization for Standardization (ISO). Dr. Pissanetzky retired after a rewarding career as an Entrepreneur, Professor, Research Scientist and Consultant. He was the founder of Magnus Software Corporation, where he focused on development of specialized applications for the Magnetic Resonance Imaging (MRI) and the High Energy Particle Accelerator industries. He has served as Member of the International Editorial Board of the “International Journal for Computation in Electrical and Electronic Engineering”, as a Member of the International Advisory Committee of the International Journal “M´etodos Num´ericos para C´alculo y Dise˜ no en Ingenier´ıa”, and as a member of the International Committee for Nuclear Resonance Spectroscopy, Tokyo, Japan. Dr. Pissanetzky has held professorships in Physics at Texas A&M University and the Universities of Buenos Aires, C´ordoba and Cuyo, Argentina. He has also held positions as a Research Scientist with the Houston Advanced Research Center, as Chairman of the Computer Center of the Atomic Energy Commission, San Carlos de Bariloche, Argentina, and as a Scientific Consultant at Brookhaven National Laboratory. Dr. Pissanetzky is currently a member of the Advisory Board of Meedio, LLC. Dr. Pissanetzky holds several US and European patents and is the author of two books and numerous peer reviewed technical papers. Dr. Pissanetzky earned his Ph.D. in Physics at the Balseiro Institute, University of Cuyo, in 1965. Dr. Pissanetzky has 35 years of teaching experience and 30 years of programming experience in languages such as Fortran, Basic, C and C++. Dr. Pissanetzky now lives in a quite suburban neighborhood in Texas. Website: http://www.SciControls.com
Trademark Notices R R R Microsoft , Windows and Visual C++ are registered trademarks of Microsoft Corporation. TM TM Java and Sun are trademarks of Sun Microsystems, Inc. R UNIX is a registered trade mark licensed through X/Open Company, Ltd. R R R PostScript , PDF and Acrobat Reader are registered trademarks of Adobe Systems, Inc. TM Merriam-Webster is a trademark of Merriam-Webster, Inc. VAXTM is a trademark of Digital Equipment Corporation. Other product and company names mentioned herein may be the trademarks of their respective owners. ISBN 0-9762775-1-4
iv
Contents Preface Highlights . . . . . . . Introductory Remarks Instructions . . . . . . Acknowledgments . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
xi . xi . xi . xiv . xv
Part I. Theory
1
1 Matrices used in Kinematics 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Matrices for Rigid Body Kinematics . . . . . . . . . . . . . 1.2.1 Symmetric and Positive Definite Matrices . . . . . . 1.2.2 The Rank of a Matrix . . . . . . . . . . . . . . . . . 1.2.3 Diagonally Dominant Matrices . . . . . . . . . . . . 1.2.4 Orthogonal Matrices . . . . . . . . . . . . . . . . . . 1.2.5 Diagonal Matrices . . . . . . . . . . . . . . . . . . . 1.3 Matrices in 3 Dimensions . . . . . . . . . . . . . . . . . . . 1.3.1 3 X 3 Skew-Symmetric Matrices . . . . . . . . . . . 1.3.2 The Orientation Matrix . . . . . . . . . . . . . . . . 1.3.3 Rotating a Vector Around an Axis . . . . . . . . . . 1.3.4 Orientation Matrix for a Rotated Coordinate System 2 Graphs and Coordinate Systems 2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Basic Notions of Graph Theory . . . . . . . . . . . . . . . . 2.2.1 Breadth-first Search and Adjacency Level Structures 2.3 The Coordinate System Graph . . . . . . . . . . . . . . . . 2.4 Coordinate Transformations . . . . . . . . . . . . . . . . . . 2.5 Interpolating Orientations . . . . . . . . . . . . . . . . . . . 2.6 Spherical Coordinates and Direction . . . . . . . . . . . . .
v
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . .
3 . 3 . 3 . 3 . 5 . 5 . 6 . 7 . 8 . 8 . 10 . 12 . 14
. . . . . . .
17 17 18 21 23 25 27 28
. . . . . . .
vi 2.7
The Bodies and Constraints Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3 The 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9
Kinematic State Tensors and Form Invariance of the Laws of Physics The Kinematic State and the State Variables . . . . Position and Velocity . . . . . . . . . . . . . . . . . . Differentiating the Orientation Matrix . . . . . . . . Angular Velocity . . . . . . . . . . . . . . . . . . . . Specific Coordinates . . . . . . . . . . . . . . . . . . Specific Coordinates and State Variables . . . . . . . Specific Coordinates and the Equations of Motion . Specific Coordinates and Constraints . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
31 31 32 33 34 36 39 40 42 46
4 The 4.1 4.2 4.3 4.4 4.5
Rigid Body Model Propagation in the Coordinate System Graph Addition of Kinematic States . . . . . . . . . Direct Subtraction of Kinematic States . . . . Transposed Subtraction of Kinematic States . Inversion of Kinematic States . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
49 51 51 53 54 55
. . . . . . . . . . . .
57 57 57 58 61 64 64 65 66 68 69 69 70
5 Orientation Coordinates 5.1 Euler Angles . . . . . . . . . . . . . . . . . . 5.1.1 Conventions . . . . . . . . . . . . . . . 5.1.2 The ZXZ Convention . . . . . . . . . . 5.1.3 The ZYX Convention . . . . . . . . . 5.1.4 Dealing with Convention Singularities 5.2 Euler Parameters . . . . . . . . . . . . . . . . 5.2.1 Orientation Matrix . . . . . . . . . . . 5.2.2 Angular Velocity . . . . . . . . . . . . 5.3 Axial Rotator . . . . . . . . . . . . . . . . . . 5.3.1 Orientation Matrix . . . . . . . . . . . 5.3.2 Angular Velocity . . . . . . . . . . . . 5.4 Implementation . . . . . . . . . . . . . . . . . Part II. Code Documentation
. . . . .
. . . . . . . . . . . .
. . . . .
. . . . . . . . . . . .
. . . . .
. . . . . . . . . . . .
. . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
71
6 C++ Code for Rigid Body Kinematics 73 6.1 All Families . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 6.2 All Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 7 Family of Classes: Specific Coordinates
77
vii 7.1 7.2
All Specific Coordinates Classes . . . . . . . Class AxialRotator . . . . . . . . . . . . . . 7.2.1 AxialRotator Attribute Detail . . . . 7.2.2 AxialRotator Constructor Detail . . 7.2.3 AxialRotator Method Detail . . . . 7.3 Class EulerAngles . . . . . . . . . . . . . . 7.3.1 EulerAngles Attribute Detail . . . . 7.3.2 EulerAngles Constructor Detail . . . 7.3.3 EulerAngles Method Detail . . . . . 7.4 Class EulerAnglesZXZ . . . . . . . . . . . . 7.4.1 EulerAnglesZXZ Constructor Detail 7.4.2 EulerAnglesZXZ Method Detail . . . 7.5 Class EulerAnglesZYX . . . . . . . . . . . . 7.5.1 EulerAnglesZYX Constructor Detail 7.5.2 EulerAnglesZYX Method Detail . . 7.6 Class EulerParams . . . . . . . . . . . . . . 7.6.1 EulerParams Constructor Detail . . 7.6.2 EulerParams Method Detail . . . . . 7.7 Class Orientator . . . . . . . . . . . . . . . 7.7.1 Orientator Attribute Detail . . . . . 7.7.2 Orientator Constructor Detail . . . . 7.7.3 Orientator Method Detail . . . . . . 7.8 Class Translator . . . . . . . . . . . . . . . 7.8.1 Translator Attribute Detail . . . . . 7.8.2 Translator Constructor Detail . . . . 7.8.3 Translator Method Detail . . . . . . 7.9 Class TranslatorXYZ . . . . . . . . . . . . . 7.9.1 TranslatorXYZ Constructor Detail . 7.9.2 TranslatorXYZ Method Detail . . . 7.10 Class OrthoMatrix . . . . . . . . . . . . . . 7.10.1 OrthoMatrix Constructor Detail . . 7.10.2 OrthoMatrix Method Detail . . . . . 8 Family of Classes: Graphs 8.1 All Graphs Classes . . . . . . . . . . . . . 8.2 Class BCComponent . . . . . . . . . . . . 8.2.1 BCComponent Constructor Detail 8.2.2 BCComponent Method Detail . . . 8.3 Class BCEdge . . . . . . . . . . . . . . . . 8.3.1 BCEdge Attribute Detail . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
78 78 81 81 82 90 92 93 94 102 104 106 113 115 117 124 127 127 137 140 140 141 150 152 152 153 156 157 157 159 163 166
. . . . . .
179 . 179 . 180 . 181 . 182 . 182 . 183
viii
8.4
8.5
8.6
8.7
8.8
8.9
8.10
8.11
8.12
8.13
8.3.2 BCEdge Constructor Detail . . . . . . . . 8.3.3 BCEdge Method Detail . . . . . . . . . . Class BCGraph . . . . . . . . . . . . . . . . . . . 8.4.1 BCGraph Attribute Detail . . . . . . . . . 8.4.2 BCGraph Constructor Detail . . . . . . . 8.4.3 BCGraph Method Detail . . . . . . . . . Class BCVertex . . . . . . . . . . . . . . . . . . . 8.5.1 BCVertex Attribute Detail . . . . . . . . 8.5.2 BCVertex Constructor Detail . . . . . . . 8.5.3 BCVertex Method Detail . . . . . . . . . Class CSEdge . . . . . . . . . . . . . . . . . . . . 8.6.1 CSEdge Attribute Detail . . . . . . . . . 8.6.2 CSEdge Constructor Detail . . . . . . . . 8.6.3 CSEdge Method Detail . . . . . . . . . . Class CSGraph . . . . . . . . . . . . . . . . . . . 8.7.1 CSGraph Attribute Detail . . . . . . . . . 8.7.2 CSGraph Constructor Detail . . . . . . . 8.7.3 CSGraph Method Detail . . . . . . . . . . Class CSState . . . . . . . . . . . . . . . . . . . . 8.8.1 CSState Attribute Detail . . . . . . . . . 8.8.2 CSState Constructor Detail . . . . . . . . 8.8.3 CSState Method Detail . . . . . . . . . . Class CSVector . . . . . . . . . . . . . . . . . . . 8.9.1 CSVector Attribute Detail . . . . . . . . . 8.9.2 CSVector Constructor Detail . . . . . . . 8.9.3 CSVector Method Detail . . . . . . . . . . Class CSVertex . . . . . . . . . . . . . . . . . . . 8.10.1 CSVertex Attribute Detail . . . . . . . . . 8.10.2 CSVertex Constructor Detail . . . . . . . 8.10.3 CSVertex Method Detail . . . . . . . . . . Class PComponent . . . . . . . . . . . . . . . . . 8.11.1 PComponent Attribute Detail . . . . . . . 8.11.2 PComponent Constructor Detail . . . . . 8.11.3 PComponent Method Detail . . . . . . . Class PComponentWithTree . . . . . . . . . . . . 8.12.1 PComponentWithTree Attribute Detail . 8.12.2 PComponentWithTree Constructor Detail 8.12.3 PComponentWithTree Method Detail . . Class PEdge . . . . . . . . . . . . . . . . . . . . . 8.13.1 PEdge Attribute Detail . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
184 184 186 188 188 189 191 192 192 193 194 198 199 200 211 212 213 213 215 219 220 220 234 237 237 239 251 252 252 252 253 255 256 256 260 263 265 266 271 273
ix 8.13.2 PEdge Constructor Detail . . . . 8.13.3 PEdge Method Detail . . . . . . Class PGraph . . . . . . . . . . . . . . . 8.14.1 PGraph Attribute Detail . . . . 8.14.2 PGraph Constructor Detail . . . 8.14.3 PGraph Method Detail . . . . . Class PPath . . . . . . . . . . . . . . . . 8.15.1 PPath Attribute Detail . . . . . 8.15.2 PPath Constructor Detail . . . . 8.15.3 PPath Method Detail . . . . . . Class PPathClosed . . . . . . . . . . . . 8.16.1 PPathClosed Constructor Detail 8.16.2 PPathClosed Method Detail . . . Class PPathOpen . . . . . . . . . . . . . 8.17.1 PPathOpen Constructor Detail . 8.17.2 PPathOpen Method Detail . . . Class PVertex . . . . . . . . . . . . . . . 8.18.1 PVertex Attribute Detail . . . . 8.18.2 PVertex Constructor Detail . . . 8.18.3 PVertex Method Detail . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
274 275 277 280 281 282 289 291 291 292 298 300 300 304 306 307 313 314 315 316
9 Family of Classes: Mechanical 9.1 All Mechanical Classes . . . . . . . . . . 9.2 Class Body . . . . . . . . . . . . . . . . 9.2.1 Body Attribute Detail . . . . . . 9.2.2 Body Constructor Detail . . . . . 9.2.3 Body Method Detail . . . . . . . 9.3 Class BodyManager . . . . . . . . . . . 9.3.1 BodyManager Attribute Detail . 9.3.2 BodyManager Constructor Detail 9.3.3 BodyManager Method Detail . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
319 319 319 324 327 327 337 339 339 340
8.14
8.15
8.16
8.17
8.18
Bibliography and Index
345
x
Preface Highlights What makes this book more attractive than others? • The fact that this work is a textbook containing an in-depth presentation of the principles of Rigid Body Kinematics. • The fact that this work is a software release with fully documented source code. • The fact that the logical objects in the theory are implemented as logical objects in the code. • The use of a mathematical graph to organize multiple coordinate systems (2.3) and their corresponding kinematic states (3.2). • The introduction of kinematic state operations such as addition, subtraction and inversion (4.2). • The concept of propagation of mechanical information in the graph (4.1). • The concept of specific coordinates and the role they play as a mediator between state variables and generalized coordinates (3.6). • The handling of the quadratic velocity vector (3.8). • The direct links from methods and equations in the theory to the code where they are implemented. • The direct links from code documentation to the theory that supports the code. • The fact that this work suggests a new standard for the use of logical objects in teaching Science.
Introductory Remarks This work is a textbook containing an in-depth presentation of the principles of Rigid Body Kinematics at an advanced College level. This work is also a software release with fully documented object-oriented source code and logical objects that correspond to those in the theory and implement them. The work provides a novel approach where theoretical Classical Mechanics is integrated with the actual code that supports the computation and brings the logical objects to life. The theory is covered in Part I, which consists of 5 chapters. The first two chapters introduce the required mathematical tools. Chapter 1 covers matrices and matrix properties and opera-
xi
xii tions specific to rigid body kinematics, such as symmetric positive-definite matrices, orthogonal matrices, the orientation matrix, and skew-symmetric matrices and their relation to vectors and cross-products. Chapter 2 discusses the use of graphs for organizing the many coordinate systems used in mechanical problems involving multi-body systems. Subjects covered include graph theory, coordinate transformations, the interpolation of orientations, and the definitions of the Coordinate System graph and the Bodies and Constraints graph. The concept of kinematic state and the definitions of the state variables position, orientation, velocity, and angular velocity, are introduced in Chapter 3. The discussion includes topics such as the definition of angular velocity by differentiation of the orientation matrix, and the definition of the specific coordinates as an intermediary agent between the state variables and the generalized coordinates. Mathematical expressions that relate the specific coordinates with the state variables, the equations of motion, and the constraint equations, and the quadratic velocity vector, are discussed in detail. Chapter 4 introduces the rigid body model and its extension to multi-body systems. The operations of addition, direct and transposed subtraction, and inversion of kinematic states are introduced. The final chapter on theory, Chapter 5, introduces various systems of orientational specific coordinates used in kinematics. Covered are Euler angles, including conventions and singularities, Euler parameters, and an axial rotator system. The presentation includes the mathematical relations between the state variables and the specific coordinates of each particular system. Part I, the theory, contains many direct links from final equations or mathematical methods to the code where those equations and methods have been implemented. Since the presence of the links may become a hindrance for a reader who is focused on learning the theory but has no plans to refer to the code just yet, we have used minimally intrusive, easy to ignore links that look like C++ , and if clicked will take the reader directly to the relevant part. These are a smart links, they know where to go, they are unimposing, and they allow the reader to easily expand into code when the need arises. The reader must be aware that there may be more than one implementation of a mathematical equation or method, such as overloaded versions, versions that use different arguments, overriden methods in derived classes, “Get” or “Set” methods, etc. The smart links point to the general area where the implementations are, or, in the case of derived classes, they point to the base class. Some of the links may point to classes described in previous volumes of this series. Part II of the book consists of 4 chapters and covers the documentation for the C++ foundational implementation of rigid body kinematics. The logical objects defined by the classes implement all the major equations and methods discussed in the theory. There are a total of 28 classes, including classes for specific coordinates, graphs, and mechanics. The foundational implementation is general and extensible. It provides support for all major features and allows extensions such as derived classes with new functionality to be added as necessary. The code is optimized for efficiency, but
xiii not at the expense of generality. Production implementations derived from the foundational code will typically optimize the code for the features they need, at the expense of generality. Part II, code documentation, contains numerous links to supporting theory, equations and definitions. Code documentation relies very heavily on the theory and contains a very large number of references. If all those references were colored or underlined, they would be too distracting. For this reason, silent links have been used in Part II. These links are undistinguishable from regular text, and therefore cause no distraction. They can be identified only by hovering the cursor over the text of interest. There are so many silent links, that chances are the link will be there when needed. Some of the silent links point to classes described in previous volumes of this series. C++ names used in text are always clearly marked to distinguish them from ordinary words. For example, Body designates a C++ class that represents a body. The word “body” is used in the ordinary sense, while Body designates a class or an object of that class. There is no representation here that C++ is the language of choice for object-oriented programming. The main reason that C++ was chosen for this work is that the author is an experienced C++ programmer. Other good object-oriented languages exist, but were not considered. C++, of course, is a powerful programming language and it does offer all the features needed to write a powerful foundational package. The designers of C++ have made an exceptionally good job, and very few mistakes. One of them was upholding the C convention for 0-based arrays. Constructs such as arrays, vectors, matrices and tensors have been used for centuries and the practice of using 1based indices is well established. Countless generations of students have been educated in that understanding. The makers of C++ have ignored the practice, making C++ look somewhat like a machine-oriented language, not a high-level user-oriented language. Java has followed suit. The consequences will haunt us for years to come. Another popular and powerful object-oriented language is Java. It would be easy to translate our C++ code into Java. The main difficulty for automating the conversion of C++ code to Java is that C++ programmers frequently use non-object-oriented features such as global variables or system functions. The code presented here does not, and should be easy to convert. We do not have plans to do the conversion, however. Object Logic is a method for modeling reality, for abstracting the complexities of the real world into simpler, more manageable entities, the Logical Objects. Thought, then, proceeds in terms of the logical objects. Humans think in terms of objects. Animals do too. They associate properties and behavior. Birds are not afraid of passing traffic, but if a person came along on the highway, the birds would fly away. They know that a passing “car” will not “harm” them. They can tell the car from the person by their properties, and they associate the behavior because they know the object. Object methodology helps to organize objects - and thoughts. When used systematically and with
xiv wisdom, it can help objects and thoughts to fall into their right places, even reconcile differences between seeming incompatibilities and offer a direction for thinking. One may envisage to apply these concepts to areas of human knowledge other than science, perhaps a legal system, a government system, an organizational chart, a company. The results may teach us a few things. It will all happen, but the task isn’t easy. The laws of Physics are already written in terms of logical objects, although this fact is not consistently acknowledged in the literature. The fact may be attributable more to the creativity and intellectual ability of the authors than to the systematic use of object methodology. The situation is somewhat similar to what happened with tensors: the laws of Physics were written in terms of tensors even before the concept of tensor was introduced. The introduction of tensors did not add to the science, but it helped to organize it. And, indirectly, also to teach it. Similarly, object methodology will not add to the science, but it will help again to organize it and to teach it. The use of logic objects in science would also simplify the ever more important interface between science and computation. It would become possible to create permanent, multi-use computational objects of general application. The current trend, unfortunately, is to create objects specific to each application, and such objects are seldom capable of communicating with each other. The impact of object methodologies in Computer Science has been impressive. As computers and software engineers alike became more powerful, programs became more and more compliant with object logic. Just think of the Windows operating system and how it has evolved in the last decade, from Windows 3.1 to Windows XP. Now, an icon, a file, the desktop, a network connection, just about anything, is a logical object with properties and behavior. The subject is too vast even to comment on it. Mathematicians and computer scientists have turned object methodologies into a science. It is time to start applying this science.
Instructions The Rigid Body Kinematics software that accompanies this eBook is free. It consists of 45 C++ files (extensions .cpp, .h). If you have purchased this product in the form of a compressed file (extension .zip), the eBook itself and the source code files are all in the compressed file. If you have purchased the eBook alone (extension .pdf), then you will need to download the file RigidBodyKinematicsCode.zip, which contains all the C++ files. In either case, you will also need to download the file VectorMatrix.zip, which contains 29 C++ files corresponding to the first volume of this series, “Vectors, Matrices, and C++ Code.” The download is free as well. You can use WinZip to unpack the compressed files. Copy the eBook and the C++ files to the directory or directories of your choice.
xv The Internet page on frequently asked questions contains the latest information about this eBook and the corresponding code, including problems encountered after release. This page is a valuable resource, and it is maintained and updated as needed. The method ASSERT has been extensively used in code. This method works only with the Microsoft Visual Studio C++ compiler, and only when compiling a debug version. ASSERT evaluates a logical condition and stops execution at that line of code if the condition is false, or does nothing if it is true. When compiling a release version, the compiler ignores all ASSERT . You can leave all ASSERT if you are using the Microsoft compiler for debugging code, or you can edit them out if you are using a different compiler or are not interested in debugging. This eBook is Volume 2 of this series, and contains links to Volume 1 “Vectors, Matrices and C++ Code.” Many of these links point to a course on C++ contained in “Vectors, Matrices and C++ Code.” The course contains many C++ concepts and definitions, very useful for readers who are not entirely familiar with C++. In order to make these links operational, please locate the pdf file for “Vectors, Matrices and C++ Code,” copy it to the same directory where this eBook is stored, and rename it as “VectorsMatrices.pdf.” To test click test. You should see the cover of “Vectors, Matrices and C++ Code.”
Acknowledgments The light shines from [13] and [14]. My way is resplendent.
xvi
Part I Theory
1
2
Chapter 1 Matrices used in Kinematics 1.1
Introduction
Vectors and matrices are very powerful tools for analysis, and they have evolved and became more and more specialized for each particular application. This is also true for Kinematics, particularly in the case of Rigid Body Kinematics. This chapter covers properties and definitions for general matrices, and then proceeds to the detailed description of some specialized 3-vectors and 3 × 3 matrices used in Kinematics, and the coordinate systems used for the kinematic description of multibody systems. Defined in this chapter are the position vector, the orientation matrix, and the velocity and angular velocity of a rigid coordinate system with respect to another.
1.2
Matrices for Rigid Body Kinematics
The properties of symmetry, diagonal dominance, positive definiteness and orthogonality are important in Matrix Analysis because so many powerful theorems rely on such properties. They are also important in computation because they allow for better algorithms and better and more efficient code to be devised. Many matrices that appear in Rigid Body Kinematics are known by construction to have one of more of those properties. we turn our attention to such matrices must be acknowledged and preserved computational objects that acknowledge, implement and preserve the props We first examine some general definitions and properties of matrices applicable in any n-dimensional space. After, that, we will concentrate in our familiar 3-D space.
1.2.1
Symmetric and Positive Definite Matrices
A square matrix A is symmetric when A T = A, where T means transpose, i.e. when Aij = Aji for all i, j. Otherwise, A is unsymmetric . A square matrix W is skew-symmetric when A T = − A,
3
4
CHAPTER 1. MATRICES USED IN KINEMATICS
i.e. when Aij = −Aji for all i, j. This means that all diagonal elements of a skew-symmetric matrix are zero: Aii = 0 for all i. Some authors use the term alternating to designate this type of matrix. A symmetric matrix A is said to be positive definite when y TA y > 0
(1.1)
for any vector y having at least one nonvanishing component. If two vectors y and z can be found for which y T A y > 0,
z TA z < 0
(1.2)
then A is said to be indefinite or nondefinite. Symmetry and positive definiteness are important in computation. It is worth examining these properties in more detail. A summary of properties follows. 1. If matrices A and B are symmetric positive definite, A + B is also symmetric positive definite. This is a useful property because frequently a large matrix is obtained as the sum of smaller ones, which are known to be positive definite. Besides, it is difficult to check positive definiteness for a large matrix, but usually not so for the small ones. 2. A symmetric positive definite matrix of order n has n eigenvalues which are all real positive numbers. 3. The determinant of a symmetric positive definite matrix is positive. 4. A minor is a submatrix obtained by deleting some rows and some columns from a given matrix. A principal minor is obtained when the set of deleted rows and the set of deleted columns are identical. If A is symmetric positive definite, any principal minor is also symmetric positive definite and has therefore a positive determinant. In particular, the diagonal elements of A are all positive: Aii > 0
for all
i
(1.3)
5. Let A be symmetric positive definite, and consider the determinant D of any 2 × 2 principal minor, which by property 4 must be positive: D=
Aii Aij
Aij Ajj
= Aii Ajj − A2ij > 0
(1.4)
Thus |Aij | < (Aii Ajj )1/2 ≤ max(Aii , Ajj )
(1.5)
In particular, if a is the value of the largest diagonal element of A, no element of A may exceed a in absolute value: |Aij | ≤ a
for all
i, j
(1.6)
1.2. MATRICES FOR RIGID BODY KINEMATICS
5
6. A necessary and sufficient condition for a symmetric matrix A of order n to be positive definite is that the determinants of the n leading principal minors of A be positive. [8] 7. If A is symmetric positive definite, a unique Cholesky factorization A = UTU
(1.7)
exists where U is upper triangular with positive diagonal elements. [10] Besides, U can be written U = D0 U0 , where D0 is diagonal with positive diagonal elements and U0 is upper triangular with unit diagonal. Thus: A = U0 T D U0
(1.8)
where D = D0 2 , is also a unique triangular factorization of A [11]. 8. If C is any matrix, either square or rectangular, then A = C T C is symmetric non-negative definite. A is clearly symmetric. To show that A is non-negative definite, consider any non-null vector x of the appropriate length. Then x T A x = x T C T C x = (Cx) T (C x) ≥ 0. Besides, if the columns of C are linearly independent, then C x 6= 0 and A is positive definite. 9. When A is indefinite, the triangular factorization may not exist, and a singular A may have an infinite number of factorizations. [8] 10. The problem of determining whether a given A is positive definite seldom arises in practice. One usually knows that A is symmetric positive definite by construction, frequently by Properties 1, 8 and 9. That fact is taken advantage of by using Property 2 or Property 7. The remaining properties have great theoretical value but limited practical application.
1.2.2
The Rank of a Matrix
The rank r of any matrix A is the order of the largest square submatrix which has a nonvanishing determinant. A matrix of order n is singular when r < n. The quantity n − r is the nullity or rank deficiency of the matrix. A symmetric positive definite matrix has rank r = n and is said to be a full rank matrix. A matrix of rank 1 has necessarily the form x y T , with x, y any non-null column vectors, because every row of the matrix is a multiple of y T and every column is a multiple of x.
1.2.3
Diagonally Dominant Matrices
The matrix A is diagonally dominant when |Aii | ≥
X j6=i
|Aij |
(1.9)
6
CHAPTER 1. MATRICES USED IN KINEMATICS
for all i, with inequality for at least one i. A is properly diagonally dominant when |Aii | >
X
|Aij |
(1.10)
j6=i
for all i. It is possible to show that if A is properly diagonally dominant and all its diagonal elements are positive, i.e., if Aii >
X
|Aij |
(1.11)
j6=i
for all i, then all the eigenvalues of A are positive and A is positive definite. The simple proof is based on a theorem due to Gerschgorin [12].
1.2.4
Orthogonal Matrices
By definition, a nonsingular square matrix R is said to be orthogonal if its transpose is equal to its inverse C++ R T = R −1
(1.12)
RRT = RT R = I
(1.13)
or
where I is the identity matrix. An orthogonal matrix is usually obtained by construction rather than by testing an existing matrix for orthogonality. When an orthogonal matrix is used as part of matrix multiplications or other operations which result in another matrix, it is important to determine whether the operations preserve the orthogonality or not. Orthogonal matrices have very useful properties, and therefore, if a matrix is orthogonal, it is important to keep track of that fact. For example, the operations of transposition, change sign and multiplication of two orthogonal matrices result in an orthogonal matrix. The multiplication of an orthogonal matrix by a number does not. If A is symmetric positive definite and R is orthogonal, then B = R T A R is also symmetric positive definite. An orthogonal matrix is always nonsingular. A singular matrix does not have an inverse and can not be orthogonal.. If R is an orthogonal matrix of order n, define the n row vectors ri as the rows of R, and the n column vectors cj as the columns of R. Equation 1.13 can now be written ri T rj = δij
(1.14)
for all i, j, where δij is the Kronecker delta. This means that the set of n vectors ri constitutes an orthonormal base for the n-space. The second part of equation 1.13 can also be written ci T cj = δij
(1.15)
1.2. MATRICES FOR RIGID BODY KINEMATICS
7
for all i, j. This means that the set of n vectors cj also constitutes an orthonormal base of the n-space. Orthogonal matrices are closely associated with coordinate systems and the transformations between them. An orthogonal matrix can be used to define the orientation of one coordinate system with respect to another, and vice versa. The same orthogonal matrix also defines the coordinate transformations between the two systems. This is the subject of Section 1.3.2. We have covered properties and definitions for matrices in an n-dimensional space. We will now turn our attention to 3 × 3 matrices defined in our familiar 3-dimensional space.
1.2.5
Diagonal Matrices
A matrix is said to be diagonal when it is square and all its off-diagonal elements are zero. In other words, the n × n matrix D is diagonal if: if i 6= j
dij = 0
(1.16)
An n × n diagonal matrix has only n independent elements d11 , . . . , dnn , the same number as an n × 1 column vector. We can, therefore, convert a diagonal matrix into a column vector, and vice versa. We use the hat mathematical accent b to denote the conversion operation. In other words, if D is an n × n diagonal matrix: d11 0 · · · 0 d22 D= . .. .. . 0
0
0 0 0 dnn
0
(1.17)
b is an n × 1 column vector given by: then D b = [d11 , d22 , . . . , dnn ] T D
(1.18)
Conversely, if v is an n × 1 column vector given by: v = [v1 , v2 , . . . , vn ] T
(1.19)
then vb is an n × n diagonal matrix given by: v1 0 · · · 0 0 v2 0 vb = . . .. .. 0 0 0 0 vn
(1.20)
If D is an n × n diagonal matrix and v is an n × 1 column vector, then the following permutation relation applies: D
v
n×n
n×1
=
vb
b D
n×n
n×1
(1.21)
8
CHAPTER 1. MATRICES USED IN KINEMATICS
This relation can be proved by inspection. It allows D and v to be permuted, and it is useful for organizing equations. Examples of application can be found in section 3.8.
1.3 1.3.1
Matrices in 3 Dimensions 3 X 3 Skew-Symmetric Matrices
As defined in section 1.2.1, a square matrix W is said to be skew-symmetric if it satisfies Wij = −Wji for all i, j. This in turn means that all the diagonal elements are zero: Wii = 0 for all i. The most general 3 × 3 skew-symmetric matrix can be written as follows: 0 −w3 w2 W = w3 0 −w1 −w2 w1 0
(1.22)
Matrix W has only 3 independent elements, w1 , w2 and w3 , the same as the number of components of a three-dimensional vector. We can use the independent elements of W to define the following 3 × 1 column vector: w = (w1 , w2 , w3 ) T
(1.23)
The object w can indeed be proved to be a vector. 1 Conversely, given a 3 × 1 column vector w, as in equation 1.23, a 3 × 3 skew-symmetric matrix can be defined, such as the one in equation 1.22. There is a complete equivalence between the vector and the skew-symmetric matrix. We use the tilde mathematical accent e to indicate the operation that converts the matrix into the vector, and also the operation that converts the vector into the matrix. In other words, if w is a 3 × 1 column vector given by equation 1.23, then: e= w
0 −w3 w2 w3 0 −w1 −w2 w1 0
(1.24)
And, conversely, if W is a 3 × 3 skew-symmetric matrix given by equation 1.22 then: f = (w1 , w2 , w3 ) T W 1
(1.25)
The object w is actually a pseudovector. However, within our scope, there is no distinction between a vector and a pseudovector because we use only cartesian orthogonal right-handed coordinate systems. The proof that w is a pseudovector entails three steps: (1) define w from W as before, with both W and w expressed in the same coordinate system, say S; (2) convert both W and w to another coordinate system, say W0 and w0 in system S0 ; and (3) verify that w0 is obtained from W0 in the same way that w was obtained from W. The proof is necessary because vectors, pseudovectors and matrices used in Kinematics are all tensors.
1.3. MATRICES IN 3 DIMENSIONS
9
The equivalence (column vector ⇐⇒ skew-symmetric matrix) can be advantageously exploited to convert cross products and some forms of dot products to matrix notation. Consider an arbitrary vector b: b = (bx , by , bz ) T
(1.26)
e b, where w e is given in equation 1.24: and let us calculate the product of w
w2 bz − w3 by bx by = w3 bx − w1 bz w1 by − w2 bx bz
0 −w3 w2 e b = w3 w 0 −w1 −w2 w1 0
(1.27)
By simple examination, the components of the resulting column vector can be verified to be exactly the same as the components of the cross-product w × b. Thus: eb w×b=w
(1.28)
This equation expresses the conversion between the classic notation of the cross product and the e as given in equation 1.24 and let us corresponding matrix notation. Consider now matrix w calculate its square: e2 w
w1 2 − 1 w1 w2 w1 w3 = w1 w2 w2 2 − 1 w2 w3 w1 w3 w2 w3 w3 2 − 1
(1.29)
Compare this with the product w w T : wwT
w1 w1 2 w1 w2 w1 w3 = w2 [w1 w2 w3 ] = w1 w2 w2 2 w2 w3 w3 w1 w3 w2 w3 w3 2
(1.30)
By examination we obtain: e2+I ww T = w
(1.31)
where I is the 3 × 3 identity matrix. Let now b be an arbitrary vector, and consider the expression:
e2+I b (w · b)w = w w T b = w
(1.32)
This equation converts one form of dot product from traditional vector notation to matrix notation, where vector b appears as a factor by itself, separated from the rest of the equation. Notation conversions such as 1.28 and 1.32 are very useful in Kinematics because they allow a quantity of interest to be isolated or separated from the rest of the equation. Many calculations in Rigid Body Kinematics rely on the equivalence between a vector and a skew-symmetric matrix and the corresponding conversions. An important example is the definition of angular velocity, see section 3.5.
10
1.3.2
CHAPTER 1. MATRICES USED IN KINEMATICS
The Orientation Matrix
In three dimensions we will always use a unique coordinate system called the global coordinate system, which is cartesian, orthogonal and right-handed, and has a basis of three mutually perpendicular unit vectors. Everything else is referred to the global system. The global system is assumed to be inertial, but this is of no consequence here because we are only concerned with kinematics, not dynamics. We may refer to the global system as G(x, y, z), where G is the origin and x, y and z are the axes, and to the unit vectors as i, j and k, or as x, y and z. We will also use many other coordinate systems, all right-handed, cartesian and orthogonal but generally not coincident with the global system, and each with a basis of three mutually perpendicular unit vectors. Such systems are used for a variety of purposes, for example we can attach a rigid body to one of them and use it to describe the motion of that body, or we can attach coordinate systems to rigid bodies at the points where the bodies are articulated with each other and use them to describe the relative motion of the bodies. These systems can move and rotate with respect to the global system and with respect to each other. We may refer to one of these systems as S(u, v, w), where S is the origin and u, v and w are the axes, and to the unit vectors as u, v and w. We may also refer to the system simply as system S. We will now consider the relative orientation of two such coordinate systems, F(p, q, t) and S(u, v, w), with unit vectors p, q, t and u, v, w, respectively, as shown in Figure 1.1.
w
t
v w
p
p F
S
rFS
t q
v u
u
q
Figure 1.1: Defining the relative orientation of coordinate systems F(p, q, t) and S(u, v, w). F stands for First and S for Second.
Our notation intentionally suggests that F is the “first” system and S is the “second” system, and thus acknowledges a sense of direction for our analysis, without establishing a hierarchy. The components of the unit vectors u, v, w of system S are given in the F system by the following dot products: up = u · p uq = u · q ut = u · t
vp = v · p vq = v · q vt = v · t
wp = w · p wq = w · q wt = w · t
(1.33)
1.3. MATRICES IN 3 DIMENSIONS
11
The components of a unit vector are known as its direction cosines. Thus, up , uq , ut are the direction cosines of u, vp , vq , vt are the direction cosines of v, and wp , wq , wt are the direction cosines of w, all with reference to system F. These nine numbers uniquely define the orientation in space of system S with respect to system F. We define the orientation matrix of system S(u, v, w) with respect to system F(p, q, t) as follows: C++ up vp wp AFS,F = uq vq wq ut vt wt
(1.34)
Matrix AFS,F uniquely defines the orientation in space of system S with respect to system F. The notation reads “from F to S, expressed in F”. It acknowledges the sense of direction “First to Second” and the fact that the elements of the matrix are vector components expressed in system F. Depending on context, we will sometimes refer to the orientation matrix as AFS , or simply as A. Since the three columns of this matrix are the three column vectors, we will sometimes use the notation AFS,F = [u v w]
(1.35)
It is easy to proof that matrix A is orthogonal. Since unit vectors u, v, w are mutually orthogonal, relations 1.14 are satisfied, and orthogonality follows. Orientation matrices are used extensively in all that follows. The orientation matrix ASF,S of system F with respect to system S is obtained by similar considerations, using the components of p, q and t expressed in system S: pu q u tu ASF,S = pv qv tv p w q w tw
(1.36)
These components are related to the previous components of u, v, w as follows: pu = p · u = u p pv = p · v = vp pw = p · w = wp
qu = q · u = uq qv = q · v = vq qw = q · w = wq
tu = t · u = u t tv = t · v = vt tw = t · w = wt
(1.37)
Substituting these into equation 1.36 and comparing with equation 1.4, we immediately obtain: ASF,S = (AFS,F ) T
(1.38)
This equation tells us that there is only one orientation matrix for the pair of systems, which is AFS,F . When used as-is, it defines the orientation of S with respect to F, and when transposed, it defines the orientation of F with respect to S. A very useful conclusion, indeed, and one that is used throughout.
12
CHAPTER 1. MATRICES USED IN KINEMATICS
Depending on context, one of the two coordinate systems, for example F, may be designated as the local coordinate system. When so, some authors have used the bar mathematical accent ¯ ¯ while matrix ASF,S for objects that refer to that system. For example, matrix AFS,F would be A, would be simply A. We may have used this notation in a few cases. We have shown that an orthogonal matrix can be obtained from the components of three mutually orthogonal unit vectors. Conversely, any orthogonal matrix in 3D is equivalent to a system of 3 mutually orthogonal unit vectors. Because the vectors are of unit length, and because they are mutually orthogonal, there are 6 independent relations between the 9 elements of the matrix, and only 3 of the elements are independent. For an arbitrary orthogonal matrix R with elements Rij : R11 R12 R13 R = R21 R22 R23 R31 R32 R33
(1.39)
the following 9 relations can be obtained by forming all the cross-products between the unit vectors
u×v =w
v×w =u
v×w =u
R21 R32
− R22 R31 = R13 R12 R31 − R11 R32 = R23 R R 11 22 − R21 R12 = R33 R22 R33
− R23 R32 = R11 R13 R32 − R12 R33 = R21 R12 R23 − R13 R22 = R31 R23 R31
R R
11 33 R R 13 21
− R21 R33 = R12 − R13 R31 = R22 − R11 R23 = R32
(1.40)
(1.41)
(1.42)
but not all are independent. Another 9 relations can be obtained by writing all the possible dot products, but, again, not all are independent. The 18 relations are useful for testing the numerical accuracy of an orthogonal matrix.
1.3.3
Rotating a Vector Around an Axis
In this section we examine the issue of orientation from a different perspective. We are given an arbitrary vector p and we would like to rotate this vector by a given angle α around an axis defined by a unit vector a, where the direction of rotation is determined by the right-hand rule. Figure 1.2 illustrates this situation. To perform the rotation, we consider the plane perpendicular to a and define vector b as the perpendicular projection of p on the plane, and vector d as a × b. Then, we rotate b in the plane
1.3. MATRICES IN 3 DIMENSIONS
13
p
q a d
O b
c
α
Figure 1.2: A given vector p is rotated by a given angle α around an axis defined by a unit vector a. The direction of rotation is determined by the right-hand rule.
by α to position c, and finally we construct q from c. The following vector relations apply: b = p − (p · a)a d = a×b=a×p c = cos α b + sin α d q = c + (p · a) a
(1.43)
Since a is a unit vector, the definition of d guarantees that |d| = |b|. Furthermore, the definition of c guarantees that |c| = |b|, which indicates that the component of q perpendicular to a has the same magnitude as the component of p perpendicular to a, and is rotated by the angle α. Both p and q have the same component in the direction of a, given by (p · a)a, as desired. Using equations 1.43, we can calculate the rotated vector q when p, a and α are given. We would like, however, an expression in matrix notation, such as: q = R(a, α) p
(1.44)
where the vector p to be rotated is all by itself, separated from the rest of the equation, and the dependence on a and α is confined to matrix R. To achieve this goal, we rewrite equations 1.43 in matrix notation as follows: b =
I − aaT p
ep d = a
c =
h
i
e p cos α I − a a T + sin α a
q = c + aaTp
(1.45)
e and used equation 1.28 to convert the form of the cross products. where we have introduced matrix a We have also used that p · a = a T p. The following is now obtained: e R(a, α) = cos α I + (1 − cos α) a a T + sin α a
(1.46)
14
CHAPTER 1. MATRICES USED IN KINEMATICS
and finally, using 1.31 to convert a a T , we obtain: e + (1 − cos α) a e2 R(a, α) = I + sin α a
(1.47)
This equation is known as the Rodriguez formula. It expresses the rotation matrix R in terms of the axis and angle of rotation. If the components of the axis unit vector a are (a1 , a2 , a3 ), matrix R(a, α) is explicitly given by: R(a, α) = cos α + a21 (1 − cos α) a1 a2 (1 − cos α) + a3 sin α a1 a3 (1 − cos α) − a2 sin α
(1.48) a1 a2 (1 − cos α) − a3 sin α cos α + a22 (1 − cos α) a2 a3 (1 − cos α) + a1 sin α
a1 a3 (1 − cos α) + a2 sin α a2 a3 (1 − cos α) − a1 sin α cos α + a23 (1 − cos α)
It is possible to show that matrix R is orthogonal by proving that it satisfies R R T = I. This is easier to do if one starts from equation 1.46. Equation 1.44 represents yet another application of an orthogonal matrix, rotating a vector around an axis by a given angle, and equation 1.47 is yet another way of obtaining a matrix that is orthogonal. We also note that a rotation by angle α around axis a is the same as a rotation by angle − α around axis − a. Therefore, matrix R must remain invariant when the signs of both α and a are changed. By inspection of equation 1.48, it is easy to verify that this is indeed the case.
1.3.4
Orientation Matrix for a Rotated Coordinate System
In the preceding section we have developed a rotation matrix R(a, α), which describes a rigid rotation by an angle α around an axis defined by a unit vector a. If R(a, α) is multiplied by any given vector p, the result is the rotated vector q. In this section, we consider a coordinate system F with unit vectors p = [1, 0, 0] T q = [0, 1, 0] T t = [0, 0, 1] T
(1.49)
and we apply the rotation to the entire system. The result is another coordinate system S with unit vectors u, v, w given by: u = R(a, α) p = [R11 , R21 , R31 ] T v = R(a, α) q = [R12 , R22 , R32 ] T w = R(a, α) t = [R13 , R23 , R33 ] T
(1.50)
where Ri,j are the elements of matrix R(a, α). We note that the components of u, v and w are, respectively, the three columns of matrix R(a, α). By definition, equation 1.34, the three columns of the orientation matrix of system S are also de components of u, v and w. Therefore: AFS,F = R(a, α)
(1.51)
1.3. MATRICES IN 3 DIMENSIONS
15
The orientation matrix of the rotated system S is the rotation matrix R(a, α). The converse problem also arises in practice: given systems F and S and the orientation matrix AFS,F , find the axis and angle of the rotation that would transform F into S. From equation 1.51, we know that the rotation matrix R for such rotation is the same as the orientation matrix. To find the axis, we can use the fact that the only vectors that remain unchanged in a rotation are those parallel to the axis: R(a, α) a = a
(1.52)
(R(a, α) − I) a = 0
(1.53)
or:
where I is the identity matrix and 0 is the zero vector. This is a homogeneous system of three linear equations with three unknowns, the three components of a. The system has no solution if the determinant is not zero, or infinitely many solutions if the determinant is zero. In this case the determinant is zero because R is orthogonal with a determinant of 1, and the determinant of I is also 1. Therefore, there are infinitely many solutions, which are all the vectors parallel to the axis, in both directions. All we need to do is to choose one of them subject to the condition |a| = 1. There are two such solutions, which differ in sign, and either one will do. Once a is determined, the angle of rotation α can be determined from a suitable pair of formulas in equation 1.48. Note that both cos α and sin α need to be obtained in order for the quadrant of α to be univocally determined. Alternatively, it is also possible to solve equations 1.48 directly. With R(a, α) given, the system is over determined, and there is more than one way to obtain the solution. For example: cos α = (R11 + R22 + R33 − 1)/2 a1 = (R32 − R23 )/(2 sin α) a2 = (R13 − R31 )/(2 sin α) a3 = (R21 − R12 )/(2 sin α)
(1.54)
Clearly, singularities exist for α = 0 and α = π. However, the case α = 0 corresponds to no rotation at all, and the rotation matrix is the identity matrix. In the case α = π, the rotation matrix of equation 1.48 simplifies to: R(a, π) = 2a21 − 1 2a1 a2 2a1 a3
(1.55) 2a1 a2 2a22 − 1 2a2 a3
2a1 a3 2a2 a3 2a23 − 1
The absolute values of a1 , a2 and a3 can be obtained from R11 , R22 and R33 . Then, taking an arbitrary sign for a1 , the signs of a2 and a3 can be obtained from the off-diagonal elements of R.
16
CHAPTER 1. MATRICES USED IN KINEMATICS
The sign for a1 is arbitrary because a rotation by π around a is the same as a rotation by π around −a. The significance of the solution to the converse problem is far reaching. It means that any orientation can always be described as a rigid rotation around some axis by some angle, a result known as Euler theorem. One case where a solution to this converse problem is needed, is considered in section 2.5 below.
Chapter 2 Graphs and Coordinate Systems 2.1
Introduction
In Mathematics, a Graph consists of a set of vertices together with a set of edges, where an edge is defined as a pair of vertices of the graph. Graph Theory, the entire mathematical theory of graphs, relies on this simple definition, which does not even say what the vertices are or what the edges are. In practical applications, the vertices and edges can be assigned additional properties. A practical system can be described by a graph when the system’s components can be mapped to vertices and the relationships between them can be mapped to edges. The mapping implies that the system component’s properties are assigned to the corresponding vertices, and the properties of the relationships are assigned to the corresponding edges. The representation of a practical system by a graph offers a powerful paradigm because of the many useful theorems and powerful algorithms introduced by Graph Theory. Anything in practical life that can be represented by a graph will obey those theorems and algorithms without regard for the nature of what is being represented. The vertices and edges can be coded as objects, using derived classes to introduce the additional properties as well as any system specific procedures. The graph and the algorithms then become a systematic, organized and functional description of the entire system and a set of tools for its analysis. In Kinematics, where multiple coordinate systems are associated with the mechanical components and multiple coordinate transformations between the systems frequently arise, a graph can be created where each coordinate system is in correspondence with a vertex and each transformation with an edge. The properties and attributes of the coordinate systems can then be associated with the corresponding vertices, and the coordinate transformations with the corresponding edges, by means of derived classes in both cases. The result is a complete management system for multiple coordinate systems, an essential tool in Kinematics.
17
18
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
Below we review some aspects of Graph Theory of direct application in Kinematics. No special skills are required other than some familiarity with sets and set notation. Then, we define the Coordinate Systems Graph by associating a graph with the coordinate systems and transformations, and proceed to introduce and expand the important concept of propagation of mechanical information across the graph. Other graphs are also used in Kinematics, such as the Body and Constraint graph introduced in Volume III.
2.2
Basic Notions of Graph Theory
A graph G = (V, E) C++ consists of a set V of objects called vertices C++ u, v, w, . . . , together with a set E of objects called edges, where each edge is a pair (u, v) of vertices of V C++. We use vertical bars to indicate the number of elements or cardinality of a set, thus |V | is the number of vertices and |E| is the number of edges in G. When no distinction is made between edge (u, v) and edge (v, u), we say that the edge is undirected. or is represented by an unordered pair of vertices. Sometimes, even though (u, v) or (v, u) are equivalent for an undirected edge, one of them is arbitrarily taken as a reference direction for the undirected edge, and the edge is represented in the computer by storing only the pair associated with the reference direction. When all edges of a graph are undirected, the graph is said to be undirected. When the pairs that represent the edges are ordered, the graph is directed or a digraph. An undirected graph may also be regarded as a digraph for which, if (u, v) is an edge, then also (v, u) is an edge. A graph with n vertices can be numbered or labeled of ordered when the vertices are put in a one-to-one correspondence with the integers 1, 2, . . . , n. We will often label graphs and refer to the vertices by their numbers. A selfedge is a pair (u, u), where the same vertex appears twice. If vertices are mapped into points and
1
10
6
8
9 2
11 4
7
5 3
Figure 2.1: A labeled planar undirected graph with 11 vertices and 14 edges.
edges into lines in the plane, a planar embedding is obtained. Figure 2.1 shows a representation
2.2. BASIC NOTIONS OF GRAPH THEORY
19
of a graph which is a planar embedding of the graph on the page. A graph is planar when an embedding exists such that no two edges intersect. A subgraph G0 = (V 0 , E 0 ) of G = (V, E) which consists of some or all vertices of G and some edges of G. The subgraph is a section graph when V 0 consists of only some of the vertices of G, and E 0 consists of all edges (u, v) of G such that both u and v are in V 0 : V0 ⊂ V E
0
(2.1) 0
0
= {(u, v) ∈ E|u ∈ V andv ∈ V }
(2.2)
where {} indicates “set”. In figure 2.1, vertices 3, 5, 7, 8, and 11, together with edges (3, 5), (5, 8), (8, 11), (11, 7), (3, 7) and (3, 11) are a section graph. If (u, v) is an edge, vertices u and v are said to be adjacent, and edge (u, v) is said to be incident to vertex u and vertex v. The degree of a vertex is the number of edges incident to it. If W is a subset of the vertices of G, the adjacent set of W , denoted as Adj(W ), is the set of all vertices not in W which are adjacent to vertices in W . Namely, given the graph G = (V, E), and W ∈ V : Adj(W ) = {u ∈ V − W |∃v ∈ W 3 (u, v) ∈ E}
(2.3)
where V − W is the set of all vertices of V which are not in W . In figure 2.1, the vertices 1 and 6 are adjacent, and both are of degree 2. If W is the set of vertices (1, 6), then Adj(W ) = (9, 10). A subgraph is a clique when every pair of vertices is adjacent. In figure 2.1, the subgraph (3, 7, 11) is a clique. A path C++ is an ordered set of distinct vertices (u1 , u2 , . . . , um+1 ) such that ui and ui+1 are adjacent for i = 1, 2, . . . , m. m is the length of the path. A path of length m can also be regarded as a set of m edges (u1 , u2 ), (u2 , u3 ), . . . , (um , um+1 ). We say that two given vertices u and v are connected by a path if a path exists having u and v as its end points. A path is a cycle when u1 = um+1 C++ . A path with no cycles and which is not a cycle itself is an open path C++. Given an edge, an enclosing path C++ is any path that connects the two vertices of the given edge but not the given edge itself. Of particular interest is the shortest enclosing path associated with a given edge. A path that consists of undirected edges is an undirected undirected path. An undirected path can be traversed in either direction, and no mathematical distinction is made between (u1 , . . . , um+1 ) and (um+1 , . . . , u1 ). Sometimes, one of the two forms is arbitrarily taken as a reference direction for the undirected path, and the path is represented in the computer by storing only the form associated with the reference direction. When all edges of a graph are undirected, all paths are also undirected. The distance d(u, v) between two vertices u and v is the length of the shortest path connecting them. Given a vertex u, the largest distance between u and any other vertex of the graph is called the eccentricity e(u) of the vertex u. The largest eccentricity of any vertex in a graph is the diameter of the graph. A peripheral vertex is one for which the eccentricity is equal to the diameter of the graph. Algorithms for graphs associated with coordinate systems require a
20
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
“starting” vertex having a large eccentricity. A peripheral vertex would be ideal for this purpose; unfortunately, however, algorithms for finding a true peripheral vertex are inefficient. On the other hand, a good algorithm exist for finding pseudoperipheral vertices. A pseudoperipheral vertex u is defined by the condition that, if v is any vertex for which d(u, v) = e(u), then e(v) = e(u). This definition guarantees that the eccentricity of a pseudoperipheral vertex is “large”, usually close to the diameter of the graph. In figure 2.1, vertices 1 and 3 are connected by the path (1, 10, 11, 3) of length 3, and also by the path (1, 6, 9, 11, 3) of length 4. The distance between 1 and 3 is thus 3. The path (5, 8, 11, 3, 5) is a cycle. The diameter of the graph is 4, and the peripheral vertices are 1, 2, 4, 5 and 6, because their eccentricity is 4. In this example, all pseudoperipheral vertices are true peripheral vertices, a situation which may presumably happen frequently in practice. A graph is connected if every pair of vertices is connected by a path. Otherwise the graph is disconnected. A disconnected graph consists of two or more connected components, C++ each of which is a connected subgraph. Graphs may be partitioned in several ways. A partitioning is obtained when the vertices are grouped into disjoint subsets S0 , S1 , . . . , Sm . If the graph is disconnected and the subsets are the connected components, a component partitioning is obtained. When vertices are partitioned into adjacency levels, a level structure is obtained. An undirected graph which is connected and has no cycles is called a tree. C++ Given two vertices u, v of the tree, there is one and only one path that connects u and v. A tree is rooted when a vertex r is designated to be the root. The unique path which connects the root r with any other vertex u of the tree is used to establish an ancestor- descendant relation between the vertices; if v belongs to such a path, v is an ancestor of u, and u is a descendant of v. If u and v are adjacent, v is the father of u, and u is the son of v. If u and v are ancestors of w, we say that u is an older (younger ) of w than v if the distance d(r, u) is shorter (longer) than d(r, v). The root r is the oldest ancestor of any vertex in the rooted tree. The pedigree of a vertex is the set of its ancestors and the offspring is the set of its descendants. As for any graph, a tree can be labeled by numbering its vertices. Different numbering schemes can be adopted and some have useful properties. The monotone ordering is important: it is one where each vertex is numbered before its father. Given a connected graph G = (V, E), a spanning tree T = (V, E 0 ) C++ is a subgraph which is a tree and contains all the vertices of G. A spanning tree can be obtained by searching the graph and breaking cycles by deleting edges without disconnecting the graph. A convenient procedure for doing this is breadth-first search 2.2.1. A spanning tree of the graph of figure 2.1 is shown in figure 2.2 A set of disjoint trees which span a graph is called a spanning forest. A spanning forest is obtained if cycles are broken in a disconnected graph. A brief summary follows:
2.2. BASIC NOTIONS OF GRAPH THEORY
21
2 4 9
7
6
11
1
8
3 10
5
Figure 2.2: Spanning tree for the graph shown in figure 2.1.
• • • • • •
A A A A A A
graph is a set of vertices and edges. subgraph is a graph containing some or all vertices and edges of the original graph. component is a connected subgraph. tree is a component with no closed paths. path is a set of sequential edges. spanning tree is a tree with all the vertices of a component.
2.2.1
Breadth-first Search and Adjacency Level Structures
In the preceding section we have mentioned that a graph G = (V, E) can be partitioned by grouping the vertices into disjoint subsets. Adjacency level structures, or simply Level structures are a very important class of partitionings. A level structure L0 , L1 , . . . , Lm with m + 1 levels is obtained when the subsets are defined in such a way that: C++ Adj(Li ) ⊆ Li−1 ∪ Li+1 ,
0
(2.4)
Adj(L0 ) ⊆ L1 Adj(Lm ) ⊆ Lm−1 m is the length of the level structure, and the width is defined as the maximum number of vertices in any level. In a level structure, each level Li , 0 < i < m is a separator of the graph. A separator is a set of vertices, the removal of which, together with their incident edges, disconnects an otherwise connected graph or connected component. A level structure is said to be rooted at L0 if L0 ⊂ V is given and each of the remaining sets is the adjacent of the union of the preceding sets:
Li = Adj
i−1 [
Lj ,
i>0
(2.5)
j=0
If L0 is a single vertex u, i.e. L0 = {u}, we say that the level structure is rooted at vertex u.
C++
22
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
A search is a procedure by which we visit the vertices and edges of a graph G = (V, E) in some sequence. The sequence in which the vertices are visited can be used to order the graph, and the properties of edges discovered during the search can be used to sort edges into classes. Many graphtheoretical algorithms employ this technique, in particular some used in Kinematics. A search is initiated at some arbitrary chosen vertex s. The remaining vertices are then visited in a sequence established by some rule. The search is breadth-first when we explore all edges incident to the current vertex before moving to a new vertex. The search is depth-first if we explore just one of the edges and take the vertex reached by the edge as the new current vertex. In this section we consider the use of breadth-first search to generate a rooted level structure. Breadth-first search sorts vertices into levels and marks edges as either tree arcs of cross-links. Level L0 is the starting vertex s alone. At a certain stage during the search we have identified all vertices in a certain level Li . All vertices in preceding levels have been visited before and marked as such, and we also mark vertices in Li as visited. Then for some v ∈ Li , we examine the edges which lead from v to other vertices. If one of those edges reaches an unvisited vertex w, then w belongs to level Li+1 and the edge is a tree arc. If the edge reaches a visited vertex x, then (v, x) is a cross-link. This visited vertex x may only belong either to Li or to Li+1 , thus cross-links can only connect vertices in the same level or in adjacent levels. Tree arcs only connect vertices in adjacent levels, and there may be no connection between two vertices not in adjacent levels. Thus, each level i, 1 < i < m is a separator. Furthermore, a spanning tree is obtained, given by the set V of vertices of the original graph and all tree arcs. The algorithm, due to Rose et al. [15], uses a queue to store vertices in the order they are visited. Consider the graph G = (V, E) and let Vv be the set of visited vertices, and Et be the set of tree arcs. The algorithm is as follows: 1. Initialization. Initialize queue to contain the starting vertex s. Set level(s) = 0, Vv ← {s} and Et ← ∅. 2. Form partition member. If queue is empty, stop. Otherwise remove the vertex v at the rear of the queue and find the set S of unvisited vertices adjacent to v: S ← Adj(v)
\
(V − V0 )
(2.6)
3. Sort vertices and edges. If S = ∅ go to step 2. Otherwise, for each w ∈ S do the following: (3a) add w to the front of the queue. (3b) set level(w) = level(v) + 1. (3c) mark (v, w) as a tree arc: Et ← Et ∪ (v, w). (3d) mark w as visited: Vv ← Vv ∪ {w}. 4. Loop. Go to step 2.
2.3. THE COORDINATE SYSTEM GRAPH
23
At the end of the algorithm, all vertices for which level(v) = i are in level Li , and all edges in E −Et are cross-links. For an example of the application of the algorithm, consider the graph shown in figure 2.1, and choose 10 as the starting vertex. Initially, 10 is the only vertex in the queue, and level(10) = 0.
10 1
6
11
9
7
2
4
3
8 5
Figure 2.3: Adjacency level structure for the graph shown in figure 2.1, obtained by breadth-first search. The tree arcs of the spanning tree are shown with full lines. Cross-links are shown with dotted lines. Vertex 10 is removed from the queue and its adjacent set is found to be S = {1, 11}, with both vertices unvisited. Thus we set level(1) = 1 and level(11) = 1, and mark the edges (10, 1) and (10, 11) as tree arcs. Vertices 1 and 11 are added to the front of the queue. Now, since 10 was removed from the queue, we find vertex 1 at the rear. We remove 1 and find that its only adjacent unvisited vertex is 6. Thus level(6) = 2 and (1, 6) is a tree arc. Next comes 11 from the rear of the queue. Its set of adjacent unvisited vertices is S = {9, 7, 3, 8}. All this vertices are inscribed in level 2, and the edges leading to them from vertex 11 are marked as tree arcs. The reader can finish the construction of the level structure, which is shown complete in figure 2.3. The spanning tree is defined by the tree arcs shown with full lines. Dotted lines indicate cross-links. There are |V | − 1 = 10 tree arcs, and |E| − |V | + 1 = 4 cross-links. The length of the level structure is m = 3 and the width is 5. Note that the set of vertices {1, 11} in level 1 is a separator of the graph. Set {6, 9, 7, 3, 8} is also a separator.
2.3
The Coordinate System Graph
A typical problem of rigid body mechanics involves several bodies. Articulations may exist that partially constrain the relative motion of the bodies. Many different coordinate systems need to be defined and used in the calculations. A global coordinate system C++, assumed to be inertial, a system attached to each body with the origin at the center of mass and the axes parallel to the principal axes of inertia, a system at each point where an articulation is attached to describe
24
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
the relative motion and the constraining effects of the articulation. An articulation that connects two bodies has two points of attachment, one for each body, and needs two different coordinate systems. Temporary systems may also be useful, for example at points where collisions between bodies occur. The Coordinate System Graph C++ offers a unified view of the various coordinate systems used in the model and their relationships. The vertices C++ of the graph are the coordinate systems themselves, and the edges C++ are pairs of coordinate systems. Figure 2.4 represents a subgraph of the
S
F
Figure 2.4: A subgraph of the Coordinate System graph consisting of two coordinate systems, “First” and “Second”, and the edge joining them. The systems are labeled F and S, respectively. Edge FS is undirected, although an arrow has been added to indicate the order in which the F and S subscripts appear in the equations.
coordinate system graph with only two vertices and one edge. The two vertices represent coordinate systems F, or “First”, and S, or “Second”. The arrow merely indicates the F ⇒ S direction used in the text for argument, although vertices F and S are arbitrary and interchangeable and edge FS is undirected. We will frequently apply this figure to any pair of vertices in the graph that are joined by an edge, particularly if system F is fixed or is used as a reference and system S is moving relative to F or is being described with reference to F. The properties of the coordinate systems, such as a name, or the identification or mass of a rigid body if one is attached to the system, should be assigned to the corresponding vertices. The properties that pertain to a pair of coordinate systems should be assigned to the edges. The state of a coordinate system S - its orientation and the position of its origin relative to another coordinate system F - is not a property of system S alone but a relative property where both systems F and S are implicated, and must therefore be assigned to the corresponding edge. Coordinate transformations always involve a pair of systems and are associated with the corresponding edges. The notion that the orientation and position of a coordinate system is an edge property may be difficult to grasp. It seems to contradict our daily experience that a body “is there” or “is moving”, which appears to imply that placement or motion are properties of the body. The motion of a body
2.4. COORDINATE TRANSFORMATIONS
25
is always relative to another body, and is a property of both. The coordinate system graph is a complete management system for multiple coordinate systems. The graph is constructed by creating a vertex for each coordinate system, and an edge for each pair where a relation is needed. For example, it will usually be necessary to have an edge connecting each coordinate system to the global system, or one that connects the two attachments of an articulation. In the foundational implementation, basic graph services are offered by the parameterized classes PGraph, PVertex and PEdge. Several more parameterized or abstract classes in the Graphs family support additional graph attributes and services. The coordinate system graph itself is implemented by the derived class CSGraph and the derived classes CSVertex and CSEdge implement properties and functional coordinate system services such as state, coordinate transformations and specific coordinates. The graph helps to put all things in their right places because it offers the right places for all things.
2.4
Coordinate Transformations
A coordinate transformation is a procedure that converts the expression of an object in one coordinate system into the expression of the same object in another coordinate system. We are particularly interested in coordinate transformations in three dimensions as they apply to vectors and matrices. Consider first an arbitrary vector b with components bu , bv , bw in the S system. If u, v and w are the unit vectors of S, then b can be written as: b = bu u + bv v + bw w
(2.7)
We will now obtain the expression of b in system F. Consider the following expressions of u, v and w in terms of the unit vectors p, q and t of system F: u = up p + uq q + ut t v = vp p + vq q + vt t w = wp p + wq q + wt t
(2.8)
Substituting these into equation 2.7, and recalling that the components of u, v and w are the columns of the orientation matrix AFS,F , as seen in equation 1.34, the following is obtained after some simple calculations: bF = AFS,F bS
(2.9)
where bF is a column vector containing the components of b in system F, and bS is a column vector formed with the components of b in system S. Equation 2.9 is the coordinate transformation for vector b from system S to system F. In words, it says that the components of a vector in system F are obtained by premultiplying its components in system S by the orientation matrix AFS,F . The
26
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
reciprocal transformation from F to S is obtained by multiplying both sides of equation 2.9 from the left by AFS,F T and using the orthogonality of AFS,F . The result is: bS = (AFS,F ) T bF
(2.10)
Note that bF and bS are not two different vectors, they are just the components of b in two different coordinate systems. We will, however, refer to them as “vector bF ” and “vector bS ”. Most authors follow the same practice. Confusion is avoided by keeping in mind that they are just two different representations or “views” of one and the same object. To obtain the transformation for a matrix, consider again vector b and an arbitrary Matrix M, and let cF = MF bF
(2.11)
be another vector defined as the product of M and b, all in coordinate system F. We want to calculate a matrix MS such that cS = MS bS
(2.12)
where all quantities are now expressed in system S and bS and cS are obtained from equation 2.10 as follows: bS = (AFS,F ) T bF cS = (AFS,F ) T cF
(2.13)
or, conversely: bF = AFS,F bS cF = AFS,F cS
(2.14)
Substituting these into equation 2.11, the following is obtained: AFS,F cS = MF AFS,F bS
(2.15)
cS = AFS,F T MF AFS,F bS
(2.16)
or:
Comparing this with the form we want, equation 2.12, we obtain: MS = AFS,F T MF AFS,F
(2.17)
which is the transformation for a matrix from system F to system S. Not all matrices are required to transform in this way, but if a matrix M does, then equation 2.11 and equation 2.12 look exactly the same, and can be written as: c=Mb
(2.18)
2.5. INTERPOLATING ORIENTATIONS
27
irrespective of the coordinate system where b, c and M are expressed, but provided, of course, that they all are expressed in the same coordinate system. This important property is called form invariance. The laws of Physics are required to be invariant in form because that makes them independent of the observer: they always look the same way irrespective of the person who does the measurements, see section 3.1.
2.5
Interpolating Orientations
There are cases in practical Kinematics where the orientation of a new coordinate system has to be obtained by approximate interpolation between two given coordinate systems, particularly when the two given systems are not very different from each other and the error caused by the approximate interpolation can be neglected. For example, movie frames may be needed for times different from the time steps used to simulate the evolution of the system. Or, in the middle of a time step, some previously unknown condition arises, such as the breaking apart of a body or a collision or merging between two bodies, forcing a recalculation. However, the state just calculated is inaccurate anyway - the new condition has not been taken into account - and the exact time when the new condition appeared can only be estimated. In all cases, even if the interpolation itself is an approximation, the orthogonality of the interpolated system must be preserved. This requires that a strictly orthogonal rotation matrix be used for the interpolation. With reference to figure 4.1, let S and T be the two given coordinate systems, and let f be a given interpolation parameter in the range 0 < f < 1, where the value f = 0 would correspond to system S and f = 1 would correspond to system T. We assume that the orientation matrices AFS,F and AFT,F of systems S and T with respect to system F are known. Consider the rotation matrix R(a, α) which converts S into T by rotating it by and angle α around an axis a. Both α and a are yet to be determined. If the orientations of systems S and T are not very different, then α is small, and we can interpolate the intermediate system simply by rotating S by the smaller angle f α around the same axis a. From section 1.3.4, we know that: R(a, α) = AST,S
(2.19)
for the rotation that converts S into T. And from equation 4.5 we know how to calculate AST,S : AST,S = AFS,F T AFT,F
(2.20)
The rest is simple. Having obtained R(a, α) for the S→T rotation, determine α and a by solving equation 1.53 and use equation 1.48 to calculate the new interpolated rotation matrix R 0 (a, f α). With this in hand, set the orientation for the new interpolated system, say system I, with respect to S, as follows: ASI,S = R 0 (a, f α)
(2.21)
28
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
and the orientation of I with respect to F as follows: AFI,F = AFS,F ASI,S
(2.22)
Matrix R 0 (a, f α) is strictly orthogonal, and the orthogonality of the interpolated orientation matrix AFI,F is thus guaranteed. The position of the origin of system I is: rFI,F = rFS,F + α (rFT,F − rFS,F )
(2.23)
where all vectors must be expressed in the F coordinate system.
2.6
Spherical Coordinates and Direction
A direction in three-dimensional space is defined by a straight line. All lines parallel to the defining line are said to have the same direction. With reference to a coordinate system, a direction can be defined by a point on the surface of a unit sphere centered at the origin: the origin and the point determine a line, which in turn determines the direction. Two independent coordinates are necessary and sufficient to specify a direction, because the point on the surface of the sphere can be specified by giving two coordinates. A direction can also be specified by a unit vector, but this has the disadvantage that the unit vector has three components and only two of them are independent. In this section we discuss the use of a subset of the spherical coordinates r, α, β to specify a direction. Only α and β are used, r is not. We use α, β instead of the traditional ϕ, ϑ in order to avoid confusion with the Euler angles ϕ, ϑ, ψ. Consider figure 2.5, where a is the unit vector that defines the direction, t is its projection on the u, v plane, β is the angle between the vector
w β
a
v
O u
t α
Figure 2.5: Using a subset of the spherical coordinates r, α, β to specify a direction. The direction is defined by the line of the unit vector a. Axis w is the polar axis. and the polar axis w , and α is the angle between the u axis and t, measured in the plane u, v
2.7. THE BODIES AND CONSTRAINTS GRAPH
29
perpendicular to the polar axis. The following relations are used to calculate the components au , av and aw of a in terms of the spherical angles: au = sin β cos α av = sin β sin α aw = cos β
(2.24)
t = sin β
(2.25)
and
The following relations are easy to obtain, and are used to calculate the spherical angles when the components of a are known: β = cos−1 aw α = tan−1 (av /au )
(2.26)
There are some problems with equations 2.26. Singularities exist at β = 0 and β = π, since in this case au = av = 0 and α is undefined. There is also a singularity at au = 0, which is easy to deal with provided av 6= 0. To avoid the β singularities we use conventions. Let the unit vector a be defined in any coordinate system (x, y, z). The following procedure is used to define the conventions: Select the coordinate axis with the smallest absolute component of a as the polar axis, and rename it as w. Rename the remaining axes in order as u and v. The convention is X, Y or Z when the selected polar axis p is x, y or z, respectively. Plane (w, a) and segment t are now well-defined, and t ≥ 2/3 > 0.8164, since 0 < β < π.
2.7
The Bodies and Constraints Graph
There is one more type of graph that is very useful in kinematics, particularly in the case of articulated figures where re present. It is the Bodies and Constraints graph. C++ In this graph, a vertex C++ describes a body and an edge C++ describes a constraint. The constraint connects two bodies, and the edge connects the two vertices associated with the two bodies. The graph may in general consist of one or more connected components C++.
30
CHAPTER 2. GRAPHS AND COORDINATE SYSTEMS
Chapter 3 The Kinematic State 3.1
Tensors and Form Invariance of the Laws of Physics
The laws of Physics are supposed to be independent from the observer. If different observers perform the same experiment under similar conditions, the results must be the same. More specifically, if a law of Physics written in a certain coordinate system is transformed to another coordinate system, the original form and the new form must be the same. In object terminology, we say that the objects involved in the law contain no information about the coordinate system, and therefore it should not be possible to use the form of the law to identify a particular coordinate system. Scalars, vectors and matrices are part of many laws of Physics. In mathematical terms, a 3-vector is simply a set of three numbers, which become a column vector if written in a column, or a row vector if written in a row. A scalar is simply a number, and a 3 × 3 matrix is a set or nine numbers. In Physics, however, a vector is an entity in itself, with its own properties of magnitude and direction. The physical vector is an object, and the magnitude and direction are its attributes. The magnitude in turn is an object, with the attributes of value and the physical units used to express the value. Any law written in terms of such vectors would be form-invariant because the vectors do not contain any information about any coordinate system. A complication arises, however, when the vector is expressed in terms of its components with reference to some coordinate system. The components are different in different systems, but the vector must remain the same, more specifically its original magnitude and direction must remain unchanged when a coordinate transformation is applied. Even more specifically, the components must transform in the coordinate transformation in such a way that the magnitude and direction calculated in the new system are the same as they were in the initial system. A vector that satisfies this requirement is called a tensor of rank 1, and the specific transformation with the required
31
32
CHAPTER 3. THE KINEMATIC STATE
properties is called a vector transformation. If a vector is a set of 3 numbers, a tensor of rank 1 is a set of 3 numbers and a reference to the coordinate system that holds the 3 numbers as components and the vector transformation rule that makes all that a tensor. Physicists refer to tensors of rank 1 as vectors and express them as columns or rows of 3 numbers, with the understanding that they behave as physical vectors in case the coordinate system is changed. Most of the vectors we use here are tensors, but if they aren’t we will say so explicitly. We will also follow a common practice that saves vertical space by writing a column vector as the transpose of a row vector. For example, with reference to figure 1.1, a vector b with components bu , bv , bw in the S system, which is given by b = bu u + bv v + bw w
(3.1)
can be written as a column vector as follows: bS = (bu , bv , bw ) T
(3.2)
The notation bS is read as “column vector b expressed in system S”. Scalars used in Physics are tensors of rank 0, or invariants. Their values do not change in a coordinate transformation. Matrices used in Physics are tensors of rank 2, and they transform in a coordinate transformation just as vectors do, but their rules of transformation are different. Do not confuse this with the rank of a matrix defined in section 1.2.2, the difference should be clear from context. There is nothing wrong with using quantities that are not tensors for intermediate calculations. For example, a component of a vector is not a tensor but can be calculated by itself. However, a law of Physics that involves that vector must involve all its components. In the following section we obtain the transformations for vectors and matrices that make them tensors.
3.2
The Kinematic State and the State Variables
Rigid bodies do not exist in nature. A rigid body is a concept, a model, obtained when we imagine matter rigidly attached to a coordinate system and moving with it, and write the dynamic equations that govern the motion of such a model body. The dynamic equations are differential equations of the second order, and require that an initial state be specified where not only positions and orientations are given, but also the first total derivatives of positions and orientations with respect to time. Such a state is known as a kinematic state, and the variables that define it are known as the state variables. We will proceed now to define a logical object capable of representing a kinematic state. Since there are six degrees of freedom, three for the position and three for the orientation of the coordinate system, the minimum number of independent quantities required to completely specify the position and orientation of an unconstrained coordinate system is 6. If more quantities are specified, as we did in the case of the orientation matrix, they will not all be independent. Another 6 independent
3.3. POSITION AND VELOCITY
33
quantities are needed to specify the first total derivatives of position and orientation with respect to time, and, again, if more are given they will not all be independent. The total minimum number of quantities to completely specify the kinematic state is 12. In practical analysis, however, it is convenient to keep more than 12 quantities, even if they are inter-dependent. As discussed in section 1.3.2, the position and orientation of system S with respect to system F is determined by the vector rFS,F , which extends from the origin of F to the origin of S, and the orientation matrix AFS,F , which contains the components of the unit vectors u, v and w of system S expressed in system F, and thus completely determines the relative orientation. Thus, both rFS,F and AFS,F are admitted as properties for the kinematic state object. The time derivative of the position vector, r˙ FS,F , is the velocity vFS,F . Regarding the orientation matrix, we show in section 3.4 below that the time derivative A˙ FS,F can be expressed in terms of the angular velocity vector 1 ωFS,F , see equation 3.21. Both vectors, vFS,F and ωFS,F are consequently admitted into the kinematic state object. In summary, the kinematic state object contains rFS,F , AFS,F , vFS,F , and ωFS,F . It may seem wasteful to keep the entire orientation matrix AFS,F in the object, taking 9 quantities where only 3 are needed. However, AFS,F contains the three components of the three unit vectors, which are needed for many calculations anyway. C++
3.3
Position and Velocity
In figure 1.1 on page 10, the position of system S with respect to system F is determined by two quantities, the vector rFS which extends from the origin of F to the origin of S, and the orientation matrix A, which contains the components of the unit vectors u, v and w of system S expressed in system F. Vector rFS determines the position of the origin of S, while matrix A determines the angular orientation of S. Consequently, if rFS or A depend on the time, then system S is moving relative to F. The relative motion can be described as the composition of two different motions: the displacement motion or translation motion or linear motion caused by the change in rFS and where the origin of S moves while the axes of S remain parallel to themselves, and the angular motion or rotation motion caused by the change in A and where the origin of S remains stationary and the unit vectors change their orientations while still remaining orthogonal to each other. The composition is more than just descriptive because the differential equations of Rigid Body Dynamics actually separate in the same way under certain conditions, as discussed in the next volume. We have just introduced an important notion in a subtle way. We did not say that system S moves relative to system F, and therefore rFS and A are functions of time. We said that rFS and A are functions of time and therefore system S moves relative to system F. In doing so, we introduced, at this early stage, the notion of motion control , where the motion of the bodies is considered to 1
Actually a pseudo-vector.
34
CHAPTER 3. THE KINEMATIC STATE
be a result of controlling actions which are considered external in the computer simulation. Such actions can be dynamic effects resulting from applied forces and calculated via equations of motion and motion constraints, or perhaps an animated control where the motion is determined by the will of the artist. The major goal of this series is the science of Robotics, and that’s where we are aiming. In this section, we examine the kinematic description of the linear motion of system S relative to F. The linear motion is simple. Vector rFS , to which we now refer as the position vector C++ is used for this purpose. It is common practice to express the position vector in system F, as rFS,F , but it can also be expressed in system S, as rFS,S . The relation between the two forms is obtained from the vector coordinate transformation: rFS,F = AFS,F rFS,S
(3.3)
The total derivative of rFS with respect to time: vFS,F = r˙ FS,F
(3.4)
is the linear velocity C++ or translation velocity or displacement velocity, or simply velocity of system S relative to system F. It too can be expressed in system S as vFS,S , and it transforms as a vector: vFS,F = AFS,F vFS,S
3.4
(3.5)
Differentiating the Orientation Matrix
With reference to figure 1.1, let AFS,F be the orientation matrix for system S relative to system F. If S moves relative to F, the elements of AFS,F are function of the time t. In this section we write an expression for the total derivative of AFS,F with respect to time, and we use the properties of orthogonal matrices and skew-symmetric matrices to introduce the angular velocity. Matrix AFS,F is orthogonal and, as such, it satisfies: AFS,F T AFS,F = I
(3.6)
where I is the identity matrix of size 3 × 3. As time evolves, the elements of AFS,F change but AFS,F remains orthogonal because S undergoes only translations and rotations and remains rigid. Differentiating 3.6 with respect to time t, we obtain: A˙ FS,F T AFS,F + AFS,F T A˙ FS,F = O
(3.7)
where O is the zero 3 × 3 matrix and the dot mathematical accent ˙ is used to indicate a total derivative with respect to time: x˙ ≡
dx dt
(3.8)
3.4. DIFFERENTIATING THE ORIENTATION MATRIX
35
for any x. This can be written:
AFS,F T A˙ FS,F = − AFS,F T A˙ FS,F
T
which means that the following matrix WFS,S = AFS,F T A˙ FS,F
(3.9)
(3.10)
is skew-symmetric. It will become clear in a moment why we designated this matrix with the subscripts FS, S. Using the orthogonality of AFS,F we obtain the derivative we are seeking: C++ A˙ FS,F = AFS,F WFS,S (3.11) We can also carry equation 3.6 in reverse: AFS,F AFS,F T = I
(3.12)
Differentiating this we obtain: A˙ FS,F AFS,F T + AFS,F A˙ FS,F T = O which can be written: A˙ FS,F AFS,F T = − A˙ FS,F AFS,F T
(3.13) T
which means that the following matrix WFS,F = A˙ FS,F AFS,F T
(3.14)
(3.15)
is skew-symmetric. Again, we will explain our notation below. Using the orthogonality of AFS,F we obtain a new version of the same derivative: A˙ FS,F = WFS,F AFS,F (3.16) In the following section we present an alternative form for equations 3.11 and 3.16, see equations 3.21. Comparing equations 3.11 and 3.16, we find that: WFS,F = AFS,F WFS,S AFS,F T
(3.17)
This equation is the transformation of matrix WFS from its expression in system S to its expression in system F. It is the correct coordinate transformation for a matrix, and it proves that WFS is acceptable as a matrix. 2 We will from now on say that the object WFS is a matrix, expressed as WFS,F in system F and as WFS,S in system S. Our language implies that the two forms are expressions of one and the same object, and when we use expression 3.17 to convert one into the other, we are not converting one object into another, but only one expression of a matrix object into another expression of the same matrix object. Even if we occasionally refer to the “matrices” WFS,F and WFS,S , we will still keep in mind that they both represent one and the same object. ¯ This is particularly the case when F is Some authors refer to WFS,F as W and to WFS,S as W. considered to be the global coordinate system, and S is a local coordinate system. 2
Actually, it proves that WFS is a tensor, and thus acceptable as a matrix in Physics.
36
3.5
CHAPTER 3. THE KINEMATIC STATE
Angular Velocity
Let ωFS,F and ωFS,S be the two vectors associated with the two W matrices defined in the previous section: fFS,F ωFS,F = W fFS,S ωFS,S = W
(3.18)
where the operation designated by the tilde mathematical accent e converts a 3×3 skew-symmetric matrix into a 3 × 1 column vector as defined in equation 1.25. The following relation can be verified by inspection: ωFS,F = AFS,F ωFS,S
(3.19)
This equation is the correct transformation for a vector from system S to system F, and proves that ωFS is a vector. This vector is called the angular velocity C++ of system S relative to system F. ¯ particularly when system Vector ωFS,F is sometimes referred to simply as ω, and vector ωFS,S as ω, F is the global system and system S is a local system, but the two are just two expressions of one and the same vector. The first time derivative of the angular velocity is the angular acceleration, expressed in either system F or S: C++ αFS,F = ω˙ FS,F αFS,S = ω˙ FS,S
(3.20)
We will now describe the angular motion and interpret the meaning of the angular velocity. If system S in figure 1.1, at a certain instant of time, is spinning relative to system F, or in other words system S is rotating around an axis that passes through its origin so that the origin doesn’t move, then the orientation matrix is a function of time. Using the equivalence between the multiplication by a skew-symmetric matrix and the cross product with the equivalent vector, equation 1.28, equations 3.11 and 3.16 can be written as follows: A˙ FS,F = −(ωFS,S × AFS,F T ) T = AFS,F × ωFS,S A˙ FS,F = ωFS,F × AFS,F
(3.21)
The cross product of a matrix by a vector is to be understood as a matrix, each row of which is the cross product of the corresponding row of the given matrix by the vector, and the cross product of a vector by a matrix is to be understood as a matrix, each column of which is the cross product of the vector by the corresponding column of the given matrix. Figure 3.1 is similar to figure 1.1, but now it has an additional point P and the radius vector rSP from S to P. We assume that the origin of S is stationary, so that the motion of system S is only rotational. Point P is rigidly attached to system S. When system S moves, it drags point P with it. We must be careful with our notation:
3.5. ANGULAR VELOCITY
37 P w
t
rSP w
p
p F
q
v S
rFS
t
v
u
u
q
Figure 3.1: Two coordinate systems, F(p, q, t) and S(u, v, w). A point P is also shown, at a fixed position rSP with reference to system S. When system S moves, it drags point P with it.
• The symbol rSP designates a vector object, with the invariant attributes of direction and magnitude which do not change in a coordinate transformation. Note, however, that nothing has been said about the time dependence of rSP . In particular, if system S is rotating, rSP is a function of time and r˙ SP is not zero. Specifically, in this case, the direction of rSP will change in time, not its magnitude. • The symbols rSP,S and rSP,F designate the column vectors that contain the components of rSP in systems S and F, respectively, and are related by the coordinate transformations for vectors, equations 2.9 and 2.10. • When we say that point P is rigidly attached to system S, we mean that rSP,S is independent of time. An observer traveling with system S would see point P in a stationary position. This does not mean that rSP,F is independent of time, in fact, an observer traveling with system F would see point S stationary but point P moving. • For an observer in system F, the position of point P is rFS + rSP . Both quantities, rFS and rSP , are tensors of rank 1, and the expression rFS + rSP is form-invariant and unrelated to any particular coordinate system. The coordinate systems enter the picture only when we try to calculate the value of rFS + rSP . To calculate that value we need to express both rFS and rSP in the same coordinate system. In this case we must choose one of F or S and represent the vectors accordingly. Let rFP,F be the position of P with respect to system F. It is given by: rFP,F = rFS,F + rSP,F
(3.22)
where all vectors are expressed in system F and, according to equation 2.9: rSP,F = AFS,F rSP,S
(3.23)
38
CHAPTER 3. THE KINEMATIC STATE
We can now write equation 3.22 as follows: rFP,F = rFS,F + AFS,F rSP,S
(3.24)
We want to calculate the velocity of point P relative to system F. According to our assumptions, rFS,F is constant in time because there is no translation motion, and rSP,S is also constant in time because point P is attached to system S. Therefore: vFP,F ≡ r˙ FP,F = A˙ FS,F rSP,S
(3.25)
(using 3.16) = WFS,F AFS,F rSP,S
(3.26)
(using 3.23) = WFS,F rSP,F
(3.27)
(using 1.28) = ωFS,F × rSP,F
(3.28)
Equation 3.28 tells us what we need to know about the rotational motion of system S as seen from system F. The line parallel to ω and passing through point S is called the instant axis of rotation. If point P is on this line, its velocity is 0. Any point which is on the instant axis at that particular instant of time is not moving. The axis is called “instant” because it is the axis for that particular instant of time, and as time elapses, the axis may, and usually will, move. If point P is located away from the axis and at a perpendicular distance ρ from it, its velocity vFP,F is perpendicular to the axis, in the right-hand direction when the thumb is placed along vector ω, and given by ρ |ω|. The angle dϑ rotated by this point P per differential time dt is: dϑ vFP,F ≡ ϑ˙ = = |ω| dt ρ
(3.29)
which shows that |ω| is indeed the scalar angular velocity of rotation about the axis at that instant of time. The distance between any two given points, P and Q, both attached to system S, can be shown to remain constant during the motion, meaning that the motion is indeed a rigid rotation around the instant axis with angular velocity |ω|. For future reference, we state here the following results. Consider the product of A˙ FS,F with a vector uS defined in the local coordinate system S of figure 1.1. Products of this type frequently appear in Kinematics. There are two ways of calculating such product, using either form 3.11 or form 3.16 to express the partial derivative. In the first case, vector uS is used as is: A˙ FS,F uS = AFS,F WFS,S uS = AFS,F ωFS,S × uS
(3.30)
In the second case, vector uS is first transformed to the F system, as uF , using the transformation equation 2.9: A˙ FS,F uS = WFS,F AFS,F uS = WFS,F uF = ωFS,F × uF
(3.31)
The two forms are equivalent, but the second form is computationally more efficient if several derivatives are to be calculated, as is the case, for example, when working with Euler angles.
3.6. SPECIFIC COORDINATES
39
The gain in efficiency is due to the fact that the coordinate transformation from uS to uF is performed only once and then reused to calculate all the necessary derivatives. Consider now the second derivative of the orientation matrix AFS,F with respect to time, obtained by differentiating equation 3.21, expressed in terms of the angular velocity: ¨ FS,F = (AFS,F × ωFS,S ) × ωFS,S + AFS,F × ω˙ FS,S A
3.6
(3.32)
Specific Coordinates
We have emphasized the fact that two different quantities are needed in order for a coordinate system S to be completely specified relative to another coordinate system F: the position of the origin of S relative to the origin of F, or rFS,F , and the orientation of S relative to F, or AFS,F . We have shown that there are three degrees of freedom for translation, and, since the orientation matrix has only three independent components, there are also three degrees of freedom for rotation. In total six degrees of freedom are sufficient to completely specify the position and orientation of a coordinate system relative to another. We now introduce the concept of Specific Coordinates. Specific coordinates are defined as any set of parameters that completely specify the position and orientation of a coordinate system relative to another. The symbol t is sometimes used to designate the set of specific coordinates: t = (t0 , t1 , . . . , tn−1 )T
(3.33)
where n is the number of specific coordinates. The Specific Velocities are the time derivatives of the specific coordinates, and the Specific Accelerations are the second time derivatives of the specific coordinates: C++ C++ t˙ = (t˙0 , t˙1 , . . . , t˙n−1 )T t¨ = (t¨0 , t¨1 , . . . , t¨n−1 )T
(3.34)
If S is unconstrained, the set of specific coordinates must contain at least 6 independent parameters. If it contains more, only 6 are independent. Usually, the set consists of two subsets: the Translational specific coordinates p C++ - frequently the three components of rFS,F - and the Orientational specific coordinates s. C++ Thus: t = (pT | sT )T
(3.35)
There are several choices for the orientational specific coordinates, among which we may mention the Euler angles - a set of 3 independent angles - and the Euler parameters - a set of 4 parameters, only 3 of which are independent. The elements of the orientation matrix are, in fact, also a possible set of orientational specific coordinates with 9 parameters, but not a very practical one.
40
CHAPTER 3. THE KINEMATIC STATE
There are situations where the motion of system S relative to F is mechanically constrained. For example, a given point of system S may be required to remain at a fixed position relative to F, so that S can only rotate about the point. This is called a spherical joint. The constraint removes the 3 degrees of freedom for translation and leaves only the 3 degrees of freedom for rotation. Another example is an axis attached to F such that S can only rotate around the axis but not slide along it - a cylindrical joint. This leaves only one degree of freedom: rotation about the axis. The translational motion can also be constrained, for example the origin of S can be constrained to stay on a plane attached to F, a planar joint, which has 5 degrees of freedom: 2 for translation in the plane and 3 more for rotation. Ad-hoc specific coordinates can be chosen for constrained cases. For example, a full set of specific coordinates for a spherical joint consists only of the 3 orientational coordinates, the translational ones would be superfluous. A cylindrical joint requires only one specific coordinate, the angle of rotation around the axis. A planar joint requires 2 translational and 3 orientational specific coordinates. If a two-dimensional coordinate system is defined on the plane, the 2 coordinates of the origin of S can be used as its translational specific coordinates. When specific coordinates are used, both their values and their first time derivatives are needed. The specific coordinates and their time derivatives for system S are kept in two separate objects, implemented by the families of classes Translator and Orientator , respectively. These classes also provide all the necessary transformations between specific coordinates and state variables, as well as the necessary support for dynamic calculations based on specific coordinates. Specific orientational coordinates are discussed in detail in chapter 5.
3.7
Specific Coordinates and State Variables
When specific coordinates are used to describe the motion of a rigid body, the state variables rFS , vFS , AFS and ωFS are considered to be functions of the specific coordinates and velocities. The conversion functions must be explicitly provided when the system of specific coordinates is defined. The position vector rFS,F is related only to the translational specific coordinates. In this work, we define only one system of translational specific coordinates, the cartesian components of rFS,F itself. Let p1 , p2 , p3 be the 3 translational specific coordinates. The simple conversions are: p1 = rx p2 = ry p3 = rz
(3.36)
where rx , ry and rz are the components of rFS,F . The orientation matrix AFS,F is related only to the orientational specific coordinates. Several systems of orientational specific coordinates are defined in chapter 5, and the conversion expressions are given there for each system.
3.7. SPECIFIC COORDINATES AND STATE VARIABLES
41
The linear velocity vFS,F is related to the translational specific coordinates and velocities. The chain rule of differentiation can be used to obtain the conversion. Let p = [p1 . . . pm ]T be a m × 1 column vector with the m translational specific coordinates for coordinate system S relative to system F. By definition, the pj ’s uniquely determine rFS,F . Using the chain rule of differentiation, we have: r˙ FS,F =
∂rFS,F ∂rFS,F p˙1 + · · · + p˙m ∂p1 ∂pm
(3.37)
which can be written in abbreviated matrix notation as follows: r˙ FS,F = 3×1
∂rFS,F ∂p
p˙
3×m
m×1
(3.38)
where ∂rFS,F /∂p is a 1 × m row vector with components that are 3 × 1 column vectors, or, in other words, a 3 × m matrix where column j is ∂rFS,F /∂pj . Let HFS,F be that 3 × m matrix C++. Then: vFS,F ≡ r˙ FS,F = HFS,F p˙
(3.39)
where vFS,F is the linear velocity of the origin of S relative to F. This shows that vFS,F can be written as a linear combination of the p˙j ’s with coefficients that depend on the pj ’s but not on the p˙j ’s. Similarly, a matrix HFS,S can be defined, such that: vFS,S ≡ r˙ FS,S = HFS,S p˙
(3.40)
Equations 3.39 and 3.40 are used to calculate the linear velocity of the origin of system S in terms of the translational specific velocities. A solution to the converse problem, calculating the translational specific velocities p˙ when then linear velocity vFS,S is given, must also be available. This can always be done by solving a system of equations consisting of equations 3.40 and any constraint equations that apply to the p˙ coordinates. Using the coordinate transformation between vFS,F and vFS,S , it is easy to prove that the two H matrices are related by: HFS,F = AFS,F HFS,S
(3.41)
The time derivatives of the two H matrices are the matrices H˙ FS,F and H˙ FS,S . Finally, the angular velocity ωFS,F is related to the orientational specific coordinates and velocities. Let s = [s1 s2 . . . sn ]T be an n × 1 column vector with the set of the n orientational specific coordinates for system S relative to system F. By definition, the sj ’s uniquely determine the orientation matrix AFS,F . Using the chain rule of differentiation, we have: A˙ FS,F = 3×3
∂AFS,F ∂s
s˙
(3×3)×n
n×1
(3.42)
42
CHAPTER 3. THE KINEMATIC STATE
where ∂AFS,F /∂s is now a 1 × n row vector with components that are 3 × 3 matrices. This shows that A˙ FS,F can be written as a linear combination of the specific velocities s˙ j ’s with coefficients that depend on the sj ’s but not on the s˙ j ’s. Now, equations 3.10 and 3.15 tell us that the elements of WFS in its two versions WFS,S and WFS,F , and hence also the components of ωFS,S and ωFS,F , can be written as linear combinations of the elements of A˙ FS,F , with coefficients that depend only on the elements of AFS,F , and hence on the sj ’s, but not on the s˙ j ’s. In summary, we conclude that the components of ωFS,S and ωFS,F can be written as linear combinations of the s˙ j ’s with coefficients that depend only on the sj ’s. This result is expressed in the following definitions for matrices GFS,F and GFS,S : C++ s˙ s˙
ωFS,S = GFS,S ωFS,F = GFS,F 3×1
3×n
(3.43)
n×1
where the two matrices GFS,F and GFS,S depend only on the sj ’s. These equations are used to calculate the angular velocity in terms of the orientational specific velocities. The two G matrices play an important role in rigid body kinematics. The calculations needed to obtain their explicit expressions for a given set of specific coordinates are often long, but simple, and the results are also simple. See chapter 5 for details. The transformation between the two G matrices is easily obtained from the transformation between the corresponding angular velocities, equation 3.19: GFS,F = AFS,F GFS,S
(3.44)
which shows that the G matrices do not transform as tensors and are not tensors. The time derivatives G˙ FS,F and G˙ FS,S of the G matrices are also frequently used: C++ G˙ FS,F = G˙ FS,S =
d GFS,F dt d GFS,S dt
(3.45)
Once either version of the angular velocity has been obtained, the time derivative of the orientation matrix, A˙ FS,F , can be obtained from equations 3.21.
3.8
Specific Coordinates and the Equations of Motion
In the previous section we have introduced the specific coordinates and we have discussed the relations between the state variables and the specific coordinates. When specific coordinates are used, the equations of motion for rigid bodies, or for systems composed of rigid bodies, are written in terms of specific coordinates. The equations of motion are differential equations of the second order, and contain second derivatives of several terms with respect to time. The equations of
3.8. SPECIFIC COORDINATES AND THE EQUATIONS OF MOTION
43
motion are not discussed in this volume, but support for the calculation of the new terms and their derivatives must be built into the specific coordinates object we are designing. Consider first the rotational kinetic energy Tr , given by: Tr =
1 ωFS,S T JS ωFS,S 2
(3.46)
Tr is a scalar quantity associated with the rotation of the rigid body. Matrix JS is a 3 × 3 matrix known as the matrix of inertia or matrix of moments of inertia. It depends only on the given rigid body, not on its state of motion, and remains constant as long as the body does not break or change shape. It is a symmetric positive-definite matrix, and it is also a diagonal matrix provided the origin of system S is at the center of mass of the body and the axes are coincident with the principal axes of inertia of the body, which are in turn determined by the shape and mass distribution of the body. We will always take S in this way for a rigid body. Taking S in this way has the important effect that the equations of motion for a rigid body are decoupled and separate equations for rotation and translation are obtained. Note that we are now expressing all matrices and vectors in the local coordinate system S, and that JS has S as its lone subscript because it is associated with system S alone. The equations developed in this section are organized in an object-oriented style where similar objects occur together in a term or factor and are used to create higher-level objects. This results in simpler equations, better and more efficient code, and smaller objects. In equation 3.46 we note that the constant diagonal matrix JS is associated with vertex S of the coordinate system graph. On the other hand, ωFS,S T and ωFS,S depend on the orientational specific coordinates s and velocities s˙ and are associated with edge FS of the graph. We recall that s is the n × 1 column vector [s1 . . . sn ] T . The calculation of Tr requires a collaborative effort between a vertex object and an edge object. To emphasize this fact, we rewrite equation 3.46 with the help of equation 1.21 as follows: Tr =
1 b FS,S b ωFS,S T ω JS 2
(3.47)
where, now, the two edge objects occur together, and the vertex object is all by itself as a separate factor at the end of the equation. Object-oriented style is nothing new in Physics. If ω1 , ω2 and ω3 are the components of ωFS,S , and J11 , J22 and J33 are the diagonal elements of JS , then equation 3.47 can be written: Tr =
1 [ω1 2 ω2 2 ω3 2 ] [J11 J22 J33 ] T 2
(3.48)
which is the familiar expression Tr = (1/2)(ω12 J11 + ω22 J22 + ω32 J33 ). We are now interested in the following expression, which appears in the equations of motion: d dt
∂Tr ∂ s˙
T
−
∂Tr ∂s
T
(3.49)
44
CHAPTER 3. THE KINEMATIC STATE
We begin with the second term in this expression. Differentiating equation 3.46 :
∂Tr ∂s
T
=
n×1
∂ωFS,S ∂s
T
n×3
JS
ωFS,S
3×3
3×1
(3.50)
or, using equation 1.21:
∂Tr ∂s
T
=
n×1
∂ωFS,S ∂s
T b FS,S ω
b JS
3×3
3×1
n×3
(3.51)
where we have separated JS at the rightmost end of the equation. When JS is given, this expression can be evaluated in terms of s and s˙ by using the first equation in 3.43. The n × 1 column vector ˙ and for that reason, with (∂Tr /∂s)T is a quadratic function of the orientational specific velocities s, its sign changed, is considered to be the first of two parts of the quadratic velocity vector. The second part is defined below. We now evaluate the first term in equation 3.49. Using the first equation in 3.43, equation 3.46 can be written as follows: Tr
=
1×1
1 T s˙ 2
GFS,S T
JS
GFS,S
s˙
1×n
n×3
3×3
3×n
n×1
(3.52)
˙ Differentiating with respect to s:
∂Tr ∂ s˙
T
= GFS,S T
n×1
n×3
JS
GFS,S
s˙
3×3
3×n
n×1
(3.53)
and differentiating with respect to time: d dt
∂ Tr ∂ s˙
T
=
n×1
G˙ FS,S T JS GFS,S + GFS,S T JS G˙ FS,S n×n
n×n
s˙
+ GFS,S T JS GFS,S
n×1
n×n
s¨
(3.54)
n×1
which can be object-organized with the help of equation 1.21 as follows: d dt
∂ Tr ∂ s˙
n×1
T
=
h
i
d d s) ˙ + GFS,S T (G˙ FS,S s) ˙ G˙ FS,S T (GFS,S n×3
n×3
JcS 3×1
+ GFS,S T JS GFS,S n×n
s¨
(3.55)
n×1
The first term on the right is a quadratic function of the orientational specific velocities. This term is an n × 1 column vector, and, with its sign changed, is the second and last part of the quadratic velocity vector introduced above. The last term on the right contains the orientational specific
3.8. SPECIFIC COORDINATES AND THE EQUATIONS OF MOTION
45
accelerations s¨, which are unknowns in the differential equations of motion and must be kept as a ˙ The quadratic velocity vector separate factor, not combined into the matrix as we just did with s. qv can now be assembled from equation 3.51 and equation 3.55: = −QT
qv n×1
n×3
b JS
(3.56)
3×1
where the 3 × n matrix Q is defined as follows
C++
" b FS,S + GFS,S Q = G˙ FS,S ω T
T
d ˙ − (G˙ FS,S s)
:
C++
∂ωFS,S ∂s
#T
T b FS,S ω
(3.57)
and the expression we were seeking, equation 3.49, can finally be written as: d dt
∂Tr ∂ s˙
T
−
∂Tr ∂s
T
= − qv + GFS,S T JS GFS,S s¨
where all terms are n × 1 column vectors. Matrix P of 3 × n is defined as follows P 3×n
b FS,S = ω 3×3
∂ωFS,S ∂s
(3.58) C++
: (3.59)
3×n
which is convenient to calculate the last term on the right of 3.57. The reason for the minus sign in the definition of qv can now be explained. When writing the equations of motion, it is common practice to keep the term with s¨ on the left side of the minus sign and the quadratic velocity on the right side. That way, qv appears with a positive sign in the equations. The expression for matrix Q, equation 3.57, contains only terms that depend on the orientational specific coordinates s and velocities s˙ and are associated with edge FS of the coordinate system graph. Therefore, matrix Q can be calculated by the edge object. The constant diagonal matrix JS is associated with vertex S of the graph, and has to be supplied by the vertex object. The calculation of qv requires a collaborative effort between a vertex object and an edge object. A caller object should obtain Q from edge FS and JS from vertex S, and use them to calculate qv . Similarly, the caller should obtain matrix GFS,S from the edge and calculate the term GTFS,S JS GFS,S needed for equation 3.55. The caller object is discussed in the volume on Rigid Body Dynamics. Explicit expressions for the vectors and matrices discussed in this section for several popular systems of specific coordinates are presented in the corresponding sections 5.1.2, 5.1.3, 5.2.2 and 5.3.2. There is a clear distinction between the specific coordinates and the Generalized Coordinates used when dealing with multibody systems. In fact, the concept of specific coordinates provides a mechanism for selecting the generalized coordinates for a complex system. In our foundational implementation, the selection of specific coordinate systems, as well as that of generalized coordinates, is and option for the user. In a production implementation, both selections could easily be automated.
46
3.9
CHAPTER 3. THE KINEMATIC STATE
Specific Coordinates and Constraints
A rigid body by itself is free to move in space with 6 degrees of freedom. But a multibody system consisting of several rigid bodies may contain articulations or other mechanical devices that are attached to the bodies in the system. We refer to such mechanical devices as constraints. Constraints restrict the relative motion of the bodies and reduce the total number of degrees of freedom. For example, a system consisting of a cabinet and a cabinet door has a total of 12 degrees of freedom. But when hinges are installed, the door can only turn around the hinges and has only one degree of freedom, the relative angle of rotation. To count the number of degrees of freedom, consider the system as a single body with 6 degrees of freedom and add 1 for the rotation, for a total of 7. Another way is to consider the two bodies as independent and having a total of 12 degrees of freedom, and then the hinges suppress 5 of them, leaving 7 active. Now make a scoop with your hand and set an orange there. You have just removed 3 of the 6 degrees of freedom of the orange. Disregarding friction, the orange can turn about either one of two mutually perpendicular horizontal axes, or one vertical axis perpendicular to the palm of your hand, but its center will remain at a fixed position relative to the hand. The system hand-orange has 9 degrees of freedom. In Kinematics, constraints are described by means of constraint equations, which are enforced in addition to the equations of motion. In its simplest form, a constraint equation is a relation between the specific coordinates of the two bodies, where both sets of specific coordinates relate to the same coordinate system, usually the global system. Frequently, there is a whole set of constraint equations associated with a multibody system. If the equations are independent, they remove 1 degree of freedom each. Thus, a cabinet with a door on hinges would have 5 constraint equations, or a hand with an orange would have 3. Constraint equations are not discussed in this volume. However, when constraint equations are written in terms of specific coordinates and used in conjunction with the equations of motion, which are differential equations and imply differentiation, they too must be differentiated. The specific coordinates object must provide the necessary support for this differentiation. In this section we consider the terms that most frequently appear in the constraint equations, and calculate various derivatives for those terms. Consider once more coordinate systems F and S of figure 2.4, and let u be a vector that is constant in system S. In other words, the components of uS are independent of time. One example of such a vector is the radius vector rSP in figure 3.1, which extends from the origin S to the fixed point P. An observer traveling with system S would determine that such a vector remains unchanged as time elapses. However, another observer traveling with system F would see the vector changing as system S moves relative to F. The rotation motion of S, but not the translation, causes the components of the vector to change in system F. In other words, uF is time-dependent because its components depend on the orientational specific coordinates. We want to obtain its first and
3.9. SPECIFIC COORDINATES AND CONSTRAINTS
47
second time derivatives, expressed in terms of the specific coordinates and velocities. Using the coordinate transformation 2.9, we have: uF = AFS,F uS
(3.60)
Differentiating with respect to time, and since uS is constant, we obtain: u˙ F
≡
d (AFS,F uS ) = A˙ FS,F dt
3×1
3×1
3×3
uS
(3.61)
3×1
where A˙ FS,F is given in terms of s˙ by equation 3.42, and explicit expressions of AFS,F for several systems of orientational specific coordinates can be found in equations 5.6, 5.17, 5.26, and 5.44. The second time derivative is calculated by chain differentiation: ¨F = u
∂(A˙ FS,F uS ) ∂(A˙ FS,F uS ) s˙ + s¨ ∂s ∂ s˙
From equation 3.42, we have
C++
(3.62)
:
∂ A˙ FS,F ∂AFS,F = (3.63) ˙ ∂s ∂s Using this and the fact that uS does not depend on s˙ for the last term of equation 3.62, and interchanging uS and s˙ in the first term on the right, we obtain: ¨F u
= −R
uS
3×1
3×3
3×1
+
∂AFS,F ∂s
uS
s¨
(3×3)×n
3×1
n×1
where the 3 × 3 matrix R is defined as follows: R 3×3
= −
∂ A˙ FS,F ∂s
(3×3)×n
s˙
(3.64)
C++
(3.65)
n×1
Note that ∂ A˙ FS,F /∂s is an array of n matrices of size 3 × 3. Each of these matrices must be multiplied by the corresponding component of s˙ and the results accumulated, so that a single 3 × 3 matrix is obtained. The term ∂AFS,F /∂s in equation 3.64 is also an array of n matrices of size 3 × 3. Each one of the matrices must be individually multiplied by uS , resulting in an array of n column vectors, each of size 3 × 1, which is the same as a 3 × n matrix. This matrix must be multiplied by s¨, and the final result is a 3 × 1 column vector. The reason for the minus sign in the definition of R is the same as in equation 3.56. The terms of equation 3.64 are properly separated by object. As before, terms that contain AFS,F and s are calculated by an edge object, while uS is a property of a vertex and is calculated by a vertex object. In the last term on the right, s¨ has been isolated, the reason being the same as before: s¨ is an unknown, and it is to be calculated by solving the equations of motion.
48
CHAPTER 3. THE KINEMATIC STATE
Chapter 4 The Rigid Body Model A model is an abstraction, a representation of nature where we abstract certain features on interest to us, under the assumption that the features left out are not very important for our purposes. A model simplifies the picture and helps us to better understand the complexities of nature. A model, however, is limited by its very nature, and can never account for situations where the features left out are influential. The model called Rigid Body C++ consists of a conglomerate of particles of matter at fixed distances from each other. The body moves rigidly, meaning that the distance between any two given particles does not change during the motion. One of the consequences of such assumptions is that the motion can be described as the superposition of a rigid translation and a rigid rotation. But bodies found in nature are never rigid. It is possible for parts of a body to move with different velocities. When a force is suddenly applied to a real body, momentum and energy are delivered to a small particle of mass located at that point and the particle begins to move. Other particles in the body are not yet moving - nothing has caused them to move, no momentum or energy have arrived yet. In order to cause them to move, momentum and energy must flow from the point where the force is applied to the rest of the body. The particles are set in motion only when reached by this flow. Momentum and energy flow in the form of a shock wave. Although a detailed analysis of shock waves is well beyond our scope, we need to be aware of their presence and the role they play. By definition, a shock wave is a boundary between two regions where matter moves with different velocities. The boundary propagates with the speed of sound in the body. As the wave reaches other particles, it sets them in motion. When the wave reaches the surface of the body, it is reflected and scattered in different directions. A complex pattern of waves emerges, and vibrations may occur. In the end, the waves are absorbed, because all their energy is converted into kinetic energy and heat, and the body finally moves as if it were rigid. The rigid body model is valid if all this happens in a very short interval of time as compared with the time scale we are interested in.
49
50
CHAPTER 4. THE RIGID BODY MODEL
We can regard a shock wave as a mechanical phenomenon, but we can also regard it as a wave of information. When the wave reaches a particle, it causes the particle to change its state of motion. The initial motion of the particle is determined only by the wave and the initial state of the particle, not by the environment. We can regard this as if the wave had in fact delivered information to the particle, the information the particle needs to define its motion. We say that the shock wave carries mechanical information. Since shock waves travel with the speed of sound in the particular material, we also say that information in a real body travels with the speed of sound. In this work, we use the rigid body model. The model does not account for shock waves or speed of sound or vibrations or the propagation of mechanical information, because all of these are elastic phenomena, and elasticity does not exist in the rigid body model. Since propagation is necessary but not accounted for by the model, we must build it into the model. We do this by establishing a mathematical apparatus to describe propagation in the presence of rigidity. Propagation means how mechanical information that originates at one point of a mechanical system is made available at other points of that system. In a real body, momentum and energy propagate as waves. In a rigid model, the propagation of mechanical information must be mathematically simulated. Rigidity causes a rigid body to respond instantaneously to a force applied anywhere to that body. The fact that the motion can be described as the superposition of a rigid translation and a rigid rotation, as previously discussed, is a direct consequence of the assumption of rigidity and fully accounts for the propagation of mechanical information within the rigid body. It also leads to a great simplification of the equations of motion. Rigidity, however, causes serious complications when dealing with articulated figures, structures composed of several rigid bodies and articulations that constrain their relative motion. An articulated robot is a good example of an articulated figure. When a force is applied to one of the bodies, this body responds instantaneously. If articulations are present, they respond instantaneously too, causing other forces to be applied to other bodies, and so on. The entire structure is instantaneously affected by any force applied to any of the bodies. We must deal with the entire structure at once. We must devise ways for information on the applied force to become available at all other parts of the structure. Fortunately, some very powerful concepts and methods can be used to deal with articulated structures, such as the use of generalized coordinates, coordinate partitioning, the method of Lagrange multipliers, and Lagrange and Hamilton Mechanics. They are all of a very general nature, but when applied to rigid bodies, they all expect mechanical information to have been propagated beforehand and made available where needed. Propagation has not been fully exploited or even understood in the past, perhaps because of computer limitations. Methods that minimize the amount of propagation have been favored instead. This places limitations in the formulation of the models, for example in the selection of participating edges. The methodology discussed here encompasses all cases, including the traditional methods. Propagation is always needed, and its systematic analysis and understanding has important advantages.
4.1. PROPAGATION IN THE COORDINATE SYSTEM GRAPH
4.1
51
Propagation in the Coordinate System Graph
The coordinate system graph introduced in section 2.3 offers a unified view of all the coordinate systems present in a problem and their relationships. A vertex of the graph represents a coordinate system, and an edge connects two coordinate systems and represents their relative kinematic state. A problem involving the motion of a system of rigid bodies is typically solved in time steps. Initially, some edges are chosen and their kinematic states are given in such a way that the kinematic states of the remaining edges can be calculated. We refer to the selected edges as the participating edges. In the course of each time step, the dynamic equations of motion are solved and new kinematic states are calculated for the participating edges. Before the next step can proceed, the states of the remaining edges are updated, external actions such as applied forces or collisions which can depend on the states are also updated, and the algorithm is repeated. The propagation of kinematic information is the procedure by which we use a set of mathematical equations and procedures to update the states of the non-participating edges initially and at the end of each time step. C++ The general procedure of graph triangulation is used to propagate the kinematic information. Each step of the triangulation involves three edges forming a triangle, where the states of two of them are known and the remaining state is not. The calculation of the unknown state amounts to a relative coordinate transformation. A chain rule for propagation is obtained when the triangles are processed in the appropriate order. The initial selection of participating edges must be done in such a way that a chain rule is possible and there are no over-determined triangles. The calculation of a kinematic state as a function of others is an operation between kinematic states. Five different state operations can be identified: the binary operations of addition, direct subtraction and transposed subtraction, and the unary operations of inversion. and assignment or copy. C++ The quantities we are going to propagate are the state variables rFS,F , AFS,F , vFS,F and ωFS,F . In the following sections each operation is considered separately, and equations are obtained for all the calculations.
4.2
Addition of Kinematic States
In section 2.4 we have considered coordinate transformations between two systems, a “First” system F, and a “Second” system S, shown in figure 1.1. The corresponding coordinate system graph is shown in figure 2.4, where we have represented each system with a circle containing the system’s name and we have omitted the axes and unit vectors. Arrows joining the circles correlate with the order the subscripts appear in the notation. Consider now systems F and S as before, but add a “Third” coordinate system T, as shown in figure 4.1. We assume that the kinematic states of edges FS and ST are known. The operation of addition of kinematic states C++ is defined as the procedure for calculating the state of edge FT in terms of the two known states. This operation effectively propagates the kinematic information available for edges FS and ST, to the edge FT. The given quantities are the orientation matrices and the position, velocity and angular velocity
52
CHAPTER 4. THE RIGID BODY MODEL S
F
?
T
Figure 4.1: A coordinate system graph with three vertices, the “First”, “Second” and “Third” coordinate systems. Each system is represented by a circle. The graph is undirected, but edges have arrows that indicate the order of the subscripts in the notation. The unknown edge is marked with a question mark.
vectors for both pairs: AF S,F AST,S
rF S,F rST,S
vF S,F vST,S
ωF S,F ωST,S
for pair FS for pair ST
(4.1)
The quantities that need to be calculated are: AF T,F
rF T,F
vF T,F
ωF T,F
for pair FT
(4.2)
We begin with the orientation matrix. Let vT be an arbitrary vector defined in system T. We have: vS = AST,S vT vF = AFS,F vS = AFS.F AST,S vT
(4.3)
According to equation 2.9, the expression that transforms vT directly into vF using the orientation matrix AFT,F is: vF = AFT,F vT
(4.4)
Comparing this equation with the second equation in 4.3, and since v is an arbitrary vector, we have: AFT,F = AFS,F AST,S
(4.5)
which is the orientation matrix for the coordinate transformation FT. The position of the origin of system T relative to F is given by: rFT,F = rFS,F + rST,F
(4.6)
where all quantities are expressed in the same coordinate system, system F. However, rST,F is not one of the given quantities, so we have to calculate it using the transformation equation 2.9, which is valid for any vector: rST,F = AFS,F rST,S
(4.7)
4.3. DIRECT SUBTRACTION OF KINEMATIC STATES
53
Substituting this in equation 4.6 we have the result: rFT,F = rFS,F + AFS,F rST,S
(4.8)
The angular velocity is a vector just like any other, and converts in the same way as vector r: ωFT,F = ωFS,F + AFS,F ωST,S
(4.9)
The linear velocity vFT,F is given by: vFT,F = vFS,F + vST,F + ωFS,F × rST,F
(4.10)
where all quantities have been expressed in system F. However, this equations can not be used as-is because vST,F and rST,F are not given. They have to be calculated from given quantities, resulting in the following final expression: vFT,F = vFS,F + AFS,F vST,S + ωFS,F × (AFS,F rST,S )
(4.11)
Equations 4.5, 4.8, 4.9 and 4.11 completely define the kinematic state of system T relative to system F, and thus the operation of addition of kinematic states.
4.3
Direct Subtraction of Kinematic States
Figure 4.2 shows the subgraph for the direct subtraction
C++ C++ C++
of kinematic states. In this
S
F
?
T
Figure 4.2: A coordinate system graph illustrating the direct subtraction of kinematic states. The unknown edge is marked with a question mark.
case, the states of edges FS and TS are given, and the state of edge FT is the unknown. The solution can be obtained by following the same procedures outlined in the previous section, or, alternatively, by simply interchanging S and T in figure 4.1 and in equations 4.5, 4.8, 4.9 and 4.11, and treating the resulting edge FT as the unknown. The results are, of course, the same. There is no need to go over the details because the calculations are simple. For the orientation matrix: AFT,F = AFS,F ATS,T T
(4.12)
54
CHAPTER 4. THE RIGID BODY MODEL
For the position vector: rFT,F = rFS,F − AFT,F rTS,T
(4.13)
Note that here we have used AFT,F just calculated, since rTS,F = AFT,F rTS,T . A similar transformation holds for the angular velocity: ωFT,F = ωFS,F − AFT,F ωTS,T
(4.14)
And finally, for the linear velocity: vFT,F = vFS,F − AFT,F vTS,T − ωFT,F × (AFT,F rTS,T )
4.4
(4.15)
Transposed Subtraction of Kinematic States
Figure 4.3 shows the coordinate system subgraph for transposed subtraction
C++ C++ C++
. This
S
F
?
T
Figure 4.3: A coordinate system graph illustrating the transposed subtraction of kinematic states. The unknown edge is marked with a question mark.
case can be obtained either by performing calculations similar to those outlined in section 4.2 or by interchanging F and S in figure 4.1 and in equations 4.5, 4.8, 4.9 and 4.11, and treating the resulting edge FT as the unknown. The result for the orientation matrix is: AFT,F = ASF,S T AST,S
(4.16)
For the position radius vector: rFT,F = ASF,S T (rST,S − rSF,S )
(4.17)
For the angular velocity: ωFT,F = ASF,S T (ωST,S − ωSF,S )
(4.18)
And for the linear velocity: vFT,F = ASF,S T (vST,S − vSF,S − ωSF,S × (rST,S − rSF,S ))
(4.19)
4.5. INVERSION OF KINEMATIC STATES
4.5
55
Inversion of Kinematic States
The coordinate system graph for the inversion C++ C++ C++ of kinematic states is shown in figure 4.4. The state of edge FS is given, and the unknown state is that of edge SF. The calculations for
S F F
S
?
Figure 4.4: A coordinate system graph illustrating the inversion of kinematic states. The unknown edge is marked with a question mark.
this case are simple. Only the results are reported. For the orientation matrix: ASF,S = AFS,F T
(4.20)
For the position vector: rSF,S = −AFS,F T rFS,F
(4.21)
since rSF,S = −rFS,S . For the angular velocity: ωSF,S = −AFS,F T ωFS,F
(4.22)
where we have used that ωSF,S = −ωFS,S . An finally for the linear velocity: vSF,S = ASF,S (−vFS,F + ωFS,F × rFS,F ) where we use that ASF,S = AFS,F T and the expression in parenthesis is vSF,F .
(4.23)
56
CHAPTER 4. THE RIGID BODY MODEL
Chapter 5 Orientation Coordinates 5.1
Euler Angles
In chapter 1 we have defined the orientation matrix AF S,F as a 3×3 matrix that uniquely defines the angular orientation of a coordinate system S relative to another coordinate system F. We recall that the symbols F and S are hints for “first” and “second”, respectively. The columns of the orientation matrix are the components of the unit vectors of system S, given in system F. The orientation matrix is very intuitive and contains a great deal of useful information - the components of the unit vectors, which are frequently needed anyway. It has led us to important conclusions, such as the implementation of coordinate transformations and the definition of the angular velocity ω. But the orientation matrix contains 9 quantities, only 3 of which are independent. This is inconvenient for calculations. The large number of dependent quantities adversely affects computational efficiency. There are other ways to uniquely define the angular orientation of system S relative to F, such as the Euler angles ϕ, ϑ, ψ discussed in this chapter C++, or the Euler Parameters discussed in the next chapter. Euler angles are independent variables. This simplifies many calculations, particularly when partial derivatives are involved as in section 3.4. But they are angles, which results in complex formulas with many trigonometric functions and is not very beneficial for computational efficiency. In practice, a choice between the orientation matrix and a reduced set such as the Euler angles seldom arises. It is nearly impossible to use one of them and abstain from using the other. The best strategy is to implement both and use the most appropriate one in each particular case. This strategy implies, of course, the need for effective conversions between the two methods.
5.1.1
Conventions
The Euler angles are a set of three independent angles ϕ, ϑ, ψ that uniquely define the relative orientation of two coordinate systems. If values for the three angles are given, it is possible to uniquely calculate the nine components of the unit vectors of either system with reference to the
57
58
CHAPTER 5. ORIENTATION COORDINATES
other. Over the years, Euler angles have been used to study the motion of ships, aircraft, satellites, planets, rigid bodies, molecules, and atomic particles, just to name some of the most popular applications. There is more than one way to define Euler angles, and the different definitions are known as conventions. To create a convention, an initial system x, y, z is postulated, and three successive rotations are applied to it, by angles ϕ, ϑ and ψ, respectively, resulting in the final system. The axes taken for the rotations differ, as well as the directions of the rotations, giving rise to the various conventions. Here, we use only two conventions, the ZXZ convention, and the ZYX convention.
5.1.2
The ZXZ Convention
In this section we discuss the ZXZ Convention, for Euler angles C++, where the first rotation is taken about the initial axis +z, causing x and y to move to different positions. 1 The second rotation is about the new axis +x, causing y and z to move to new positions, and the final rotation is about the final +z. Hence the name ZXZ we use for this convention. Our ZXZ convention is the same main convention used by Goldstein [13] and has also been used by Shabana. [14]
z w0 w1 v3
v2
ϑ
ϑ
ψ
w3
v1
w2
ϕ O u0 x
ψ ϕ
u3
v0
y
u1 u 2
Figure 5.1: Definition of Euler angles according to the ZXZ convention.
Figure 5.1 illustrates the four different coordinate systems involved in the transformation, all with the same origin O but with different orientations, all of them orthogonal, cartesian and right1
Rotations follow the right-hand rule. A rotation about +z means that the positive direction for measuring the angle is determined by the fingers of the right hand when the thumb is placed in the direction of the +z axis. The corkscrew rule is also applicable: the positive direction for the angle is the direction the corkscrew has to spin in order to advance in the +z direction.
5.1. EULER ANGLES
59
handed. The designations of the systems and their respective unit vectors are: S0 S1 S2 S3
u 0 , v0 , w 0 u 1 , v1 , w 1 u 2 , v2 , w 2 u 3 , v3 , w 3
black green blue red
The initial system (5.1) The final system
The initial black system u0 , v0 , w0 undergoes a rotation around +z by an angle ϕ. Unit vector u0 moves to position u1 , v0 to position v1 , and w0 does not move so that w1 coincides with w0 . This rotation results in the green system u1 , v1 , w1 , where u1 and v1 are still in the xy-plane. The direction of u1 is called the line of nodes. It is easy to determine the components of u1 , v1 , and w1 expressed in system u0 , v0 , w0 , and to write the corresponding orientation matrix: cos(ϕ) − sin(ϕ) 0 A01,0 = sin(ϕ) cos(ϕ) 0 0 0 1
(5.2)
Next, the green system u1 , v1 , w1 undergoes a rotation by angle ϑ around the line of nodes +u1 . This moves v1 to position v2 and w1 to position w2 , while u2 coincides with u1 , both still in the xy-plane, and results in the blue system u2 , v2 , w2 . The corresponding orientation matrix is: 1 0 0 A12,1 = 0 cos(ϑ) − sin(ϑ) 0 sin(ϑ) cos(ϑ)
(5.3)
Finally, the blue system u2 , v2 , w2 rotates around +w2 by an angle ψ, causing u2 to move to position u3 and v2 to go to position v3 , while w3 remains where w2 was. The final red system u3 , v3 , w3 is obtained. This time the orientation matrix is: A23,2
cos(ψ) − sin(ψ) 0 = sin(ψ) cos(ψ) 0 0 0 1
(5.4)
The final orientation matrix expresses the components of the unit vectors u3 , v3 , w3 directly in terms of the initial unit vectors u0 , v0 , w0 , and, according to equation 4.5 is given by: A03,0 = A01,0 A12,1 A23,2 All calculations done, the result for the ZXZ convention is:
(5.5) C++
AZXZ = (5.6) cos(ϕ) cos(ψ) − sin(ϕ) cos(ϑ) sin(ψ) − cos(ϕ) sin(ψ) − sin(ϕ) cos(ϑ) cos(ψ) sin(ϕ) sin(ϑ) sin(ϕ) cos(ψ) + cos(ϕ) cos(ϑ) sin(ψ) − sin(ϕ) sin(ψ) + cos(ϕ) cos(ϑ) cos(ψ) − cos(ϕ) sin(ϑ) sin(ϑ) sin(ψ) sin(ϑ) cos(ψ) cos(ϑ)
60
CHAPTER 5. ORIENTATION COORDINATES
where we have written AZXZ for A04,0 to identify the ZXZ convention. The ZXZ convention has a singularity when sin(ϑ) = 0, or ϑ is 0 or π, because ϕ and ψ can not be told apart. The expression for the orientation matrix, equation 5.6, is correct even at the singularity. However, the equations of Kinematics also require the converse to be possible, the ability to calculate the Euler angles from a given orientation matrix. This can not be done at the singularity, and would be inaccurate near the singularity. Therefore, the ZXZ convention should not be used at or near the singularity. Strategies to deal with singularities are discussed in Section 5.1.4. Away from the singularity, the problem of calculating ϕ, ϑ, ψ from the orientation matrix is overdetermined, because there are more equations than unknowns, but one can always use some of the equations and ignore the rest, or use the remaining equations for a numerical check of accuracy. One way to do it is to calculate ψ as tan−1 (A31 /A32 , then obtain sin(ϑ) from either A31 or A32 , and use this value along with A33 to obtain ϑ. Once sin(ϑ) is known, ϕ can be obtained from A13 and A23 . Note that both the sine and cosine of an angle are needed to calculate the angle uniquely.
The Angular Velocity in the ZXZ Convention Let ϕ, ϑ, ψ be the Euler angles used to specify the orientation of coordinate system S with reference to coordinate system F, based on the ZXZ convention. As before, F stands for “First” and S for “Second.” Equation 5.6 can be used to calculate the corresponding orientation matrix AF S,F , which in turn contains the components of the unit vectors of system S, and thus the orientation of S is uniquely defined. If the Euler angles are functions of time, then system S is moving relative to F, and we need an explicit expression for the two G matrices defined in equation 3.43 that will allow us to calculate the angular velocity introduced in section 3.5 in terms of the time derivatives of the Euler angles: C++ ˙ ψ] ˙ T ωFS,S = GFS,S [ϕ, ˙ ϑ, ˙ ψ] ˙ T ωFS,F = GFS,F [ϕ, ˙ ϑ,
(5.7)
˙ ψ] ˙ T is a where the two G matrices are of size 3 × 3 and depend only on ϕ, ϑ and ψ, and [ϕ, ˙ ϑ, column vector formed from the time derivatives of the Euler angles. Explicit expressions for the two G matrices are obtained by differentiation of equation 5.6 and substitution of the results in equations 3.43 and 3.42. The calculations are long but simple, and the results are also very simple: C++
sin(ϑ) sin(ψ) cos(ψ) 0 ¯ GFS,S (ZXZ) ≡ G(ZXZ) = sin(ϑ) cos(ψ) − sin(ψ) 0 cos(ϑ) 0 1
(5.8)
0 cos(ϕ) sin(ϑ) sin(ϕ) GFS,F (ZXZ) ≡ G(ZXZ) = 0 sin(ϕ) − sin(ϑ) cos(ϕ) 1 0 cos(ϑ)
(5.9)
5.1. EULER ANGLES
61
The G matrices are intended to calculate ωFS,F and ωFS,S when the time derivatives of the Euler angles are known. The converse calculation is also possible because the G matrices are nonsingular and can both be inverted, except at the ZXZ singularity at ϑ = 0, π. The inverse matrices can be calculated directly from equations 5.8 and 5.9. The results are: C++ −1 = ¯ GFS,S (ZXZ) −1 ≡ G(ZXZ)
1 sin(ϑ)
sin(ψ) cos(ψ) 0 sin(ϑ) cos(ψ) − sin(ϑ) sin(ψ) 0 − cos(ϑ) sin(ψ) − cos(ϑ) cos(ψ) sin(ϑ)
(5.10)
GFS,F (ZXZ) −1 ≡ G(ZXZ) −1 =
1 sin(ϑ)
− sin(ϕ) cos(ϑ) cos(ϕ) cos(ϑ) sin(ϑ) cos(ϕ) sin(ϑ) sin(ϕ) sin(ϑ) 0 sin(ϕ) − cos(ϕ) 0
(5.11)
In both equations, the denominator sin(ϑ) clearly indicates the presence of the ZXZ singularity at sin(ϑ) = 0. Matrix P was defined near the end of section 3.6. It contains the derivatives of the rotational kinetic energy with respect to the Euler angles. Matrix P is 3 × 3 in this case and is given by: C++ ω ¯ 1 (∂ ω ¯ 1 /∂ϕ) ω ¯ 1 (∂ ω ¯ 1 /∂ϑ) ω ¯ 1 (∂ ω ¯ 1 /∂ψ) P= ω ¯ 2 (∂ ω ¯ 2 /∂ϕ) ω ¯ 2 (∂ ω ¯ 2 /∂ϑ) ω ¯ 2 (∂ ω ¯ 2 /∂ψ) ω ¯ 3 (∂ ω ¯ 3 /∂ϕ) ω ¯ 3 (∂ ω ¯ 3 /∂ϑ) ω ¯ 3 (∂ ω ¯ 3 /∂ψ)
(5.12)
This expression is convention-independent, provided the values and derivatives of the angular velocity are calculated for the corresponding convention.
5.1.3
The ZYX Convention
In the ZYX Convention C++, the rotations are taken in the +z, +y and +x order. This convention has been used by Goldstein [13] with the name xyz. Figure 5.2 illustrates the four coordinate systems involved in the transformation. The designations of the systems and their respective unit vectors are, as before: S0 S1 S2 S3
u 0 , v0 , w 0 u 1 , v1 , w 1 u 2 , v2 , w 2 u 3 , v3 , w 3
black green blue red
The initial system (5.13) The final system
The initial black system u0 , v0 , w0 undergoes a rotation around +z by an angle ϕ. Unit vector u0 moves to position u1 and v0 to position v1 , leaving w1 in coincidence with w0 . This rotation results in the green system u1 , v1 , w1 , where u1 and v1 are still in the xy-plane. It is easy to determine
62
CHAPTER 5. ORIENTATION COORDINATES z
w3
ϑ ψ w0 w1
w2 ψ ϕ
O u0 x
ϕ
v3 v2 v1 v0
ϑ u 2 u3
y
u1
Figure 5.2: Definition of Euler angles according to the ZYX convention.
the components of u1 , v1 , and w1 expressed in system u0 , v0 , w0 , and to write the corresponding orientation matrix: A01,0
cos(ϕ) − sin(ϕ) 0 = sin(ϕ) cos(ϕ) 0 0 0 1
(5.14)
Next, the green system u1 , v1 , w1 undergoes a rotation by angle ϑ around +v1 . This moves u1 to position u2 and w1 to position w2 , while v2 coincides with v1 , both still in the xy-plane, and results in the blue system u2 , v2 , w2 . The corresponding orientation matrix is: A12,1 =
cos(ϑ) 0 sin(ϑ) 0 1 0 − sin(ϑ) 0 cos(ϑ)
(5.15)
Finally, the blue system u2 , v2 , w2 rotates around +u2 by an angle ψ, causing v2 to move to position v3 and w2 to go to position w3 , while u3 stays where u2 was. The final red system u3 , v3 , w3 is obtained. This time the orientation matrix is: A23,2
1 0 0 = 0 cos(ψ) − sin(ψ) 0 sin(ψ) cos(ψ)
The final orientation matrix is given by equation 4.5. The result for the ZYX convention is:
(5.16) C++
AZYX = (5.17) cos(ϕ) cos(ϑ) − sin(ϕ) cos(ψ) + cos(ϕ) sin(ϑ) sin(ψ) sin(ϕ) sin(ψ) + cos(ϕ) sin(ϑ) cos(ψ) sin(ϕ) cos(ϑ) cos(ϕ) cos(ψ) + sin(ϕ) sin(ϑ) sin(ψ) − cos(ϕ) sin(ψ) + sin(ϕ) sin(ϑ) sin(ψ) − sin(ϑ) cos(ϑ) sin(ψ) cos(ϑ) cos(ψ)
5.1. EULER ANGLES
63
where we have written AZYX for A04,0 to identify the ZYX convention. The ZYX convention has a singularity when cos(ϑ) = 0, or ϑ is π/2 or 3π/2, because ϕ and ψ can not be told apart. The expression for the orientation matrix, equation 5.17, is correct even at the singularity. However, the calculation of the Euler angles from a given orientation can not be done at the singularity, and would be inaccurate near the singularity. Therefore, the ZYX convention should not be used at or near the singularity. Strategies to deal with singularities are discussed in Section 5.1.4. Away from the singularity, the Euler angles can be calculated by a procedure similar to the one discussed at the end of Section 5.1.2.
The Angular Velocity in the ZYX Convention Following a procedure similar to the one outlined in section 5.1.2, we can obtain explicit expressions for the two G matrices in the case of the ZYX convention. We recall that the G matrices are used to calculate the angular velocity C++ in terms of the time derivatives of the Euler angles. The expressions are obtained by differentiation of equation 5.17 and substitution of the results in equation 3.42, and then following the same path as we did in section 5.1.2. The results are: C++ − sin(ϑ) 0 1 cos(ϑ) sin(ψ) cos(ψ) 0 cos(ϑ) cos(ψ) − sin(ψ) 0
(5.18)
0 − sin(ϕ) cos(ϕ) cos(ϑ) GFS,F (ZY X) ≡ G(ZXZ) = 0 cos(ϕ) sin(ϕ) cos(ϑ) 1 0 − sin(ϑ)
(5.19)
¯ GFS,S (ZY X) ≡ G(ZXZ) =
The corresponding inverse matrices are:
C++
¯ GFS,S (ZY X) −1 ≡ G(ZY X) −1 =
1 cos(ϑ)
0 sin(ψ) cos(ψ) 0 cos(ϑ) cos(ψ) − cos(ϑ) sin(ψ) cos(ϑ) sin(ϑ) sin(ψ) sin(ϑ) cos(ψ)
(5.20)
GFS,F (ZY X) −1 ≡ G(ZY X) −1 =
1 cos(ϑ)
cos(ϕ) sin(ϑ) sin(ϕ) sin(ϑ) cos(ϑ) − sin(ϕ) cos(ϑ) cos(ϕ) cos(ϑ) 0 cos(ϕ) sin(ϕ) 0
(5.21)
In both equations, the denominator cos(ϑ) clearly indicates the presence of the ZYX singularity at cos(ϑ) = 0. As before, none of these matrices are tensors. Matrix P, as defined near the end of section 3.6, is of size 3 × 3 and is given by expression 5.12, which is convention-independent.
64
CHAPTER 5. ORIENTATION COORDINATES
5.1.4
Dealing with Convention Singularities
All Euler angle conventions have singularities C++, including the two conventions discussed here. If a computer simulation that uses Euler angles is approaching a singularity, some action must be taken. The following strategy relies on switching between two conventions that have their singularities in different places. If the simulation is near a convention’s singularity, then the other convention is away from its singularity and is safe to use. The strategy is simple and works well in practice. Specifically: 1. For each convention, establish a danger zone where the convention should not be used. 2. If the simulation approaches the danger zone of the current convention, stop the simulation. 3. Using the current values of the Euler angles and their time derivatives, calculate the current orientation matrix and angular velocity. 4. Find another convention with a non-overlapping danger zone. 5. Using the values of the orientation matrix and angular velocity just obtained, find the Euler angles and their time derivatives in the new convention. 6. Resume the simulation, using the new convention. This strategy only changes the underlying mathematics, but does not change any kinematic or dynamic properties and is completely transparent as long as the motion of the mechanical system is concerned. Of course, in the course of a run, a number of back and forth switches may occur for each coordinate system, and there is an issue of computational efficiency. However, if the two conventions are chosen in such a way that their danger zones are far apart, there will be many time steps between switches, and hopefully fewer overall switches.
5.2
Euler Parameters
In sections 1.3.3 and 1.3.4 we considered a rotation of a coordinate system F by an angle α around an axis defined by a unit vector a and we argued that the rotation matrix given by equation 1.48 in terms of a and α can be used to describe any orientation. This concept is formalized here by the introduction of the Euler Parameters C++, a set of four quantities defined in terms of the angle of rotation and the three components of the axis, as follows: e0 = cos(α/2) e1 = a1 sin(α/2) e2 = a2 sin(α/2) e3 = a3 sin(α/2)
(5.22)
5.2. EULER PARAMETERS
65
where a1 , a2 and a3 are the components of the unit vector a. The four Euler parameters are not independent. They satisfy the relation: e0 2 + e1 2 + e2 2 + e3 2 = 1
(5.23)
and as a consequence, when they depend on time, they also satisfy the relation: e0 e˙0 + e1 e˙1 + e2 e˙2 + e3 e˙3 = 0
(5.24)
The Euler parameters are very popular. They are easy to use and result in simple formulations that simplify computation. This last statement, however, needs to be re-examined, because the present tendency in computation is to hide complexity in the internal implementation of an object, and evaluate simplicity or ease of use in terms of the external behavior and efficiency of the object rather than its internal structure. One disadvantage of the Euler parameters is that they are not independent, as Euler angles are, which creates some complications. Another is that they are less intuitive than Euler angles and rotations. Again, this is not much of a disadvantage in modern computation.
5.2.1
Orientation Matrix
In this section, we use the definition of the Euler parameters in terms of an angle and axis of rotation, equation 5.22, to express the orientation matrix directly in terms of the Euler parameters. If coordinate system S is rotated by angle α around axis a, then, according to equation 1.51, the orientation matrix AF S,F for the rotated system S is equal to the rotation matrix R(a, α) that describes the rotation, which is in turn given in equation 1.48 in terms of α and the components of a. To effect the conversion to Euler parameters, we use the following trigonometric identities: sin α = 2 sin(α/2) cos(α/2) cos α = 1 − 2 sin2 (α/2) After a short calculation, and using equation 1.51, we obtain:
AFS,F
(5.25) C++
1 − 2e2 2 − 2e3 2 2e1 e2 − 2e0 e3 2e1 e3 + 2e0 e2 = 2e1 e2 + 2e0 e3 1 − 2e1 2 − 2e3 2 2e2 e3 − 2e0 e1 2e1 e3 − 2e0 e2 2e2 e3 + 2e0 e1 1 − 2e1 2 − 2e2 2
(5.26)
The algebraic form of the expression of A is not unique. It can be written in many forms using the constraint equation 5.23 without affecting the numerical values of the elements of the matrix. As discussed near equation 1.34, the columns of the orientation matrix are the components of the unit vectors of system S, given in system F. Therefore, with the Euler parameters given, the matrix can be calculated and the orientation of system S is uniquely defined.
66
5.2.2
CHAPTER 5. ORIENTATION COORDINATES
Angular Velocity
When the Euler parameters are functions of time, system S is moving. To calculate the angular velocity we follow a procedure similar to the one outlined in section 3.5 and subsequently used in sections 5.1.2 and 5.1.3. Let e = [e0 , e1 , e2 , e3 ] T be the 4 × 1 column vector of Euler parameters. We seek two relations of the form
(5.27) C++
ωFS,S = GFS,S e˙ T ωFS,F = GFS,F e˙ T
(5.28)
similar to equations 3.43, where now the G matrices are of size 3 × 4. As usual, the calculations are long but straightforward and the results are simple: C++ GFS,S
−2e1 2e0 2e3 −2e2 ¯ ≡ G = −2e2 −2e3 2e0 2e1 −2e3 2e2 −2e1 2e0
(5.29)
GFS,F
−2e1 2e0 −2e3 2e2 ≡ G = −2e2 2e3 2e0 −2e1 −2e3 −2e2 2e1 2e0
(5.30)
The following two relations can be verified by inspection and using equation 5.23: GFS,S T GFS,S = 4 I GFS,F T GFS,F = 4 I
(5.31)
where I is the 3 × 3 identity matrix. Premultiplying the first equation 5.28 by GFS,S T and the second by GFS,F T , the following two equations are obtained: e˙ = e˙ =
1 GFS,S ωFS,S 4 1 GFS,F ωFS,F 4
(5.32)
These equations are used to calculate the time derivatives of the Euler parameters when either ωFS,S or ωFS,F are given. The two G matrices can be combined with equation 5.24 to create two ¯ and B, respectively, which have some very useful 4 × 4 matrices BFS,S and BFS,F , also known as B C++ properties. They are defined as follows:
BFS,S
e0 e1 e2 e3 e0 e3 −e2 ¯ = −e1 ≡B −e2 −e3 e0 e1 −e3 e2 −e1 e0
(5.33)
5.2. EULER PARAMETERS
67
and
BFS,F
e0 e1 e2 e3 −e1 e0 −e3 e2 ≡B= −e2 e3 e0 −e1 −e3 −e2 e1 e0
(5.34)
By simple inspection, it can be proved that the two B matrices are orthogonal: ¯ −1 = B ¯T B B
−1
= B
(5.35)
T
(5.36)
and, of course: ¯ = Det(B) = 1 Det(B)
(5.37)
The property of orthogonality is so useful that it alone is a justification for the definition. In addition, the following properties also hold and can be verified by inspection: ¯T =B ¯TB= BB
[1] [0]
[0] T AFS,F
(5.38)
where the term on the right is a 4 × 4 matrix, containing the 1 × 1 matrix [1] with a single element equal to 1, the 3 × 1 column vector [0] with 3 components all equal to 0, the 1 × 3 transpose of the column vector, and matrix AFS,F of equation 5.26. Equation 5.38 offers an alternative way to calculate AFS,F when the values of the parameters are known. Using equations 5.28 and equation 5.24, and the orthogonality of the B matrices, the following relations are easily demonstrated: 0 ω ¯ 1 /2 ω ¯ 2 /2 ω ¯ 3 /2 e˙ 0 e˙ 1 e˙ 2 e˙ 3
e˙ 0 ¯ e˙ 1 = B e˙ 2 e˙ 3
¯T = B
0 ω ¯ 1 /2 ω ¯ 2 /2 ω ¯ 3 /2
(5.39)
(5.40)
¯ and: where ω ¯1, ω ¯ 2 and ω ¯ 3 are the three components of ω, 0 ω1 /2 ω2 /2 ω3 /2
e˙ 0 e˙ = B 1 e˙ 2 e˙ 3
(5.41)
68
CHAPTER 5. ORIENTATION COORDINATES e˙ 0 e˙ 1 e˙ 2 e˙ 3
= BT
0 ω1 /2 ω2 /2 ω3 /2
(5.42)
where ω1 , ω2 and ω3 are the three components of ω. Equations 5.39 and 5.41 are the same as equations 5.28 combined with equation 5.24. Equations 5.40 and 5.42 solve the converse problem: how to calculate the time derivatives of the Euler parameters when the angular velocity is known. Matrix P, as defined near the end of section 3.6, is now of size 3 × 4 and contains the derivatives of the rotational kinetic energy with respect to the Euler parameters. In this case it can be calculated explicitly, and is given by: C++ P=2
5.3
ω ¯ 1 e˙ 1 −¯ ω1 e˙ 0 −¯ ω1 e˙ 3 ω ¯ 1 e˙ 2 ω ¯ 2 e˙ 2 ω ¯ 2 e˙ 3 −¯ ω2 e˙ 0 −¯ ω2 e˙ 1 ω ¯ 3 e˙ 3 −¯ ω3 e˙ 2 ω ¯ 3 e˙ 1 −¯ ω3 e˙ 0
(5.43)
Axial Rotator
The axial rotator is a constrained orientator with only one degree of freedom: coordinate system S can only rotate around axis xF of system F, without sliding in the direction parallel to the axis, as shown in figure 5.3. C++ The angle or rotation α determines the angular position of S
yF
yS
α
F
zF
xF
S
xS
α zS Figure 5.3: The Axial Rotator is an orientator that allows coordinate system S to rotate around axis xF of system F, without sliding. relative to F and is used as the only specific coordinate for the axial rotator. α is measured in the direction specified by the right-hand rule. The axial rotator is used mainly for the cylindrical joint, a kinematic constraint that restricts the relative motion of two rigid bodies to rotation around an axis.
5.3. AXIAL ROTATOR
5.3.1
69
Orientation Matrix
The orientation matrix for the axial rotator is obtained by examination of figure 5.3, and using the property that the columns of the orientation matrix are the components of the unit vectors of system S, expressed in system F. The result is: C++ 1 0 0 AFS,F = 0 cos(α) − sin(α) 0 sin(α) cos(α)
5.3.2
(5.44)
Angular Velocity
To calculate the angular velocity we follow a procedure similar to the one outlined in section 3.5. Let e = [α] T
(5.45)
be the 1 × 1 column vector of specific coordinates for the axial rotator. We seek two relations of the form C++ ωFS,S = GFS,S e˙ T ωFS,F = GFS,F e˙ T
(5.46)
similar to equations 3.43, where now the G matrices are of size 3×1. This time both the calculations and the results are simple: C++ 1 ¯= 0 GFS,S ≡ G 0
(5.47)
1 ≡G= 0 0
(5.48)
ω ≡ ωFS,F = [α, ˙ 0, 0] T
(5.49)
¯ ≡ ωFS,S = [α, ω ˙ 0, 0] T
(5.50)
GFS,F This means that: and
These last two equations are quite obvious. The two D matrices and the P matrix introduced near the end of section 3.6 are all of size 3 × 1 for the axial rotator. They can be obtained by differentiating equations 5.49 and 5.50 directly: C++ DFS,F = [0, 0, 0] T DFS,S = [0, 0, 0] T P = [0, 0, 0] T
(5.51)
70
5.4
CHAPTER 5. ORIENTATION COORDINATES
Implementation
This chapter is a good example of object-oriented design. The code consists of an abstract base class that offers all the required services. In our implementation, this base class is Orientator. The outside world only needs a pointer or reference of type base class to obtain all the services, and never needs to know how the services are implemented or which particular type of orientational specific coordinates are being used. The base class contains two arrays that hold the values and the time derivatives of the orientational specific coordinates. The services themselves are provided by classes derived from the base. In the current release, these classes are EulerAngles for the Euler angles, EulerParams for the Euler parameters, and AxialRotator for the axial rotator. Two additional classes, EulerAnglesZXZ and EulerAnglesZYX, both derived from EulerAngles , implement the ZXZ and the ZYX Euler angles conventions, respectively. Additional types of orientational specific coordinates can easily be implemented by deriving other classes from the base, without affecting the existing code or the existing functionality. It is also possible to derive classes from the derived classes, for example one could implement other Euler angles conventions by deriving classes from EulerAngles .
Part II Code Documentation
71
72
CHAPTER 5. ORIENTATION COORDINATES
A man is trying to make friends with a C/C++ programmer. − − − − − −
How many children do you have? Two. How old is your first child? Five. And how old is your second child? I don’t have a second child. I only have a zero-th child and a first child.
Chapter 6 C++ Code for Rigid Body Kinematics Presented in this chapter are high level descriptions of the families of classes developed to support the object foundation of Rigid Body Kinematics. More detailed descriptions of each family and the classes that it consists of can be found in the following chapters. A Family of Classes is a set of classes that share a common purpose. For example, all classes derived from a base abstract or parameterized class support the services defined in the interface, and, as such, they are all part of the same family. A family can include more than one group of base-derived classes, and also any individual classes that are associated with the definition of the family and are used to provide similar services.
73
74
6.1
CHAPTER 6. C++ CODE FOR RIGID BODY KINEMATICS
All Families
Family
Description
Classes
Specific Coordinates
Services for translational and orientational specific coordinate systems with full support for rigid body kinematic and dynamic calculations. Includes two abstract base classes: Translator, with support for regular x, y, z translations, and Orientator, with support for Euler angles with two conventions, Euler parameters, and an Axial Rotator.
AxialRotator EulerAngles EulerAnglesZXZ EulerAnglesZYX EulerParams Orientator Translator TranslatorXYZ OrthoMatrix
Graphs
Services for graphs including trees, breadth-first search, adjacency level structures, connected components and paths, and state services. Consists of four parameterized base classes, one abstract parameterized base class, and several concrete and derived classes with support for coordinate system graphs and bodies and constraints graphs.
BCComponent BCEdge BCGraph BCVertex CSEdge CSGraph CSState CSVector CSVertex PComponent PComponentWithTree PEdge PGraph PPath PPathClosed PPathOpen PVertex
Mechanical
Services for rigid bodies, inertia and collisions. Consists of two abstract classes and several concrete and derived classes.
Body BodyManager
6.2. ALL CLASSES
6.2
All Classes
Class name AxialRotator BCComponent BCEdge BCGraph BCVertex Body BodyManager CSEdge CSGraph CSState CSVector
Description This class describes the Axial Rotator set of specific coordinates, which consists of a single angle, and provides all the required services to the Orientator interface. A class derived from PComponentWithTree that describes a connected component of a BCGraph object. A class derived from PEdge that describes an edge of a BCGraph object. A class derived from PGraph that describes the graph of an articulated multibody system, where the vertices are rigid bodies and the edges are constraints. A class derived from PVertex that describes a vertex of a BCGraph. A Body is an entity that has size, shape and position and can be treated as a whole. This class owns and manages all Body objects in a mechanical system. A class derived from PEdge that describes an edge of a CSGraph object. A class derived from PGraph that describes a Coordinate System Graph, an undirected graph that represents a set of coordinate systems and the transformations between them. The kinematic state of a coordinate system in the coordinate system graph. A three-dimensional vector that knows the coordinate system where it is expressed.
CSVertex
A class derived from PVertex that describes a vertex in a CSGraph object.
EulerAngles
An abstract class derived from Orientator that serves as base for all Euler angles classes.
EulerAnglesZXZ
EulerAnglesZYX EulerParams
This class describes the ZXZ Convention for the Euler angles specific coordinates and provides the corresponding services to the Orientator interface. This class describes the ZYX Convention for the Euler angles specific coordinates and provides the corresponding services to the Orientator interface. This class describes the Euler parameter specific coordinates and provides the corresponding services to the Orientator interface.
75
76 Class name (cntd) Orientator OrthoMatrix PComponent PComponentWithTree PEdge PGraph
PPath
PPathClosed
CHAPTER 6. C++ CODE FOR RIGID BODY KINEMATICS Description Abstract class used as base for all orientational specific coordinate classes. The class provides services for conversion between state variables and orientational specific coordinates. A class derived from Matrix3 that describes an orthogonal matrix of size 3 × 3. A parameterized class that describes a connected component of a PGraph object and is used as base for all specialized component classes. A parameterized class derived from PComponent that describes a connected component of a PGraph and a spanning tree for that component. A parameterized class that describes an edge of a mathematical graph and is used as base for all specialized edge classes. A parameterized class that describes a mathematical graph and is used as base for all specialized graph classes. A parameterized class describing a connected path in a PGraph object and used as base for all path classes. The direction of the path is left-to-right in array PathEdges. A PPath with one edge does not have a direction, but a temporary direction is set same as edge. Append and Prepend refer to left-to-right in the list of edges. A parameterized class that describes a connected closed path in a PGraph object. The direction of the path is defined as left-to-right in array
PathEdges.
PPathOpen
PVertex
A parameterized class that describes a connected open path in a PGraph object. The path can actually be “closed” if the head vertex is the same as the tail vertex, but this fact is of no consequence. The only purpose of a “closed” PPathOpen object is to use it to construct a PPathClosed object. A parameterized class that describes a vertex of a mathematical graph and is used as base for all specialized vertex classes.
Translator
Abstract class used as base for all translational specific coordinate systems. Just as an Orientator object controls the orientation of a coordinate system by associating the state variables A and ω with the orientational specific coordinates, a Translator object controls the translation of a coordinate system by associating the state variables r and v with the translational specific coordinates.
TranslatorXYZ
This class describes a Translator object that uses the three cartesian coordinates x, y and z as specific coordinates.
Chapter 7 Family of Classes: Specific Coordinates Services for translational and orientational specific coordinate systems with full support for rigid body kinematic and dynamic calculations. Currently includes two abstract base classes: Translator, with support for regular x, y, z translations, and Orientator, with support for Euler angles with two conventions, Euler parameters, and an Axial Rotator for cylindrical constraints.
77
78
7.1
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
All Specific Coordinates Classes
Class name AxialRotator EulerAngles EulerAnglesZXZ
EulerAnglesZYX EulerParams
Orientator
Translator
TranslatorXYZ
OrthoMatrix
7.2
Description This class describes the Axial Rotator set of specific coordinates, which consists of a single angle, and provides all the required services to the Orientator interface. Abstract class derived from Orientator which serves as base for all Euler angles classes and provides all services specific to Euler angles. This class describes the ZXZ Convention for the Euler angles specific coordinates and provides the corresponding services to the Orientator interface. This class describes the ZYX Convention for the Euler angles specific coordinates and provides the corresponding services to the Orientator interface. This class describes the Euler parameter specific coordinates and provides the corresponding services to the Orientator interface. Abstract class used as base for all orientational specific coordinate classes. Provides support for conversions between the orientational specific coordinates and the state variables associated with orientation, such as the orientation matrix and the angular velocity, and for the calculation of other kinematic vectors and matrices discussed in sections 3.5 and 3.6. Abstract class used as base for all translational specific coordinate classes. This class is derived from Translator . It describes a simple system of 3 independent translational specific coordinates, which are the 3 cartesian coordinates of the origin of coordinate system S relative to coordinate system F. The class implements all services of the abstract base class Translator for this particular case. A class derived from Matrix3 that describes an orthogonal matrix of size 3 × 3.
Class AxialRotator Orientator AxialRotator
A system of orientational specific coordinates with only one coordinate, the angle α of rotation around a fixed axis.
7.2. CLASS AXIALROTATOR
79
Attribute Summary protected: double protected: double
sina The value of sin α. cosa The value of cos α.
Constructor Summary public: public:
AxialRotator() Public default constructor. ∼AxialRotator() Virtual destructor.
Method Summary public: void public: void public: int public: int public: void public: void public: void public: void public: void public: void
CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates ∂(AF S,F uS )/∂s where the given vector uS is constant in system S. CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂s. CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific acceleration α ¨. CalculateDots(const Vector3 & omega FSF, double * dots) Calculates the orientational specific velocity α. ˙ CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F . CalculateMatrixA(OrthoMatrix & AA) Calculates the orientation matrix AFS,F . CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F . CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F . CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S . CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S .
80
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary (continued) public: void public: void public: void public: void public: void public: void public: Str public: Str public: Str public: int public: bool public: void public: void public: void public: void public: bool
CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 1 matrix P. CalculateMatrixR(PMatrix & R) Calculates matrix R. CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F . CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F . CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S . CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S . DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinates. GetClass() Returns the name of this class. GetNumberCoordinates() Returns the number of orientational specific coordinates. IsStable() Verifies if this object is in a stable condition. SetDots(const CSVector & omega FSF) Sets the value of the orientational specific velocity α˙ to a value calculated from the angular velocity. SetDots(const double * dots) Sets the value of the orientational specific velocity α˙ to the given value. SetValues(const double * values) Sets the value of the orientational specific coordinate α to the given value. SetValues(const OrthoMatrix & AFSF) Sets the value of the orientational specific coordinate α to the value calculated from the given orientation matrix. Verify() Verifies the consistency and correctness of this object.
7.2. CLASS AXIALROTATOR
7.2.1
81
AxialRotator Attribute Detail
protected: double sina The value of sin α. This value is calculated only once each time a new value for α is set, and is kept in storage to improve efficiency.
protected: double cosa The value of cos α. This value is calculated only once each time a new value for α is set, and is kept in storage to improve efficiency.
7.2.2
AxialRotator Constructor Detail
public: AxialRotator::AxialRotator() Public default constructor. It creates the object and the internal arrays, but does not set any values.
public: AxialRotator::∼AxialRotator() Virtual destructor.
82
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
7.2.3
AxialRotator Method Detail
public: void AxialRotator::CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates the 3 × 1 matrix ∂(AFS,F uS )/∂s, where the given vector uS is constant in system S and s is the 1 × 1 column vector of orientational specific coordinates. Arguments • uS A reference to a Vector3 object that contains the given vector uS , expressed in system S. The vector is constant in system S. • Result
public: void AxialRotator::CalculatedA ds(int s, double * dAds) Calculates ∂A/∂s, where s is the 1 × 1 column vector [α]T . Arguments • s
The integer 0-based index of the only orientational specific coordinate. It must be 0.
• dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
7.2. CLASS AXIALROTATOR
83
public: int AxialRotator::CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific acceleration α ¨ , from a given angular acceleration αFS,F of system S relative to system F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 1 in this case. Arguments • alfa FSS A reference to a constant Vector3 object containing the given angular acceleration αFS,F of system S relative to system F. • dotDots A pointer to an array of doubles, which, upon return, will contain the resulting specific accelerations. The length of the array must be at least equal to 1.
public: int AxialRotator::CalculateDots(const Vector3 & omega FSF, double * dots) Calculates the orientational specific velocity α˙ from a given angular velocity ωFS,F of system S relative to system F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 1 in this case. Arguments • omega FSF A reference to a constant Vector3 object containing the given angular velocity ωFS,F of system S relative to system F. • dots A pointer to an array of doubles, which, upon return, will contain the resulting specific velocity. The length of the array must be at least equal to 1.
84
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void AxialRotator::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F from the current value of the angle α, and returns the elements of the resulting matrix in an array, by rows. Arguments • aa A pointer to an array of doubles of length at least 9, which, upon return, will contain the elements of the resulting matrix by rows.
public: void AxialRotator::CalculateMatrixA(OrthoMatrix & AA) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the angle α. Arguments • AA A reference to an OrthoMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void AxialRotator::CalculateMatrixG(PMatrix & G) Calculates the 3 × 1 matrix GFS,F from the current value of the angle α. The result is returned by argument. Arguments • G A reference to a PMatrix object of size 3 × 1, which, upon return, will contain the resulting matrix.
public: void AxialRotator::CalculateMatrixGDot(PMatrix & GDot) Calculates the 3 × 1 matrix G˙ FS,F from the current values of α and α. ˙ The result is returned by argument. Arguments • GDot A reference to a PMatrix object of size 3 × 1, which, upon return, will contain the resulting matrix.
7.2. CLASS AXIALROTATOR
85
public: void AxialRotator::CalculateMatrixGR(PMatrix & GR) Calculates the 3 × 1 matrix GFS,S from the current value of the angle α. The result is returned by argument. Arguments • GR A reference to a PMatrix object of size 3 × 1, which, upon return, will contain the resulting matrix.
public: void AxialRotator::CalculateMatrixGRDot(PMatrix & GRDot) ˙ The result is returned by Calculates the 3 × 1 matrix G˙ FS,S from the current values of α and α. argument. Arguments • GRDot A reference to a PMatrix object of size 3 × 1, which, upon return, will contain the resulting matrix.
public: void AxialRotator::CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 1 matrix P from the current values of α and α˙ and a given value of the angular velocity ωFS,S , and returns the result by argument. Arguments • omegaFSS A reference to a constant Vector3 object that contains the given angular velocity ωFS,S . • P A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
86
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void AxialRotator::CalculateMatrixR(PMatrix & R) Calculates the 3×3 matrix R from the current values of α and α, ˙ and returns the result by argument. Arguments • R A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void AxialRotator::CalculateOmega FSF(Vector3 & omega FSF) ˙ and returns the result by Calculates the angular velocity ωFS,F from the current values of α and α, argument. Arguments • omega FSF
A reference to a Vector3 object, which, upon return, will contain the result.
public: void AxialRotator::CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F from the current value of α and the given value of α, ˙ and returns the result by argument. Arguments • dots A pointer to the constant array of doubles that contains the given orientational specific velocity. • omega FSF result.
A reference to a CSVector object, which, upon return, will contain the
7.2. CLASS AXIALROTATOR
87
public: void AxialRotator::CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S from the current values of α and α, ˙ and returns the result by argument. Arguments • omega FSS
A reference to a Vector3 object, which, upon return, will contain the result.
public: void AxialRotator::CalculateOmega FSS(const double * dots, CSVector & omega FSS) ˙ and Calculates the angular velocity ωFS,S from the current value of α and the given value of α, returns the result by argument. Arguments • dots A pointer to the constant array of doubles that contains the given orientational specific velocity. • omega FSS result.
A reference to a CSVector object, which, upon return, will contain the
public: Str AxialRotator::DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. Return An Str object with the desired report. Arguments • specor The integer index of the orientational specific coordinate of interest. It must be 0 in this case.
88
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: Str AxialRotator::DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinates. Return An Str object with the desired report.
public: Str AxialRotator::GetClass() Returns the name of this class. Return An Str object that contains the name of this class.
public: int AxialRotator::GetNumberCoordinates() Returns the number of orientational specific coordinates, 1 in this case. Return The integer number of orientational specific coordinates, 1 in this case.
public: bool AxialRotator::IsStable() Verifies if this object is in a stable condition. The AxialRotator object is always stable. Return true .
public: void AxialRotator::SetDots(const CSVector & omega FSF) Sets the value of the orientational specific velocity α˙ to a value calculated from the angular velocity ωFS,F . Arguments • omega FSF A reference to a constant CSVector object that contains the given value of the angular velocity ωFS,F .
7.2. CLASS AXIALROTATOR
89
public: void AxialRotator::SetDots(const double * dots) Sets the value of the orientational specific velocity α˙ to the given value. Arguments • dots A pointer to a constant array of doubles that contains the new value for the orientational specific velocity α. ˙
public: void AxialRotator::SetValues(const double * values) Sets the value of the orientational specific coordinate α to the given value. Arguments • values A pointer to a constant array of doubles that contains the new value for the orientational specific coordinate α.
public: void AxialRotator::SetValues(const OrthoMatrix & AFSF) Sets the value of the orientational specific coordinate α to the value calculated from the given orientation matrix AFS,F . Arguments • AFSF A reference to a constant OrthoMatrix object containing the given orientation matrix AFS,F .
public: bool AxialRotator::Verify() Verifies the consistency and correctness of this object. This method is intended for debugging. Return true if this object is correct, false otherwise.
90
7.3
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Class EulerAngles Orientator EulerAngles
A system of independent orientational specific coordinates where Euler Angles are used as the 3 coordinates. This class supports Conventions, which are different ways of defining the Euler Angles.
Attribute Summary protected: double protected: double protected: double protected: double protected: double protected: double
sth A protected spsi A protected sfi A protected cth A protected cpsi A protected cfi A protected
double that holds the value of sin(ϑ) double that holds the value of sin(ψ) double that holds the value of sin(ϕ) double that holds the value of cos(ϑ) double that holds the value of cos(ψ) double that holds the value of cos(ϕ)
Constructor Summary public: public: virtual
EulerAngles() Default constructor. ∼EulerAngles() Virtual destructor.
7.3. CLASS EULERANGLES
91
Method Summary public: virtual public: virtual public: virtual public: virtual public: virtual public: virtual public: virtual
void void void void void void void
public: void public: virtual public: int public: int public: virtual public: void public: virtual public: virtual public: virtual public: void public: void public: void
void
void
void void void
CalculateD2A dfi dfi(double * dAdfidfi) Calculates ∂ 2 AFS,F /∂ϕ2 CalculateD2A dfi dpsi(double * dAdfidpsi) Calculates ∂ 2 AFS,F /∂ϕ ∂ψ CalculateD2A dfi dth(double * dAdfidth) Calculates ∂ 2 AFS,F /∂ϕ ∂ϑ CalculateD2A dpsi dpsi(double * dAdpsidpsi) Calculates ∂ 2 AFS,F /∂ψ 2 CalculateD2A dth dpsi(double * dAdthdpsi) Calculates ∂ 2 AFS,F /∂ϑ ∂ψ CalculateD2A dth dth(double * dAdthdth) Calculates ∂ 2 AFS,F /∂ϑ2 CalculateDADotDfiDthDpsi(double * dADotdfi, double * dADotdth, double * dADotdpsi) Calculates the three matrices ∂ A˙ FS,F /∂ϕ, ∂ A˙ FS,F /∂ϑ, and ∂ A˙ FS,F /∂ψ. CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates ∂(AF S,F uS )/∂s where the given vector uS is constant in system S. CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂s. CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) ¨ Calculates the orientational specific accelerations ϕ, ¨ ϑ¨ and ψ. CalculateDots(const Vector3 & omega FSF, double * dots) ˙ Calculates the orientational specific velocities ϕ, ˙ ϑ˙ and ψ. CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F . CalculateMatrixA(OrthoMatrix & AFSF) Calculates the orientation matrix AFS,F . CalculateMatrixAfromEulerRotations(double * aa) Creates matrix AFS,F by rotating the unit vectors of system F. CalculateMatrixGInv(PMatrix & GInv) Calculates matrix GFS,F −1 . CalculateMatrixGRInv(PMatrix & GRInv) Calculates matrix GFS,S −1 . CalculateMatrixR(PMatrix & R) Calculates matrix R. CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F . CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F .
92
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary (continued) public: void public: void public: Str public: Str public: virtual void
public: int public: Str public: bool
7.3.1
CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S . CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S . DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinates. GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the current ϕ, ϑ, ψ instantaneous axes of rotation. GetNumberCoordinates() Returns the number of orientational specific coordinates. ReportAnglesAndDots() Creates a report with the current values of the orientational specific coordinates and velocities. Verify() Verifies the consistency of this object.
EulerAngles Attribute Detail
protected: double sth A protected double that holds the value of sin(ϑ)
protected: double spsi A protected double that holds the value of sin(ψ)
7.3. CLASS EULERANGLES
protected: double sfi A protected double that holds the value of sin(ϕ)
protected: double cth A protected double that holds the value of cos(ϑ)
protected: double cpsi A protected double that holds the value of cos(ψ)
protected: double cfi A protected double that holds the value of cos(ϕ)
7.3.2
EulerAngles Constructor Detail
public: EulerAngles::EulerAngles() Default constructor. It creates the object in a default state.
public: virtual EulerAngles::∼EulerAngles() Virtual destructor.
93
94
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
7.3.3
EulerAngles Method Detail
public: virtual void EulerAngles::CalculateD2A dfi dfi(double * dAdfidfi) Calculates the 3×3 matrix ∂ 2 AFS,F /∂ϕ2 using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdfidfi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: virtual void EulerAngles::CalculateD2A dfi dpsi(double * dAdfidpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ψ using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdfidpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: virtual void EulerAngles::CalculateD2A dfi dth(double * dAdfidth) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ϑ using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdfidth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
7.3. CLASS EULERANGLES
95
public: virtual void EulerAngles::CalculateD2A dpsi dpsi(double * dAdpsidpsi) Calculates the 3×3 matrix ∂ 2 AFS,F /∂ψ 2 using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdpsidpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: virtual void EulerAngles::CalculateD2A dth dpsi(double * dAdthdpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϑ ∂ψ using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdthdpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: virtual void EulerAngles::CalculateD2A dth dth(double * dAdthdth) Calculates the 3×3 matrix ∂ 2 AFS,F /∂ϑ2 using the current values of the Euler angles and the current convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • dAdthdth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
96
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void EulerAngles::CalculateDADotDfiDthDpsi(double dADotdfi, double * dADotdth, double * dADotdpsi)
*
Calculates the three 3×3 matrices ∂ A˙ FS,F /∂ϕ, ∂ A˙ FS,F /∂ϑ, and ∂ A˙ FS,F /∂ψ, and returns the elements of the three resulting matrices by argument in three arrays, ordered by rows. Arguments • dADotdfi , dADotdth , dADotdpsi Pointers to three arrays of doubles, which, upon return, will contain the elements of the resulting matrix ordered by rows.
public: void EulerAngles::CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates the 3 × n matrix ∂(AFS,F uS )/∂s, where the given vector uS is constant in system S, s is the n × 1 column vector of orientational specific coordinates, and n is 3 in this case. Arguments • uS A reference to a constant Vector3 object that contains the given vector uS , expressed in system S. The vector is constant in system S. • Result A reference to a PMatrix object, which, upon return, will contain the resulting 3 × n matrix.
public: virtual void EulerAngles::CalculatedA ds(int s, double * dAds) This pure virtual method calculates ∂A/∂s where s is the column vector of Euler angles [ϕ, ϑ, ψ]T . Arguments • s
The integer 0-based index of one of the Euler angles in the range 0 to 2.
• dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
7.3. CLASS EULERANGLES
97
public: int EulerAngles::CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific accelerations ϕ, ¨ ϑ¨ and ψ¨ from a given angular acceleration αFS,F of system S relative to F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 3 in this case. Arguments • alfa FSS A reference to a constant Vector3 object containing the given angular acceleration αFS,F of system S relative to system F. • dotDots A pointer to an array of doubles, which, upon return, will contain the resulting specific accelerations. The length of the array must be at least equal to 3.
public: int EulerAngles::CalculateDots(const Vector3 & omega FSF, double * dots) Calculates the orientational specific velocities ϕ, ˙ ϑ˙ and ψ˙ from a given angular velocity ωFS,F of system S relative to F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 3 in this case. Arguments • omega FSF A reference to a constant Vector3 object containing the given angular velocity ωFS,F of system S relative to F. • dots A pointer to an array of doubles, which, upon return, will contain the resulting specific velocities. The length of the array must be at least equal to 3.
98
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void EulerAngles::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the Euler angles, and returns the elements of the resulting matrix in an array, by rows. Arguments • aa A pointer to an array of doubles of length at least 9, which, upon return, will contain the elements of the resulting matrix by rows.
public: void EulerAngles::CalculateMatrixA(OrthoMatrix & AFSF) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the Euler angles. Arguments • AFSF A reference to an OrthoMatrix object of size 3×3, which, upon return, will contain the resulting matrix.
public: virtual void EulerAngles::CalculateMatrixAfromEulerRotations(double * aa) Creates the orientation matrix AFS,F with the 3 unit vectors of coordinate system S obtained by rotating the original unit vectors of coordinate system F, and returns the result by argument. This method is intended mostly for debugging. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the elements of the resulting matrix ordered by rows.
7.3. CLASS EULERANGLES
99
public: virtual void EulerAngles::CalculateMatrixGInv(PMatrix & GInv) Calculates matrix GFS,F −1 from the current values and convention of the Euler angles. The result is returned by argument. Arguments • GInv A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: virtual void EulerAngles::CalculateMatrixGRInv(PMatrix & GRInv) Calculates matrix GFS,S −1 from the current values and convention of the Euler angles. The result is returned by argument. Arguments • GRInv matrix.
A reference to a matrix of size 3×3, which, upon return, will contain the resulting
public: void EulerAngles::CalculateMatrixR(PMatrix & R) Calculates the 3 × 3 matrix R from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • R A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAngles::CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • omega FSF
A reference to a Vector3 object, which, upon return, will contain the result.
100
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAngles::CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F from the current values of the orientational specific coordinates and the given values of the orientational specific velocities, and returns the result by argument. Arguments • dots A pointer to the constant array of doubles that contains the given orientational specific velocities. • omega FSF result.
A reference to a CSVector object, which, upon return, will contain the
public: void EulerAngles::CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • omega FSS
A reference to a Vector3 object, which, upon return, will contain the result.
public: void EulerAngles::CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S from the current values of the orientational specific coordinates and the given values of the orientational specific velocities, and returns the result by argument. Arguments • dots A pointer to a constant array of doubles that contains the given orientational specific velocities. • omega FSS result.
A reference to a CSVector object, which, upon return, will contain the
7.3. CLASS EULERANGLES
101
public: Str EulerAngles::DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. Return An Str object with the desired report. Arguments • specor 0 to 2.
The integer index of the orientational specific coordinate of interest, in the range
public: Str EulerAngles::DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinates. Return An Str object with the desired report.
public: virtual void EulerAngles::GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the instantaneous axes of the rotations that would take place if the current values of the orientational specific coordinates ϕ, ϑ and ψ were incremented by an infinitesimally small amount, respectively. Arguments • afi , ath , apsi References to three constant UnitVector3 objects, which, upon return, will contain the three resulting unit vectors.
public: int EulerAngles::GetNumberCoordinates() Returns the number of orientational specific coordinates, 3 in this case. Return The integer number of orientational specific coordinates, 3 in this case.
102
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: Str EulerAngles::ReportAnglesAndDots() Creates a report with the current values of the orientational specific coordinates and velocities. Return An Str object that contains the resulting report.
public: bool EulerAngles::Verify() Verifies the consistency and correctness of this object. This method is intended for debugging. Return true if this object is correct, false otherwise.
7.4
Class EulerAnglesZXZ Orientator EulerAngles EulerAnglesZXZ
Constructor Summary public: public: public: public: public:
EulerAnglesZXZ() Public default constructor. EulerAnglesZXZ(const double * angles) Public constructor. EulerAnglesZXZ(double fi, double th, double psi) Public constructor. EulerAnglesZXZ(const OrthoMatrix & AFSF) Public constructor. ∼EulerAnglesZXZ() Public virtual destructor.
7.4. CLASS EULERANGLESZXZ
103
Method Summary public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void
public: Str
CalculateD2A dfi dfi(double * d2Adfidfi) Calculates ∂ 2 AFS,F /∂ϕ2 . CalculateD2A dfi dpsi(double * d2Adfidpsi) Calculates ∂ 2 AFS,F /∂ϕ ∂ψ. CalculateD2A dfi dth(double * d2Adfidth) Calculates ∂ 2 AFS,F /∂ϕ ∂ϑ. CalculateD2A dpsi dpsi(double * d2Adpsidpsi) Calculates ∂ 2 AFS,F /∂ψ 2 . CalculateD2A dth dpsi(double * d2Adthdpsi) Calculates ∂ 2 AFS,F /∂ϑ ∂ψ. CalculateD2A dth dth(double * d2Adthdth) Calculates ∂ 2 AFS,F /∂ϑ2 . CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂s. CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F . CalculateMatrixAfromEulerRotations(double * aa) Creates matrix AFS,F by rotating the unit vectors of system F. CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F . CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F . CalculateMatrixGInv(PMatrix & GInv) Calculates matrix GFS,F −1 . CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S . CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S . CalculateMatrixGRInv(PMatrix & GRInv) Calculates matrix GFS,S −1 . CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 3 matrix P. GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the current ϕ, ϑ, ψ instantaneous axes of rotation. GetClass() Returns the name of this class.
104
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary public: bool public: void public: void public: void public: void
7.4.1
IsStable() Verifies if this object is in a stable condition. SetDots(const double * dots) Sets the Euler angle velocities to the given values. SetDots(const CSVector & omega FSF) Sets the Euler velocities to values calculated from the given angular velocity. SetValues(const double * angles) Sets the Euler angles to the values passed in an array. SetValues(const OrthoMatrix & AFSF) Sets the Euler angles to values calculated from the given orientation matrix.
EulerAnglesZXZ Constructor Detail
public: EulerAnglesZXZ::EulerAnglesZXZ() Public constructor. It creates the object and invokes the constructor of the superclass.
public: EulerAnglesZXZ::EulerAnglesZXZ(const double * angles) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to the given values. The Euler velocities are left undetermined. Arguments • angles A pointer to a constant array of doubles that contains the given values for the Euler angles.
7.4. CLASS EULERANGLESZXZ
105
public: EulerAnglesZXZ::EulerAnglesZXZ(double fi, double th, double psi) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to the given values. The Euler velocities are left undetermined. Arguments • fi , th , psi
The given values for the Euler angles.
public: EulerAnglesZXZ::EulerAnglesZXZ(const OrthoMatrix & AFSF) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to values calculated from the given orientation matrix. The Euler velocities are left undetermined. Arguments • AFSF matrix.
A reference to a constant OrthoMatrix object that contains the given orientation
public: EulerAnglesZXZ::∼EulerAnglesZXZ() Public virtual destructor.
106
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
7.4.2
EulerAnglesZXZ Method Detail
public: void EulerAnglesZXZ::CalculateD2A dfi dfi(double * d2Adfidfi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ2 using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidfi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZXZ::CalculateD2A dfi dpsi(double * d2Adfidpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ψ using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZXZ::CalculateD2A dfi dth(double * d2Adfidth) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ϑ using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
7.4. CLASS EULERANGLESZXZ
107
public: void EulerAnglesZXZ::CalculateD2A dpsi dpsi(double * d2Adpsidpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ψ 2 using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adpsidpsi ordered by rows.
Upon return, this array will contain the elements of the resulting matrix
public: void EulerAnglesZXZ::CalculateD2A dth dpsi(double * d2Adthdpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϑ ∂ψ using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adthdpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZXZ::CalculateD2A dth dth(double * d2Adthdth) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϑ2 using the current values of the Euler angles and the ZXZ convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adthdth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
108
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZXZ::CalculatedA ds(int s, double * dAds) Calculates ∂A/∂s where s is the column vector of Euler angles [ϕ, ϑ, ψ]T . Arguments • s
The integer 0-based index of one of the Euler angles in the range 0 to 2.
• dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
public: void EulerAnglesZXZ::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F using the current values of the Euler angles and the ZXZ convention, and returns the result by argument. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the elements of the resulting matrix, ordered by rows.
public: void EulerAnglesZXZ::CalculateMatrixAfromEulerRotations(double * aa) Creates the orientation matrix AFS,F with the 3 unit vectors of coordinate system S obtained by rotating the original unit vectors of coordinate system F, and returns the result by argument. This method is intended mostly for debugging. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the elements of the resulting matrix ordered by rows.
7.4. CLASS EULERANGLESZXZ
109
public: void EulerAnglesZXZ::CalculateMatrixG(PMatrix & G) Calculates the 3×3 matrix GFS,F from the current values of the Euler angles and the ZXZ convention. The result is returned by argument. Arguments • G A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZXZ::CalculateMatrixGDot(PMatrix & GDot) Calculates the 3 × 3 matrix G˙ FS,F from the current values of the Euler angles and velocities, and the ZXZ convention. The result is returned by argument. Arguments • GDot A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZXZ::CalculateMatrixGInv(PMatrix & GInv) Calculates the 3 × 3 matrix GFS,F −1 from the current values of the Euler angles and the ZXZ convention. The result is returned by argument. Arguments • GInv A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
110
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZXZ::CalculateMatrixGR(PMatrix & GR) Calculates the 3×3 matrix GFS,S from the current values of the Euler angles and the ZXZ convention. The result is returned by argument. Arguments • GR A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZXZ::CalculateMatrixGRDot(PMatrix & GRDot) Calculates the 3 × 3 matrix G˙ FS,S from the current values of the Euler angles and velocities, and the ZXZ convention. The result is returned by argument. Arguments • GRDot A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZXZ::CalculateMatrixGRInv(PMatrix & GRInv) Calculates the 3 × 3 matrix GFS,S −1 from the current values of the Euler angles and the ZXZ convention. The result is returned by argument. Arguments • GRInv A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
7.4. CLASS EULERANGLESZXZ
111
public: void EulerAnglesZXZ::CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 3 matrix P from the current values of the orientational specific coordinates and velocities and a given value of the angular velocity ωFS,S , and returns the result by argument. Arguments • omegaFSS A reference to a constant Vector3 object that contains the given angular velocity ωFS,S . • P A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZXZ::GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the instantaneous axes of the rotations that would take place if the current values of the orientational specific coordinates ϕ, ϑ and ψ were incremented by an infinitesimally small amount, respectively. Arguments • afi , ath , apsi References to three UnitVector3 objects, which, upon return, will contain the three resulting unit vectors.
public: Str EulerAnglesZXZ::GetClass() Returns the name of this class. Return An Str object that contains the name of this class.
112
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: bool EulerAnglesZXZ::IsStable() Verifies if this object is in a stable condition. The ZXZ convention has a singularity at sin ϑ = 0, and the object is considered unstable in the vicinity of the singularity. Return true if this object is stable, false if not.
public: void EulerAnglesZXZ::SetDots(const double * dots) Sets the Euler angle velocities to the given values. Arguments • dots A pointer to a constant array of doubles that contains the new values for the Euler velocities.
public: void EulerAnglesZXZ::SetDots(const CSVector & omega FSF) Sets the Euler velocities to values calculated from the given angular velocity ωFS,F . Arguments • omega FSF A reference to a constant CSVector object that contains the given value of the angular velocity ωFS,F .
public: void EulerAnglesZXZ::SetValues(const double * angles) Sets the Euler angles to the values passed in an array. Arguments • angles angles.
A pointer to a constant array of doubles containing the new values for the Euler
7.5. CLASS EULERANGLESZYX
113
public: void EulerAnglesZXZ::SetValues(const OrthoMatrix & AFSF) Sets the Euler angles to values calculated from the given orientation matrix AFS,F . Arguments • AFSF A reference to a constant OrthoMatrix object containing the given orientation matrix AFS,F .
7.5
Class EulerAnglesZYX Orientator EulerAngles EulerAnglesZYX
A system of 3 independent orientational specific coordinates where the ZYX convention for Euler Angles is used. The first rotation is taken about the initial +z axis, the second rotation about the new +y axis, and the third rotation is about the final +x axis. All rotations follow the right-hand or corkscrew rule.
Constructor Summary public: public: public: public: public:
EulerAnglesZYX() Public default constructor. EulerAnglesZYX(const double * angles) Public constructor. EulerAnglesZYX(double fi, double th, double psi) Public constructor. EulerAnglesZYX(const OrthoMatrix & AFSF) Public constructor. ∼EulerAnglesZYX() Public virtual destructor.
114
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void public: void
CalculateD2A dfi dfi(double * d2Adfidfi) Calculates ∂ 2 AFS,F /∂ϕ2 . CalculateD2A dfi dpsi(double * d2Adfidpsi) Calculates ∂ 2 AFS,F /∂ϕ ∂ψ. CalculateD2A dfi dth(double * d2Adfidth) Calculates ∂ 2 AFS,F /∂ϕ ∂ϑ. CalculateD2A dpsi dpsi(double * d2Adpsidpsi) Calculates ∂ 2 AFS,F /∂ψ 2 . CalculateD2A dth dpsi(double * d2Adthdpsi) Calculates ∂ 2 AFS,F /∂ϑ ∂ψ. CalculateD2A dth dth(double * d2Adthdth) Calculates ∂ 2 AFS,F /∂ϑ2 . CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂s. CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F . CalculateMatrixAfromEulerRotations(double * aa) Creates matrix AFS,F by rotating the unit vectors of system F. CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F . CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F . CalculateMatrixGInv(PMatrix & GInv) Calculates matrix GFS,F −1 . CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S . CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S . CalculateMatrixGRInv(PMatrix & GRInv) Calculates matrix GFS,S −1 . CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × n matrix P. GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the current ϕ, ϑ, ψ instantaneous axes of rotation.
7.5. CLASS EULERANGLESZYX
115
Method Summary (continued) public: Str public: bool public: void public: void public: void public: void
7.5.1
GetClass() Returns the name of this class. IsStable() Verifies if this object is in a stable condition. SetDots(const double * dots) Sets the Euler velocities to the given values. SetDots(const CSVector & omega FSF) Sets the Euler velocities to values calculated from the given angular velocity. SetValues(const double * angles) Sets the Euler angles to the values passed in an array. SetValues(const OrthoMatrix & AFSF) Sets the Euler angles to values calculated from the given orientation matrix.
EulerAnglesZYX Constructor Detail
public: EulerAnglesZYX::EulerAnglesZYX() Public constructor. It creates the object and invokes the constructor of the superclass.
public: EulerAnglesZYX::EulerAnglesZYX(const double * angles) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to the given values. The Euler velocities are left undetermined. Arguments • angles A pointer to a constant array of doubles that contains the given values for the Euler angles.
116
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: EulerAnglesZYX::EulerAnglesZYX(double fi, double th, double psi) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to the given values. The Euler velocities are left undetermined. Arguments • fi , th , psi
The given values for the Euler angles.
public: EulerAnglesZYX::EulerAnglesZYX(const OrthoMatrix & AFSF) Public constructor. It creates the object, invokes the constructor of the superclass, and sets the Euler angles to values calculated from the given orientation matrix. The Euler velocities are left undetermined. Arguments • AFSF matrix.
A reference to a constant OrthoMatrix object that contains the given orientation
public: EulerAnglesZYX::∼EulerAnglesZYX() Public virtual destructor.
7.5. CLASS EULERANGLESZYX
7.5.2
117
EulerAnglesZYX Method Detail
public: void EulerAnglesZYX::CalculateD2A dfi dfi(double * d2Adfidfi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ2 using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidfi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZYX::CalculateD2A dfi dpsi(double * d2Adfidpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ψ using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZYX::CalculateD2A dfi dth(double * d2Adfidth) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϕ ∂ϑ using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adfidth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
118
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZYX::CalculateD2A dpsi dpsi(double * d2Adpsidpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ψ 2 using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adpsidpsi ordered by rows.
Upon return, this array will contain the elements of the resulting matrix
public: void EulerAnglesZYX::CalculateD2A dth dpsi(double * d2Adthdpsi) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϑ ∂ψ using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adthdpsi Upon return, this array will contain the elements of the resulting matrix ordered by rows.
public: void EulerAnglesZYX::CalculateD2A dth dth(double * d2Adthdth) Calculates the 3 × 3 matrix ∂ 2 AFS,F /∂ϑ2 using the current values of the Euler angles and the ZYX convention, and returns the elements of the resulting matrix by argument in an array, ordered by rows. Arguments • d2Adthdth Upon return, this array will contain the elements of the resulting matrix ordered by rows.
7.5. CLASS EULERANGLESZYX
119
public: void EulerAnglesZYX::CalculatedA ds(int s, double * dAds) Calculates ∂A/∂s where s is the column vector of Euler angles [ϕ, ϑ, ψ]T . Arguments • s
The integer 0-based index of one of the Euler angles in the range 0 to 2.
• dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
public: void EulerAnglesZYX::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F using the current values of the Euler angles and the ZYX convention, and returns the result by argument. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the elements of the resulting matrix, ordered by rows.
public: void EulerAnglesZYX::CalculateMatrixAfromEulerRotations(double * aa) Creates the orientation matrix AFS,F with the 3 unit vectors of coordinate system S obtained by rotating the original unit vectors of coordinate system F, and returns the result by argument. This method is intended mostly for debugging. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the elements of the resulting matrix ordered by rows.
120
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZYX::CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • G A reference to a constant PMatrix object, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZYX::CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • GDot A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZYX::CalculateMatrixGInv(PMatrix & GInv) Calculates the 3 × 3 matrix GFS,F −1 from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • GInv A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
7.5. CLASS EULERANGLESZYX
121
public: void EulerAnglesZYX::CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • GR A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZYX::CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • GRDot A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZYX::CalculateMatrixGRInv(PMatrix & GRInv) Calculates the 3 × 3 matrix GFS,S −1 from the current values of the Euler angles and the ZYX convention. The result is returned by argument. Arguments • GRInv A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
122
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZYX::CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × n matrix P from the current values of the orientational specific coordinates and velocities and a given value of the angular velocity ωFS,S , where n is 3 in this case, and returns the result by argument. Arguments • omegaFSS A reference to a constant Vector3 object that contains the given angular velocity ωFS,S . • P A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: void EulerAnglesZYX::GetAxesForInfinitesimalRotations(UnitVector3 & afi, UnitVector3 & ath, UnitVector3 & apsi) Calculates the unit vectors for the instantaneous axes of the rotations that would take place if the current values of the orientational specific coordinates ϕ, ϑ and ψ were incremented by an infinitesimally small amount, respectively. Arguments • afi , ath , apsi References to three UnitVector3 objects, which, upon return, will contain the three resulting unit vectors.
public: Str EulerAnglesZYX::GetClass() Returns the name of this class. Return An Str object that contains the name of this class.
7.5. CLASS EULERANGLESZYX
123
public: bool EulerAnglesZYX::IsStable() Verifies if this object is in a stable condition. The ZYX convention has a singularity at cos ϑ = 0, and the object is considered unstable in the vicinity of the singularity. Return true if this object is stable, false if not.
public: void EulerAnglesZYX::SetDots(const double * dots) Sets the Euler velocities to the given values. Arguments • dots A pointer to a constant array of doubles that contains the new values for the Euler velocities.
public: void EulerAnglesZYX::SetDots(const CSVector & omega FSF) Sets the Euler velocities to values calculated from the given angular velocity ωFS,F . Arguments • omega FSF A reference to a constant CSVector object that contains the given value of the angular velocity ωFS,F .
public: void EulerAnglesZYX::SetValues(const double * angles) Sets the Euler angles to the values passed in an array. Arguments • angles angles.
A pointer to a constant array of doubles containing the new values for the Euler
124
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerAnglesZYX::SetValues(const OrthoMatrix & AFSF) Sets the Euler angles to values calculated from the given orientation matrix AFS,F . Arguments • AFSF A reference to a constant OrthoMatrix object containing the given orientation matrix AFS,F .
7.6
Class EulerParams Orientator EulerParams
A system of orientational specific coordinates where the four Euler parameters are used. The four parameters are related by one constraint equation, and in consequence only three of them are independent. The parameters, or orientational specific coordinates, are referred to as s = [s0 , s1 , s2 , s3 ]T .
Constructor Summary public: public: virtual
EulerParams() Default constructor. ∼EulerParams() Virtual destructor.
7.6. CLASS EULERPARAMS
125
Method Summary public: void public: void public: void public: int public: int public: void public: void public: void public: void public: void public: void public: void public: void public: void
CalculateD2A dp dq(int p, int q, double * D2Adpdq) Calculates ∂ 2 AFS,F /∂sp ∂sq . CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates ∂(AF S,F uS )/∂s where the given vector uS is constant in system S. CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂ss . CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific accelerations s¨. CalculateDots(const Vector3 & omega FSF, double * dots) ˙ Calculates the orientational specific velocities s. CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F for the Euler parameters. CalculateMatrixA(OrthoMatrix & AFSF) Calculates the orientation matrix AFS,F for the Euler parameters. CalculateMatrixB(PMatrix & B) Calculates matrix BFS,F from the current values of the Euler parameters. CalculateMatrixBR(PMatrix & BR) Calculates matrix BFS,S from the current values of the Euler parameters. CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F . CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F . CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S . CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S . CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 4 matrix P.
126
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary (continued) public: void public: void public: void public: void public: void public: Str public: Str public: Str public: int public: bool public: void public: void public: void public: void public: bool
CalculateMatrixR(PMatrix & R) Calculates matrix R. CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F . CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F . CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S . CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S . DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinates. GetClass() Returns the name of this class. GetNumberCoordinates() Returns the number of orientational specific coordinates. IsStable() Verifies if this object is in a stable condition. SetDots(const double * paramDots) Sets the Euler parameter velocities to the given values. SetDots(const CSVector & omega FSF) Sets the Euler parameter velocities to values calculated from the given angular velocity. SetValues(const double * params) Sets the Euler parameters to the values passed in an array. SetValues(const OrthoMatrix & AFSF) Sets the Euler parameters to values calculated from the given orientation matrix. Verify() Verifies the consistency of this object.
7.6. CLASS EULERPARAMS
7.6.1
127
EulerParams Constructor Detail
public: EulerParams::EulerParams() Default constructor. It creates the object in a default state.
public: virtual EulerParams::∼EulerParams() Virtual destructor.
7.6.2
EulerParams Method Detail
public: void EulerParams::CalculateD2A dp dq(int p, int q, double * D2Adpdq) Calculates the second derivative of the orientation matrix AFS,F with respect to sp and sq , or ∂ 2 AFS,F /∂sp ∂sq , where the indexes p and q are in the range 0 to 3 and sp and sq are the corresponding Euler parameters. Arguments • pq
The integer indexes of two Euler parameters, in the range 0 to 3.
• D2Adpdq
The second partial derivative ∂ 2 AFS,F /∂sp ∂sq .
128
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerParams::CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates the 3 × n matrix ∂(AFS,F uS )/∂s, where the given vector uS is constant in system S and s is the n × 1 column vector of orientational specific coordinates, and n is 4 in this case. Arguments • uS A reference to a constant Vector3 object that contains the given vector uS , expressed in system S. The vector is constant in system S. • Result A reference to a PMatrix object, which, upon return, will contain the resulting 3 × n matrix.
public: void EulerParams::CalculatedA ds(int s, double * dAds) Calculates the 3×3 matrix ∂A/∂ss where s is the column vector of Euler parameters [s0 , s1 , s2 , s3 ]T . Arguments • s
The integer 0-based index of one of the Euler parameters in the range 0 to 3.
• dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
7.6. CLASS EULERPARAMS
129
public: int EulerParams::CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific accelerations s¨ from a given angular acceleration αFS,F of system S relative to system F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 4 in this case. Arguments • alfa FSS A reference to a constant Vector3 object containing the given angular acceleration αFS,F of system S relative to system F. • dotDots A pointer to an array of doubles, which, upon return, will contain the resulting specific accelerations. The length of the array must be at least equal to 4.
public: int EulerParams::CalculateDots(const Vector3 & omega FSF, double * dots) Calculates the orientational specific velocities s˙ from a given angular velocity ωFS,F of system S relative to system F. The results are returned by argument in an array. Return The number of orientational specific coordinates, 4 in this case. Arguments • omega FSF A reference to a constant Vector3 object containing the given angular velocity ωFS,F of system S relative to system F. • dots A pointer to an array of doubles, which, upon return, will contain the resulting specific velocities. The length of the array must be at least equal to 4.
130
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerParams::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the Euler parameters, and returns the elements of the resulting matrix in an array, by rows. Arguments • aa A pointer to an array of doubles of length at least 9, which, upon return, will contain the elements of the resulting matrix by rows.
public: void EulerParams::CalculateMatrixA(OrthoMatrix & AFSF) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the Euler parameters. Arguments • AFSF A reference to an OrthoMatrix object, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixB(PMatrix & B) Calculates the 4 × 4 matrix BFS,F from the current values of the Euler parameters and returns the result by argument. Arguments • B A reference to a PMatrix object of size 4 × 4, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixBR(PMatrix & BR) Calculates the 4 × 4 matrix BFS,S from the current values of the Euler parameters and returns the result by argument. Arguments • BR A reference to a PMatrix object of size 4 × 4, which, upon return, will contain the resulting matrix.
7.6. CLASS EULERPARAMS
131
public: void EulerParams::CalculateMatrixG(PMatrix & G) Calculates the 3 × 4 matrix GFS,F from the current values of the Euler parameters. The result is returned by argument. Arguments • G A reference to a PMatrix object of size 3 × 4, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F from the current values of the Euler parameters and velocities. The result is returned by argument. Arguments • GDot A reference to a PMatrix object of size 3 × 4, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixGR(PMatrix & GR) Calculates the 3 × 4 matrix GFS,S from the current values of the Euler parameters. The result is returned by argument. Arguments • GR A reference to a PMatrix object of size 3 × 4, which, upon return, will contain the resulting matrix.
132
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerParams::CalculateMatrixGRDot(PMatrix & GRDot) Calculates the 3 × 4 matrix G˙ FS,S from the current values of the Euler parameters and velocities. The result is returned by argument. Arguments • GRDot A reference to a PMatrix object of size 3 × 4, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × 4 matrix P from the current values of the orientational specific coordinates and velocities and a given value of the angular velocity ωFS,S , and returns the result by argument. Arguments • omegaFSS A reference to a constant Vector3 object that contains the given angular velocity ωFS,S . • P A reference to a PMatrix object of size 3 × 4, which, upon return, will contain the resulting matrix.
public: void EulerParams::CalculateMatrixR(PMatrix & R) Calculates the 3 × 3 matrix R from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • R A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
7.6. CLASS EULERPARAMS
133
public: void EulerParams::CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • omega FSF
A reference to a Vector3 object, which, upon return, will contain the result.
public: void EulerParams::CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F from the current values of the orientational specific coordinates and the given values of the orientational specific velocities, and returns the result by argument. Arguments • dots A pointer to a constant array of doubles that contains the given orientational specific velocities. • omega FSF result.
A reference to a CSVector object, which, upon return, will contain the
public: void EulerParams::CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S from the current values of the orientational specific coordinates and velocities, and returns the result by argument. Arguments • omega FSS
A reference to a Vector3 object, which, upon return, will contain the result.
134
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerParams::CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S from the current values of the orientational specific coordinates and the given values of the orientational specific velocities, and returns the result by argument. Arguments • dots A pointer to a constant array of doubles that contains the given orientational specific velocities. • omega FSS result.
A reference to a CSVector object, which, upon return, will contain the
public: Str EulerParams::DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one orientational specific coordinate. Return An Str object with the desired report. Arguments • specor 0 to 3.
The integer index of the orientational specific coordinate of interest, in the range
public: Str EulerParams::DescribeMeaningOfSpecors() Creates a report describing the meaning of all orientational specific coordinate. Return An Str object with the desired report.
public: Str EulerParams::GetClass() Returns the name of this class. Return An Str object that contains the name of this class.
7.6. CLASS EULERPARAMS
135
public: int EulerParams::GetNumberCoordinates() Returns the number of orientational specific coordinates, 4 in this case. Return The integer number of orientational specific coordinates.
public: bool EulerParams::IsStable() Verifies if this object is in a stable condition. The Euler parameters system of orientational specific coordinates is always stable. Return true .
public: void EulerParams::SetDots(const double * paramDots) Sets the Euler parameter velocities to the given values. Arguments • paramDots A pointer to a constant array of doubles that contains the new values for the Euler velocities.
public: void EulerParams::SetDots(const CSVector & omega FSF) Sets the Euler parameter velocities to values calculated from the given angular velocity ωFS,F . Arguments • omega FSF A reference to a constant CSVector object that contains the given value of the angular velocity ωFS,F .
136
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void EulerParams::SetValues(const double * params) Sets the Euler parameters to the values passed in an array. Arguments • params A pointer to a constant array of doubles containing the new values for the Euler parameters.
public: void EulerParams::SetValues(const OrthoMatrix & AFSF) Sets the Euler parameters to values calculated from the given orientation matrix AFS,F . Arguments • AFSF A reference to a constant OrthoMatrix object containing the given orientation matrix AFS,F .
public: bool EulerParams::Verify() Verifies the consistency and correctness of this object. This method is intended for debugging. Return true if this object is correct, false otherwise.
7.7. CLASS ORIENTATOR
7.7
137
Class Orientator
Abstract class used as base for all orientational specific coordinate classes such as Euler Angles and Euler Parameters. An Orientator object controls the orientation of a coordinate system by associating the state variables with the orientational specific coordinates. It provides support for conversion between orientational specific coordinates and the state variables associated with orientation such as the orientation matrix and the angular velocity, and for the calculation of the kinematic matrices G, H, P, Q, and R.
Attribute Summary protected: ArrayOfDoubles protected: ArrayOfDoubles
tVal An ArrayOfDoubles object that contains the values of the orientational specific coordinates. tDot An ArrayOfDoubles object that contains the time derivatives of the orientational specific coordinates.
Constructor Summary public: public: virtual
Orientator() Constructor. It constructs the object in a default state. ∼Orientator() Destructor. It destroys the object.
138
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary public: virtual void public: virtual void public: virtual int public: virtual public: virtual public: virtual public: void public: virtual public: virtual public: virtual public: virtual public: virtual public: virtual
int void void
void void void void void void
public: virtual void public: virtual void public: virtual void
CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) Calculates ∂(AF S,F uS )/∂s where the given vector uS is constant in system S. CalculatedA ds(int s, double * dAds) Calculates ∂AFS,F /∂s. CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific accelerations s¨ and returns the result in an array. CalculateDots(const Vector3 & omega FSF, double * dots) ˙ Calculates the orientational specific velocities s. CalculateMatrixA(double * aa) Calculates the orientation matrix AFS,F and returns its elements in an array. CalculateMatrixA(OrthoMatrix & A) Calculates the orientation matrix AFS,F . CalculateMatrixADot(PMatrix & ADot) Calculates matrix A˙ FS,F . CalculateMatrixG(PMatrix & G) Calculates matrix GFS,F CalculateMatrixGDot(PMatrix & GDot) Calculates matrix G˙ FS,F CalculateMatrixGR(PMatrix & GR) Calculates matrix GFS,S CalculateMatrixGRDot(PMatrix & GRDot) Calculates matrix G˙ FS,S CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates matrix P from a given angular velocity ωFS,F . CalculateMatrixQ(PMatrix & Q) Calculates matrix Q from the current values of the orientational specific coordinates and velocities. CalculateMatrixR(PMatrix & R) Calculates matrix R CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F from the current values of the orientational specific coordinates and velocities. CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F from given orientational specific velocities, and using the current values of the orientational specific coordinates.
7.7. CLASS ORIENTATOR
139
Method Summary (continued) public: virtual void public: virtual void public: virtual Str public: virtual Str public: virtual Str public: const double * public: virtual int public: const double * public: virtual bool public: virtual void public: virtual void public: virtual void public: virtual void public: virtual bool
CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S from the current values of the orientational specific coordinates and velocities. CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S from given orientational specific velocities, and using the current values of the orientational specific coordinates. DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one of the orientational specific coordinates. DescribeMeaningOfSpecors() Creates a report describing the meaning of each orientational specific coordinate. GetClass() Returns the name of the class that the calling object belongs to. GetDots() Returns a pointer to the constant internal array containing the values of the orientational specific velocities. GetNumberCoordinates() Returns the number of orientational specific coordinates. GetValues() Returns a pointer to the constant internal array containing the values of the orientational specific coordinates. IsStable() Returns a boolean value indicating if the caller object is stable. SetDots(const double * dots) Sets the orientational specific velocities to the values given in an array. SetDots(const CSVector & omega FSF) Sets the orientational specific velocities to values calculated from the angular velocity ωFS,F SetValues(const double * values) Sets the orientational specific coordinates to the values passed by the caller. SetValues(const OrthoMatrix & AFSF) Sets the orientational specific coordinates to values calculated from the orientation matrix AFS,F . Verify() Verifies the consistency of this Orientator object.
140
7.7.1
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Orientator Attribute Detail
protected: ArrayOfDoubles tVal An ArrayOfDoubles object that contains the values of the orientational specific coordinates.
protected: tDot An ArrayOfDoubles object that contains the time derivatives of the orientational specific coordinates.
7.7.2
Orientator Constructor Detail
public: Orientator::Orientator() Constructor. It constructs the object in a default state.
public: virtual Orientator::∼Orientator() Virtual destructor. It destroys the object.
7.7. CLASS ORIENTATOR
7.7.3
141
Orientator Method Detail
public: virtual void Orientator::CalculateDAuSDs(const Vector3 & uS, PMatrix & Result) This pure virtual method calculates the 3 × n matrix ∂(AFS,F uS )/∂s, where the given vector uS is constant in system S and s is the n × 1 column vector of orientational specific coordinates. Arguments • uS A reference to a constant Vector3 object that contains the given vector uS , expressed in system S. The vector is constant in system S. • Result A reference to a PMatrix object, which, upon return, will contain the resulting 3 × n matrix.
public: virtual void Orientator::CalculatedA ds(int s, double * dAds) This pure virtual method calculates ∂A/∂s where s is the column vector of orientational specific coordinates [s0 , . . . , sn−1 ]T . Arguments • s The integer 0-based index of one of the orientational specific coordinates in the range 0 to n − 1, where n is the number of orientational specific coordinates. • dAds Pointer to an array of doubles, which, upon return, will contain the values of the elements of the resulting matrix, by rows.
142
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual int Orientator::CalculateDotDots(const Vector3 & alfa FSS, double * dotDots) Calculates the orientational specific accelerations s¨, where s = [s0 , . . . , sn−1 ]T are the orientational specific coordinates, from a given angular acceleration αFS,F of system S relative to F. The results are returned by argument in an array. Return The number of orientational specific coordinates. Arguments • alfa FSS A reference to a constant Vector3 object containing the given angular acceleration αFS,F of system S relative to F. • dotDots A pointer to an array of doubles, which, upon return, will contain the desired specific accelerations. The length of the array must be at least equal to the number of orientational specific coordinates.
public: virtual int Orientator::CalculateDots(const Vector3 & omega FSF, double * dots) ˙ where s = [s0 , . . . , sn−1 ]T are the orientational Calculates the orientational specific velocities s, specific coordinates, from a given angular velocity ωFS,F of system S relative to F. Return The number of orientational specific coordinates. Arguments • omega FSF A reference to a constant Vector3 object containing the given angular velocity ωFS,F of system S relative to F • dots A pointer to an array of doubles, which, upon return, will contain the desired specific velocities. The length of the array must be at least equal to the number of orientational specific coordinates. The values of the orientational specific coordinates stored internally in this object are not modified.
7.7. CLASS ORIENTATOR
143
public: virtual void Orientator::CalculateMatrixA(double * aa) Calculates the 3 × 3 orientation matrix AFS,F and returns its elements in an array, by rows. Arguments • aa A pointer to an array of doubles, which, upon return, will contain the resultin elements of the orientation matrix, ordered by row. The array must be at least 9 elements long.
public: virtual void Orientator::CalculateMatrixA(OrthoMatrix & A) Calculates the 3 × 3 orientation matrix AFS,F from the current values of the orientational specific coordinates. Arguments • A A reference to an OrthoMatrix object, which, upon return, will contain the resulting matrix.
public: void Orientator::CalculateMatrixADot(PMatrix & ADot) Calculates the 3 × 3 matrix A˙ FS,F , where AFS,F is the orientation matrix of coordinate system S relative to F, expressed in system F. Arguments • ADot A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
public: virtual void Orientator::CalculateMatrixG(PMatrix & G) Calculates the 3 × n matrix GFS,F for system S relative to F, expressed in system F, where n is the number of orientational specific coordinates. Arguments • G A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
144
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void Orientator::CalculateMatrixGDot(PMatrix & GDot) Calculates the 3 × n matrix G˙ FS,F for system S relative to F, expressed in system F, where n is the number of orientational specific coordinates. Arguments • GDot A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: virtual void Orientator::CalculateMatrixGR(PMatrix & GR) Calculates the 3 × n matrix GFS,S for system S relative to F, expressed in system S, where n is the number of orientational specific coordinates. Arguments • GR A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: virtual void Orientator::CalculateMatrixGRDot(PMatrix & GRDot) Calculates the 3 × n matrix G˙ FS,S for system S relative to F, expressed in system S, where n is the number of orientational specific coordinates. Arguments • GRDot A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
7.7. CLASS ORIENTATOR
145
public: virtual void Orientator::CalculateMatrixP(const Vector3 & omegaFSS, PMatrix & P) Calculates the 3 × n matrix P from a given angular velocity ωFS,F , where n is the number of orientational specific coordinates. Arguments • omegaFSS A reference to a constant Vector3 object containing the given angular velocity ωFS,F . • P A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: virtual void Orientator::CalculateMatrixQ(PMatrix & Q) Calculates the 3 × n matrix Q from the current values of the orientational specific coordinates and velocities, where n is the number of orientational specific coordinates. Arguments • Q A reference to a PMatrix object of size 3 × n, which, upon return, will contain the resulting matrix.
public: virtual void Orientator::CalculateMatrixR(PMatrix & R) Calculates the 3 × 3 matrix R. Arguments • R A reference to a PMatrix object of size 3 × 3, which, upon return, will contain the resulting matrix.
146
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void Orientator::CalculateOmega FSF(Vector3 & omega FSF) Calculates the angular velocity ωFS,F of system S relative to system F, expressed in system F, from the current values of the orientational specific coordinates and velocities. Arguments • omega FSF A reference to a Vector3 object, which, upon return, will contain the resulting angular velocity.
public: virtual void Orientator::CalculateOmega FSF(const double * dots, CSVector & omega FSF) Calculates the angular velocity ωFS,F of system S relative to system F, expressed in system F, from given orientational specific velocities, and using the current values of the orientational specific coordinates. Arguments • dots A pointer to a constant array of doubles that contains the given values of the orientational specific velocities. • omega FSF A reference to a CSVector object, which, upon return, will contain the resulting angular velocity.
public: virtual void Orientator::CalculateOmega FSS(Vector3 & omega FSS) Calculates the angular velocity ωFS,S of system S relative to system F, expressed in system S, from the current values of the orientational specific coordinates and velocities. Arguments • omega FSS A reference to a Vector3 object, which, upon return, will contain the resulting angular velocity.
7.7. CLASS ORIENTATOR
147
public: virtual void Orientator::CalculateOmega FSS(const double * dots, CSVector & omega FSS) Calculates the angular velocity ωFS,S of system S relative to system F, expressed in system S, from given orientational specific velocities, and using the current values of the orientational specific coordinates. Arguments • dots A pointer to a constant array of doubles that contains the given values of the orientational specific velocities. • omega FSS A reference to a CSVector object, which, upon return, will contain the resulting angular velocity.
public: virtual Str Orientator::DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of one of the orientational specific coordinates. Return An Str object containing the resulting report. Arguments • specor The integer index of one of the orientational specific coordinates, in the range 0 to n − 1, where n is the number of orientational specific coordinates.
public: virtual Str Orientator::DescribeMeaningOfSpecors() Creates a report describing the meaning of each orientational specific coordinate. Return An Str object containing the resulting report.
public: virtual Str Orientator::GetClass() Returns the name of the class that the calling object belongs to. Return An Str object containing the name of the class of the calling object.
148
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: const double * Orientator::GetDots() Returns a pointer to the constant internal array containing the values of the orientational specific velocities. Return A pointer to the constant internal array of doubles containing the values of the orientational specific velocities.
public: virtual int Orientator::GetNumberCoordinates() Returns the number of orientational specific coordinates. Return The integer number of orientational specific coordinates.
public: const double * Orientator::GetValues() Returns a pointer to the constant internal array containing the values of the orientational specific coordinates. Return The integer number of orientational specific coordinates.
public: virtual bool Orientator::IsStable() Returns a boolean value indicating if the caller object is stable. A system of orientational specific coordinates may become unstable under certain circumstances. For example, Euler angles are unstable near a singularity. This method warns the caller program if the condition is present, but takes no further action. Return true if the caller object is stable, false if not.
7.7. CLASS ORIENTATOR
149
public: virtual void Orientator::SetDots(const double * dots) This pure virtual method sets the orientational specific velocities of the caller object to the values passed in an array. Arguments • dots A pointer to a constant array of doubles that contains the new values for the orientational specific velocities.
public: virtual void Orientator::SetDots(const CSVector & omega FSF) This pure virtual method sets the orientational specific velocities to values calculated from the angular velocity ωFS,F Arguments • omega FSF ωFS,F
A reference to a constant CSVector object that contains the angular velocity
public: virtual void Orientator::SetValues(const double * values) This pure virtual method sets the orientational specific coordinates of the caller object to the values passed in an array. Arguments • values A pointer to a constant array of doubles that contains the new values for the orientational specific coordinates.
150
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void Orientator::SetValues(const OrthoMatrix & AFSF) A pure virtual method that sets the orientational specific coordinates to values calculated from the orientation matrix AFS,F . Arguments • AFSF A reference to a constant OrthoMatrix object that contains the given orientation matrix AFS,F .
public: virtual bool Orientator::Verify() Verifies the consistency of this Orientator object. Useful for debugging. Return true if this object is correct, false otherwise.
7.8
Class Translator
Abstract class used as base for all translational specific coordinate classes. Provides support for conversion between translational specific coordinates and the state variables associated with translation such as position and velocity, and for the calculation of the kinematic matrix H.
Attribute Summary protected: ArrayOfDoubles protected: ArrayOfDoubles
tVal An ArrayOfDoubles object that contains the values of the translational specific coordinates. tDot An ArrayOfDoubles object that contains the time derivatives of the translational specific coordinates.
7.8. CLASS TRANSLATOR
151
Constructor Summary public: public: virtual
Translator() Public constructor. It creates the object but does nothing else. ∼Translator() Public destructor. It destroys the object.
Method Summary public: virtual int public: virtual void public: virtual void public: virtual void public: virtual Str public: const double * public: virtual int public: const double * public: virtual void public: virtual void
CalculateDots(const Vector3 & v FSF, double * dots) Calculates the translational specific velocities for a given value of the state variable vFS,F . CalculateLinearVelocity(Vector3 & V FSF) Calculates the linear velocity vFS,F from the current values of the translational specific coordinates and velocities. CalculateMatrixH(PMatrix & H) Calculates the kinematic matrix H from the current values of the translational specific coordinates. CalculatePositionVector(Vector3 & R FSF) Calculates the position vector rFS,F from the current values of the translational specific coordinates. GetClass() Returns the name of the derived class that the caller object belongs to. GetDots() Returns a pointer to the array where the current values of the translational specific velocities are stored. GetNumberCoordinates() Returns the number of translational specific coordinates for the class of the caller object. GetValues() Returns a pointer to the array where the current values of the translational specific coordinates are stored. SetDots(const double * dots) Sets the translational specific velocities to the values given in an array. SetValues(const double * values) Sets the translational specific coordinates to the values passed by the caller.
152
7.8.1
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Translator Attribute Detail
protected: ArrayOfDoubles tVal An ArrayOfDoubles object that contains the values of the translational specific coordinates.
protected: ArrayOfDoubles tDot An ArrayOfDoubles object that contains the time derivatives of the translational specific coordinates.
7.8.2
Translator Constructor Detail
public: Translator::Translator() Public constructor. It creates the object but does nothing else.
public: virtual Translator::∼Translator() Public virtual destructor. It destroys the object.
7.8. CLASS TRANSLATOR
7.8.3
153
Translator Method Detail
public: virtual int Translator::CalculateDots(const Vector3 & v FSF, double * dots) Pure virtual method that calculates the translational specific velocities corresponding to a given value of vFS,F , the velocity of coordinate system S relative to system F. The values of the translational specific coordinates themselves are also used in the calculations and must have been updated as needed prior to calling this method. The results are returned by argument in an array. Return The number of translational specific coordinates. Arguments • v FSF vFS,F .
A reference to a constant Vector3 object that contains the given linear velocity
• dots Upon return, this array will contain the calculated values of the translational specific velocities.
public: virtual void Translator::CalculateLinearVelocity(Vector3 & V FSF) Pure virtual method that calculates the linear velocity vFS,F of the origin of system S relative to system F, from the current values of the translational specific coordinates and velocities. Returns the result by argument. Arguments • V FSF A reference to a Vector3 object, which, upon return, will contain the calculated linear velocity vFS,F .
154
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: virtual void Translator::CalculateMatrixH(PMatrix & H) Pure virtual method that calculates the kinematic matrix H from the current values of the translational specific coordinates. Returns the results by argument. Arguments • H A reference to a PMatrix object, which, upon return, will contain the calculated matrix H.
public: virtual void Translator::CalculatePositionVector(Vector3 & R FSF) Pure virtual method that calculates the position vector rFS,F of the origin of system S relative to system F from the current values of the translational specific coordinates. Returns the result by argument. Arguments • R FSF A reference to a Vector3 object, which, upon return, will contain the calculated position vector rFS,F .
public: virtual Str Translator::GetClass() This pure virtual method returns the name of the derived class that the caller object belongs to. Return An Str object with the name of the derived class that the caller object belongs to.
public: const double * Translator::GetDots() Returns a pointer to the constant array of doubles where the current values of the translational specific velocities are stored. Return A pointer to the constant internal array of doubles tDot that contains the values of translational specific velocities.
7.8. CLASS TRANSLATOR
155
public: virtual int Translator::GetNumberCoordinates() Returns the number of translational specific coordinates or velocities for the class of the caller object. Return The number of translational specific coordinates for the caller object.
public: const double * Translator::GetValues() Returns a pointer to a constant array of doubles where the current values of the translational specific coordinates are stored. Return A pointer to the constant internal array of doubles tVal that contains the values of translational specific coordinates.
public: virtual void Translator::SetDots(const double * dots) This pure virtual method sets the translational specific velocities of the caller object to the values passed in an array. Arguments • dots A pointer to the constant array of doubles that contains the new values for the translational specific velocities.
public: virtual void Translator::SetValues(const double * values) This pure virtual method sets the translational specific coordinates of the caller object to the values passed in an array. Arguments • values A pointer to the constant array of doubles that contains the new values for the translational specific coordinates.
156
7.9
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Class TranslatorXYZ Translator TranslatorXYZ
This class describes a system of independent translational specific coordinates where the three cartesian components rx , ry , rz of the position vector rFS,F are used as the translational specific coordinates.
Constructor Summary public: public:
TranslatorXYZ() Public constructor. ∼TranslatorXYZ() Public destructor.
Method Summary public: int public: void public: void public: void public: Str public: int public: void public: void
CalculateDots(const Vector3 & v FSF, double * dots) Calculates the translational specific velocities for a given value of the state variable vFS,F . CalculateLinearVelocity(Vector3 & V FSF) Calculates the linear velocity vFS,F from the current values of the translational specific coordinates and velocities. CalculateMatrixH(PMatrix & H) Calculates the kinematic matrix HFS,F from the current values of the translational specific coordinates. CalculatePositionVector(Vector3 & R FSF) Calculates the position vector rFS,F from the current values of the translational specific coordinates. GetClass() Returns the name of this class. GetNumberCoordinates() Returns the number of translational specific coordinates. SetDots(const double * dots) Sets the translational specific velocities to the values given in an array. SetValues(const double * values) Sets the translational specific coordinates to the values passed by the caller.
7.9. CLASS TRANSLATORXYZ
7.9.1
157
TranslatorXYZ Constructor Detail
public: TranslatorXYZ::TranslatorXYZ() Public constructor. It creates the object and sets the internal arrays tVal and tDot , but leaves the values undetermined.
public: TranslatorXYZ::∼TranslatorXYZ() Public destructor. It destroys the object.
7.9.2
TranslatorXYZ Method Detail
public: int TranslatorXYZ::CalculateDots(const Vector3 & v FSF, double * dots) Pure virtual method that calculates the translational specific velocities corresponding to a given value of vFS,F , the velocity of coordinate system S relative to system F. The values of the translational specific coordinates themselves are also used in the calculations and must have been updated as needed prior to calling this method. The results are returned by argument in an array. Return The number of translational specific coordinates. Arguments • v FSF vFS,F .
A reference to a constant Vector3 object which contains the given linear velocity
• dots A pointer to an array of doubles, which, upon return, will contain the calculated values of the translational specific velocities.
158
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void TranslatorXYZ::CalculateLinearVelocity(Vector3 & V FSF) Calculates the linear velocity vFS,F of the origin of system S relative to system F, from the current values of the translational specific coordinates and velocities. Returns the result by argument. Arguments • V FSF A reference to a Vector3 object, which, upon return, will contain the calculated linear velocity vFS,F .
public: void TranslatorXYZ::CalculateMatrixH(PMatrix & H) Calculates the kinematic matrix HFS,F from the current values of the translational specific coordinates. Returns the results by argument. Arguments • H A reference to a PMatrix object, which, upon return, will contain the calculated matrix HFS,F .
public: void TranslatorXYZ::CalculatePositionVector(Vector3 & R FSF) Calculates the position vector rFS,F of the origin of system S relative to system F from the current values of the translational specific coordinates. Returns the result by argument. Arguments • R FSF A reference to a Vector3 object, which, upon return, will contain the calculated position vector rFS,F .
public: Str TranslatorXYZ::GetClass() Returns the name of this class, “TranslatorXYZ” in this case. Return An Str object with the name of this class.
7.10. CLASS ORTHOMATRIX
159
public: int TranslatorXYZ::GetNumberCoordinates() Returns the number of translational specific coordinates, 3 in this case. Return The integer value of the number of translational specific coordinates.
public: void TranslatorXYZ::SetDots(const double * dots) Sets the translational specific velocities to the values passed in an array. Arguments • dots A pointer to a constant array of doubles that contains the new values for the translational specific velocities.
public: void TranslatorXYZ::SetValues(const double * values) Sets the translational specific coordinates to the values passed by the caller. Arguments • values A pointer to a constant array of doubles that contains the new values for the translational specific coordinates.
7.10
Class OrthoMatrix PMatrix Matrix3 OrthoMatrix
This class describes a 3 × 3 orthogonal matrix. A matrix A is orthogonal if it satisfies AT = A−1 . A 3 × 3 orthogonal matrix defines a set of three mutually perpendicular unit vectors in 3D space. The elements of the columns of the matrix are the components of the three vectors, taken in the order defined by the right-hand rule. The three vectors constitute the orthonormal base of a coordinate system.
160
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Constructor Summary public:
private:
public:
public:
public:
public:
public:
public:
public:
public: virtual
OrthoMatrix(const Vector3 & axis, double angle) Public constructor. It constructs this orthogonal matrix by rotating the identity matrix by a given angle about a given axis. OrthoMatrix(const Matrix3 & other) Private constructor. It constructs this object with a matrix that is orthogonal but not necessarily contained in an OrthoMatrix object. OrthoMatrix(const EulerParams & EP) Public constructor. It constructs this orthogonal matrix as defined by given Euler parameters orientational specific coordinates. OrthoMatrix(const EulerAngles & EA) Public constructor. It constructs this orthogonal matrix as defined by given Euler angles orientational specific coordinates. OrthoMatrix() Public constructor. It constructs this orthogonal matrix as the identity matrix. OrthoMatrix(const Vector3 & p, int whichCol) Public constructor. It constructs this orthogonal matrix with a specified direction for one of the unit vectors of its orthonormal base. The other two directions are taken arbitrarily. OrthoMatrix(const OrthoMatrix & other) Public constructor. It constructs this orthogonal matrix as an identical copy of another. OrthoMatrix(double angle, const Vector3 & axis) Public constructor. It constructs this orthogonal matrix by rotating each of the three base unit vectors of the coordinate system by an angle around an axis. OrthoMatrix(const Vector3 & u, const Vector3 & v) Public constructor. It constructs this orthogonal matrix with an orthonormal base determined by two given vectors. ∼OrthoMatrix() Public destructor.
7.10. CLASS ORTHOMATRIX
161
Method Summary public: bool public: bool public: bool
public: bool public: bool public: void public: double
public: void public: void public: void public: void public: void public: void public: void public: void
Create(const OrthoMatrix & other) Creates this orthogonal matrix as an identical copy of another. Create(const Vector3 & u, const Vector3 & v) Creates this orthogonal matrix with an orthonormal base determined by two given vectors. Create(const Vector3 & p, int whichCol) Creates this orthogonal matrix with a specified direction for one of the unit vectors of its orthonormal base. The other two directions are taken arbitrarily. Create(const Vector3 & axis, double angle) Creates this orthogonal matrix by rotating the identity matrix by a given angle about a given axis. Create(double angle, const Vector3 & axis) Creates this orthogonal matrix by rotating each of the three base unit vector of the coordinate system by an angle around an axis. CreateAsIdentity() Creates this orthogonal matrix as the identity matrix. GetAxisAndAngleOfRotation(UnitVector3 & axis) The orthonormal base defined by this orthogonal matrix can be obtained by a rotation of the original orthonormal base. This method finds the axis and angle of rotation. GetMyTranspose(OrthoMatrix & Result) Returns the transpose of this orthogonal matrix. MeEqualsMeTimesOrthoMatrix(const OrthoMatrix & M) Multiplies this orthogonal matrix by another given orthogonal matrix. MeEqualsMeTimesOrthoMatrixTransposed(const OrthoMatrix & M) Multiplies this orthogonal matrix by the transpose of another given orthogonal matrix. MeEqualsMeTransposedTimesOrthoMatrix(const OrthoMatrix & M) Transposes this orthogonal matrix and multiplies the result by another given orthogonal matrix. MeEqualsOrthoMatrixTimesMe(const OrthoMatrix & M) Premultiplies this orthogonal matrix with another given orthogonal matrix. MeEqualsOrthoMatrixTimesMeTransposed(const OrthoMatrix & M) Premultiplies the transpose of this orthogonal matrix with another given orthogonal matrix. MeEqualsOrthoMatrixTransposedTimesMe(const OrthoMatrix & M) Premultiplies this orthogonal matrix with the transpose of another given orthogonal matrix. MeTimesOrthoMatrix(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix and another given orthogonal matrix.
162
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Method Summary (continued) public: void
public: void
public: void
public: void
public: Vector3 public: CSVector public: OrthoMatrix public: Matrix3 public: Matrix3 public: Matrix3 public: OrthoMatrix public: OrthoMatrix & public: void public: void public: bool
MeTimesOrthoMatrixTimesMeTransposed(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix by another given orthogonal matrix and by the transpose of this matrix. MeTimesOrthoMatrixTransposed(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix and the transpose of another given orthogonal matrix. MeTransposedTimesOrthoMatrix(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of the transpose of this orthogonal matrix and another given orthogonal matrix. MeTransposedTimesOrthoMatrixTimesMe(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of the transpose of this orthogonal matrix, another given orthogonal matrix, and this matrix. operator*(const Vector3 & uu) Calculates the product of this orthogonal matrix and a column vector. operator*(const CSVector & uu) Calculates the product of this orthogonal matrix and a column vector. operator*(const OrthoMatrix & M) Calculates the product of this orthogonal matrix and another given orthogonal matrix. operator*(double dd) Calculates the product of this orthogonal matrix by a number. operator+(const PMatrix & other) Calculates the sum of this orthogonal matrix and another 3 × 3 matrix. operator-(const PMatrix & other) Calculates the difference between this orthogonal matrix and another 3 × 3 matrix. operator-() Calculates the negative of this orthogonal matrix. operator=(const OrthoMatrix & other) Calculates this orthogonal matrix as an exact copy of another orthogonal matrix. ReadFromFile(FILE * file) Reads this orthogonal matrix from a given file. SaveToFile(FILE * file) Saves this orthogonal matrix to a file. Verify() Verifies the orthogonality of this orthogonal matrix.
7.10. CLASS ORTHOMATRIX
7.10.1
163
OrthoMatrix Constructor Detail
public: OrthoMatrix::OrthoMatrix(const Vector3 & axis, double angle) Public constructor. It constructs this orthogonal matrix by rotating the identity matrix by a given angle about a given axis. Arguments • axis A reference to a constant Vector3 object that contains a unit vector in the direction of the axis of rotation. • angle
The angle of rotation in radians.
private: OrthoMatrix::OrthoMatrix(const Matrix3 & other) Private constructor. It constructs this object with a 3 × 3 matrix that is orthogonal but not necessarily contained in an OrthoMatrix object. The caller is responsible for providing a matrix that is truly orthogonal. Arguments • other matrix.
A reference to a constant Matrix3 object that contains the given 3×3 orthogonal
public: OrthoMatrix::OrthoMatrix(const EulerParams & EP) Public constructor. It constructs this orthogonal matrix as defined by the Euler parameters orientational specific coordinates given in an EulerParams object. Arguments • EP A reference to an EulerParams object that contains the given Euler parameters orientational specific coordinates.
164
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: OrthoMatrix::OrthoMatrix(const EulerAngles & EA) Public constructor. It constructs this orthogonal matrix as defined by the Euler angles orientational specific coordinates given in an EulerAngles object. Arguments • EA A reference to an EulerAngles object that contains the given Euler angles orientational specific coordinates.
public: OrthoMatrix::OrthoMatrix() Public constructor. It constructs this orthogonal matrix as the 3 × 3 identity matrix.
public: OrthoMatrix::OrthoMatrix(const Vector3 & p, int whichCol) Public constructor. It constructs this orthogonal matrix with a specified direction for one of the unit vectors of its orthonormal base. The other two directions are taken arbitrarily. Arguments • p A reference to a constant Vector3 object that contains a vector that defines the desired direction. • whichCol The direction of the given vector is used to determine the direction of one of the three unit vectors of the orthonormal base. This parameter determines which unit vector’s direction. Range 1 to 3.
public: OrthoMatrix::OrthoMatrix(const OrthoMatrix & other) Public constructor. It constructs this orthogonal matrix as an identical copy of another. Arguments • other matrix.
A reference to a constant OrthoMatrix object that contains the given orthogonal
7.10. CLASS ORTHOMATRIX
165
public: OrthoMatrix::OrthoMatrix(double angle, const Vector3 & axis) Public constructor. It constructs this orthogonal matrix by rotating each of the three base unit vector of the coordinate system by an angle around an axis. Arguments • angle
The angle of rotation, in radians.
• axis A reference to a constant Vector3 object that contains a unit vector in the direction of the axis of rotation.
public: OrthoMatrix::OrthoMatrix(const Vector3 & u, const Vector3 & v) Public constructor. It constructs this orthogonal matrix with an orthonormal base determined by two given vectors u and v. The first direction in the orthonormal base is the direction of vector u. The second direction is the direction of the component of v perpendicular to u. The third direction is perpendicular to u and v and given by the right-hand rule. Arguments • u , v References to two Vector3 objects that contain the two given vectors. Both vectors must be different from zero and not parallel to each other.
public: virtual OrthoMatrix::∼OrthoMatrix() Public destructor.
166
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
7.10.2
OrthoMatrix Method Detail
public: bool OrthoMatrix::Create(const OrthoMatrix & other) Creates this orthogonal matrix as an identical copy of another. Return Always returns true . Arguments • other matrix.
A reference to a constant OrthoMatrix object that contains the given orthogonal
public: bool OrthoMatrix::Create(const Vector3 & u, const Vector3 & v) Creates this orthogonal matrix with an orthonormal base determined by two given vectors u and v. The first direction in the orthonormal base is the direction of vector u. The second direction is the direction of the component of v perpendicular to u. The third direction is perpendicular to u and v and given by the right-hand rule. Return true if execution was successful, false if not. Arguments • u , v References to two Vector3 objects that contain the two given vectors. Both vectors must be different from zero and not parallel to each other.
7.10. CLASS ORTHOMATRIX
167
public: bool OrthoMatrix::Create(const Vector3 & p, int whichCol) Creates this orthogonal matrix with a specified direction for one of the unit vectors of its orthonormal base. The other two directions are taken arbitrarily. Return true if execution was successful, false if not. Arguments • p A reference to a constant Vector3 object that contains a vector that defines the desired direction. • whichCol The direction of the given vector is used to determine the direction of one of the three unit vectors of the orthonormal base. This parameter determines which unit vector’s direction. Range 1 to 3.
public: bool OrthoMatrix::Create(const Vector3 & axis, double angle) Creates this orthogonal matrix by rotating the identity matrix by a given angle about a given axis. Return true if execution was successful, false otherwise. Arguments • axis A reference to a constant Vector3 object that contains a unit vector in the direction of the axis of rotation. • angle
The angle of rotation in radians.
168
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: bool OrthoMatrix::Create(double angle, const Vector3 & axis) Creates this orthogonal matrix by rotating each of the three base unit vector of the coordinate system by an angle around an axis. Return true if execution was successful, false otherwise. Arguments • angle
The angle of rotation, in radians.
• axis A reference to a constant Vector3 object that contains a unit vector in the direction of the axis of rotation.
public: void OrthoMatrix::CreateAsIdentity() Creates this orthogonal matrix as the identity matrix.
public: double OrthoMatrix::GetAxisAndAngleOfRotation(UnitVector3 & axis) The orthonormal base defined by this orthogonal matrix can be obtained by a rotation of the original orthonormal base. This method finds the axis and angle of rotation. if A is this matrix and a is a unit vector along the axis, the following two conditions hold: A a = a and AT a = a Return The angle α of rotation in radians, in the range −π < α ≤ π. Arguments • axis A reference to a UnitVector3 object, which, upon return, will contain the unit vector that defines the axis of rotation. If the angle of rotation is zero, then the unit vector is undefined.
7.10. CLASS ORTHOMATRIX
169
public: void OrthoMatrix::GetMyTranspose(OrthoMatrix & Result) Returns the transpose of this orthogonal matrix. The transpose of an orthogonal matrix is also its inverse. Arguments • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 matrix.
public: void OrthoMatrix::MeEqualsMeTimesOrthoMatrix(const OrthoMatrix & M) Multiplies this orthogonal matrix by another given 3 × 3 orthogonal matrix. The product of two orthogonal matrices is an orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← A M. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
public: void OrthoMatrix::MeEqualsMeTimesOrthoMatrixTransposed(const OrthoMatrix & M) Multiplies this orthogonal matrix by the transpose of another given 3 × 3 orthogonal matrix. The result is also an orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← A MT . Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
170
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void OrthoMatrix::MeEqualsMeTransposedTimesOrthoMatrix(const OrthoMatrix & M) Transposes this orthogonal matrix and multiplies the result by another given 3 × 3 orthogonal matrix. The result is also an orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← AT M. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
public: void OrthoMatrix::MeEqualsOrthoMatrixTimesMe(const OrthoMatrix & M) Premultiplies this orthogonal matrix with another given orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← M A. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
public: void OrthoMatrix::MeEqualsOrthoMatrixTimesMeTransposed(const OrthoMatrix & M) Premultiplies the transpose of this orthogonal matrix with another given orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← M AT . Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
7.10. CLASS ORTHOMATRIX
171
public: void OrthoMatrix::MeEqualsOrthoMatrixTransposedTimesMe(const OrthoMatrix & M) Premultiplies this orthogonal matrix with the transpose of another given orthogonal matrix. If A is this matrix and M is the given matrix, this operation is A ← MT A. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
public: void OrthoMatrix::MeTimesOrthoMatrix(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix and another given orthogonal matrix, and returns the result by argument. If A is this matrix, M is the given matrix, and R is the result, this operation is R = A M. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix. • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 orthogonal matrix.
172
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: void OrthoMatrix::MeTimesOrthoMatrixTimesMeTransposed(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix by another given orthogonal matrix and by the transpose of this matrix, and returns the result by argument. If A is this matrix, M is the given matrix, and R is the result, this operation is R = A M AT . Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix. • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 orthogonal matrix.
public: void OrthoMatrix::MeTimesOrthoMatrixTransposed(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of this orthogonal matrix and the transpose of another given orthogonal matrix, and returns the result by argument. If A is this matrix, M is the given matrix, and R is the result, this operation is R = A MT . Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix. • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 orthogonal matrix.
7.10. CLASS ORTHOMATRIX
173
public: void OrthoMatrix::MeTransposedTimesOrthoMatrix(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of the transpose of this orthogonal matrix and another given orthogonal matrix, and returns the result by argument. If A is this matrix, M is the given matrix, and R is the result, this operation is R = AT M. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix. • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 orthogonal matrix.
public: void OrthoMatrix::MeTransposedTimesOrthoMatrixTimesMe(const OrthoMatrix & M, OrthoMatrix & Result) Calculates the product of the transpose of this orthogonal matrix, another given orthogonal matrix, and this matrix, and returns the result by argument. If A is this matrix, M is the given matrix, and R is the result, this operation is R = AT M A. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix. • Result A reference to an OrthoMatrix object, which, upon return, will contain the resulting 3 × 3 orthogonal matrix.
174
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: Vector3 OrthoMatrix::operator*(const Vector3 & uu) Calculates the product of this orthogonal matrix and a 3 × 1 column vector. If A is this matrix, u is the given vector, and r is the resulting vector, this operation is r = A u. Return A Vector3 object with the resulting 3 × 1 column vector. Arguments • uu A reference to a constant Vector3 object that contains the given 3 × 1 column vector.
public: CSVector OrthoMatrix::operator*(const CSVector & uu) Calculates the product of this orthogonal matrix and a 3 × 1 column vector. If A is this matrix, u is the given vector, and r is the resulting vector, this operation is r = A u. Return A CSVector object with the resulting 3 × 1 column vector. Arguments • uu A reference to a constant CSVector object that contains the given 3 × 1 column vector.
public: OrthoMatrix OrthoMatrix::operator*(const OrthoMatrix & M) Calculates the product of this orthogonal matrix and another given orthogonal matrix. If A is this matrix, M is the given matrix, and R is the result, this operation is R = A M. Return An OrthoMatrix object that contains the resulting 3 × 3 orthogonal matrix. Arguments • M A reference to a constant OrthoMatrix object that contains the given 3×3 orthogonal matrix.
7.10. CLASS ORTHOMATRIX
175
public: Matrix3 OrthoMatrix::operator*(double dd) Calculates the product of this orthogonal matrix by a number. The result is a 3 × 3 matrix which is not orthogonal. Return A Matrix3 object that contains the resulting matrix. Arguments • dd
The given numerical factor.
public: Matrix3 OrthoMatrix::operator+(const PMatrix & other) Calculates the sum of this orthogonal matrix and another 3 × 3 matrix. The result is a 3 × 3 matrix which is not orthogonal. Return A Matrix3 object that contains the resulting matrix. Arguments • other matrix.
A reference to a constant PMatrix object that contains the given 3 × 3 addend
public: Matrix3 OrthoMatrix::operator-(const PMatrix & other) Calculates the difference between this orthogonal matrix and another 3 × 3 matrix. The result is a 3 × 3 matrix which is not orthogonal. Return A Matrix3 object that contains the resulting matrix. Arguments • other matrix.
A reference to a constant PMatrix object that contains the given 3×3 subtrahend
176
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
public: OrthoMatrix OrthoMatrix::operator-() Calculates the negative of this orthogonal matrix. The negative of an orthogonal matrix is an orthogonal matrix. If A is this matrix and R is the result, this operation is R = −A. Return An OrthoMatrix object that contains the resulting 3 × 3 orthogonal matrix.
public: OrthoMatrix & OrthoMatrix::operator=(const OrthoMatrix & other) Calculates this orthogonal matrix as an exact copy of another orthogonal matrix. If A is this matrix and M is the other given matrix, this operation is A ← M. Return A reference to this OrthoMatrix object. Arguments • other
A reference to a constant OrthoMatrix object that contains the given matrix.
public: void OrthoMatrix::ReadFromFile(FILE * file) Reads this orthogonal matrix from a given file. Arguments • file
A pointer to a FILE object open for reading.
public: void OrthoMatrix::SaveToFile(FILE * file) Saves this orthogonal matrix to a file. Arguments • file
A pointer to a FILE object open for writing.
7.10. CLASS ORTHOMATRIX
public: bool OrthoMatrix::Verify() Performs tests to verify the orthogonality of this orthogonal matrix. Return true if this matrix has passed the tests, false if not.
177
178
CHAPTER 7. FAMILY OF CLASSES: SPECIFIC COORDINATES
Chapter 8 Family of Classes: Graphs Services for graphs including trees, breadth-first search, adjacency level structures, connected components and paths, and state services. Consists of four parameterized base classes, one abstract parameterized base class, and several concrete and derived classes with support for coordinate system graphs and body-constraint graphs. The following uniform naming convention has been used to designate the parameters of the parameterized classes: • VERTEX . An object that describes a vertex of the graph, usually a PVertex or a PVertex -derived object. • EDGE . An object that describes an edge of the graph, usually a PEdge or PEdge -derived object.
8.1
All Graphs Classes
Class name BCComponent BCEdge BCGraph BCVertex CSEdge CSGraph
Description A class derived from PComponentWithTree that describes a connected component of a BCGraph object. A class derived from PEdge that describes an edge of a BCGraph object. A class derived from PGraph that describes the graph of an articulated multibody system, where the vertices are rigid bodies and the edges are constraints. A class derived from PVertex that describes a vertex of a BCGraph. A class derived from PEdge that describes an edge of a CSGraph object. A class derived from PGraph that describes a Coordinate System Graph, an undirected graph that represents a set of coordinate systems and the transformations between them.
179
180
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Class name CSState CSVector CSVertex PComponent PComponentWithTree PEdge PGraph
PPath
PPathClosed
PPathOpen
PVertex
8.2
Description (continued) The kinematic state of a coordinate system in the coordinate system graph. A three-dimensional vector that knows the coordinate system where it is expressed. A class derived from PVertex that describes a vertex in a CSGraph object. A parameterizad class that describes a connected component of a PGraph object and is used as base for all specialized component classes. A parameterizad class derived from PComponent that describes a connected component of a PGraph and a spanning tree for that component. A parameterized class that describes an edge of a mathematical graph and is used as base for all specialized edge classes. A parameterized class that describes a mathematical graph and is used as base for all specialized graph classes. A parameterized class describing a connected path in a PGraph object and used as base for all path classes. The Direction of the Path is left-to-right in array PathEdges. A PPath with one edge does not have a direction, but a temporary direction is set same as edge. Append and Prepend refer to left-to-right in the list of edges. A parameterized class that describes a connected closed path in a PGraph object. The Direction of the path is defined as left-to-right in array PathEdges. A parameterized class that describes a connected open path in a PGraph object. The path can actually be “closed” if the head vertex is sane as the tail vertex, but this fact is of no consequence. The only purpose of a “closed” PPathOpen object is to use it to construct a PPathClosed object. A parameterized class that describes a vertex of a mathematical graph and is used as base for all specialized vertex classes.
Class BCComponent PComponent PComponentWithTree BCComponent
A connected component of a graph contained in a BCGraph object, with a spanning tree.
8.2. CLASS BCCOMPONENT
181
Constructor Summary public:
BCComponent(const PArray
& graphVertices, PArray & graphEdges) Public constructor. ∼BCComponent() Virtual destructor.
public: virtual
const
Method Summary public: Str public: Str
8.2.1
ListAllEdgeNamesInComponent() Returns a report with the names of all edges in this connected component. ListAllVertexNamesInComponent() Returns a report with the names of all vertices in this connected component.
BCComponent Constructor Detail
public: BCComponent::BCComponent(const PArray & graphEdges)
*>
&
Public constructor. It constructs this object with an empty graph. Arguments • graphVertices A pointer to a constant PArray object that contains pointers to the vertices of the parent graph. • graphEdges A pointer to a constant PArray object that contains pointers to the edges of the parent graph.
public: virtual BCComponent::∼BCComponent() Virtual destructor.
182
8.2.2
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
BCComponent Method Detail
public: Str BCComponent::ListAllEdgeNamesInComponent() Returns a report with the names of all edges in this connected component. Return An Str object with the resulting report.
public: Str BCComponent::ListAllVertexNamesInComponent() Returns a report with the names of all vertices in this connected component. Return An Str object with the resulting report.
8.3
Class BCEdge PEdge BCEdge
An edge of a BCGraph object associated with a constraint in a mechanical system.
Attribute Summary protected: const Constraint *
m pConstraint A pointer to the constant Constraint object corresponding to this edge.
Constructor Summary public: public: virtual
BCEdge(BCVertex * pV1, BCVertex * pV2, const Constraint * pCnstr) Public constructor. ∼BCEdge() Virtual destructor.
8.3. CLASS BCEDGE
183
Method Summary public: const Str & public: const Constraint * public: const Body * public: const Body * public: Str public: const Body *
8.3.1
GetBCEdgeName() Returns the name of the constraint associated with this edge. GetConstraint() Returns a pointer to the constraint associated with this edge. GetFirstBody() Returns a pointer to the body that corresponds to the tail vertex of this edge, GetSecondBody() Returns a pointer to the body that corresponds to the head vertex of this edge, ReportBCEdgeBrief() Creates a brief report describing this edge. ToggleBody(const Body * body) Given one vertex of this edge, finds the other.
BCEdge Attribute Detail
protected: const Constraint * m pConstraint A pointer to the constant constraint corresponding to this BCEdge object.
184
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.3.2
BCEdge Constructor Detail
public: BCEdge::BCEdge(BCVertex * pV1, BCVertex * pV2, const Constraint * pCnstr) Public constructor. It constructs this BCEdge object with the two given BCVertex objects and associated with the given constraint. Arguments • pV1 , pV2 Pointers to the two BCVertex objects that contain the two vertices for this edge. Vertex pV1 becomes the tail vertex of the edge, and vertex pV2 becomes the head vertex of this edge. • pCnstr object.
A pointer to the constant constraint that is to be associated with this BCEdge
public: virtual BCEdge::∼BCEdge() Virtual destructor.
8.3.3
BCEdge Method Detail
public: const Str & BCEdge::GetBCEdgeName() Returns the name of the constraint associated with this BCEdge object. Return The name of the constraint associated with this BCEdge object.
8.3. CLASS BCEDGE
185
public: const Constraint * BCEdge::GetConstraint() Returns a pointer to the constant Constraint object that contains the constraint associated with this BCEdge object. Return A pointer to the constant Constraint object that contains the constraint associated with this BCEdge object.
public: const Body * BCEdge::GetFirstBody() Returns a pointer to the constant Body object that contains the body associated with the tail vertex of this edge. Return A pointer to the constant Body object that contains the body associated with the tail vertex of this edge.
public: const Body * BCEdge::GetSecondBody() Returns a pointer to the constant Body object that contains the body associated with the head vertex of this edge. Return A pointer to the constant Body object that contains the body associated with the head vertex of this edge.
public: Str BCEdge::ReportBCEdgeBrief() Creates a brief report describing the edge contained in this CSEdge object. Return An Str object with the resulting report.
186
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: const Body * BCEdge::ToggleBody(const Body * body) Given the Body object associated with one vertex of this edge, finds the other. An error condition occurs if the given Body object is neither one of the two vertices of this edge. Return The Body object associated with the other vertex of this edge. Arguments • body A pointer to the constant Body object that is in correspondence with one of the vertices of this edge.
8.4
Class BCGraph PGraph BCGraph
A mathematical graph that represents a mechanical system composed of Body objects and constraints, where the Body objects correspond to graph vertices and the constraints correspond to graph edges. Frequently, the Body objects describe rigid bodies and the constraints describe mechanical articulations, and the system is known as an articulated figure.
Attribute Summary protected: const ConstraintManager * protected: const BodyManager * protected: BCComponent *
m pCnstrMgr A pointer to a constant ConstraintManager object, which owns all the constraints associated with the edges in the graph. m pBodyMgr A pointer to a constant BodyManager object, which owns all the Body objects associated with the vertices in the graph. m pBCComponent A pointer to a BCComponent object owned by this object.
8.4. CLASS BCGRAPH
187
Constructor Summary public:
public: virtual
BCGraph(const BodyManager * pBodyMgr, const ConstraintManager * pCnstrMgr) Public constructor. It creates an empty BCGraph object. ∼BCGraph() Virtual destructor.
Method Summary public: bool public: bool public: bool public: bool public: BCComponent * public: BCVertex * public: int public: int public: Str
CreateBCComponent(int rootGIndex) The internal BCComponent object is created for a given root vertex. CreateBCComponent(const BCVertex * rootVertex) The internal BCComponent object is created for a given root vertex. CreateWithAllBodiesAndAllConstraints() This BCGraph object is created with all bodies and all constraints present in the specified mechanical system. CreateWithAllConstraintsAndTheirBodies() This BCGraph object is created with all constraints and all bodies that have constraints in the specified mechanical system. GetBCComponent() Returns a pointer to the internal BCComponent object. GetBCVertexWithBody(const Body * body) Finds the BCVertex object that corresponds to a given Body object, and returns a pointer to it. GetNumberInertialVertices() Calculates and returns the number of Body objects that have inertia. GetNumberNoninertialVertices() Calculates and returns the number of Body objects that do not have inertia. ReportBCGraph() Creates a report with a description of this BCGraph object.
188
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.4.1
BCGraph Attribute Detail
protected: const ConstraintManager * m pCnstrMgr A pointer to a constant ConstraintManager object, which owns all the constraints associated with the edges in the graph.
protected: const BodyManager * m pBodyMgr A pointer to a constant BodyManager object, which owns all the Body objects associated with the vertices in the graph.
protected: BCComponent * m pBCComponent A pointer to a BCComponent object owned by this object. The BCComponent object can be created by breadth-first search passing a root vertex.
8.4.2
BCGraph Constructor Detail
public: BCGraph::BCGraph(const BodyManager * pBodyMgr, const ConstraintManager * pCnstrMgr) Public constructor. It creates an empty BCGraph object. Arguments • pBodyMgr A pointer to a constant BodyManager object, which owns all the Body objects associated with the vertices in the graph. • pCnstrMgr A pointer to a constant ConstraintManager object, which owns all the constraints associated with the edges in the graph.
8.4. CLASS BCGRAPH
189
public: virtual BCGraph::∼BCGraph() Virtual destructor.
8.4.3
BCGraph Method Detail
public: bool BCGraph::CreateBCComponent(int rootGIndex) The internal BCComponent object is created by breadth-first search rooted at the given root vertex. Return true if execution has been successful, false otherwise. Arguments • rootGIndex The integer 0-based graph index of a vertex of the graph in the range 0 to n − 1, where n is the number of vertices of the graph. This vertex is used as root for the connected component.
public: bool BCGraph::CreateBCComponent(const BCVertex * rootVertex) The internal BCComponent object is created by breadth-first search rooted at the given root vertex. Return true if execution has been successful, false otherwise. Arguments • rootVertex A pointer to a constant BCVertex object that contains a vertex of the graph. This vertex is used as root for the connected component.
190
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool BCGraph::CreateWithAllBodiesAndAllConstraints() This BCGraph object is created with all bodies and all constraints present in the specified mechanical system. Return true if execution has been successful, false if not.
public: bool BCGraph::CreateWithAllConstraintsAndTheirBodies() This BCGraph object is created with all constraints and all bodies that have constraints in the specified mechanical system. Bodies without constraints can exist, but are not included in the graph. Return true if execution has been successful, false if not.
public: BCComponent * BCGraph::GetBCComponent() Returns a pointer to the internal BCComponent object. Return A pointer to the internal BCComponent object that contains the connected component previously created from a root vertex.
public: BCVertex * BCGraph::GetBCVertexWithBody(const Body * body) Finds the BCVertex object that corresponds to a given Body object, and returns a pointer to it. Return A pointer to the BCVertex object that corresponds to a given Body object. Arguments • body
The given Body object.
8.5. CLASS BCVERTEX
191
public: int BCGraph::GetNumberInertialVertices() Calculates and returns the number of Body objects in the graph that have inertia. Return The integer number of inertial Body objects in the graph.
public: int BCGraph::GetNumberNoninertialVertices() Calculates and returns the number of Body objects in the graph that do not have inertia. Return The integer number of non-inertial Body objects in the graph.
public: Str BCGraph::ReportBCGraph() Creates a report with a description of this BCGraph object. Return An Str object that contains the resulting report.
8.5
Class BCVertex PVertex BCVertex
A vertex of a BCGraph object, which is associated with a Body object in a mechanical system.
Attribute Summary protected: const Body *
m pBody A pointer to the constant Body object corresponding to this vertex.
192
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Constructor Summary public:
BCVertex(const Body * pBody) Public constructor. ∼BCVertex() Virtual destructor.
public: virtual
Method Summary public: const Str & public: const Body * public: Str
8.5.1
GetBCVertexName() Returns the name of the Body object associated with this vertex. GetBody() Returns a pointer to the Body object associated with this vertex. ReportVertex() Creates a report describing this vertex.
BCVertex Attribute Detail
protected: const Body * m pBody A pointer to the constant Body object corresponding to this BCVertex object.
8.5.2
BCVertex Constructor Detail
public: BCVertex::BCVertex(const Body * pBody) Public constructor. It constructs a BCVertex object associated with the given Body object. Arguments • pBody object.
A pointer to a constant Body object that is to be associated with this BCVertex
8.5. CLASS BCVERTEX
193
public: virtual BCVertex::∼BCVertex() Virtual destructor.
8.5.3
BCVertex Method Detail
public: const Str & BCVertex::GetBCVertexName() Returns the name of the Body object associated with this BCVertex object. Return The name of the Body object associated with this BCVertex object.
public: const Body * BCVertex::GetBody() Returns a pointer to the constant Body object that contains the body associated with this BCVertex object. Return A pointer to the constant Body object that contains the body associated with this BCVertex object.
public: Str BCVertex::ReportVertex() Creates a report describing this BCVertex object. Return An Str object containing the resulting report.
194
8.6
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Class CSEdge PEdge CSEdge
An edge of a CSGraph object, which is associated with a pair of coordinate systems described by CSVertex objects. The edge knows about the relative kinematic state of the two coordinate systems. The symbol F is used to refer to the tail vertex or first vertex of the edge, and the symbol S is used for the head vertex or second vertex.
Attribute Summary protected: CSState * protected: CSState * protected: Translator * protected: Orientator * protected: protected: int protected: protected: Str
TheState A pointer to a CSState object that contains the relative kinematic state for the two coordinate systems. ThePreviousState If the kinematic state of this edge changes with time, the edge keeps track of the previous state in the object pointed at by this attribute. m pTranslator A pointer to a Translator object that contains a description of the translational kinematic state of this edge. m pOrientator A pointer to a Orientator object that contains a description of the orientational kinematic state of this edge. m NumberTranslationalSpecors The number of translational specific coordinates. m NumberSpecors The total number of specific coordinates. m NumberRotationalSpecors The number of orientational specific coordinates. EdgeName The name of this edge.
8.6. CLASS CSEDGE
195
Constructor Summary public:
public:
CSEdge(CSVertex * pV1, CSVertex * pV2) Public constructor. It creates this CSEdge object with the two specified vertices. ∼CSEdge() Public destructor.
Method Summary public: int
public: void public: const CSVector & public: virtual Str public: const Str & public: const CSVector & public: const CSVector & public: int public: int public: int public: const OrthoMatrix & public: const Orientator *
CalculateDots(const CSVector & v FSF, const CSVector & omega FSF, const ArrayOfDoubles & dots) Calculates the time derivatives of the specific coordinates from a given linear velocity and angular velocity. Displace(const CSVector & dd) Displaces coordinate system S parallel to itself by a specified distance. GetAngularVelocity() Returns the current value of the angular velocity of system S relative to system F. GetEdgeClass() Returns the class that this edge belongs to. GetEdgeName() Returns the name of this edge. GetMyVector() Returns the position radius vector for the origin of system S relative to system F. GetMyVelocity() Returns the linear velocity of the origin of system S relative to system F. GetNumberRotationalSpecors() Returns the number of orientational specific coordinates. GetNumberSpecors() Returns the total number of specific coordinates. GetNumberTranslationalSpecors() Returns the number of translational specific coordinates. GetOrientationMatrix() Returns the orientation matrix for system S relative to system F. GetOrientator() Returns the Orientator object associated with this edge.
196
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary (continued) public: void public: CSState * public: const Translator * public: void public: void public: void public: Str public: void public: void public: void public: void public: void public: bool public: void public: void
GetSecondVertexLocalAngularVelocity(CSVector & Result) Returns the angular velocity of coordinate system S relative to F, expressed in coordinate system S. GetState() Returns the CSState object that contains the kinematic state of this edge. GetTranslator() Returns the Translator object associated with this edge. GetUnitCoordinateVector(int index, CSVector & Result) Returns a unit vector parallel to a specified coordinate direction of system S. GetValuesAndDots(double * values, double * dots) Returns the current values of the specific coordinates and their time derivatives. InitializeState(Translator * pTr, Orientator * pOr) Initializes the kinematic state of this edge with a specified Translator and Orientator object. ReportCSEdgeBrief() Creates a brief report describing this edge. RotateAboutAxisThroughPoint(double angle, const CSVector & axis, const CSVector & point) Rotates coordinate system S about a given axis and by a specified angle. RotateAboutAxisThroughPoint(const OrthoMatrix & AA, const CSVector & point) Applies a given rotation to coordinate system S about a given point. SetEdgeName(const Str & name) Sets the name for this edge. SetState(const double * values, const double * dots) Sets the kinematic state for this CSEdge object. SetState(const CSVector & r, const CSVector & v, const CSVector & o, const OrthoMatrix & a) Sets the kinematic state for this CSEdge object. StabilizeOrientatorIfNeeded() Stabilizes the Orientator object owned by this CSEdge. TraceCSEdge(const Str & title) Creates a report with a description of this CSEdge object. TransformMatrixToFirstVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3×3 matrix expressed in coordinate system S to its expression in coordinate system F.
8.6. CLASS CSEDGE
197
Method Summary (continued) public: void
public: void
public: void
public: void public: void public: void
public: void
public: bool
TransformMatrixToSecondVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3×3 matrix expressed in coordinate system F to its expression in coordinate system S. TransformPositionToFirstVertex(const CSVector & SPosition, CSVector & Result) Transforms a radius vector expressed in coordinate system S to its expression in coordinate system F. TransformPositionToSecondVertex(const CSVector & FPosition, CSVector & Result) Transforms a radius vector expressed in coordinate system F to its expression in coordinate system S. TransformVectorToFirstVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system S to its expression in system F. TransformVectorToSecondVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system F to its expression in system S. TransformVelocityToFirstVertex(const CSVector & SPosition, CSVector & Result) Given a point fixed in system S, this method transforms the velocity of that point expressed in system S to the velocity of the same point expressed in system F. TransformVelocityToFirstVertex(const CSVector & SPosition, const CSVector & SVelocity, CSVector & Result) Given a point moving with respect to system S, this method transforms the velocity of that point expressed in system S to the velocity of the same point expressed in system F. Verify() Verifies the consistency and correctness of this object.
198
8.6.1
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
CSEdge Attribute Detail
protected: CSState * TheState A pointer to a CSState object that contains the relative kinematic state for the two coordinate systems.
protected: CSState * ThePreviousState If the kinematic state of this edge changes with time, the edge keeps track of the previous state in the object pointed at by this attribute.
protected: Translator * m pTranslator A pointer to a Translator object that contains a description of the translational kinematic state of this edge.
protected: Orientator * m pOrientator A pointer to a Orientator object that contains a description of the orientational kinematic state of this edge.
protected: m NumberTranslationalSpecors The integer number of translational specific coordinates.
protected: int m NumberSpecors The total number of specific coordinates.
8.6. CLASS CSEDGE
199
protected: m NumberRotationalSpecors The integer number of orientational specific coordinates.
protected: Str EdgeName An Str object containing the name of this edge.
8.6.2
CSEdge Constructor Detail
public: CSEdge::CSEdge(CSVertex * pV1, CSVertex * pV2) Public constructor. It creates this CSEdge object with the two specified vertices. Arguments • pV1 , pV2
Pointers to two CSVertex objects that contain the two vertices for this edge.
public: CSEdge::∼CSEdge() Public destructor.
200
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.6.3
CSEdge Method Detail
public: int CSEdge::CalculateDots(const CSVector & v FSF, const CSVector & omega FSF, const ArrayOfDoubles & dots) This method uses the Translator and Orientator objects associated with the relative kinematic state of this edge to calculate the time derivatives of the specific coordinates corresponding to given values of the linear velocity and the angular velocity. The resulting array is passed back by argument. Return The integer value of the total number of specific coordinates for this edge. Arguments • v FSF A reference to a constant CSVector object that contains the given value of the given relative linear velocity vFS,F . • omega FSF A reference to a constant CSVector object that contains the given value of the given relative angular velocity ωFS,F . • dots A reference to a constant ArrayOfDoubles object, which, upon return, will contain the resulting array of time derivatives.
public: void CSEdge::Displace(const CSVector & dd) Displaces coordinate system S parallel to itself by a specified distance. Arguments • dd A reference to a constant CSVector object that contains the distance that system S is to be displaced relative to system F.
public: const CSVector & CSEdge::GetAngularVelocity() Uses the CSState object associated with this edge to obtain and return the current value of the angular velocity ωFS,F of system S relative to system F. Return A reference to a CSVector object that contains the resulting angular velocity.
8.6. CLASS CSEDGE
201
public: virtual Str CSEdge::GetEdgeClass() Returns the class that this edge belongs to, in this case “CSEdge”. Return An Str object that contains the name of this class.
public: const Str & CSEdge::GetEdgeName() Returns the name of the edge described by this CSEdge object. Return An Str object with the name of this edge.
public: const CSVector & CSEdge::GetMyVector() Returns the position radius vector rFS,F for the origin of system S relative to system F. Return A reference to a constant CSVector object that contains the position radius vector rFS,F for the origin of system S relative to system F.
public: const CSVector & CSEdge::GetMyVelocity() Returns the linear velocity vector vFS,F of the origin of system S relative to system F. Return A reference to a constant CSVector object that contains the linear velocity vector vFS,F of the origin of system S relative to system F.
public: int CSEdge::GetNumberRotationalSpecors() Returns the integer number of orientational specific coordinates for this edge. Return An integer with the number of orientational specific coordinates.
202
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: int CSEdge::GetNumberSpecors() Returns the total integer number of specific coordinates for this edge. Return An integer with the number of orientational specific coordinates.
public: int CSEdge::GetNumberTranslationalSpecors() Returns the integer number of orientational specific coordinates for this edge. Return An integer with the value of the number of orientational specific coordinates.
public: const OrthoMatrix & CSEdge::GetOrientationMatrix() Returns the orientation matrix AFS,F for system S relative to system F. Return A reference to a constant OrthoMatrix object that contains the resulting orientation matrix.
public: const Orientator * CSEdge::GetOrientator() Returns the Orientator object associated with this edge. Return A pointer to a constant Orientator object that contains the result.
public: void CSEdge::GetSecondVertexLocalAngularVelocity(CSVector & Result) Returns the angular velocity ωFS,S of coordinate system S relative to coordinate system F, expressed in coordinate system S. Arguments • Result
A reference to a CSVector object that contains the resulting angular velocity.
8.6. CLASS CSEDGE
203
public: CSState * CSEdge::GetState() Returns the CSState object that contains the kinematic state of this edge. Return A pointer to a CSState object that contains the resulting kinematic state.
public: const Translator * CSEdge::GetTranslator() Returns a pointer to the Translator object associated with this edge. Return A pointer to the constant Translator object associated with this edge.
public: void CSEdge::GetUnitCoordinateVector(int index, CSVector & Result) Returns a unit vector parallel to a specified coordinate direction of system S relative to system F, and expressed in system F. The result is passed back by argument. Arguments • index The 0-based integer index of one of the coordinate directions of system S, in the range 0 to 2. • Result A reference to a CSVector object, which, upon return, will contain the resulting unit vector.
public: void CSEdge::GetValuesAndDots(double * values, double * dots) Returns the current values of the specific coordinates and their time derivatives. Arguments • values A pointer to an array of doubles, which, upon return, will contain the current values of the specific coordinates. • dots A pointer to an array of doubles, which, upon return, will contain the current time derivatives of the specific coordinates.
204
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSEdge::InitializeState(Translator * pTr, Orientator * pOr) Initializes the kinematic state of this edge with a specified Translator and Orientator object. Arguments • pTr
A pointer to the given Translator object.
• pOr
A pointer to the given Orientator object.
public: Str CSEdge::ReportCSEdgeBrief() Creates a brief report describing this edge. Return An Str object with the resulting report.
public: void CSEdge::RotateAboutAxisThroughPoint(double angle, CSVector & axis, const CSVector & point)
const
Rotates coordinate system S about a given axis and by a specified angle, relative to system F. Arguments • angle
The angle of rotation.
• axis , point References to two constant CSVector objects, which, together, specify the axis of rotation. The first CSVector object contains a vector parallel to the axis, and the second contains the radius vector to a point of the axis of rotation.
8.6. CLASS CSEDGE
205
public: void CSEdge::RotateAboutAxisThroughPoint(const OrthoMatrix & AA, const CSVector & point) Applies a given rotation to coordinate system S about a given point, relative to system F. Arguments • AA A reference to a constant OrthoMatrix object that contains the rotation matrix for the rotation, relative to system F. • point The radius vector of a point on the axis of rotation, relative to system F and expressed in system F.
public: void CSEdge::SetEdgeName(const Str & name) Sets the name for the edge described in this CSEdge object Arguments • name
A reference to a constant Str object that contains the new name.
public: void CSEdge::SetState(const double * values, const double * dots) Sets the kinematic state for this CSEdge object. The Translator and Orientator objects owned by this CSEdge are updated, and new values are calculated for the state variables rFS,F , vFS,F , AFS,F and ωFS,F . Arguments • values A pointer to a constant array of doubles that contains the new values for the specific coordinates, ordered first the translational specific coordinates, and last the orientational specific coordinates. • dots A pointer to a constant array of doubles that contains the new values for the specific velocities, ordered in the same way as the specific coordinates.
206
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSEdge::SetState(const CSVector & r, const CSVector & v, const CSVector & o, const OrthoMatrix & a) Sets the kinematic state for this CSEdge object. The Translator and Orientator objects owned by this CSEdge are updated, and new values are calculated for the state variables rFS,F , vFS,F , AFS,F and ωFS,F . Arguments • r A reference to a constant CSVector object that contains the new value for the position vector rFS,F for the kinematic state. • v A reference to a constant CSVector object that contains the new value for the linear velocity vector vFS,F for the kinematic state. • o A reference to a constant CSVector object that contains the new value for the angular velocity vector ωFS,F for the kinematic state. • a A reference to a constant OrthoMatrix object that contains the new value for the orientation matrix AFS,F for the kinematic state.
public: bool CSEdge::StabilizeOrientatorIfNeeded() Stabilizes the Orientator object owned by this CSEdge. Some Orientator objects may become unstable near a singularity or in other conditions. To stabilize the Orientator object, values for the specific coordinates and velocities are recalculated, but the state variables AFS,F and ωFS,F stay the same. Return false if there is no need to stabilize, true if Orientator object was indeed unstable, and was stabilized.
public: void CSEdge::TraceCSEdge(const Str & title) Creates a report with a description of this CSEdge object. The report is passed back by parameter. Arguments • title
A reference to a constant Str object that contains a title for the report.
8.6. CLASS CSEDGE
207
public: void CSEdge::TransformMatrixToFirstVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3 × 3 matrix expressed in coordinate system S to its expression in coordinate system F. The result is returned by parameter. Arguments • matrix
A reference to a constant Matrix3 object that contains the given 3 × 3 matrix.
• Result A reference to a Matrix3 object, which, upon return, will contain the resulting 3 × 3 matrix.
public: void CSEdge::TransformMatrixToSecondVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3 × 3 matrix expressed in coordinate system F to its expression in coordinate system S. The result is returned by parameter. Arguments • matrix
A reference to a constant Matrix3 object that contains the given 3 × 3 matrix.
• Result A reference to a Matrix3 object, which, upon return, will contain the resulting 3 × 3 matrix.
208
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSEdge::TransformPositionToFirstVertex(const CSVector & SPosition, CSVector & Result) Transforms a radius vector expressed in coordinate system S to its expression in coordinate system F. The result is returned by parameter. This transformation is not a tensor transformation, but rather a conversion of one vector to another. Arguments • SPosition A reference to a constant CSVector object that contains the given radius vector. This vector points from the origin of system S to a certain point P, and is expressed in system S. • Result A reference to a CSVector object, which, upon return, will contain the resulting radius vector. This vector points from the origin of system F to point P, and is expressed in system F.
public: void CSEdge::TransformPositionToSecondVertex(const CSVector & FPosition, CSVector & Result) Transforms a radius vector expressed in coordinate system F to its expression in coordinate system S. The result is returned by parameter. This transformation is not a tensor transformation, but rather a conversion of one vector to another. Arguments • FPosition A reference to a constant CSVector object that contains the given radius vector. This vector points from the origin of system F to a certain point P, and is expressed in system F. • Result A reference to a CSVector object, which, upon return, will contain the resulting radius vector. This vector points from the origin of system S to point P, and is expressed in system S.
8.6. CLASS CSEDGE
209
public: void CSEdge::TransformVectorToFirstVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system S to its expression in system F. This transformation is a true tensor transformation. Arguments • vector
A reference to a constant CSVector object that contains the given vector.
• Result vector.
A reference to a CSVector object, which, upon return, will contain the resulting
public: void CSEdge::TransformVectorToSecondVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system F to its expression in system S. This transformation is a true tensor transformation. Arguments • vector
A reference to a constant CSVector object that contains the given vector.
• Result vector.
A reference to a CSVector object, which, upon return, will contain the resulting
210
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSEdge::TransformVelocityToFirstVertex(const CSVector & SPosition, CSVector & Result) Given a point fixed in system S, this method transforms the velocity of that point expressed in system S to the velocity of the same point expressed in system F at that particular instant of time. The transformation is not a true tensor transformation, rather a conversion of one vector into another. Arguments • SPosition A reference to a constant CSVector object that contains the fixed position of the given point, expressed in system S. • Result A reference to a CSVector object, which, upon return, will contain the resulting velocity expressed in system F.
public: void CSEdge::TransformVelocityToFirstVertex(const CSVector & SPosition, const CSVector & SVelocity, CSVector & Result) Given a point moving with respect to system S, this method transforms the velocity of that point expressed in system S to the velocity of the same point expressed in system F at that particular instant of time. The transformation is not a true tensor transformation, rather a conversion of one vector into another. Arguments • SPosition A reference to a constant CSVector object that contains the position of the given point, expressed in system S. • SVelocity A reference to a constant CSVector object that contains the velocity of the given point with respect to system S, and expressed in system S. • Result A reference to a CSVector object, which, upon return, will contain the resulting velocity expressed in system F.
8.7. CLASS CSGRAPH
211
public: bool CSEdge::Verify() Verifies the consistency and correctness of this object. Return Return true if this edge is correct, false otherwise.
8.7
Class CSGraph PGraph CSGraph
A mathematical graph that represents a Coordinate System graph. The vertices are associated with the coordinate systems, and the edges represent pairs of coordinate systems and describe relative transformations. This object owns all the CSVertex objects and CSEdge objects in the graph.
Attribute Summary protected: CSVertex *
GlobalVertex A pointer to a CSVertex object that contains the vertex associated with the global coordinate system.
Constructor Summary public: public: virtual
CSGraph() Public constructor. ∼CSGraph() Virtual destructor.
212
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary public: void public: void public: CSVertex * public: bool public: bool public: Str public: Str public: const CSEdge *
8.7.1
CreateGlobalVertex() Creates a new CSVertex object, adds it to the graph, and designates it as the global vertex. DescribeAllCSEdgesToFile(const Str & filename) Creates a file with a report describing all CSEdge objects of this graph. GetGlobalVertex() Returns a pointer to the global vertex. IsCSVectorGlobal(const CSVector & vector) Confirms or denies if a given CSVector object is expressed in the global coordinate system or not. IsCSVertexGlobal(const CSVertex & vertex) Confirms or denies if a given CSVertex object is associated with the global vertex. ReportAllCSEdges() Creates a report describing all the CSEdge objects in the graph. ReportCSGraph() Creates a report describing this graph. VerifyAllCSEdges() Verifies all the CSEdge objects in this graph for consistency and correctness.
CSGraph Attribute Detail
protected: CSVertex * GlobalVertex A pointer to a CSVertex object that contains the vertex associated with the global coordinate system.
8.7. CLASS CSGRAPH
8.7.2
213
CSGraph Constructor Detail
public: CSGraph::CSGraph() Public constructor. It constructs this object and leaves the graph empty.
public: virtual CSGraph::∼CSGraph() Virtual destructor.
8.7.3
CSGraph Method Detail
public: void CSGraph::CreateGlobalVertex() Creates a new CSVertex object, adds it to the graph, and designates the corresponding vertex as the global vertex.
public: void CSGraph::DescribeAllCSEdgesToFile(const Str & filename) Creates a file with a report describing all CSEdge objects of this graph. Arguments • filename
An Str object containing the full path for the file to be created.
public: CSVertex * CSGraph::GetGlobalVertex() Returns a pointer to the CSVertex object that contains the global vertex. Return A pointer to the CSVertex object that contains the global vertex.
214
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool CSGraph::IsCSVectorGlobal(const CSVector & vector) Confirms or denies if a given CSVector object is expressed in the global coordinate system or not. Arguments • vector
public: bool CSGraph::IsCSVertexGlobal(const CSVertex & vertex) Confirms or denies if a given CSVertex object is associated with the global vertex. Return true if the given CSVertex object contains the global vertex, or false if not. Arguments • vertex
A reference to the constant CSVertex object of interest.
public: Str CSGraph::ReportAllCSEdges() Creates a report describing all the CSEdge objects in the graph. Return An Str object with the resulting report.
public: Str CSGraph::ReportCSGraph() Creates a report describing the graph contained in this CSGraph object. Return An Str object with the resulting report.
public: const CSEdge * CSGraph::VerifyAllCSEdges() Verifies all the CSEdge objects in this graph for consistency and correctness. Return NULL if all CSEdge objects are correct. Otherwise, returns a pointer to the first constant CSEdge that has been found to be incorrect.
8.8. CLASS CSSTATE
8.8
215
Class CSState
This class describes the kinematic state of a coordinate system S relative to another coordinate system F. Both systems are vertices in the Coordinate System Graph. The kinematic state is defined by the following four state variables, all expressed in system F: • the position vector rFS,F , which defines the position of the origin of S relative to F; • the velocity vFS,F of the origin of system S relative to system F; • the orientation matrix AFS,F , which defines the orientation of system S relative to system F, and • the angular velocity ωFS,F of system S relative to system F. This class offers all the services that a kinematic state can provide, such as coordinate transformations, rotations and displacements, propagation of state information, operations with kinematic states, and others.
Attribute Summary private: CSVector * private: CSVector * private: CSVector * private: const CSVertex * private: const CSVertex * private: OrthoMatrix *
V FSF The velocity vFS,F of the origin of system S relative to F. R FSF The position vector rFS,F of the origin of system S relative to F. Omega FSF The angular velocity ωFS,F of system S relative to F. m pCSVertexS The vertex in the coordinate system graph corresponding to coordinate system S. m pCSVertexF The vertex in the coordinate system graph corresponding to coordinate system F. A FSF The orientation matrix AFS,F , which defines the orientation of system S relative to system F.
216
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Constructor Summary public: public: virtual
CSState(const CSVertex * pFirstVertex, const CSVertex * pSecondVertex) Public constructor. ∼CSState() Public destructor.
Method Summary public: void public: void public: void public: void public: inline const OrthoMatrix & public: inline const CSVertex * public: inline const CSVector & public: void public: inline const CSVector & public: void public: inline const CSVertex * public: CSVector public: void
CalculateODotFromOmegaNonlocal(Matrix3 & Result) Calculates A˙ FS,F in terms of ωF S,F . CopyReverseState(const CSState & other) Calculates this state as an exact copy of the inverse of a given state. CopyState(const CSState & other) Calculates this state as an exact copy of a given state. Displace(const Vector3 & dd) Performs a parallel displacement of coordinate system S by a specified amount. GetA FSF() Returns a reference to the orientation matrix AFS,F . GetFirstVertex() Returns a pointer to vertex F. GetOmega FSF() Returns a reference to the angular velocity ωFS,F . GetOmega FSS(CSVector & Omega FSS) Returns the angular velocity ωFS,S . GetR FSF() Returns a reference to the position vector rFS,F . GetR FSS(CSVector & R FSS) Returns the position vector rFS,S . GetSecondVertex() Returns a pointer to vertex S. GetVersorOfSecondVertex(int index) Returns one of the base unit vectors of coordinate system S. GetVersorOfSecondVertex(int index, CSVector & Result) Returns one of the base unit vectors of coordinate system S.
8.8. CLASS CSSTATE
217
Method Summary (continued) public: inline const CSVector & public: void public: void public: void public: void public: void public: void public: CSState public: CSState public: CSState public: const CSState & public: Str public: void
public: void
protected: void
GetV FSF() Returns a reference to the relative velocity vFS,F . GetV FSS(CSVector & V FSS) Returns the relative velocity rFS,S . MeEqualsDifferenceOf(const CSState & csa, const CSState & csb) Calculates this kinematic state as the direct or transposed difference between two given kinematic states. MeEqualsMeMinusOther(const CSState & other) Calculates this kinematic state as the direct or transposed difference between this kinematic state and another given kinematic state. MeEqualsMePlusOther(const CSState & other) Adds a given kinematic state to this kinematic state. MeEqualsMeReversed() Inverts this kinematic state. MeEqualsSumOf(const CSState & csa, const CSState & csb) Calculates this kinematic state as the sum of two given kinematic states. operator+(const CSState & other) Constructs a new kinematic state equal to the sum of this state and another given kinematic state. operator-(const CSState & other) Constructs a new kinematic state equal to the direct or transposed difference between this state and another given kinematic state. operator-() Constructs a new kinematic state equal to the inverse of this state. operator=(const CSState & other) Calculates this kinematic state as an exact copy of another given kinematic state. ReportState(const char * title = NULL) Creates a report describing this kinematic state. RotateAboutAxisThroughPoint(double angle, const CSVector & axis, const CSVector & point) Performs a rotation of coordinate system S by a given angle around a given axis. RotateAboutAxisThroughPoint(const OrthoMatrix & AA, const CSVector & point) Performs a rigid rotation of coordinate system S about an axis passing through a given point. The axis and angle of rotation are defined by a rotation matrix. SetDefaultState() Sets a default kinematic state.
218
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary (continued) public: void public: void public: void
public: void
public: void
public: void
public: void public: void public: void
public: void
public: void
public: bool
SetState(const Translator * pTr, const Orientator * pOr) Sets the state variables that define this state to values calculated from a given set of specific coordinates. SetState(const CSVector & r, const CSVector & v, const CSVector & o, const OrthoMatrix & a) Sets the state variables that define this state to the given values. TransformMatrixToFirstVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3 × 3 matrix originally expressed in coordinate system S, to its expression in coordinate system F. TransformMatrixToSecondVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3 × 3 matrix originally expressed in coordinate system F, to its expression in coordinate system S. TransformPointToFirstVertex(const CSVector & r SPS, CSVector & r FPF) Transforms a point defined by a radius vector expressed in system S, to its expression in system F. TransformPointToSecondVertex(const CSVector & r FPF, CSVector & r SPS) Transforms a point defined by a radius vector expressed in system F, to its expression in system S. TransformVectorToFirstVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system S, to its expression in system F. TransformVectorToSecondVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system F, to its expression in system S. TransformVelocityToFirstVertex(const CSVector & r SPS, CSVector & v FPF) Given a point that is fixed in coordinate system S, obtains its velocity relative to system F, expressed in system F. TransformVelocityToFirstVertex(const CSVector & r SPS, const CSVector & v SPS, CSVector & v FPF) Given a point that is moving relative to system S, obtains its velocity relative to system F. TransformVelocityToSecondVertex(const CSVector & r FPF, const CSVector & v FPF, CSVector & v SPS) Given a point that is moving relative to system F, obtains its velocity relative to system S. Verify() Verifies the consistency and correctness of this state object.
8.8. CLASS CSSTATE
8.8.1
219
CSState Attribute Detail
private: CSVector * V FSF A pointer to a CSVector object that contains the velocity vFS,F of the origin of system S relative to F, expressed in system F.
private: CSVector * R FSF A pointer to a CSVector object that contains the position vector rFS,F of the origin of system S relative to F, expressed in system F.
private: CSVector * Omega FSF A pointer to a CSVector object that contains the angular velocity ωFS,F of system S relative to F, expressed in system F.
private: const CSVertex * m pCSVertexS A pointer to a CSVertex object that contains the vertex in the coordinate system graph corresponding to coordinate system S.
private: const CSVertex * m pCSVertexF A pointer to a CSVertex object that contains the vertex in the coordinate system graph corresponding to coordinate system F.
private: OrthoMatrix * A FSF A pointer to a OrthoMatrix object that contains the orientation matrix AFS,F , which defines the orientation of system S relative to system F.
220
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.8.2
CSState Constructor Detail
public: CSState::CSState(const CSVertex * pFirstVertex, const CSVertex * pSecondVertex) Public constructor. It constructs a default kinematic state where the state variables rFS,F , vFS,F and ωFS,F are all initialized to zero, and the orientation matrix AFS,F is set to the identity matrix. The two vertices uniquely identify the edge in the coordinate system graph that this state is associated with. Arguments • pFirstVertex , pSecondVertex Pointers to two constant CSVector objects which contain the vertices F and S, respectively, of the coordinate system graph.
public: virtual CSState::∼CSState() Public destructor.
8.8.3
CSState Method Detail
public: void CSState::CalculateODotFromOmegaNonlocal(Matrix3 & Result) ˙ Calculates the time derivative of the orientation matrix A(FS, F in terms of ωF S,F , using expression 3.21. The result is returned by argument. Arguments • Result matrix.
A reference to a Matrix3 object, which, upon return, will contain the resulting
8.8. CLASS CSSTATE
221
public: void CSState::CopyReverseState(const CSState & other) Calculates this state as an exact copy of the inverse of a given state. The roles of coordinate systems F and S are reversed and new values for the state variables are calculated accordingly. Arguments • other state.
A reference to a constant CSState object which contains the given kinematic
public: void CSState::CopyState(const CSState & other) Calculates this kinematic state as an exact copy of a given kinematic state. Arguments • other state.
A reference to a constant CSState object which contains the given kinematic
public: void CSState::Displace(const Vector3 & dd) Performs a parallel displacement of coordinate system S by a specified amount. Arguments • dd
A reference to a constant CSVector object, which contains the desired displacement.
public: inline const OrthoMatrix & CSState::GetA FSF() Returns a reference to the orientation matrix AFS,F . Return A reference to a constant OrthoMatrix object which contains the orientation matrix AFS,F .
222
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: inline const CSVertex * CSState::GetFirstVertex() Returns a pointer to vertex F Return A pointer to a constant CSVector object, which contains vertex F in the coordinate system graph.
public: inline const CSVector & CSState::GetOmega FSF() Returns a reference to the angular velocity ωFS,F . Return A reference to a constant CSVector object which contains the angular velocity.
public: void CSState::GetOmega FSS(CSVector & Omega FSS) Calculates and returns by argument the angular velocity ωFS,S . Arguments • Omega FSS A reference to a CSVector object, which, upon return, will contain the resulting angular velocity.
public: inline const CSVector & CSState::GetR FSF() Returns a reference to the position vector rFS,F , expressed in system F. Return A reference to a constant CSVector object which contains the position vector.
public: void CSState::GetR FSS(CSVector & R FSS) Calculates and returns by argument the position vector rFS,S , expressed in system S. Arguments • R FSS A reference to a CSVector object, which, upon return, will contain the resulting position vector.
8.8. CLASS CSSTATE
223
public: inline const CSVertex * CSState::GetSecondVertex() Returns a pointer to vertex S. Return A pointer to a constant CSVector object, which contains vertex S in the coordinate system graph.
public: CSVector CSState::GetVersorOfSecondVertex(int index) Returns one of the three unit vectors that form the base of coordinate system S, expressed in system F. Return A CSVector object which contains the resulting unit vector. Arguments • index
The integer index of the desired unit vector, in the range 0 to 2.
public: void CSState::GetVersorOfSecondVertex(int index, CSVector & Result) Returns by argument one of the three unit vectors that form the base of coordinate system S, expressed in system F. Arguments • index
The integer index of the desired unit vector, in the range 0 to 2.
• Result A reference to a CSVector object, which, upon return, will contain the resulting unit vector.
public: inline const CSVector & CSState::GetV FSF() Returns a reference to the relative velocity vFS,F , expressed in system F. Return A reference to a constant CSVector object which contains the velocity.
224
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSState::GetV FSS(CSVector & V FSS) Calculates and returns by argument the relative velocity vFS,S , expressed in system S. Arguments • V FSS A reference to a CSVector object, which, upon return, will contain the resulting relative velocity.
public: void CSState::MeEqualsDifferenceOf(const CSState & csa, const CSState & csb) Calculates this kinematic state as the direct or transposed difference between two given kinematic states. Arguments • csa , csb References to two CSVector objects that contain the given kinematic states. State csb is subtracted from csa .
public: void CSState::MeEqualsMeMinusOther(const CSState & other) Calculates this kinematic state as the direct or transposed difference between this kinematic state and another given kinematic state. Arguments • other A reference to a constant CSState object which contains the kinematic state to be subtracted.
public: void CSState::MeEqualsMePlusOther(const CSState & other) Adds a given kinematic state to this kinematic state. Arguments • other A reference to a constant CSState object which contains the kinematic state to be added to this kinematic state.
8.8. CLASS CSSTATE
225
public: void CSState::MeEqualsMeReversed() Inverts this kinematic state.
public: void CSState::MeEqualsSumOf(const CSState & csa, const CSState & csb) Calculates this kinematic state as the sum of two given kinematic states. Arguments • csa , csb
References to two CSState objects which contain the given kinematic states.
public: CSState CSState::operator+(const CSState & other) Constructs and returns a new kinematic state equal to the sum of this state and another given kinematic state. Return A CSState object which contains the new kinematic state. Arguments • other
A reference to a constant CSState object which contains the state to be added.
public: CSState CSState::operator-(const CSState & other) Binary minus operator. It constructs a new kinematic state equal to the direct or transposed difference between this state and another given kinematic state. Return A CSState object that contains the resulting new kinematic state. Arguments • other tracted.
A reference to a constant CSState object which contains the state to be sub-
226
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: CSState CSState::operator-() Unary minus operator. Constructs a new kinematic state equal to the inverse of this state. Return A CSState object that contains the resulting new kinematic state.
public: const CSState & CSState::operator=(const CSState & other) Calculates this kinematic state as an exact copy of another given kinematic state, and returns a reference to this state. Return A reference to the CSState object that contains this kinematic state. Arguments • other A reference to a constant CSState object which contains the kinematic state to be copied.
public: Str CSState::ReportState(const char * title = NULL) Creates a report with an optional title describing this kinematic state. Return A Str object that contains the report. Arguments • title A pointer to a constant char array which contains the desired title for the report. This pointer defaults to NULL , or NULL can be passed. In either case, the report will have no title.
8.8. CLASS CSSTATE
public: void CSState::RotateAboutAxisThroughPoint(double angle, CSVector & axis, const CSVector & point)
227
const
Performs a rotation of coordinate system S by a given angle around a given axis. Arguments • angle
The angle of rotation in radians.
• axis A reference to a constant CSVector object which contains a vector parallel to the given axis of rotation, expressed in coordinate system F. • point A reference to a constant CSVector object which contains a radius vector from the origin of system F to a point on the desired axis of rotation, expressed in coordinate system F.
public: void CSState::RotateAboutAxisThroughPoint(const OrthoMatrix & AA, const CSVector & point) Performs a rigid rotation of coordinate system S about an axis passing through a given point. The axis and angle of rotation are defined by a rotation matrix. Arguments • AA A reference to a constant OrthoMatrix object which contains the rotation matrix that defines the axis and angle of rotation. • point A reference to a constant CSVector object which contains a radius vector from the origin of system F to a point on the desired axis of rotation, expressed in coordinate system F.
protected: void CSState::SetDefaultState() Sets a default kinematic state where the state variables rFS,F , vFS,F and ωFS,F are all initialized to zero, and the orientation matrix AFS,F is set to the identity matrix.
228
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSState::SetState(const Translator * pTr, const Orientator * pOr) Sets the state variables that define this state to values calculated from a given set of specific coordinates. The translational specific coordinates are specified by a given Translator object, and the rotational specific coordinates by an Orientator object. Arguments • pTr A pointer to a constant Translator object that defines the given translational specific coordinates. • pOr A pointer to a constant Orientator object that defines the given orientational specific coordinates.
public: void CSState::SetState(const CSVector & r, const CSVector & v, const CSVector & o, const OrthoMatrix & a) Sets the state variables that define this state to the given values. Arguments • r
A reference to a constant CSVector object that contains the new value for rFS,F .
• v
A reference to a constant CSVector object that contains the new value for vFS,F
• o
A reference to a constant CSVector object that contains the new value for ωFS,F
• a
A reference to a constant OrthoMatrix object that contains the new value for AFS,F
8.8. CLASS CSSTATE
229
public: void CSState::TransformMatrixToFirstVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3×3 matrix originally expressed in coordinate system S, to its expression in coordinate system F, and returns the result by parameter. Arguments • matrix A reference to a constant Matrix3 object which contains the given matrix expressed in system S. • Result A reference to a Matrix3 object, which, upon return, will contain the expression of the same matrix in system F.
public: void CSState::TransformMatrixToSecondVertex(const Matrix3 & matrix, Matrix3 & Result) Transforms a 3×3 matrix originally expressed in coordinate system F, to its expression in coordinate system S, and returns the result by parameter. Arguments • matrix A reference to a constant Matrix3 object which contains the given matrix expressed in system F. • Result A reference to a Matrix3 object, which, upon return, will contain the expression of the same matrix in system S.
230
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSState::TransformPointToFirstVertex(const CSVector & r SPS, CSVector & r FPF) Transforms a point defined by a radius vector expressed in system S, to its expression in system F, and returns the result by parameter. Arguments • r SPS A reference to a constant CSVector object that contains the radius vector rSP,S from the origin of system S to the given point P, expressed in system S. • r FPF A reference to a CSVector object, which, upon return, will contain the radius vector rFP,F from the origin of system F to the given point P, expressed in system F.
public: void CSState::TransformPointToSecondVertex(const CSVector & r FPF, CSVector & r SPS) Transforms a point defined by a radius vector expressed in system F, to its expression in system S, and returns the result by parameter. Arguments • r FPF A reference to a constant CSVector object that contains the radius vector rFP,F from the origin of system F to the given point P, expressed in system F. • r SPS A reference to a CSVector object, which, upon return, will contain the radius vector rSP,S from the origin of system S to the given point P, expressed in system S.
8.8. CLASS CSSTATE
231
public: void CSState::TransformVectorToFirstVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system S, to its expression in system F, and returns the result by parameter. Arguments • vector A reference to a constant CSVector object that contains the given vector expressed in system S. • Result A reference to a CSVector object, which, upon return, will contain the expression of the same vector in system F.
public: void CSState::TransformVectorToSecondVertex(const CSVector & vector, CSVector & Result) Transforms a vector expressed in system F, to its expression in system S, and returns the result by parameter. Arguments • vector A reference to a constant CSVector object that contains the given vector expressed in system F. • Result A reference to a CSVector object, which, upon return, will contain the expression of the same vector in system S.
232
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSState::TransformVelocityToFirstVertex(const CSVector & r SPS, CSVector & v FPF) A point P is given. The point is fixed in system S at a position defined by radius vector rSP,S from the origin of system S to the point, expressed in system S. This method calculates the velocity vFP,F of point P relative to system F, expressed in system F. Arguments • r SPS A reference to a constant CSVector object that contains the radius vector rSP,S from the origin of system S to the given fixed point P, expressed in system S. • v FPF A reference to a CSVector object, which, upon return, will contain the velocity vFP,F of point P relative to system F, expressed in system F.
public: void CSState::TransformVelocityToFirstVertex(const CSVector & r SPS, const CSVector & v SPS, CSVector & v FPF) A point P is given. The point is moving relative to system S with the velocity vSP,S , expressed in system S, and is currently at position rSP,S relative to system S, also expressed in system S. This method calculates the velocity vFP,F of point P relative to system F, expressed in system F. Arguments • r SPS A reference to a constant CSVector object that contains the current position rSP,S of point P relative to system S, expressed in system S. • v SPS A reference to a constant CSVector object that contains the current velocity vSP,S of point P relative to system S, expressed in system S. • v FPF A reference to a constant CSVector object, which, upon return, will contain the velocity vFP,F of point P relative to system F, expressed in system F.
8.8. CLASS CSSTATE
233
public: void CSState::TransformVelocityToSecondVertex(const CSVector & r FPF, const CSVector & v FPF, CSVector & v SPS) A point P is given. The point is moving relative to system F with the velocity vFP,F , expressed in system F, and is currently at position rFP,F relative to system F, also expressed in system F. This method calculates the velocity vSP,S of point P relative to system S, expressed in system S. Arguments • r FPF A reference to a constant CSVector object that contains the current position rFP,F of point P relative to system F, expressed in system F. • v FPF A reference to a constant CSVector object that contains the current velocity vFP,F of point P relative to system F, expressed in system F. • v SPS A reference to a constant CSVector object, which, upon return, will contain the velocity vSP,S of point P relative to system S, expressed in system S.
public: bool CSState::Verify() Verifies the consistency and correctness of this state object. Return true if this object is correct, false otherwise.
234
8.9
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Class CSVector PVector Vector3 CSVector
This class describes a three-dimensional vector that knows the coordinate system it is expressed in. The class has a pointer to a constant CSVertex object that contains the description of the corresponding vertex - or coordinate system - in the coordinate system graph. The class is convenient for cases where multiple coordinate systems are employed and vectors are frequently transformed between systems. Using the class in such cases results in more robust code, because it has the ability to verify the correctness of the transformations and other operations.
Attribute Summary protected: const CSVertex *
m pCSVertex A pointer to a constant CSVertex object that contains the description of the coordinate system this vector is expressed in.
Constructor Summary public:
public:
public:
public:
public:
public: virtual
CSVector(const Vector3 & vv, const CSVertex * CoordSystem) Public constructor. It constructs this vector with the same components as a given vector, and a given coordinate system. CSVector(double ux, double uy, double uz, const CSVertex * CoordSystem) Public constructor. It constructs this vector with given components and a given coordinate system. CSVector(const CSVector & other) Public constructor. It constructs this vector as an exact copy of another given vector. CSVector() Public default constructor. It constructs this object but leaves the components and coordinate system unspecified. CSVector(const CSVertex * CoordSystem) Public constructor. It constructs this vector with a given coordinate system but unspecified components. ∼CSVector() Public virtual destructor.
8.9. CLASS CSVECTOR
235
Method Summary public: void public: void public: void public: bool public: bool public: void public: void public: void public: CSVector public: void public: void public: double public: CSVector public: CSVector public: const CSVertex * public: CSVector public: CSVector
Add(const CSVector & uu) Adds a given vector to this vector. Add(const CSVector & uu, const CSVector & ww) Adds two given vectors to this vector. Copy(const CSVector & uu) Overwrites this vector with an exact copy of another given vector. Create(const CStr & text, const CSVertex * CoordSystem) Creates this vector from a textual description, in a given coordinate system. Create(const Str & text, const CSVertex * CoordSystem) Creates this vector with components encoded in text, and sets its coordinate system. Create(const Vector3 & vv, const CSVertex * CoordSystem) Creates this vector with components equal to the components of another given vector, and sets its coordinate system. Create(const CSVector & other) Creates this vector as an exact copy of a given vector. Create(double x, double y, double z, const CSVertex * CoordSystem) Sets the components and coordinate system of this vector to given values. CrossVector(const CSVector & uu) Calculates the cross product of this vector and another given vector. CrossVector(const CSVector & uu, CSVector & Result) Calculates the cross product of this vector and another given vector. Difference(const CSVector & a, const CSVector & b) Creates this vector as the difference between two given vectors. DotVector(const CSVector & uu) Calculates the dot product between this vector and another given vector. DoubleCrossVector(const CSVector & uu) Calculates the double cross-product of this vector and a given vector. GenerateArbitraryNormal() Constructs an arbitrary vector that is normal to this vector. GetCoordinateSystem() Returns the coordinate system that this vector is expressed in. GetMyPNormal(const CSVector & u) Given another vector, calculates the component that is normal to this vector. GetMyUnit() Calculates a unit vector in the direction of this vector and expressed in the same coordinate system.
236
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary (continued) public: bool public: CSVector public: CSVector public: CSVector & public: CSVector public: CSVector public: CSVector & public: CSVector public: CSVector & public: bool public: void public: void public: void public: void public: void public: void public: void
IsInCoordinates(const CSVertex * coord) Verifies if this vector is expressed in a given coordinate system. operator*(double ss) Constructs a vector equal to this vector multiplied by a constant. operator+(const CSVector & uu) Constructs a vector equal to the sum of this vector and another given vector. operator+=(const CSVector & uu) Adds a given vector to this vector. operator-(const CSVector & uu) Constructs a vector equal to the difference between this vector and another given vector. operator-() Constructs a vector equal to the negative of this vector. operator-=(const CSVector & uu) Subtracts a given vector from this vector. operator/(double ss) Constructs a vector equal to this vector divided by a constant. operator=(const CSVector & uu) Makes this vector an identical copy of another given vector. operator==(const CSVector & uu) Verifies if this vector is equal to another given vector. ReadFromFile(FILE * file) Reads this vector from a file. RotateMe(double alfa, const CSVector & n) Rotates this vector by a given angle around a given axis. SaveToFile(FILE * file) Saves this vector to a file. SetComponents(double ux, double uy, double uz) Sets the components of this vector to specified values. SetComponents(const Vector3 & comps) Sets the components of this vector to the same values as the components of another given vector. SetComponents(const double * uu) Sets the components of this vector to new values given in an array. SetComponentsAndCoordinateSystem(double ux, double uy, double uz, const CSVertex * coord) Sets the components and coordinate system of this vector to specified values.
8.9. CLASS CSVECTOR
237
Method Summary (continued) public: void public: void public: void public: void public: bool
8.9.1
SetCoordinateSystem(const CSVertex * newcoord) Sets the coordinate system of this vector to a new values. Subtract(const CSVector & uu) Subtracts a given vector from this vector. Sum(const CSVector & a, const CSVector & b) Calculates this vector as the sum of two given vectors. Sum(const CSVector & a, const CSVector & b, const CSVector & c) Calculates this vector as the sum of three given vectors. Verify() Verifies the consistency and correctness of this vector.
CSVector Attribute Detail
protected: const CSVertex * m pCSVertex A pointer to a constant CSVertex object that contains the description of the coordinate system this vector is expressed in.
8.9.2
CSVector Constructor Detail
public: CSVector::CSVector(const Vector3 & vv, const CSVertex * CoordSystem) Public constructor. It constructs this vector with the same components as a given vector, and a given coordinate system. Arguments • vv
A reference to a constant Vector3 object that contains the given vector.
• CoordSystem A pointer to a constant CSVertex object that contains the coordinate system for this vector.
238
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: CSVector::CSVector(double ux, double uy, double uz, const CSVertex * CoordSystem) Public constructor. It constructs this vector with given components and a given coordinate system. Arguments • ux , uy
, uz
The values for the components of this vector.
• CoordSystem A pointer to a constant CSVertex object that contains the coordinate system for this vector.
public: CSVector::CSVector(const CSVector & other) Public constructor. It constructs this vector as an exact copy of another given vector. Arguments • other
A reference to a constant CSVector object that contains the given vector.
public: CSVector::CSVector() Public default constructor. It constructs this object but leaves the components and coordinate system unspecified.
public: CSVector::CSVector(const CSVertex * CoordSystem) Public constructor. It constructs this vector with a given coordinate system but unspecified components. Arguments • CoordSystem A pointer to a constant CSVertex object that contains the coordinate system for this vector.
8.9. CLASS CSVECTOR
239
public: virtual CSVector::∼CSVector() Public virtual destructor.
8.9.3
CSVector Method Detail
public: void CSVector::Add(const CSVector & uu) Adds a given vector to this vector. Arguments • uu A reference to a constant CSVector object that contains the vector to be added to this vector. Both vectors must be expressed in the same coordinate system.
public: void CSVector::Add(const CSVector & uu, const CSVector & ww) Adds two given vectors to this vector. Arguments • uu , ww References to two CSVector objects that contain the two given vectors. This vector, and the two given vectors, must all be expressed in the same coordinate system.
public: void CSVector::Copy(const CSVector & uu) Overwrites this vector with an exact copy of another given vector. Arguments • uu A reference to a CSVector object that contains the given vector to be copied. The given vector can be expressed in any coordinate system, and the resulting copy will be expressed in that same system.
240
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool CSVector::Create(const CStr & text, const CSVertex * CoordSystem) Creates this vector from a textual description, in a given coordinate system. The Create method of the Vector3 class is used for the text conversion. Return Returns true if the conversion succeeded, false otherwise. Arguments • text A reference to a constant CStr object containing a textual description of the 3 components. The first three space-enclosed strings in text are interpreted as the values for the components. • CoordSystem A pointer to a constant CSVertex object that contains the coordinate system where this vector is to be expressed.
public: bool CSVector::Create(const Str & text, const CSVertex * CoordSystem) Creates this vector with components encoded in given text, and sets its coordinate system. The Create method of the Vector3 class is used for the text conversion. Return Returns true if the conversion succeeded, false otherwise. Arguments • text A reference to a constant Str object containing a textual description of the 3 components. The first three space-enclosed strings in text are interpreted as the values for the components. • CoordSystem A pointer to a constant CSVertex object that contains the coordinate system where this vector is to be expressed.
8.9. CLASS CSVECTOR
241
public: void CSVector::Create(const Vector3 & vv, const CSVertex * CoordSystem) Creates this vector with components equal to the components of another given vector, and sets its coordinate system. Arguments • vv
A reference to a constant Vector3 object that contains the given vector.
• CoordSystem system.
A pointer to a constant CSVertex object that contains the coordinate
public: void CSVector::Create(const CSVector & other) Creates this vector as an exact copy of a given vector. Arguments • other
A reference to a constant CSVector object that contains the given vector.
public: void CSVector::Create(double x, double y, double z, const CSVertex * CoordSystem) Sets the components and coordinate system of this vector to given values. Arguments • x,y,z
The new values for the three components of this vector.
• CoordSystem A pointer to a constant CSVertex object that contains the new coordinate system for this vector.
242
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: CSVector CSVector::CrossVector(const CSVector & uu) Calculates the cross product of this vector and another given vector. Return A CSVector object that contains the resulting vector. Arguments • uu
The given vector. It must be expressed in the same coordinate system as this vector.
public: void CSVector::CrossVector(const CSVector & uu, CSVector & Result) Calculates the cross product of this vector and another given vector. Returns the result by argument. Arguments • uu • Result vector.
The given vector. It must be expressed in the same coordinate system as this vector. A reference to a CSVector object, which, upon return, will contain the resulting
public: void CSVector::Difference(const CSVector & a, const CSVector & b) Creates this vector as the difference between two given vectors. Arguments • a,b References to two constant CSVector objects that contain the two given vectors. The first is the minuend and the last is the subtrahend.
8.9. CLASS CSVECTOR
243
public: double CSVector::DotVector(const CSVector & uu) Calculates the dot product between this vector and another given vector. Return The result. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: CSVector CSVector::DoubleCrossVector(const CSVector & uu) Calculates the double cross-product of this vector and a given vector. If this vector is t and the other vector is u, the calculation if t × (t × u). Return A CSVector object that contains the resulting vector. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: CSVector CSVector::GenerateArbitraryNormal() Constructs an arbitrary vector that is normal to this vector. There are infinitely many vectors in space that are normal to this vectors. This method finds one of them. Return A CSVector object that contains the resulting vector.
public: const CSVertex * CSVector::GetCoordinateSystem() Returns the coordinate system that this vector is expressed in. Return A pointer to a constant CSVertex object that describes this vector’s coordinate system.
244
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: CSVector CSVector::GetMyPNormal(const CSVector & u) Given another vector, calculates the component that is normal to this vector. If t is this vector, t˘ is a unit vector in the direction of t, and u is the given vector, the p-normal of is calculated ˘ t. ˘ The p-normal is a vector contained in the (t, u) plane, and is normal to t. The as u − (u · t) p-normal is zero if (t and u) are parallel. Return A CSVector object that contains the resulting p-normal. Arguments • u
A reference to a constant CSVector object that contains the given vector u.
public: CSVector CSVector::GetMyUnit() Calculates a unit vector in the direction of this vector and expressed in the same coordinate system. Return A CSVector object that contains the resulting unit vector.
public: bool CSVector::IsInCoordinates(const CSVertex * coord) Verifies if this vector is expressed in a given coordinate system. Return true if this vector is expressed in the given coordinate system, false if not. Arguments • coord system.
A pointer to a constant CSVertex object that contains the given coordinate
8.9. CLASS CSVECTOR
245
public: CSVector CSVector::operator*(double ss) Constructs and returns a vector equal to this vector multiplied by a constant. Return A CSVector object that contains the resulting vector. Arguments • ss
The constant used for the calculation.
public: CSVector CSVector::operator+(const CSVector & uu) Constructs and returns a vector equal to the sum of this vector and another given vector. Return A CSVector object that contains the resulting vector. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: CSVector & CSVector::operator+=(const CSVector & uu) Adds a given vector to this vector and returns a reference to this vector after the addition has been performed. Return A reference to this CSVector object after the addition has been completed. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
246
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: CSVector CSVector::operator-(const CSVector & uu) Constructs and returns a vector equal to the difference between this vector and another given vector. Return A CSVector object that contains the resulting vector. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: CSVector CSVector::operator-() Constructs and returns a vector equal to the negative of this vector. Return A CSVector object that contains the resulting vector.
public: CSVector & CSVector::operator-=(const CSVector & uu) Subtracts a given vector from this vector and returns a reference to this vector after the subtraction has been performed. Return A reference to this CSVector object after the subtraction has been completed. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: CSVector CSVector::operator/(double ss) Constructs and returns a vector equal to this vector divided by a constant. Return A CSVector object that contains the resulting vector. Arguments • ss
The constant used for the calculation.
8.9. CLASS CSVECTOR
247
public: CSVector & CSVector::operator=(const CSVector & uu) Makes this vector an identical copy of another given vector. Return A reference to this CSVector object after the calculations have been completed. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: bool CSVector::operator==(const CSVector & uu) Verifies if this vector is equal to another given vector. The two vectors are considered equal if they have the same components and are expressed in the same coordinate system. Return Returns true if the given vector is equal to this vector, false if not. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
public: void CSVector::ReadFromFile(FILE * file) Reads this vector from a file open for reading. Arguments • file
A pointer to a FILE object that contains the open file.
248
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSVector::RotateMe(double alfa, const CSVector & n) Rotates this vector by a given angle around a given axis defined by a unit vector. The right-hand rule determines the direction for positive rotations. Arguments • alfa The angle of rotation in radians. The direction for positive rotations is defined by the right-hand rule. • n A reference to a constant CSVector object that contains the unit vector that defines the axis of rotation.
public: void CSVector::SaveToFile(FILE * file) Saves this vector to a file open for writing. Arguments • file
A pointer to a FILE object that contains the open file.
public: void CSVector::SetComponents(double ux, double uy, double uz) Sets the components of this vector to specified values. The coordinate system is not changed. Arguments • ux , uy , uz
The new values for the components.
public: void CSVector::SetComponents(const Vector3 & comps) Sets the components of this vector to the same values as the components of another given vector. The coordinate system is not changed. Arguments • comps
A reference to a constant Vector3 object that contains the given vector.
8.9. CLASS CSVECTOR
249
public: void CSVector::SetComponents(const double * uu) Sets the components of this vector to new values given in an array. The coordinate system is not changed. Arguments • uu A pointer to a constant array of doubles that contains the three new values for the components.
public: void CSVector::SetComponentsAndCoordinateSystem(double ux, double uy, double uz, const CSVertex * coord) Sets the components and coordinate system of this vector to specified values. Arguments • ux , uy , uz
The new values for the components.
• coord A pointer to a constant CSVertex object that contains the new coordinate system for this vector.
public: void CSVector::SetCoordinateSystem(const CSVertex * newcoord) Sets the coordinate system of this vector to a new values. The components are left unchanged. Arguments • newcoord system.
A pointer to a constant CSVertex object that contains the new coordinate
public: void CSVector::Subtract(const CSVector & uu) Subtracts a given vector from this vector. Arguments • uu
A reference to a constant CSVector object that contains the given vector.
250
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void CSVector::Sum(const CSVector & a, const CSVector & b) Calculates this vector as the sum of two given vectors. Arguments • a,b
References to two constant CSVector objects that contain the two given vectors.
public: void CSVector::Sum(const CSVector & a, const CSVector & b, const CSVector & c) Calculates this vector as the sum of three given vectors. Arguments • a,b ,c vectors.
References to three constant CSVector objects that contain the three given
public: bool CSVector::Verify() Verifies the consistency and correctness of this vector. Return Returns true if this CSVector object is correct, false if not.
8.10. CLASS CSVERTEX
8.10
251
Class CSVertex PVertex CSVertex
A vertex of a CSGraph object, which is associated with an orthogonal cartesian coordinate system in three-dimensional space.
Attribute Summary protected: Str
VertexName The name of this vertex.
Constructor Summary public: public: virtual
CSVertex() Public default constructor. ∼CSVertex() Virtual destructor.
Method Summary public: const Str & public: Str public: void
GetName() Returns the name of this vertex. ReportVertex() Creates a report describing this vertex. SetName(const Str & name) Sets the name of this vertex.
252
8.10.1
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
CSVertex Attribute Detail
protected: Str VertexName The name of the vertex contained in this CSVertex object.
8.10.2
CSVertex Constructor Detail
public: CSVertex::CSVertex() Public default constructor. It constructs an empty CSVertex object.
public: virtual CSVertex::∼CSVertex() Virtual destructor.
8.10.3
CSVertex Method Detail
public: const Str & CSVertex::GetName() Returns the name of the vertex contained in this CSVertex object. Return A reference to a constant Str object containing the name of this vertex.
public: Str CSVertex::ReportVertex() Creates a report describing the vertex contained in this CSVertex object. Return An Str object containing the resulting report.
8.11. CLASS PCOMPONENT
253
public: void CSVertex::SetName(const Str & name) Sets the name of the vertex contained in this CSVertex object. Arguments • name
8.11
A reference to a constant Str object that contains the new name.
Class PComponent
A parameterized base class that describes a connected component of a mathematical graph stored in a PGraph object. The class uses the template as part of the class definition and the definitions of all methods. The component is initially constructed as an empty graph, and is subsequently created by breadth-first search.
Attribute Summary protected: ArrayOfIntegers protected: ArrayOfIntegers protected: const PArray & protected: const PArray <EDGE *> &
TheVertices An array containing the list of graph indices of all vertices that belong to the component. TheEdges An array containing the list of graph indices of all edges that belong to the component. GraphVertices A reference to the list of vertices in the graph. GraphEdges A reference to the list of edges in the graph.
254
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Constructor Summary public:
public: virtual
PComponent(const PArray & graphVertices, PArray<EDGE *> & graphEdges) Public constructor. It constructs an empty component. ∼PComponent() Virtual destructor.
const
Method Summary protected: virtual void protected: virtual void public: void public: const int * public: const int * public: EDGE * public: const PArray <EDGE *> & public: const PArray & public: int public: int public: VERTEX * public: virtual Str protected: void
AppendEdge(int edgeIndex, int rootsideVertex, int farsideVertex, bool isTreeArc) Adds a given edge to the component. AppendVertex(int vertexIndex, int level, int parent) Adds a given vertex to the component. CreateByBreadthFirstSearch(int root) Performs a breadth-first search in the parent graph. GetComponentEdges() Returns the list of edges of this connected component. GetComponentVertices() Returns the list of vertices of this connected component. GetEdge(int edgeLocalIndex) Returns a selected edge of this component. GetGraphEdges() Returns the list of graph edges. GetGraphVertices() Returns the list of graph vertices. GetNumberEdgesInComponent() Returns the number of edges in this component. GetNumberVerticesInComponent() Returns the number of edges in this component. GetVertex(int vertexLocalIndex) Returns a selected vertex of this component. ReportPComponent() Creates a report with a description of this component. SetVertexTags(int tag) Sets the tags of all component vertices to the specified value.
8.11. CLASS PCOMPONENT
8.11.1
255
PComponent Attribute Detail
protected: ArrayOfIntegers TheVertices An ArrayOfIntegers object with an array containing the list of graph indices of all vertices that belong to the component. The range of the indices is 0 to nv − 1, where nv is the number of vertices in the graph.
protected: ArrayOfIntegers TheEdges An ArrayOfIntegers object with an array containing the list of graph indices of all edges that belong to the component. The range of the indices is 0 to ne − 1, where ne is the number of edges in the graph.
protected: const PArray & GraphVertices A reference to the constant PArray object which is part of the PGraph object and contains the list of all vertices of the graph.
protected: const PArray<EDGE *> & GraphEdges A reference to the constant PArray object which is part of the PGraph object and contains the list of all edges of the graph.
256
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.11.2
PComponent Constructor Detail
public: PComponent::PComponent(const PArray & graphVertices, const PArray<EDGE *> & graphEdges) Public constructor. It constructs an empty component. Arguments • graphVertices • graphEdges A reference to a constant PArray object that contains the list of all edges of the parent graph, each stored in a EDGE object.
public: virtual PComponent::∼PComponent() Virtual destructor.
8.11.3
PComponent Method Detail
protected: virtual void PComponent::AppendEdge(int edgeIndex, int rootsideVertex, int farsideVertex, bool isTreeArc) Adds a given edge to the component.
This is a protected method intended to be used by
CreateByBreadthFirstSearch. Arguments • edgeIndex The integer 0-based graph index of the edge to be added, in the range 0 to n − 1, where n is the number of edges in the parent graph. • rootsideVertex , farsideVertex • isTreeArc
Reserved arguments for use by derived classes.
Reserved arguments for use by derived classes.
8.11. CLASS PCOMPONENT
257
protected: virtual void PComponent::AppendVertex(int vertexIndex, int level, int parent) Adds a given vertex to the component. This is a protected method intended to be used by
CreateByBreadthFirstSearch. Arguments • vertexIndex The integer 0-based graph index of the vertex to be added, in the range 0 to n − 1, where n is the number of vertices in the parent graph. • level , parent
Reserved arguments for use by derived classes.
public: void PComponent::CreateByBreadthFirstSearch(int root) Performs a breadth-first search in the parent graph, starting from a given vertex. A spanning tree rooted at the given vertex and an adjacency level structure are internally created. The connected component is created with all vertices and all edges found in the spanning tree, tree arcs and cross links alike. The spanning tree and the adjacency level structure are destroyed. Arguments • root The 0-based graph index of the vertex that determines the component. The search will start at this vertex.
public: const int * PComponent::GetComponentEdges() Returns the list of edges of this connected component. Return A reference to a constant PArray object that contains a list of pointers to a set of EDGE objects, which in turn contain the edges of this connected component.
258
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: const int * PComponent::GetComponentVertices() Returns the list of vertices of this connected component. Return A reference to a constant PArray object that contains a list of pointers to a set of VERTEX objects, which in turn contain the vertices of this connected component.
public: EDGE * PComponent::GetEdge(int edgeLocalIndex) Returns a pointer to a selected edge of this connected component. Return Returns a pointer to the EDGE object that contains the edge of interest. Arguments • edgeLocalIndex The 0-based component index of the edge of interest, in the range 0 to e − 1, where e is the number of edges in the component.
public: const PArray<EDGE *> & PComponent::GetGraphEdges() Returns the list of all graph edges. Return A reference to a constant PArray object that contains a list of EDGE objects, each of which contains an edge of the graph.
public: const PArray & PComponent::GetGraphVertices() Returns the list of all graph vertices. Return A reference to a constant PArray object that contains a list of VERTEX objects, each of which contains a vertex of the graph.
8.11. CLASS PCOMPONENT
259
public: int PComponent::GetNumberEdgesInComponent() Returns the number of edges in this connected component. Return Returns the integer number of edges in this connected component.
public: int PComponent::GetNumberVerticesInComponent() Returns the number of edges in this connected component. Return Returns the integer number of vertices in this connected component.
public: VERTEX * PComponent::GetVertex(int vertexLocalIndex) Returns a pointer to a selected vertex of this connected component. Return Returns a pointer to the VERTEX object that contains the vertex of interest. Arguments • vertexLocalIndex The 0-based component index of the vertex of interest, in the range 0 to v − 1, where v is the number of vertices in the component.
public: virtual Str PComponent::ReportPComponent() Creates a report with a description of this component. Return An Str object that contains the resulting description.
260
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
protected: void PComponent::SetVertexTags(int tag) Sets the tags of all component vertices to the specified value. These tags may be used to identify the component that a vertex belongs to. Arguments • tag
8.12
The integer value that is to be set as the tag value for all vertices in the component.
Class PComponentWithTree PComponent PComponentWithTree
A parameterized base class that describes a connected component of a mathematical graph stored in a PGraph object, with a spanning tree and an adjacency level structure. The class uses the template as part of the class definition and the definitions of all methods. The component is initially constructed as an empty graph, and is subsequently created by breadth-first search.
8.12. CLASS PCOMPONENTWITHTREE
261
Attribute Summary protected: ArrayOfIntegers protected: int protected: int protected: int protected: int protected: ArrayOfIntegers protected: ArrayOfIntegers protected: ArrayOfIntegers private: bool protected: ArrayOfIntegers
Parents The parent tree arc of each vertex (-1 for the root). NTreeArcs The number of tree arcs in the spanning tree. NGraphVertices The number of vertices in this component. NGraphEdges The number of edges in this component. NCrossLinks The number of cross-links in the spanning tree. LocalVertex Local index for each vertex in the graph. LocalEdge Local index for each edge in the graph. Levels The level or distance from root of each vertex. IsCreated A private value that confirms if this component has been properly created. Directions The direction of each edge relative to the spanning tree.
Constructor Summary public:
public: virtual
PComponentWithTree(const PArray & graphVertices, const PArray<EDGE *> & graphEdges) Public constructor. It constructs an empty component. ∼PComponentWithTree() Virtual destructor.
262
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary protected: void
AppendFullEdge(int edgeIndex, int rootsideVertex, int treetopsideVertex, bool isTreeArc) Adds a given edge to the component. protected: AppendFullVertex(int vertexIndex, int level, int parent) Adds a given vertex to the component. void public: CreateEnclosingTreepath(int crosslinkLocalIndex) PPathClosed * public: CreatePathFromVertexToRoot(int vertexIndex, PPathOpen & Result) Given a vertex, creates a path from that vertex to the root of the spanning tree. public: CreateWithPredefinedTree(int root, bool treearcsTagged = false) Creates this component from a given root vertex and a subset of edges. bool public: GetEdgeDirections() const int * Returns a pointer to the constant internal integer array of edge directions. public: GetEdgeDirections(int edgeLocalIndex) int Returns an integer indicating the reference direction of a given edge. public: GetIsCreated() bool Confirms or denies if this component has been properly created. public: GetNumberCrossLinks() int Returns the number of edges that are cross-links in the spanning tree. public: GetNumberTreeArcs() int Returns the number of edges that are tree arcs in the spanning tree. public: GetRootVertex() const VERTEX * Returns the root vertex of the spanning tree. public: GetVertexLevels() Returns a pointer to the constant internal integer array of vertex levels. const int * public: GetVertexParents() const int * Returns a pointer to the constant internal integer array of vertex parents. public: IsTree() bool Confirms of denies if this component is a tree. public: ReportPComponentVerbose() Str Creates a verbose report describing this component. protected: Reset() void Resets this component to be empty.
8.12. CLASS PCOMPONENTWITHTREE
8.12.1
263
PComponentWithTree Attribute Detail
protected: ArrayOfIntegers Parents An ArrayOfIntegers object with an array of integers in correspondence with the vertices of this component. Each element of the array contains the graph index of the parent edge for the corresponding vertex. The element corresponding to the root of the tree, which has no parent edge, contains a negative number.
protected: int NTreeArcs The integer number of tree arcs in the spanning tree.
protected: int NGraphVertices The integer number of vertices in this connected component.
protected: int NGraphEdges The integer number of edges in this connected component.
protected: int NCrossLinks The integer number of cross-links in the spanning tree.
protected: ArrayOfIntegers LocalVertex An ArrayOfIntegers object that contains an expanded array with the local component index of each vertex in the graph, in the range 0 to v −1, where v is the number of vertices in the component. The array is in correspondence with the vertices of the parent graph. Locations of the array that correspond to vertices not in the component contain a negative integer.
264
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
protected: ArrayOfIntegers LocalEdge An ArrayOfIntegers object that contains an expanded array with the local component index of each edge in the graph, in the range 0 to e − 1, where e is the number of edges in the component. The array is in correspondence with the edges of the parent graph. Locations of the array that correspond to edges not in the component contain a negative integer.
protected: ArrayOfIntegers Levels An ArrayOfIntegers object that contains an array in correspondence with the vertices in this components. Each element of the array contains the integer value of the level of the corresponding vertex. The level of the root vertex is 0.
private: bool IsCreated A private value that confirms if this component has been properly created by a call to
CreateWithPredefinedTree.
protected: ArrayOfIntegers Directions An ArrayOfIntegers object with an array in correspondence with the edges of this component. Each element of the array contains an integer indicating the direction of the corresponding edge relative to the spanning tree. Currently, the value of this integer is 0 for a cross-link, 1 if the reference direction of the edge is down the tree (away from root), or -1 if the reference direction is up the tree (towards the root).
8.12. CLASS PCOMPONENTWITHTREE
8.12.2
265
PComponentWithTree Constructor Detail
public: PComponentWithTree::PComponentWithTree(const PArray & graphVertices, const PArray<EDGE *> & graphEdges) Public constructor. It constructs an empty component. Arguments • graphVertices A reference to a constant PArray object that contains the list of pointers to vertices of the parent graph. • graphEdges A reference to a constant PArray object that contains the list of pointers to edges of the parent graph.
public: virtual PComponentWithTree::∼PComponentWithTree() Virtual destructor.
266
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.12.3
PComponentWithTree Method Detail
protected: void PComponentWithTree::AppendFullEdge(int edgeIndex, int rootsideVertex, int treetopsideVertex, bool isTreeArc) Adds a given edge to the component.
This is a protected method intended to be used by
CreateWithPredefinedTree. Arguments • edgeIndex The integer 0-based graph index of the edge to be added, in the range 0 to n − 1, where n is the number of edges in the parent graph. • rootsideVertex , treetopsideVertex If the edge being added is a tree arc, it will be added to the tree, and its two vertices will be assigned into adjacent levels, say level ` and level ` + 1. These two arguments contain the 0-based integer graph indices of the vertices to be assigned into level ` and level ` + 1, respectively. The side of the tree opposite the root is referred to as the tree top, and is where the leaves are. Mathematical trees are frequently shown upside down, with the root at the top and the leaves at the bottom. If the edge being added is a cross-link, these two arguments are ignored. • isTreeArc arc.
A boolean value that confirms or denies that the edge being added is a tree
8.12. CLASS PCOMPONENTWITHTREE
267
protected: void PComponentWithTree::AppendFullVertex(int vertexIndex, int level, int parent) Adds a given vertex to the component. This is a protected method intended to be used by
CreateWithPredefinedTree. Arguments • vertexIndex The integer 0-based graph index of the vertex to be added, in the range 0 to n − 1, where n is the number of vertices in the parent graph. • level The 0-based integer value of the level in the adjacency level structure that this vertex is to be added to. • parent The 0-based integer graph index of the parent edge of this vertex, in the range 0 to n − 1, where n is the number of edges in the parent graph. The parent edge is the edge leading from the vertex towards the root of the tree.
public: PPathClosed * PComponentWithTree :: CreateEnclosingTreepath(int crosslinkLocalIndex) Creates an enclosing path made of tree arcs for a given cross-link. Return A pointer to a PPathClosed object that contains the resulting path. Arguments • crosslinkLocalIndex The 0-based integer component index of the given cross-link, in the range 0 to e − 1, where e is the number of edges in this connected component.
268
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool PComponentWithTree::CreatePathFromVertexToRoot(int vertexIndex, PPathOpen & Result) Given a vertex, creates a path from that vertex to the root of the spanning tree. The result is returned by argument. Return A boolean value indicating if execution has been successful. Arguments • vertexIndex The 0-based integer graph index of the vertex of interest, in the range 0 to n − 1, where n is the total number of vertices in the parent graph. • Result A reference to a PPathOpen object, which, upon return, will contain the resulting path.
public: bool PComponentWithTree::CreateWithPredefinedTree(int root, bool treearcsTagged = false) Given are a set of edges of the parent graph and a root vertex that belongs to at least one of the edges. A breadth-first search is conducted starting at the root but using only edges from the prescribed set. A spanning tree and an adjacency level structure are generated out of the given edges, and all remaining edges in the component are marked as cross-links. Return A boolean value that confirms or denies if execution has been successful. Arguments • root The 0-based integer graph index of the root vertex where the breadth-first search is to start. • treearcsTagged A boolean value that confirms of denies if a subset of the graph edges has been tagged. If true , then only edges marked with a tag of 1 are used in the spanning tree, while the remaining edges, if any, become cross-links. If false , then all the graph edges are used in the search.
8.12. CLASS PCOMPONENTWITHTREE
269
public: const int * PComponentWithTree::GetEdgeDirections() Returns a pointer to the constant internal integer array of edge directions, which is contained in the ArrayOfIntegers object Directions . Return A pointer to the constant internal integer array of edge directions contained in the ArrayOfIntegers object Directions .
public: int PComponentWithTree::GetEdgeDirections(int edgeLocalIndex) Returns an integer indicating the reference direction of a given edge relative to the spanning tree. Return An integer indicating the reference direction of a given edge relative to the spanning tree. Currently, the value of this integer is 0 for a cross-link, 1 if the reference direction of the edge is down the tree (away from root), or -1 if the reference direction is up the tree (towards the root). Arguments • edgeLocalIndex The 0-based integer component index of the edge of interest, in the range 0 to e − 1, where e is the number of edges in this component.
public: bool PComponentWithTree::GetIsCreated() Confirms
or
denies
if
this
component
has
been
properly
created
by
CreateWithPredefinedTree Return A boolean value that confirms or denies if this component has been properly created.
public: int PComponentWithTree::GetNumberCrossLinks() Returns the number of edges that are cross-links in the spanning tree. Return The integer number of edges that are cross-links in the spanning tree.
a
call
to
270
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: int PComponentWithTree::GetNumberTreeArcs() Returns the number of edges that are tree arcs in the spanning tree. Return The integer number of edges that are tree arcs in the spanning tree.
public: const VERTEX * PComponentWithTree::GetRootVertex() Returns a pointer to the constant VERTEX object that contains the root vertex of the spanning tree. Return A pointer to the constant VERTEX object that contains the root vertex of the spanning tree.
public: const int * PComponentWithTree::GetVertexLevels() Returns a pointer to the constant internal integer array of vertex levels, which is contained in the ArrayOfIntegers object Levels . Return A pointer to the constant internal integer array of vertex levels contained in the ArrayOfIntegers object Levels .
public: const int * PComponentWithTree::GetVertexParents() Returns a pointer to the constant internal integer array of vertex parents, which is contained in the ArrayOfIntegers object Parents . Return A pointer to the constant internal integer array of vertex parents contained in the ArrayOfIntegers object Parents .
8.13. CLASS PEDGE
271
public: bool PComponentWithTree::IsTree() Confirms of denies if this component is a tree. A connected component is a tree when all edges belong to spanning tree. Return A boolean value that confirms of denies if this component is a tree.
public: Str PComponentWithTree::ReportPComponentVerbose() Creates a verbose report describing this component. Return An Str object containing the resulting report.
protected: void PComponentWithTree::Reset() Resets this component to be empty. This is a protected method intended to be used by the constructor and other class methods.
8.13
Class PEdge
A parameterized base class that describes an undirected edge of a mathematical graph. The edge is described by an unordered pair of PVertex objects that contain the two vertices u and v of the edge. The arbitrary order that the two objects PVertex are stored in the class is taken as the reference direction of the undirected edge, and the two vertices are called the tail and head in the order of the reference direction. The class uses the template as part of the class definition and the definitions of all methods.
272
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Attribute Summary protected: VERTEX * protected: VERTEX * protected: int public: int
m pSecondVertex A pointer to the head vertex of this edge. m pFirstVertex A pointer to the tail vertex of this edge. MyGraphIndex The graph index of this edge. ETag An integer tag accessible to the user.
Constructor Summary public: public: public: virtual
PEdge(VERTEX * pV1, VERTEX * pV2) Public constructor. PEdge(const EDGE & other) Blocking copy constructor. ∼PEdge() Public destructor.
8.13. CLASS PEDGE
273
Method Summary public: VERTEX public: int public: int public: int public: VERTEX public: VERTEX public: int public: Str public: void public: VERTEX
8.13.1
*
* *
*
GetHeadVertex() Returns a pointer to the head vertex of this edge. GetHeadVertexIndex() Returns the index of the head vertex of this edge. GetMyComponent() Returns the index of the connected component where this edge belongs. GetMyGraphIndex() Returns the index of this edge in the graph. GetSharedVertex(const PEdge * other) Finds the vertex shared by this edge and another given edge. GetTailVertex() Returns a pointer to the tail vertex of this edge. GetTailVertexIndex() Returns the index of the tail vertex of this edge. ReportEdge() Creates a report describing this edge. SetMyGraphIndex(int graphIndex) Sets the graph index for this edge to the given value. ToggleVertex(const VERTEX * vertex) Of the two vertices of this edge, returns the one that is not the given one.
PEdge Attribute Detail
protected: VERTEX * m pSecondVertex A pointer to a VERTEX object that contains the head vertex of this edge. The edge is undirected. The naming convention refers only to the reference direction.
protected: VERTEX * m pFirstVertex A pointer to a VERTEX object that contains the tail vertex of this edge. The edge is undirected. The naming convention refers only to the reference direction.
274
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
protected: int MyGraphIndex The graph index of this edge. This value is determined at the time the edge is added to the graph.
public: int ETag An integer tag accessible to the user. The tag provides a storage location associated with this object where the user can store and retrieve any integer value.
8.13.2
PEdge Constructor Detail
public: PEdge::PEdge(VERTEX * pV1, VERTEX * pV2) Public constructor. It constructs a PEdge object with the two given vertices and an undefined graph index. Arguments • pV1 , pV2 edge.
Pointers to two VERTEX objects that contain the two vertices for the new
public: PEdge::PEdge(const EDGE & other) Mathematically, it makes no sense to make a copy of an edge of a graph. This blocking copy constructor is provided to prevent the compiler from supplying a default one. An error occurrs if the constructor is invoked. Arguments • other
A reference to a constant EDGE object that contains the edge to be copied.
8.13. CLASS PEDGE
275
public: virtual PEdge::∼PEdge() Public destructor. It destroys this EDGE object.
8.13.3
PEdge Method Detail
public: VERTEX * PEdge::GetHeadVertex() Returns a pointer to an EDGE object that contains the head vertex of this edge. Return Returns a pointer to an EDGE object that contains the head vertex of this edge.
public: int PEdge::GetHeadVertexIndex() Returns the integer 0-based graph index of the head vertex of this edge. Return Returns the integer index of the head vertex of this edge.
public: int PEdge::GetMyComponent() Returns the index of the connected component where this edge belongs. Return The integer index of the connected component where this edge belongs, in the range 0 to k − 1, where k is the number of connected components in the graph.
public: int PEdge::GetMyGraphIndex() Returns the index of this edge in the graph. This index is defined only after the edge has been added to the graph in the course of the creation process. Return The integer value of the index of this edge in the graph.
276
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: VERTEX * PEdge::GetSharedVertex(const PEdge * other) Finds the vertex shared by this edge and another given edge. Returns NULL if no vertex is shared by the two edges. Return A pointer to a VERTEX object that contains the vertex shared by this edge and another given edge, or NULL if no shared vertex exists. Arguments • other
A pointer to a constant PEdge object that contains the other given edge.
public: VERTEX * PEdge::GetTailVertex() Returns a pointer to an EDGE object that contains the tail vertex of this edge. Return Returns a pointer to an EDGE object that contains the tail vertex of this edge.
public: int PEdge::GetTailVertexIndex() Returns the integer 0-based graph index of the tail vertex of this edge. Return Returns the integer 0-based graph index of the tail vertex of this edge.
public: Str PEdge::ReportEdge() Creates a report describing properties of this edge such as its graph index and the graph indices of its two vertices. Return An Str object that contains the resulting report.
8.14. CLASS PGRAPH
277
public: void PEdge::SetMyGraphIndex(int graphIndex) Sets the graph index for this vertex to the given value. Arguments • graphIndex The given integer value of the index of this edge in the graph, range 0 to n − 1, where n is the current number of edges in the graph.
public: VERTEX * PEdge::ToggleVertex(const VERTEX * vertex) Of the two vertices of this edge, returns the one that is not the given vertex. An error occurrs if the given vertex is none of the two vertices of this edge. Return A pointer to a VERTEX object that contains one of the two vertices of this edge, the one that is not the given vertex. Arguments • vertex
8.14
A pointer to a constant VERTEX object that contains the given vertex.
Class PGraph
A parameterized base class that describes a mathematical graph. The class uses the template as part of the class definition and the definitions of all methods.
278
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Attribute Summary protected: PArray protected: PArray<EDGE *> protected: int protected: int protected: int private: bool
TheVertices An array that contains pointers to all the VERTEX objects in the graph. TheEdges An array that contains pointers to all the EDGE objects in the graph. NumberVertices The number of vertices in the graph. NumberEdges The number of edges in the graph. NumberConnectedComponents The number of connected components in the graph. IsCreated A boolean value that is true only if this graph has been properly created.
Constructor Summary public: public: virtual
PGraph() Public constructor. It constructs and empty graph. ∼PGraph() Destructor. It destructs the individual VERTEX and EDGE objects.
8.14. CLASS PGRAPH
279
Method Summary public: int public: bool public: int public: int public: void public: bool
public: EDGE * public: int public: int public: bool public: int public: int public: int private: int
public: const PArray<EDGE *> &
AddEdge(EDGE * edge) Adds an EDGE object to this graph. AddEdgeIfVerticesPresent(EDGE * edge) Conditionally adds an EDGE object edge to this graph, if both vertices are present. AddVertex(VERTEX * vertex) Adds a VERTEX object to this graph. CreateAllConnectedComponents() Performs a breadth-first search of the graph to identify the connected components. DeleteAllVerticesAndEdges() Destroys all VERTEX and all EDGE of the graph. FindShortestPath(int vaGlobal, int vbGlobal, PPathOpen & Result, bool activeEdgesTagged = false) Uses breadth-first search to find the shortest path between two given vertices. GetEdgeWithIndex(int edgeIndex) Returns the pointer to the EDGE object identified by its index. GetIndexWithEdge(const EDGE * pE) Given an EDGE object, finds its index in the graph. GetIndexWithVertex(const VERTEX * pV) Given a VERTEX object, finds its index in the graph. GetIsCreated() Returns true when the creation process of this graph has been completed, false otherwise. GetNumberConnectedComponents() Returns the number of connected components. GetNumberEdges() Returns the current number of edges in the graph. GetNumberVertices() Returns the current number of vertices in the graph. GetShortestPathIndex(const PArray *> & nsp) Finds the index of one of the enclosing paths created by SortSelectedEdgesByLengthOfEnclosingPath . GetTheEdges() Returns a reference to the constant array of edges of this graph.
280
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary public: const PArray & public: VERTEX * public: void public: void public: bool private: bool
8.14.1
GetTheVertices() Returns a reference to the constant array of vertices of this graph.
GetVertexWithIndex(int vertexGIndex) Given the graph index of a vertex, returns a pointer to that vertex. SetEdgeTags(int tag) Sets the tags of all edges to a given integer value. SetVertexTags(int tag) Sets the tags of all vertices to a given integer value. SortSelectedEdgesByLengthOfEnclosingPath(PArray<EDGE *> & edges, PArray *¿ & paths) Sorts a given subset of edges in the order of their shortest enclosing paths. UpdateUnsortedPaths(const PArray<EDGE *> & edg, PArray *> & pth) Finds the shortest enclosing paths for each edge in a given subset.
PGraph Attribute Detail
protected: PArray TheVertices A PArray object that contains an array of pointers of type VERTEX *, which point to all the VERTEX objects in the graph.
protected: PArray<EDGE *> TheEdges A PArray object that contains an array of pointers of type EDGE * , which point to all the EDGE objects in the graph.
protected: int NumberVertices The integer number of vertices in the graph.
8.14. CLASS PGRAPH
281
protected: int NumberEdges The integer number of edges in the graph.
protected: int NumberConnectedComponents The integer number of connected components in the graph.
private: bool IsCreated A boolean value that is true only if this graph has been properly created. For details of the process of creation see the constructor PGraph.
8.14.2
PGraph Constructor Detail
public: PGraph::PGraph() Public constructor. It constructs the object with no vertices, edges, or connected components, and sets IsCreated to false. Once the PGraph object has been constructed, it has to be created. The process of creation has two steps: adding all vertices and edges by respective calls to AddVertex and AddEdge, and a final call to CreateAllConnectedComponents, where a breadth-first search is performed in the graph, the connected components are identified, and IsCreated is set to true. The PGraph object can be used only after the process of creation has been completed.
public: virtual PGraph::∼PGraph() Destructor. It destructs the individual VERTEX and EDGE objects.
282
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.14.3
PGraph Method Detail
public: int PGraph::AddEdge(EDGE * edge) Adds an EDGE object to this graph. The addition can be performed only if both VERTEX objects of the edge are already present in the graph, and as part of the process of creation. No other tests are performed, the caller is responsible for not adding the same edge twice. Return The integer total number of edges after the addition. Arguments • edge A pointer to the EDGE object being added. The PGraph object takes ownership of the EDGE object and will destroy it in the destructor.
public: bool PGraph::AddEdgeIfVerticesPresent(EDGE * edge) Conditionally adds an EDGE object edge to this graph. The addition can be performed only if both VERTEX objects of the edge are already present in the graph, and as part of the process of creation. No other tests are performed, the caller is responsible for not adding the same edge twice. Return true if the EDGE object has been added, false otherwise. Arguments • edge A pointer to the EDGE object being added. If the EDGE object is actually added, the PGraph object takes ownership of it and will destroy it in the destructor.
8.14. CLASS PGRAPH
283
public: int PGraph::AddVertex(VERTEX * vertex) Adds a VERTEX object to this graph. The addition can be performed only as part of the process of creation. No other tests are performed, the caller is responsible for not adding the same vertex twice. Return The integer total number of vertices after the addition. Arguments • vertex A pointer to the VERTEX object being added. The PGraph object takes ownership of the VERTEX object and will destroy it in the destructor.
public: int PGraph::CreateAllConnectedComponents() Performs a breadth-first search of the graph to identify the connected components. This completes the process of creation of the graph. Return The integer number of connected components.
public: void PGraph::DeleteAllVerticesAndEdges() Destroys all VERTEX and all EDGE objects of the graph and sets IsCreated to false .
284
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool PGraph::FindShortestPath(int vaGlobal, int vbGlobal, PPathOpen & Result, bool activeEdgesTagged = false) Given two distinct vertices of the graph, this method uses breadth-first search and finds the shortest path between the given vertices, if one exists. Optionally, some edges can be excluded from the search. The resulting path is returned by argument in a PPathOpen object. Return Returns true if the shortest path has been found. In this case, the resulting path is stored in the PPathOpen argument. Returns false if the path does not exist because the vertices are in different components or are unreachable due to excluded edges. Arguments • vaGlobal , vbGlobal error occurrs.
The two given vertices. They must be different, otherwise an
• Result A PPathOpen object, which, upon return, will contain the resulting path. If a path has not been found, Result is left undetermined. • activeEdgesTagged PEdge edge objects can be tagged with an integer value accessible to the user. When the activeEdgesTagged argument is true , then all PEdge objects tagged with -1 are excluded from the breadth-first search. The tags are disregarder if activeEdgesTagged is false .
public: EDGE * PGraph::GetEdgeWithIndex(int edgeIndex) Returns the pointer to the EDGE object identified by its 0-based integer index. Return The pointer to the desired EDGE object. Arguments • edgeIndex
The integer 0-based index of the desired object.
8.14. CLASS PGRAPH
285
public: int PGraph::GetIndexWithEdge(const EDGE * pE) Given an EDGE object, finds its index in the graph. Returns -1 if not found. Return The integer 0-based index in the graph of the EDGE object passed as argument. EDGE objects are assigned indices sequentially in the order they are added to the graph during creation. Arguments • pE
A pointer to the constant EDGE object whose index is requested.
public: int PGraph::GetIndexWithVertex(const VERTEX * pV) Given a VERTEX object, finds its index in the graph. Returns -1 if not found. Return The integer 0-based index in the graph of the VERTEX passed as argument. VERTEX objects are assigned indices sequentially in the order they are added to the graph during creation. Arguments • pV
A pointer to the constant VERTEX object whose index is requested.
public: bool PGraph::GetIsCreated() Returns true when the process of creation of this graph has been completed, false otherwise. For details of the process of creation see the constructor. Return true when the process of creation is complete for this graph, false otherwise.
public: int PGraph::GetNumberConnectedComponents() Returns the number of connected components. Return The integer number of connected components.
286
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: int PGraph::GetNumberEdges() Returns the current number of edges in the graph. Return The integer current number of edges in the graph.
public: int PGraph::GetNumberVertices() Returns the current number of vertices in the graph. Return The integer current number of vertices in the graph.
private: int PGraph::GetShortestPathIndex(const PPathOpen * > & nsp) Finds
the
index
of
one
of
the
enclosing
open
paths
PArray< created
by
SortSelectedEdgesByLengthOfEnclosingPath. Returns -1 if not found. Return The index of the given path. Arguments • nsp A reference to a constant PArray > object that contains the array of pointers to the enclosing open paths.
public: const PArray<EDGE *> & PGraph::GetTheEdges() Returns a reference to a constant PArray <EDGE *> object that contains the list of pointers to the edges of this graph. Return Returns a reference to a constant PArray <EDGE *> object that contains the list of pointers to the edges of this graph.
8.14. CLASS PGRAPH
287
public: const PArray & PGraph::GetTheVertices() Returns a reference to a constant PArray object that contains the list of pointers to the vertices of this graph. Return Returns a reference to a constant PArray object that contains the list of pointers to the vertices of this graph.
public: VERTEX * PGraph::GetVertexWithIndex(int vertexGIndex) Given the graph index of a vertex, returns a pointer to the VERTEX object that contains the vertex with that index. Return The pointer to the VERTEX object that contains the vertex with the given index. Arguments • vertexGIndex
The integer 0-based index of the vertex of interest.
public: void PGraph::SetEdgeTags(int tag) Sets the tags of all edges to a given integer value. Arguments • tag
The value that all edge tags are to be set to.
public: void PGraph::SetVertexTags(int tag) Sets the tags of all vertices to a given integer value. Arguments • tag
The value that all vertex tags are to be set to.
288
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool PGraph::SortSelectedEdgesByLengthOfEnclosingPath(PArray< EDGE * > & edges, PArray< PPathOpen * > & paths) Sorts a given subset of edges in the order of their shortest enclosing paths. The given edges must all be in the same connected component, and are said to be inactive. The algorithm proceeds in steps. In each step, the shortest enclosing path is found for each inactive edge, the shortest of all such paths is added to the sorted order, and the corresponding edge is activated. The algorithm then proceeds to the next step, and is repeated until no more inactive edges are left. Note that the shortest path found in each step may include edges that were initially inactive but had been activated in a previous step. The sorted edges and their corresponding enclosing paths are passed back by argument in edges and paths , respectively. Return Returns true if the algorithm has been successful, false in case of error. Arguments • edges A reference to a PArray <EDGE *> object that contains the pointers to the given subset of edges. Upon return, the array will contain the same pointers sorted in the order of the shortest of their shortest enclosing paths. • paths A reference to a PArray *> object, which, upon return, will contain pointers to the shortest enclosing paths sorted from shortest to longest, in correspondence with the edges in array edges .
private: bool PGraph::UpdateUnsortedPaths(const PArray<EDGE *> & edg, PArray *> & pth) Finds the shortest enclosing paths for each edge in a given subset. Return true is the algorithm has been successful, false in case of error. Arguments • edg A reference to a constant PArray <EDGE *> object that contains the pointes to the edges in the given subset. • pth A reference to a PArray *> object, which, upon return and if execution has been successful, will contain the pointers to the shortest enclosing paths, in correspondence with the edges in the given subset.
8.15. CLASS PPATH
8.15
289
Class PPath
A parameterized base class that describes a connected path in a mathematical undirected graph. The path is undirected, and can be traversed in either direction. The path is described by a list of edges stored in array PathEdges , and the reference direction is taken to be the one defined by the order that the edges are stored. If the path has only one edge, then the reference direction for the path is taken the same as the reference direction of the edge. The class uses the template as part of the class definition and the definitions of all methods.
Attribute Summary protected: PArray<EDGE *> protected: PArray
PathEdges The list of edges that his path is made of. EdgeDirections An array of boolean values that indicate the reference direction of each edge in relation to the reference direction of the path.
Constructor Summary public: public: virtual
PPath() Public constructor. It creates an empty path object. ∼PPath() Virtual destructor.
290
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary public: bool public: int public: void public: const VERTEX * public: const EDGE * public: PArray & public: const EDGE * public: const VERTEX * public: int public: EDGE * public: int public: int public: PArray<EDGE *> & public: const EDGE * public: virtual bool
Compare(const PPath & other) Compares this path with another given path. CountSharedEdges(const PPath & other) Counts the number of edges shared by this path and another given path. EmptyMe() Empties this path of edges. GetBackVertex(int localEdgeIndex) Of the two vertices of a given edge, returns the one that is closer to this path’s tail. GetConstantEdge(int localEdgeIndex) Finds an edge of this path when its local index is given. GetEdgeDirections() Returns a reference to the array EdgeDirections , that contains the relative reference directions of all edges of this path. GetFollowingEdge(int localEdgeIndex) Of the two edges connected to a given edge of this path, returns the one that’s closer to the path’s head. GetFrontVertex(int localEdgeIndex) Of the two vertices of a given edge, returns the one that is closer to this path’s head. GetLocalEdgeIndex(const EDGE * edge) Finds the local index of a given edge of this path. GetNonconstantEdge(int localEdgeIndex) Finds an edge of this path when its local index is given. GetNumberEdges() Returns the length of this path. GetOverlap(const PPath & other, int & ia, int & ib, int & ja, int & jb, int start = 0) Finds the range of overlapping edges for this path and another given path. GetPathEdges() Returns a reference to the array PathEdges , that contains the list of all edges of this path. GetPreviousEdge(int localEdgeIndex) Of the two edges connected to a given edge of this path, returns the one that’s closer to the path’s tail. IsClosed() Finds if this path is closed or not.
8.15. CLASS PPATH
291
Method Summary (continued) public: bool public: Str public: Str public: virtual void public: virtual bool
8.15.1
operator==(const PPath & other) Compares this path with another given path. ReportPathTerse(const char * title = NULL) Creates a report with a brief description of this path. ReportPathVerbose(const char * title = NULL) Creates a report with a detailed description of this path. ReverseMe() Reverses the reference direction of this path. Verify() Verifies the consistency and correctness of this path.
PPath Attribute Detail
protected: PArray<EDGE *> PathEdges A PArray object that contains the list of pointers to the edges of the path. The order in which the pointers are stored in the list determines the reference direction for the path.
protected: PArray EdgeDirections An PArray
of boolean values in one-to-one correspondence with the edges stored in array PathEdges . A value of true means that the reference directions of the edge and the path are the same. A value of false indicates that the two directions are opposite.
8.15.2
PPath Constructor Detail
public: PPath::PPath() Public constructor. It creates an empty path object.
292
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: virtual PPath::∼PPath() Virtual destructor.
8.15.3
PPath Method Detail
public: bool PPath::Compare(const PPath & other) Compares this path with another given path. Returns true if the two paths consist of the same edges and have the same reference direction. Return true if this path and the given paths are identical, false otherwise. Arguments • other
A PPath object containing the path to be compared with this path.
public: int PPath::CountSharedEdges(const PPath & other) Counts the number of edges shared by this path and another given path, irrespective of the reference directions of the edges. Return The number of edges shared by this path and another given path Arguments • other
A PPath object containing the given path.
public: void PPath::EmptyMe() Removes all edges from this path, leaving it empty.
8.15. CLASS PPATH
293
public: const VERTEX * PPath::GetBackVertex(int localEdgeIndex) Given an edge of this path, finds which one of the two vertices of the edge is closer to the tail vertex of the path. If the reference directions of the given edge and the path are the same, this vertex is the tail vertex of the edge. Otherwise, it is the head vertex of the edge. Return A pointer to a constant VERTEX object that contains the resulting vertex. Arguments • localEdgeIndex The 0-based index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: const EDGE * PPath::GetConstantEdge(int localEdgeIndex) Finds an edge of this path when its local index is given. Return A pointer to a constant EDGE object that contains the resulting edge. Arguments • localEdgeIndex The 0-based local index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: PArray & PPath::GetEdgeDirections() Returns a reference to the array EdgeDirections , that contains the relative reference directions of all edges of this path. Return A reference to a PArray object that contains boolean values indicating the reference directions of the edges of this path.
294
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: const EDGE * PPath::GetFollowingEdge(int localEdgeIndex) Of the two edges connected to a given edge of this path, returns the one that’s closer to the path’s head, or NULL if none exists. Return A pointer to a constant EDGE object that contains the resulting edge. Arguments • localEdgeIndex The 0-based index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: const VERTEX * PPath::GetFrontVertex(int localEdgeIndex) Given an edge of this path, finds which one of the two vertices of the edge is closer to the head vertex of the path. If the reference directions of the given edge and the path are the same, this vertex is the head vertex of the edge. Otherwise, it is the tail vertex of the edge. Return A pointer to a constant VERTEX object that contains the resulting vertex. Arguments • localEdgeIndex The 0-based index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: int PPath::GetLocalEdgeIndex(const EDGE * edge) Finds the 0-based local index of a given edge of this path. The index is in the range 0 to k − 1, where k is the length of this path. Return The integer 0-based local index of the given edge if it belongs to this path, or -1 if not. Arguments • edge
A pointer to a constant EDGE object that contains the edge of interest.
8.15. CLASS PPATH
295
public: EDGE * PPath::GetNonconstantEdge(int localEdgeIndex) Finds an edge of this path when its local index is given. Return A pointer to an EDGE object that contains the resulting edge. Arguments • localEdgeIndex The 0-based index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: int PPath::GetNumberEdges() Returns the length of this path. Return An integer equal to the value of the length of this path.
public: int PPath::GetOverlap(const PPath & other, int & ia, int & ib, int & ja, int & jb, int start = 0) Finds the range of overlapping edges for this path and another edge, starting from a given edge of this path. If found, passes back the local start and end indices for both paths in ia , ib and ja jb , and returns the number of overlapping edges. Note ib >= ia always, but jb may be less than ja if the range passes over the end of the other path. If not found, returns 0 and leaves ia , ib , ja , jb undetermined. Return The number of overlapping edges. Arguments • other
A reference to a constant PPath object that contains the given edge.
• ia , ib
Index of first and last overlapping edges for this path.
• ja , jb
Index of first and last overlapping edges for path other .
• start
The 0-based local index of an edge of this path where the search is to begin.
296
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: PArray<EDGE *> & PPath::GetPathEdges() Returns a reference to the array PathEdges , that contains the list of all edges of this path. Return A reference to a PArray object with a list of pointers to EDGE objects containing all the edges of this path.
public: const EDGE * PPath::GetPreviousEdge(int localEdgeIndex) Of the two edges connected to a given edge of this path, returns the one that’s closer to the path’s tail, or NULL if none exists. Return A pointer to a constant EDGE object that contains the resulting edge. Arguments • localEdgeIndex The 0-based index of the edge of interest in this path, range 0 to k − 1 where k is the length of the path.
public: virtual bool PPath::IsClosed() Returns a boolean value indicating if this path is closed or not. Return true if this path is closed, false if not.
public: bool PPath::operator==(const PPath & other) Compares this path with another given path. Returns true if the two paths consist of the same edges and have the same reference direction. Return true if this path and the given paths are identical, false otherwise. Arguments • other
A PPath object containing the path to be compared with this path.
8.15. CLASS PPATH
297
public: Str PPath::ReportPathTerse(const char * title = NULL) Creates a report with a brief description of this path. Return An Str object that contains the resulting report. Arguments • NULL A pointer to a constant char array that contains a title for the report. If NULL is passed, or the argument omitted, the report will have no title.
public: Str PPath::ReportPathVerbose(const char * title = NULL) Creates a report with a detailed description of this path. Return An Str object that contains the resulting report. Arguments • NULL A pointer to a constant char array that contains a title for the report. If NULL is passed, or the argument omitted, the report will have no title.
public: virtual void PPath::ReverseMe() Reverses the reference direction of this path by reversing the order in which the edges are stored.
public: virtual bool PPath::Verify() Verifies the consistency and correctness of this path. This method is intended for debugging. Return A boolean value with the value of true if this path is consistent and correct, false otherwise.
298
8.16
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Class PPathClosed
PPath PPathClosed
A parameterized base class that describes a connected closed path in a mathematical undirected graph. The path is undirected, and can be traversed in either direction. The class uses the template as part of the class definition and the definitions of all methods.
Constructor Summary public: public: virtual
PPathClosed(PPathOpen & path) Public copy constructor. ∼PPathClosed() Virtual destructor.
8.16. CLASS PPATHCLOSED
299
Method Summary public: bool public: bool public: bool
public: bool public: bool
public: bool public: void public: void public: bool
CreateOpenpathWithEdges(int nStart, int nEdges, PPathOpen & Result) Creates an open path with selected edges from this path. CreateOpenpathWithoutEdges(int nStart, int nEdges, PPathOpen & Result) Creates an open path by excluding selected edges from this path. FindOverlappingPath(const PPathClosed & other, PPathOpen & overlap, PPathOpen & restofthis, PPathOpen & restofother) Determines if this path and another given closed path share a connected path of edges. If they do, finds the overlapping path, the rest of this path, and the rest of the other path, and returns true. If they don’t, or if there is more than one shared path, or if all edges are shared, returns false. GetMidPath(int nStart, PPathOpen & Result) Creates an open path that contains all edges of this path between a given position and the head of this path. GetMidPath(int nStart, int nEdges, PPathOpen & Result) Creates an open path that contains a given number of edges from this path, starting at a given position. IsClosed() Always returns true . ReverseMe() Reverses the reference direction of this path. RotateMe(int nSteps) Rotates this closed path by the specified number of steps. Verify() Verifies the consistency and correctness of this path.
300
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.16.1
PPathClosed Constructor Detail
public: PPathClosed::PPathClosed(PPathOpen & path) Public copy constructor. It constructs this object with all the edges of a given closed path, and the same reference direction. The given closed path is stored in a PPathOpen object, and must have the same tail vertex and head vertex. This is the only way of constructing a PPathClosed object. Arguments • path
A reference to the given PPathOpen object.
public: virtual PPathClosed::∼PPathClosed() Virtual destructor.
8.16.2
PPathClosed Method Detail
public: bool PPathClosed::CreateOpenpathWithEdges(int nStart, int nEdges, PPathOpen & Result) Creates a PPathOpen object that contains selected edges of this PPathClosed object. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be included in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • nEdges The number of edges to be included, starting with edge nStart and proceeding along the reference direction. Must be in the range 0 to k. • Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting open path.
8.16. CLASS PPATHCLOSED
public: bool PPathClosed::CreateOpenpathWithoutEdges(int nEdges, PPathOpen & Result)
301
nStart,
int
Creates a PPathOpen object that contains all the edges of this path except those identified in a given list. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be excluded in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • nEdges The number of edges to be excluded, starting with edge nStart and proceeding along the reference direction. Must be in the range 0 to k. • Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting open path.
302
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool PPathClosed::FindOverlappingPath(const PPathClosed & other, PPathOpen & overlap, PPathOpen & restofthis, PPathOpen & restofother) Determines if this path and another given path share a connected path of edges. If they do, finds the overlapping path, the rest of this path, and the rest of the other path, and returns true. If they don’t, or if there is more than one shared path, or if all edges are shared, returns false. Return A boolean value that contains true if execution was successful, or false if not. Arguments • other path.
A reference to a constant PPathClosed object that contains the given closed
• overlap A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the overlapping path. • restofthis A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the rest of this path. • restofother A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the rest of the given path.
public: bool PPathClosed::GetMidPath(int nStart, PPathOpen & Result) Creates an open path that contains all edges of this path between a given position and the head of this path, taken in the reference direction. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be included in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting path.
8.16. CLASS PPATHCLOSED
public: bool PPathClosed::GetMidPath(int PPathOpen & Result)
303
nStart,
int
nEdges,
Creates an open path that contains a given number of edges from this path, starting at a given position and proceeding in the reference direction. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be included in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • nEdges
The number of edges to be included in the resulting open path.
• Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting path.
public: bool PPathClosed::IsClosed() Returns a boolean value indicating if this path is closed or not. Since this path is closed, this method always returns true . It is not possible to store an open path in a PPathClosed object. Return A boolean value that contains true .
public: void PPathClosed::ReverseMe() Reverses the reference direction of this path.
304
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void PPathClosed::RotateMe(int nSteps) Performs a circular rotation of the list of edges by the specified number of steps. The rotation takes place counterclockwise if a positive number of steps is specified, or clockwise if the number of steps is negative. Arguments • nSteps
An integer number containing the number of steps for the rotation.
public: bool PPathClosed::Verify() Verifies the consistency and correctness of this PPathClosed object. Return A boolean containing the value true if this object is consistent and correct, or false if it is not.
8.17
Class PPathOpen PPath PPathOpen
A parameterized base class that describes a connected open path in a mathematical undirected graph. The path is undirected, and can be traversed in either direction. The class uses the template as part of the class definition and the definitions of all methods.
Constructor Summary public: public: public: virtual
PPathOpen(const PPathOpen & other) Public copy constructor. PPathOpen() Public default constructor. ∼PPathOpen() Virtual destructor.
8.17. CLASS PPATHOPEN
305
Method Summary public: int public: int public: void public: int public: int public: const EDGE * public: bool public: const VERTEX * public: bool public: bool
AppendEdge(EDGE * edge) Appends the given edge to this open path. AppendPath(const PPathOpen & other) Appends the given open path to this open path. Copy(const PPathOpen & other) Makes an identical copy of a given open path. CountOverlappingHeadEdges(const PPathOpen & other) Counts overlapping edges sequentially starting from the head. CountOverlappingTailEdges(const PPathOpen & other) Counts overlapping edges sequentially starting from the tail. GetHeadEdge() Returns the head edge of this open path. GetHeadPath(int nEdges, PPathOpen & Result) Creates an open path with a given number of edges counting from the head of this path. GetHeadVertex() Returns the head vertex of this open path. GetMidPath(int nStart, PPathOpen & Result) Creates an open path that contains all edges of this path between a given position and the head of this path. GetMidPath(int nStart, int nEdges, PPathOpen & Result) Creates an open path that contains a given number of edges from this path, starting at a given position.
306
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary (continued) public: const EDGE * public: bool public: const VERTEX * public: bool public: int public: int public: void public: bool
8.17.1
public: other)
GetTailEdge() Returns the tail edge of this open path. GetTailPath(int nEdges, PPathOpen & Result) Creates an open path with a given number of edges counting from the tail of this path. GetTailVertex() Returns the tail vertex of this open path. IsClosed() Returns true if this path is open, or false if this is a closed path stored in this PPathOpen object. PrependEdge(EDGE * edge) Prepends the given edge to this open path. PrependPath(const PPathOpen & other) Prepends the given open path to this open path. ReverseMe() Reverses the reference direction of this path. Verify() Verifies the consistency and correctness of this path.
PPathOpen Constructor Detail
PPathOpen::PPathOpen(const PPathOpen &
Public copy constructor. It constructs this object with all the edges of a given open path, and the same reference direction. Arguments • other
A reference to the given PPathOpen object.
public: PPathOpen::PPathOpen() Public default constructor. It constructs an empty object.
8.17. CLASS PPATHOPEN
307
public: virtual PPathOpen::∼PPathOpen() Virtual destructor.
8.17.2
PPathOpen Method Detail
public: int PPathOpen::AppendEdge(EDGE * edge) Appends the given edge to the head of this open path. The edge is appended only if one of its vertices is the head vertex of the path, and the other vertex does not belong to the path. Return The integer total number of edges of the path after the new edge was appended, or -1 if the new edge was not appended. Arguments • edge
A pointer to an EDGE object that contains the edge to be appended.
public: int PPathOpen::AppendPath(const PPathOpen & other) Appends the given open path to the head of this open path. The path is appended only if its tail vertex is the head vertex of this path, and none of the other vertices belong to this path. Return The integer total number of edges of this path after the new path was appended. Arguments • other A reference to a constant PPathOpen object that contains the open path to be appended.
308
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void PPathOpen::Copy(const PPathOpen & other) Makes an identical copy of the given path. Arguments • other copied.
A reference to a constant PPathOpen object that contains the open path to be
public: int PPathOpen::CountOverlappingHeadEdges(const PPathOpen & other) Counts overlapping edges sequentially starting from the head. Return Compares this path and another given open path and counts overlapping edges sequentially starting from the head. Arguments • other A reference to a constant PPathOpen object containing the open path that is to be compared with this open path.
public: int PPathOpen::CountOverlappingTailEdges(const PPathOpen & other) Compares this path and another given open path and counts overlapping edges sequentially starting from the tail. Return The number of overlapping edges. Arguments • other A reference to a constant PPathOpen object containing the open path that is to be compared with this open path.
8.17. CLASS PPATHOPEN
309
public: const EDGE * PPathOpen::GetHeadEdge() Returns a pointer to the head edge of this open path. Return A pointer to a constant EDGE object that contains the head edge of this open path.
public: bool PPathOpen::GetHeadPath(int nEdges, PPathOpen & Result) Creates an open path with a given number of edges counting from the head of this path. The new path has the same reference direction as this path. Return A boolean value containing true if execution was successful, or false if not. Arguments • nEdges
The number of edges to be included in the resulting path.
• Result ing path.
A reference to a PPathOpen object, which, upon return, will contain the result-
public: const VERTEX * PPathOpen::GetHeadVertex() Returns a pointer to the head vertex of this open path. Return A pointer to a constant VERTEX object that contains the head vertex of this open path.
310
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: bool PPathOpen::GetMidPath(int nStart, EDGE> & Result)
PPathOpen
Creates an open path that contains all edges of this path between a given position and the head of this path, taken in the reference direction. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be included in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting path.
public: bool PPathOpen::GetMidPath(int PPathOpen & Result)
nStart,
int
nEdges,
Creates an open path that contains a given number of edges from this path, starting at a given position and proceeding in the reference direction. Return A boolean value that contains true if execution was successful, or false if not. Arguments • nStart The 0-based integer local index of the initial edge of this path to be included in the resulting open path, in the range 0 to k − 1, where k is the length of this path. • nEdges
The number of edges to be included in the resulting open path.
• Result A reference to a PPathOpen object, which, upon return and if execution was successful, will contain the resulting path.
public: const EDGE * PPathOpen::GetTailEdge() Returns a pointer to the tail edge of this open path. Return A pointer to a constant EDGE object that contains the tail edge of this open path.
8.17. CLASS PPATHOPEN
311
public: bool PPathOpen::GetTailPath(int nEdges, PPathOpen & Result) Creates an open path with a given number of edges counting from the tail of this path. The new path has the same reference direction as this path. Return A boolean value containing true if execution was successful, or false if not. Arguments • nEdges
The number of edges to be included in the resulting path.
• Result ing path.
A reference to a PPathOpen object, which, upon return, will contain the result-
public: const VERTEX * PPathOpen::GetTailVertex() Returns a pointer to the tail vertex of this open path. Return A pointer to a constant VERTEX object that contains the tail vertex of this open path.
public: bool PPathOpen::IsClosed() Returns true if this path is actually open. However, it is possible to store a closed path in this PPathOpen object. In this case, the head vertex and the tail vertex of the closed path are the same, and this method will return false . Return Returns a boolean with the value true if this path is actually open, or false if this is a closed path stored in this PPathOpen object.
312
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: int PPathOpen::PrependEdge(EDGE * edge) Appends the given edge to the tail of this open path. The edge is appended only if one of its vertices is the tail vertex of the path, and the other vertex does not belong to the path. Return The integer total number of edges of the path after the new edge was prepended, or -1 if the new edge was not prepended. Arguments • edge
A pointer to an EDGE object that contains the edge to be prepended.
public: int PPathOpen::PrependPath(const PPathOpen & other) Appends the given open path to the tail of this open path. The given path is appended only if its head vertex is the tail vertex of this path, and none of the other vertices belong to this path. Return The integer total number of edges of this path after the new path was appended. Arguments • other A reference to a constant PPathOpen object that contains the open path to be appended.
public: void PPathOpen::ReverseMe() Reverses the reference direction of this path.
public: bool PPathOpen::Verify() Verifies the consistency and correctness of this PPathOpen object. Return A boolean containing the value true if this object is consistent and correct, or false if it is not.
8.18. CLASS PVERTEX
8.18
313
Class PVertex
A parameterized base class that describes a vertex of a mathematical graph. The class uses the template as part of the class definition and the definitions of all methods.
Attribute Summary public: int protected: PArray<EDGE *> protected: int protected: int protected: int
VTag An integer tag accessible to the user. m pIncidentEdges An array that contains pointers to all edges incident to this vertex MyGraphIndex The graph index of this vertex. MyDegree The degree of this vertex. MyComponent The index of the connected component where this vertex belongs.
Constructor Summary public: public: virtual
PVertex() Public constructor. ∼PVertex() Public destructor.
314
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
Method Summary public: int public: int public: EDGE * public: EDGE * public: int public: int public: Str public: void public: void
8.18.1
AddIncidentEdge(EDGE * edge) Adds the given edge to the list of edges incident to this vertex. GetDegree() Returns the degree of this vertex. GetEdgeToVertex(const PVertex * other) Finds the edge that connects this vertex with another given vertex. GetIncidentEdge(int localEdgeIndex) Given the index of an incident edge, returns a pointer to the edge. GetMyComponent() Returns the index of the connected component where this vertex belongs. GetMyGraphIndex() Returns the index of this vertex in the graph. ReportVertex() Creates a report describing this vertex. SetMyComponent(int component) Sets the connected component index for this vertex to the given value. SetMyGraphIndex(int graphIndex) Sets the graph index for this vertex to the given value.
PVertex Attribute Detail
public: int VTag An integer tag accessible to the user. The tag provides a storage location associated with this object where the user can store and retrieve any integer value.
protected: PArray<EDGE *> m pIncidentEdges A PArray <EDGE *> object with pointers to all the EDGE objects that describe the edges incident to this vertex.
8.18. CLASS PVERTEX
315
protected: int MyGraphIndex The graph index of this vertex. This value is determine at the time when the vertex is added to the graph.
protected: int MyDegree The degree of this vertex, or number of edges incident to it.
protected: int MyComponent The index of the connected component where this vertex belongs.
8.18.2
PVertex Constructor Detail
public: PVertex::PVertex() Public constructor. It constructs a PVertex object with degree 0 and undefined graph index and connected component index.
public: virtual PVertex::∼PVertex() Public destructor. It destroys this VERTEX object.
316
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
8.18.3
PVertex Method Detail
public: int PVertex::AddIncidentEdge(EDGE * edge) Adds the given edge to the list of edges incident to this vertex. An error occurrs if an attempt is made to add an edge which is already present in the list. Return Returns the degree of this vertex after the addition. Arguments • edge vertex.
A pointer to the EDGE object that is to be added as an incident edge for this
public: int PVertex::GetDegree() Returns the integer degree of this vertex. Return An integer equal to the degree of this vertex.
public: EDGE * PVertex::GetEdgeToVertex(const PVertex * other) Finds the edge that connects this vertex with another given vertex. Return A pointer to an EDGE object that contains the edge connecting this vertex to the other given vertex. Returns NULL if such an edge does not exist. Arguments • other
A pointer to a constant PVertex object that contains the other vertex of interest.
8.18. CLASS PVERTEX
317
public: EDGE * PVertex::GetIncidentEdge(int localEdgeIndex) Given the index of an incident edge, returns a pointer to the EDGE object that contains the edge with that index. Return A pointer to the EDGE object that contains the edge with the given index. Arguments • localEdgeIndex The 0-based index of the incident edge of interest, in the range 0 to n − 1, where n is the number of incident edges for this vertex. This index refers to the local internal list of incident edges of this vertex, and is different from the index of the edge in the graph.
public: int PVertex::GetMyComponent() Returns the index of the connected component where this vertex belongs. Return The integer index of the connected component where this vertex belongs, in the range 0 to k − 1, where k is the number of connected components in the graph.
public: int PVertex::GetMyGraphIndex() Returns the index of this vertex in the graph. This index is defined only after the vertex has been added to the graph in the course of the creation process. Return The integer value of the index of this vertex in the graph.
public: Str PVertex::ReportVertex() Creates a report describing properties of this vertex such as its degree, the index of its connected component, and the list of indices of its incident edges. Return An Str object that contains the resulting report.
318
CHAPTER 8. FAMILY OF CLASSES: GRAPHS
public: void PVertex::SetMyComponent(int component) Sets the connected component index for this vertex to the given value. Arguments • component longs.
The given integer value of the connected component where this vertex be-
public: void PVertex::SetMyGraphIndex(int graphIndex) Sets the graph index for this vertex to the given value. Arguments • graphIndex The given integer value of the index of this vertex in the graph, range 0 to n − 1, where n is the current number of vertices in the graph.
Chapter 9 Family of Classes: Mechanical Services for rigid bodies, inertia, collisions and visual display.
9.1
All Mechanical Classes
Class name Body BodyManager
9.2
Description A Body is an entity that has size, shape and position and can be treated as a whole. This class owns and manages all Body objects in a mechanical system.
Class Body
A Body is an entity that has size, shape and position and can be treated as a whole. A Body can move, change its shape, and collide with other Body objects. It can have inertial properties and experience external actions such as forces. A Body ’s shape can be visualized in a display. Yet a Body is indivisible. If it breaks apart, it ceases to exist, and each piece in turn becomes a new independent Body. A rigid body, in the traditional sense used in Physics, meets the definition. A deformable body does too. A simulated figure such as a cartoon character, a model, any object used in animation, can also be considered and treated as a Body . A Body does not necessarily has to have all of the properties above. An animated character does not need to have inertia. It can still move and have a shape and change its shape under the control of the computer. There is no implication that a Body has to consist of matter or obey the laws of Physics. A Body object is said to be inertial if it obeys Newton’s laws. An inertial Body has mass, and its state of motion can be modified only in response to externally applied actions such as forces, torques or collisions. The computer simulation controls the external actions, but does not exercise direct control over the motion, which is determined by the mathematical solution of the equations of motion. In contrast,
319
320
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
the motion of a non-inertial Body object is under the direct control of the computer program, and the user can control it in a variety of ways. Hybrid cases are not considered here, but can be implemented if needed. The properties and behavior of Body objects are of a complex nature, and are stored in separate objects owned by the Body . Some of the objects are entire families of classes. They are: • class Collider and its derived classes, which deal with collisions between Body objects and have collision-detection capabilities; • class Inertia and its derived classes, which deal with the inertial properties of Body objects and provide services to the dynamic equations of motion; • class Outline and its derived classes, which deal with the visual display of Body objects, and • class ExternalAction , which deals with forces and torques applied to Body objects and their time dependence and points of application. All properties are optional, although Body objects usually have an Outline object, which is required for display. A non-inertial body does not have an inertia object. NamedPoints are optional points defined and named by the user in the local coordinate system. After they have been defined, the user can refer to them by name. They serve many purposes, such as assembling or moving the Body , defining constraints, and others.
9.2. CLASS BODY
321
Attribute Summary protected: CSVertex * protected: CSVertex * protected: int protected: PArray protected: PArray<Str> protected: Str protected: const CSState * protected: Outline * protected: Inertia * protected: ExternalAction * protected: Collider * protected: CSEdge * protected: BCVertex * protected: int
VertexL The local coordinate system for this Body . VertexG The global coordinate system for this Body . NumberDOF The number of degrees of freedom for this object. NamedPointPositions An array containing the positions of all the NamedPoints defined by the user. NamedPointNames An array containing the names of all the NamedPoints defined by the user. m szName The name of this Body object. m pState The kinematic state of the local coordinate system relative to the global system m pOutline The Outline object owned by this Body . m pInertia The Inertia object owned by this Body . m pExternalAction The ExternalAction object owned by this Body . m pCollider The Collider object owned by this Body . EdgeGL The edge in the coordinate system graph that connects the global coordinate system and the local coordinate system. BodyVertex The vertex in the bodies and constraints graph corresponding to this Body . BodyIndex The global index of this Body object.
322
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
Constructor Summary public: public: virtual
Body(CSGraph * graph) Public constructor. ∼Body() Public destructor.
Method Summary public: bool public: Str public: Str public: const CSVector * public: int public: BCVertex * public: Collider * public: Str public: CSEdge * public: ExternalAction * public: const CSVector & public: const CSVector & public: const OrthoMatrix &
CreateBodyFromScript(const CStr & script) Creates this body using data contained in a script provided by the user. DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of a given specific coordinate. DescribeMeaningOfSpecors() Creates a report describing the meaning of all specific coordinates. FindNamedPoint(const CStr & pointName) Finds a Named Point by name. GetBodyIndex() Returns the global index of this body. GetBodyVertex() Returns a pointer to the vertex in the bodies and constraints graph that is associated with this body. GetCollider() Returns a pointer to the Collider object owned by this body. GetDescription() Creates a report with a description of this body. GetEdgeGL() Returns a pointer to the global-to-local edge of this body. GetExternalAction() Returns a pointer to the ExternalAction object owned by this body. GetGlobalCMPosition() Returns the position of the origin of the local coordinate system for this body. GetGlobalCMVelocity() Returns the velocity of the origin of the local coordinate system for this body. GetGlobalOrientation() Returns the orientation matrix for the local coordinate system.
9.2. CLASS BODY
323
Method Summary (continued) public: void public: void public: const Inertia * public: const CSVertex * public: void public: const Str & public: int public: int public: int public: int public: const Orientator * public: const Outline * public: const CSState * public: const Translator * protected: bool protected: bool protected: bool
GetGlobalPositionOfLocalPoint(const CSVector & localPointoint, CSVector & globalPoint) Converts a radius vector from local coordinates to global coordinates. GetGlobalVelocityOfLocalPoint(const CSVector & localPoint, CSVector & globalVelocity) Calculates the global velocity of a given local point. GetInertia() Returns a pointer to the Inertia object of this body. GetLocalCSVertex() Returns a pointer to the local coordinate system for this body. GetLocalPositionOfGlobalPoint(const CSVector & globalPoint, CSVector & localPoint) Calculates the local position of a global point. GetName() Returns the name of this body. GetNbrDOF() Returns the number of degrees of freedom of this body. GetNbrRotationalSpecors() Returns the number of rotational specific coordinates. GetNbrTranslationalSpecors() Returns the number of translational specific coordinates. GetNumberSpecors() Returns the number of specific coordinates. GetOrientator() Returns a pointer to the Orientator object of this body. GetOutline() Returns a pointer to the Outline object of this body. GetState() Returns a pointer to the kinematic state of this body. GetTranslator() Returns a pointer to the Translator object of this body. InterpretCollider(const CStr & script) Creates a Collider object for this body using data contained in a script provided by the user. InterpretInertia(const CStr & script) Creates an Inertia object for this body using data contained in a script provided by the user. InterpretOutline(const CStr & script) Creates an Outline object for this body using data contained in a script provided by the user.
324
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
Method Summary (continued) public: bool public: void public: bool public: bool
9.2.1
IsInertial() Verifies if this body is inertial or not. SetBodyIndex(int bodyIndex) Sets the global index for this body. SetName(const CStr & name) Sets the name for this body. SetName(const Str & name) Sets the name for this body.
Body Attribute Detail
protected: CSVertex * VertexL A pointer to a CSVertex object that contains the local coordinate system for this Body . In general, there are no particular rules for defining this coordinate system. However, if the Body is rigid and has inertial properties, it is best to take the coordinate system with its origin at the center of mass and with its axes aligned with the principal axes of inertia. Such a selection results in a simplification of the equations of motion.
protected: CSVertex * VertexG A pointer to a CSVertex object that contains the global coordinate system.
protected: int NumberDOF The number of degrees of freedom for this object. This is 6 for a rigid body, but it can be a large number for a deformable one.
protected: PArray NamedPointPositions A PArray of CSVector objects containing the positions of all the NamedPoints defined by the user.
9.2. CLASS BODY
325
protected: PArray<Str> NamedPointNames A PArray of Str objects containing the names of all the NamedPoints defined by the user.
protected: Str m szName An Str object containing the user-defined name of this Body object.
protected: const CSState * m pState A pointer to a constant CSState object that contains the kinematic state of the local coordinate system relative to the global system.
protected: Outline * m pOutline A pointer to the Outline object owned by this Body . A value of NULL is allowed, in which case the Body can not be shown on a display.
protected: Inertia * m pInertia A pointer to the Outline object owned by this Body . A value of NULL is allowed, in which case the Body has no inertial properties such as mass or moments of inertia, and can not experience applied forces.
protected: ExternalAction * m pExternalAction A pointer to the ExternalAction object owned by this Body . A value of NULL is allowed, in which case no forces or torques are applied to this Body
326
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
protected: Collider * m pCollider A pointer to the Collider object owned by this Body . A value of NULL is allowed, in which case the Body will not be impenetrable.
protected: CSEdge * EdgeGL A pointer to a CSEdge object that contains the edge in the coordinate system graph that connects the global coordinate system VertexG and the local coordinate system VertexL . The CSEdge object is owned by the graph.
protected: BCVertex * BodyVertex A pointer to a BCVertex object that contains the vertex in the bodies and constraints graph corresponding to this Body . The BCVertex object is owned by the graph.
protected: int BodyIndex The global index of this Body object. Many Body objects are involved in a multibody problem. They are sequentially numbered at the time they are constructed, and each Body is informed of the index assigned to it.
9.2. CLASS BODY
9.2.2
327
Body Constructor Detail
public: Body::Body(CSGraph * graph) Public constructor. It constructs a Body object with a coordinate system but without any other properties. Arguments • graph A pointer to a CSGraph object that contains the coordinate system graph for this problem.
public: virtual Body::∼Body() Public destructor. It destroys this object, as well as the NamedPoint objects and the Collider , Inertia , Outline and ExternalAction objects that may be owned by this body.
9.2.3
Body Method Detail
public: bool Body::CreateBodyFromScript(const CStr & script) Creates this Body object using data contained in a script written in Articulated Robot Simulation Language (ARSL) and provided by the user. Return true if creation of this Body object was successful, false if not. Arguments • script A reference to a constant CStr object that contains the ARSL script provided by the user.
328
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: Str Body::DescribeMeaningOfOneSpecor(int specor) Creates a report describing the meaning of a given specific coordinate. Return A Str containing the resulting report. Arguments • specor The integer 0-based index of the specific coordinate of interest. Translational specific coordinates are numbered first, rotational specific coordinates are numbered last.
public: Str Body::DescribeMeaningOfSpecors() Creates a report describing the meaning of all specific coordinates. Return A Str object containing the resulting report.
public: const CSVector * Body::FindNamedPoint(const CStr & pointName) Finds a Named Point by name. Return A pointer to the constant radius vector rLP,L , where L is the local coordinate system and P is the point. Arguments • pointName of interest.
A reference to a constant CStr object that contains the name of the point
public: int Body::GetBodyIndex() Returns the 0-based global index of this Body object. Return The integer 0-based global index of this Body object.
9.2. CLASS BODY
329
public: BCVertex * Body::GetBodyVertex() Returns a pointer to the vertex in the bodies and constraints graph that is associated with this Body object. Return A pointer to the vertex in the bodies and constraints graph that is associated with this Body object.
public: Collider * Body::GetCollider() Returns a pointer to the Collider object owned by this Body object, or NULL if this body does not own a Collider object. Return A pointer to the Collider object owned by this Body object, or NULL if this body does not own a Collider object.
public: Str Body::GetDescription() Creates a report with a description of this Body object. Return A Str object with the resulting report.
public: CSEdge * Body::GetEdgeGL() Returns a pointer to the GL edge of this Body object. The GL edge connects the global coordinate system G with this Body ’s local coordinate system L. Return A pointer to a CSEdge object that contains edge GL for this body.
330
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: ExternalAction * Body::GetExternalAction() Returns a pointer to the ExternalAction object owned by this Body object, or NULL if this Body object does not own an ExternalAction object. Return A pointer to the ExternalAction object, or NULL if this body does not own a ExternalAction object.
public: const CSVector & Body::GetGlobalCMPosition() Returns the position of the origin of the local coordinate system for this Body object, relative to the global system and expressed in global coordinates. Return A reference to a constant CSVector object that contains the resulting radius vector.
public: const CSVector & Body::GetGlobalCMVelocity() Returns the velocity of the origin of the local coordinate system for this Body object, relative to the global system and expressed in global coordinates. Return A reference to a constant CSVector object that contains the resulting velocity.
public: const OrthoMatrix & Body::GetGlobalOrientation() Returns the orientation matrix for the local coordinate system. Return A reference to an OrthoMatrix object that contains the resulting orientation matrix.
9.2. CLASS BODY
331
public: void Body::GetGlobalPositionOfLocalPoint(const CSVector & localPointoint, CSVector & globalPoint) Converts a radius vector from local coordinates to global coordinates. Arguments • localPointoint A reference to a constant CSVector object that contains the given radius vector expressed in local coordinates. • globalPoint A reference to a CSVector object, which, upon return, will contain the value of the same radius vector, expressed in global coordinates.
public: void Body::GetGlobalVelocityOfLocalPoint(const CSVector & localPoint, CSVector & globalVelocity) The position of a point P is defined by the given radius vector rLP,L from the local origin L to the point P, expressed in local coordinates. This method calculates vGP,G , the velocity of point P relative to the global system, expressed in global coordinates. Point P is attached to this body and moving with it. Arguments • localPoint A reference to a constant CSVector object that contains the radius vector rLP,L from the local origin L to the given point P, expressed in local coordinates. • globalVelocity A reference to a CSVector object, which, upon return, will contain the resulting velocity vGP,G of point P relative to the global system, expressed in global coordinates.
public: const Inertia * Body::GetInertia() Returns a pointer to the Inertia object of this Body object, or NULL if this Body does not own an Inertia object. Return A pointer to the Inertia object owned by this Body object, or NULL if this Body does not own an Inertia object.
332
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: const CSVertex * Body::GetLocalCSVertex() Returns a pointer to the local coordinate system for this Body object. Return A pointer to a constant CSVertex object that contains the local coordinate system for this Body object.
public: void Body::GetLocalPositionOfGlobalPoint(const CSVector & globalPoint, CSVector & localPoint) The position of a point P is defined by the given radius vector rGP,G from the global origin G to the point P, expressed in global coordinates. This method calculates rLP,L , the position of point P relative to the local system L, expressed in local coordinates. Arguments • globalPoint A reference to a constant CSVector object that contains the radius vector rGP,G from the global origin G to the given point P, expressed in global coordinates. • localPoint A reference to a CSVector object, which, upon return, will contain the resulting position rLP,L of point P relative to the local system, expressed in local coordinates.
public: const Str & Body::GetName() Returns the name of this Body object. Return A reference to a constant Str object that contains the name of this Body object.
public: int Body::GetNbrDOF() Returns the number of degrees of freedom of this Body object. Return The integer number of degrees of freedom of this Body object.
9.2. CLASS BODY
333
public: int Body::GetNbrRotationalSpecors() Returns the number of rotational specific coordinates. Return The integer number of rotational specific coordinates.
public: int Body::GetNbrTranslationalSpecors() Returns the number of translational specific coordinates. Return The integer number of translational specific coordinates.
public: int Body::GetNumberSpecors() Returns the number of specific coordinates. Return The integer number of specific coordinates.
public: const Orientator * Body::GetOrientator() Returns a pointer to the Orientator object of this Body object, or NULL if this body does not own an Orientator object. Return A pointer to the constant Orientator object owned by this Body object, or NULL if this body does not own an Orientator object.
public: const Outline * Body::GetOutline() Returns a pointer to the Outline object of this Body object, or NULL if this body does not own an Outline object. Return A pointer to the Outline object owned by this Body object, or NULL if this body does not own an Outline object.
334
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: const CSState * Body::GetState() Returns a pointer to the kinematic state of this Body object. Return Returns a pointer to a constant CSState object that contains the kinematic state of this Body object.
public: const Translator * Body::GetTranslator() Returns a pointer to the Translator object of this Body object, or NULL if this body does not own an Translator object. Return A pointer to the constant Translator object owned by this Body object, or NULL if this body does not own an Translator object.
protected: bool Body::InterpretCollider(const CStr & script) Creates a Collider object for this Body object using data contained in a script written in Articulated Robot Simulation Language (ARSL) and provided by the user. Return true if creation of the Collider object was successful, false if not. Arguments • script A reference to a constant CStr object that contains the ARSL script provided by the user.
9.2. CLASS BODY
335
protected: bool Body::InterpretInertia(const CStr & script) Creates an Inertia object for this Body object using data contained in a script written in Articulated Robot Simulation Language (ARSL) and provided by the user. Return true if creation of the Inertia object was successful, false if not. Arguments • script A reference to a constant CStr object that contains the ARSL script provided by the user.
protected: bool Body::InterpretOutline(const CStr & script) Creates an Outline object for this Body object using data contained in a script written in Articulated Robot Simulation Language (ARSL) and provided by the user. Return true if creation of the Outline object was successful, false if not. Arguments • script A reference to a constant CStr object that contains the ARSL script provided by the user.
public: bool Body::IsInertial() Verifies if this Body object is inertial or not. Return true if this Body object is inertial, false otherwise.
336
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: void Body::SetBodyIndex(int bodyIndex) Sets the global index for this Body object. This method is intended for use by the BodyManager class only. Arguments • bodyIndex
The new value for the global index for this body.
public: bool Body::SetName(const CStr & name) Sets the name for this Body object. Return true if the name has been successfully set, false otherwise. Arguments • name
A reference to a constant CStr object that contains the new name for this body.
public: bool Body::SetName(const Str & name) Sets the name for this Body object. Return true if the name has been successfully set, false otherwise. Arguments • name
A reference to a constant Str object that contains the new name for this body.
9.3. CLASS BODYMANAGER
9.3
337
Class BodyManager
This class owns and manages all Body objects for a multi-body system.
Attribute Summary protected: const CSVertex * protected: Body * protected: int protected: PArray
VertexG A pointer to the global coordinate system. m pReferenceBody For some applications, a special body called the reference body can be designated by setting this pointer. m NumberBodies The total number of bodies in the system. AllBodies The set of all bodies in the system.
Constructor Summary public: public: virtual
BodyManager(const CSVertex * vertexG) Public constructor. ∼BodyManager() Public destructor.
338
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
Method Summary public: void public: bool public: Str public: Body * public: Body * public: CSEdge * public: Body * public: int public: int public: int public: Body * public: int public: int public: void
AddBody(Body * body) Adds a new body to the system. AssembleStructureFromScript(const CStr & script) Arranges the positions of bodies according to instructions in a script provided by the user. DescribeMeaningOfAllSpecors() Creates a report describing the meaning of all specific coordinates. GetBodyWithIndex(int globalIndex) Returns the body with a given global index. GetBodyWithName(const CStr & bodyName) Returns the body with a given name. GetCSEdgeWithBodyIndex(int globalIndex) Returns the global-to-local edge for a body identified by a global index. GetHeaviestInertialBody() Selects the heaviest body from among all inertial bodies and returns its pointer. GetNumberBodies() Returns the total number of bodies in the system. GetNumberInertialBodies() Returns the total number of inertial bodies in the system. GetNumberNoninertialBodies() Returns the total number of non-inertial bodies in the system. GetReferenceBody() Returns a pointer to the reference body. GetTotalNbrBodyDOF() Returns the total number of degrees of freedom of all bodies in the system. GetTotalNbrInertialDOF() Returns the total number of degrees of freedom of all inertial bodies in the system. SetReferenceBody(Body * refBody) Designates a body as the reference body.
9.3. CLASS BODYMANAGER
9.3.1
339
BodyManager Attribute Detail
protected: const CSVertex * VertexG A pointer to a constant CSVertex object that contains the global coordinate system.
protected: Body * m pReferenceBody For some applications, a special body called the reference body can be designated by setting this pointer. A example is the root of a tree in the bodies and constraints graph.
protected: int m NumberBodies The total number of Body objects in the mechanical system.
protected: PArray AllBodies A PArray object that contains the pointers to all Body objects in the mechanical system.
9.3.2
BodyManager Constructor Detail
public: BodyManager::BodyManager(const CSVertex * vertexG) Public constructor. It constructs this object with no bodies. Arguments • vertexG system.
A pointer to a constant CSVertex object that contains the global coordinate
340
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: virtual BodyManager::∼BodyManager() Public destructor.
9.3.3
BodyManager Method Detail
public: void BodyManager::AddBody(Body * body) Adds a new Body object to the mechanical system. Arguments • body
public: bool BodyManager::AssembleStructureFromScript(const CStr & script) Initially, all Body objects are created and placed at default positions and orientations relative to the global coordinate system. This method assembles the mechanical structure by displacing or rotating the Body objects as instructed by a script written in Articulated Figure Description Language (AFDL) and provided by the user. Return true if execution of the script has been successful, false if not. Arguments • script user.
A reference to a constant CStr object that contains the script provided by the
public: Str BodyManager::DescribeMeaningOfAllSpecors() Creates a report describing the meaning of all specific coordinates. Return An Str object containing the resulting report.
9.3. CLASS BODYMANAGER
341
public: Body * BodyManager::GetBodyWithIndex(int globalIndex) Returns a pointer to the Body with a given global index. Return A pointer to the Body with a given global index. Arguments • globalIndex
The integer global index of the Body of interest.
public: Body * BodyManager::GetBodyWithName(const CStr & bodyName) Returns a pointer to the Body with the given name. Return A pointer to the Body with a given name. Arguments • bodyName
A reference to a CStr object that contains the name for the body of interest.
public: CSEdge * BodyManager::GetCSEdgeWithBodyIndex(int globalIndex) Returns the global-to-local edge in the coordinate system graph for a Body object identified by a global index. Return A pointer to a CSEdge object containing the resulting edge. Arguments • globalIndex
The integer global index of the Body object of interest.
public: Body * BodyManager::GetHeaviestInertialBody() Selects the heaviest Body object from among all inertial bodies and returns its pointer. Return A pointer to the heaviest Body object selected from among all inertial bodies.
342
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
public: int BodyManager::GetNumberBodies() Returns the total number of Body objects in the system. Return The total number of Body objects in the system.
public: int BodyManager::GetNumberInertialBodies() Returns the total number of inertial bodies in the system. Return The total number of inertial bodies in the system.
public: int BodyManager::GetNumberNoninertialBodies() Returns the total number of non-inertial bodies in the system. Return The total number of non-inertial bodies in the system.
public: Body * BodyManager::GetReferenceBody() For some applications, a special body called the reference body can be designated by setting this pointer. This method returns a pointer to the reference body. Return A pointer to a Body object that contains the reference body.
public: int BodyManager::GetTotalNbrBodyDOF() Returns the total number of degrees of freedom of all Body objects in the system. Return The total integer number of degrees of freedom of all bodies in the system.
9.3. CLASS BODYMANAGER
343
public: int BodyManager::GetTotalNbrInertialDOF() Returns the total number of degrees of freedom of all inertial bodies in the system. Return The total number of degrees of freedom of all inertial bodies in the system.
public: void BodyManager::SetReferenceBody(Body * refBody) For some applications, a special body called the reference body can be designated by the user. This method designates the reference body. Arguments • refBody ence.
A pointer to a Body object that contains the body to be designated as refer-
344
CHAPTER 9. FAMILY OF CLASSES: MECHANICAL
Bibliography [1] Brian W. Kernighan, Dennis M. Ritchie. The C Programming Language, 2nd edition, Prentice Hall, Englewood Cliffs, New Jersey, USA, 1988. [2] Microsoft Visual C++ Language Reference. Microsoft Press, 1997 or later. [3] Sergio Pissanetzky. Sparse Matrix Technology, Academic Press, London, 1984. Russian translation published by Mir, Moscow, 1988. [4] Ira Pohl. Object-Oriented Programming Using C++, The Benjamin Cummings Publishing Company, Redwood City, California, USA, 1993. [5] Sergio Pissanetzky. KUBIK: a three-dimensional finite element mesh generator. User’s manual. Computer Phys. Comm., Vol. 32, pp. 267-279, 1984. [6] Angelo Ferrari and Sergio Pissanetzky. Recent extensions of the program MAGNUS-3D for Three-dimensional Accelerator Magnetic Engineering. European Particle Accelerator Conference. Roma, Italy, June 7-11, 1988. Proceedings, pp. 1315-1317. [7] Mingwu Fan and Sergio Pissanetzky. Three-dimensional Magnetic Engineering: the programs MAGNUS and EPILOG. Nuclear Instruments and Methods in Physics Research, Vol. A272, pp. 606-609 (1988). [8] J. H. Wilkinson. The Algebraic Eigenvalue Problem. Clarendon Press, Oxford, 1965. [9] A L´opez D´avalos, D. Zanette (with software by S. Pissanetzky). Fundamentals of Electromagnetism. Vacuum Electrodynamics, Media and Relativity, Springer-Verlag, Berlin, Heidelberg, New York, 1999. [10] G. W. Stewart. Introduction to Matrix Computations, Academic Press, New York, 1973. [11] R. S. Martin and J. H. Wilkinson. Symmetric decomposition of positive definite band matrices, Numer. Math. Vol. 7, pp. 355-361, 1965. ¨ [12] S. Gerschgorin. Uber die Abgrenzung der Eigenwerte einer Matrix, Izv. Akad. Nauk SSSR, Ser. fiz. mat., Vol 6, pp. 749-754, 1931.
345
346
BIBLIOGRAPHY
[13] H. Goldstein. Classical Mechanics, Addison-Wesley, Reading, Massachusetts. [14] A. A. Shabana. Dynamics of Multibody Systems, second edition, Cambridge University Press, 1998. [15] D. J. Rose, R. E. Tarjan, G. S. Lueker. Algorithmic aspects of vertex elimination on graphs, SIAM J. Comput, Vol. 5, pp. 266-283, 1976.
Index Acceleration angular, 36 Accelerations specific, 39, 45 Addition of kinematic states, 51 Adjacency level structures, 21 Angular acceleration, 36 Angular motion, 33 Angular velocity, 9, 36 Axial rotator, 69 Euler parameters, 66 ZXZ convention, 60 ZYX convention, 63 Articulated figure, 50 Assignment of kinematic states, 51 Axes of inertia principal, 43 Axial rotator, 68 angular velocity, 69 orientation matrix, 69 AxialRotator class, 78 Axis polar, 28 Bar mathematical accent, 12 BCComponent class, 180 BCEdge class, 182 BCGraph class, 186 BCVertex class, 191 Bibliography, 345 Bodies and Constraints Graph, 29
Body class, 319 BodyManager class, 337 Breadth-first search, 21 Cardinality, 18 Cholesky factorization, 5 Classes all, 75 AxialRotator, 78 BCComponent, 180 BCEdge, 182 BCGraph, 186 BCVertex, 191 Body, 319 BodyManager, 337 CSEdge, 194 CSGraph, 211 CSState, 215 CSVector, 234 CSVertex, 251 EulerAngles, 90 EulerAnglesZXZ, 102 EulerAnglesZYX, 113 EulerParams, 124 Orientator, 137 OrthoMatrix, 159 PComponent, 253 PComponentWithTree, 260 PEdge, 271 PGraph, 277 PPath, 289 PPathClosed, 298 PPathOpen, 304
347
348 Classes (cntd.) PVertex, 313 Translator, 150 TranslatorXYZ, 156 Class families, 74 Class families for rigid body kinematics, 74 Code for rigid body kinematics, 73 Column vector, 31 Constraint equations, 46 Constraints, 46 Contents, v Conventions dealing with singularities, 64 Euler angles, 58 for spherical coordinates, 29 Coordinates generalized, 45 specific, 39 Coordinate system global, 10, 23 local, 12, 35 orientation matrix for rotated, 14 Coordinate system graph, 23 propagation, 51 Coordinate systems, 17 Coordinate transformations relative, 51 Coordinate transformations, 25 Cross-links, 22 CSEdge class, 194 CSGraph class, 211 CSState class, 215 CSVector class, 234 CSVertex class, 251 Cylindrical joint, 40 Decoupling the equations of motion, 43 Degrees of freedom, 32 Depth-first search, 22 Diagonally dominant matrix, 5
INDEX Diagonal matrix, 7 Differentiating the orientation matrix, 34 Digraph, 18 Direction, 28 reference, 18, 19 Direction cosines, 11 Displacement motion, 33 Displacement velocity, 34 Dot mathematical accent, 34 Edge reference direction, 18 undirected, 18 unordered pair, 18 Edges, 18 participating, 51 Enclosing path, 19 shortest, 19 Equations of motion, 42 decoupled, 43 Euler theorem, 16 Euler angles, 39, 57 angular velocity, 60, 63 conventions, 58 dealing with singularities, 64 implementation, 70 ZXZ convention, 58 ZYX convention, 61 EulerAngles class, 90 EulerAnglesZXZ class, 102 EulerAnglesZYX class, 113 Euler parameters, 39, 64 angular velocity, 66 orientation matrix, 65 EulerParams class, 124 Factorization Cholesky, 5 Families, 74
INDEX Family of classes graphs, 179 mechanical, 319 specific coordinates, 77 Figure articulated, 50 Form invariance, 27 Form invariance of the laws of Physics, 31 Generalized coordinates, 45 Global coordinate system, 10, 23 Graph, 17, 18 adjacency level structures, 21 adjacent set, 19 adjacent vertices, 19 basic notions, 18 Bodies and Constraints, 29 breadth-first search, 21 clique, 19 component partitioning, 20 connected, 20 connected component, 20 coordinate system, 23 degree of a vertex, 19 depth-first search, 22 diameter, 19 digraph, 18 directed, 18 disconnected, 20 distance, 19 eccentricity, 19 edges, 18 cross-links, 22 tree arcs, 22 incident edge, 19 labeled, 18 level structure, 20, 21 numbered, 18 ordered, 18
349 partitioning, 20 path, 19 cycle, 19 length, 19 planar, 19 planar embedding, 18 rooted tree, 20 search, 22 section graph, 19 selfedge, 18 separator, 21, 22 spanning forest, 20 spanning tree, 20 subgraph, 19 tree, 20 ancestor, 20 descendant, 20 father, 20 monotone ordering, 20 son, 20 triangulation, 51 undirected, 18 vertex offspring, 20 pedigree, 20 peripheral, 19 pseudoperipheral, 20 vertices, 18 Graphs and coordinate systems, 17 classes, 179 family of classes, 179 Graph theory, 17, 18 Hat mathematical accent, 7 Indefinite matrix, 4 Inertia matrix of, 43 Interpolating orientations, 27
350 Invariance in form, 27 Inversion of kinematic states, 55 Joint Cylindrical, 40 planar, 40 spherical, 40 Kinematics vectors and matrices, 3 Kinematic state, 31, 32 addition, 51 assignment, 51 direct subtraction, 53 inversion, 55 operations, 51 propagation, 51 transposed subtraction, 54 Kinetic energy rotational, 43, 61, 68 Level structure, 21 length, 21 rooted, 21 rooted at vertex, 21 width, 21 Linear motion, 33 Linear velocity, 34 Line of nodes, 59 Links silent, xiii smart, xii Local coordinate system, 12, 35 Logical objects, xiii Mathematical accents bar, 12 dot, 34 hat, 7
INDEX tilde, 8, 36 Matrices used in Kinematics, 3 Matrix ˙ 35 A, A, 11 alternating, 4 diagonal, 7 diagonally dominant, 5 full rank, 5 ˙ 42 G, G, 42 ˙ 41 H, H, 41 indefinite, 4 minor, 4 nondefinite, 4 nullity, 5 of inertia, 43 of moments of inertia, 43 orientation, 10, 11 differentiation, 34 orthogonal, 6 P, 45 positive definite, 4 principal minor, 4 properly diagonally dominant, 6 Q, 45 R, 47 rank, 5 rank deficiency, 5 singular, 5 skew-symmetric, 3, 8 symmetric, 3 triangular factorization, 5 unsymmetric, 3 Mechanical classes, 319 family of classes, 319
INDEX Model, 49 rigid body, 49 Motion angular, 33 displacement, 33 linear, 33 rotation, 33 translation, 33 Motion control, 33 Object logic, xiii Objects logical, xiii Operations with kinematic states, 51 Orientational specific coordinates, 39 Orientation coordinates, 57 Orientation matrix, 10, 11 axial rotator, 69 Euler angles ZXZ convention, 59 ZYX convention, 62 Euler parameters, 65 for a rotated system, 14 interpolating, 27 Orientator class, 137 Orthogonal matrix, 6 OrthoMatrix class, 159 Orthonormal base, 6 Part I, 1 Participating edges, 51 Part II, 71 Path, 19 closed, 19 enclosing, 19 open, 19 reference direction, 19 PComponent class, 253 PComponentWithTree class, 260 PEdge class, 271
351 PGraph class, 277 Planar joint, 40 Polar axis, 28 Position, 33 Position vector, 34 Positive definite matrix, 4 PPath class, 289 PPathClosed class, 298 PPathOpen class, 304 Preface, xi Propagation of kinematic states, 51 Pseudovector, 8 PVertex class, 313 Quadratic velocity vector, 44, 45 Rank, 5 Relative coordinate transformations, 51 Rigid body kinematics Class families, 74 Code, 73 Rigid body model, 49 Rodriguez formula, 14 Rotating a vector, 12 Rotational kinetic energy, 43, 61, 68 Rotation motion, 33 Row vector, 31 Section graph, 19 Silent links, xiii Skew-symmetric matrices, 8 Smart links, xii Spanning forest, 20 Spanning tree, 20 Specific accelerations, 39, 45 Specific coordinates, 39 and constraints, 46 and state variables, 40 and the equations of motion, 42 classes, 78
352 Specific coordinates (cntd.) family of classes, 77 orientational, 39 translational, 39 Specific velocities, 39 Spherical coordinates, 28 and direction, 28 conventions, 29 Spherical joint, 40 State kinematic, 32 State variables, 32 and specific coordinates, 40 Subgraph, 19 Subtraction of kinematic states direct, 53 transposed, 54 Symmetric matrix, 3 Table of contents, v Tensor, 31 rank, 31 Tilde mathematical accent, 8, 36 Transformations coordinate, 25 Translational specific coordinates, 39 Translation motion, 33 Translation velocity, 34 Translator class, 150 TranslatorXYZ class, 156 Tree, 20 ancestor, 20 descendant, 20 father, 20 monotone ordering, 20 older ancestor, 20 rooted, 20 son, 20 spanning, 20
INDEX younger ancestor, 20 Tree arcs, 22 Triangulation graph, 51 Undirected edge, 18 graph, 18 Variables state, 32 Vector column, 31 position, 34 rotating, 12 row, 31 transformation, 32 Vectors used in Kinematics, 3 Velocities specific, 39 Velocity, 33, 34 angular, 36 displacement, 34 linear, 34 quadratic vector, 44, 45 translation, 34 Vertices, 18 ZXZ convention for Euler angles, 58 ZYX convention for Euler angles, 61
INDEX Oh, I almost forgot! You can now put the orange away and go by your business!
353
