Editing AttitudeMFD

== Description ==

This MFD provides the user with attitude information (pitch, yaw, and roll) with respect to a
pre-selected attitude.  It also provides an "Attitude Hold" mode to automatically hold the
desired attitude.

The current version is 3.2 (December 2007).

== Credits ==

Original Author: Chris Knestrick

V3 by:  Bob Denny

V3.1 & V3.2 by: Tim Blaxland

== Download and Installation ==

Download the addon from [http://www.orbithangar.com/searchid.php?ID=3165 Orbit Hangar].

To install, simply unzip into your Orbiter directory.  Then, activate the module
"AttitudeMFD" under the Modules tab of the Launchpad.

== Operation ==

=== Introduction ===

There are four base reference attitudes that the MFD uses:

# User Attitude:	Attitude selected by the user.  The user orients the spacecraft to
			the desired attitude and "marks" it.

# Velocity:		Attitude defined by the velocity vector and the local horizon.
			This can be thought of as a combination of the Prograde and H-Level
			navcomp modes that are built into Orbiter.

# Target Relative:	Orient towards a user-defined target.

# Entry Interface:	Attitude defined by the velocity vector and local horizon at entry 
			interface.  Currently, this feature is only supported for elliptical
			orbits reentering the Earth's atmosphere (defined as an altitude of
			approximately 99 km above the Earth's surface).

Based on this reference attitude, the user can select a relative pitch, yaw, and roll.  The
relative attitude becomes the reference by which all attitude information is measured.

=== Setting Pitch, Yaw and Roll ===

For all base reference attitudes the user can enter a relative pitch, 
yaw, and roll to serve as the reference attitude.  A limitation of the input dialog used to enter
these values is the inability to handle decimal points.  To enter a decimal number, simply
use a single space in place of the decimal point; for eample, 45.32 would be entered as "45 32".

Also, note that the rotations are non-commutative, meaning that the order matters.  Pitching up
90 degrees and then yawing right 90 degrees is a different attitude than yawing right 90 and then
performing the pitch up.  In Obiter, rotations are done pitch, then yaw, and finally roll.  Please 
keep this is mind when entering these values, otherwise you will wind up in the wrong orientation.

=== Display ===

The MFD display is divided into four basic sections (Target Relative is slightly
modified).  The top section contains the name of the current attitude reference, plus any
specialized information for that reference mode; for example, Entry Interface includes the
entry angle and the time to go.

Next is the relative pitch, yaw and roll angles entered by the user.  In the case of Target
Relative, this is relpaced by the relaive velocity along the spacecraft axes.

The third section displays the spacecraft's pitch, yaw, and roll from the specified attitude.
Also included are the angular rates along each of the spacecraft's axes.

The final section provides a graphical display of the spacecraft's rotatational thrusters.

=== Keyboard Commands ===

The following are a basic list of commands.  Certain keys have different meanings when 
in Target Relative mode - see the special section later for a description of Target 
Relative-specific commands.  Note that the numeric keys used to select reference attitudes
are on the keyboard, NOT the numeric keypad.

Key			Description
--------------------------------------------------------------------------------------
SHIFT + U		Activate Attitude MFD 
SHIFT + 1		Set User Attitude reference attitude
SHIFT + 2		Set Velocity reference attitude
SHIFT + 3		Set Target Relative Attitude reference attitude
SHIFT + 4		Set Entry Interface reference attitude
SHIFT + M		Manually set the mode.  The user is prompted to enter the mode
			number (1 - 4).   This is only needed in rare instances where
			the vessel defines a SHIFT + Number key combination (such as the
			shuttle's RMS).  In all other instances, the mode can be switched
			directly using SHIFT + Number.
SHIFT + P		Set the pitch relative to the reference attitude
SHIFT + Y		Set the yaw relative to the reference attitude
SHIFT + R		Set the roll relative to the reference attitude
SHIFT + H		Toggle Attitude Hold mode
SHIFT + . 		Set current attitude as the reference attitude (User Attitude mode only)
SHIFT + C		Toggle the color mode.  This allows the user to specify color scheme
			used to display negative pitch, yaw, and roll values.  This key cycles
			through the three colors - the default green, white, or red.

=== Target Relative Mode ===

In Target Relative reference mode, the reference vector for the roll angle is defined as a vector
perpendicular to the plane defined by the velocity vector and the vector to the target. This
reference was selected because you always have these two references, whereas a local vertical is
not always obvious. When performing a orbital rendezvous, this roll reference vector will be the
same as the local horizontal anyway, assuming the orbital planes are aligned.

Target Relative mode provides the ability to trim out relative velocities along the
the spacecraft axes using the linear thrusters, as well as main main/retro/hover engines.

Also useful in this mode, if performing a rendezvous between a space shuttle and the ISS, are the
RPM and TOR buttons. These buttons can be found on the second page of buttons by pressing the MNU
button until they appear. Pressing these buttons will command the auto-pilot to maintain a
positive pitch rate of 0.75deg/sec and orbital rate, respectectively. Press the buttons again to
deactivate.

The following are a list of commands specific to the Target Relative mode: 

Key			Description
--------------------------------------------------------------------------------------
SHIFT + T		Select target.  The user is prompted to enter the object name.
SHIFT + N		Select next target.  Targets are stored in order of increasing distance
			for the spacecraft.  Cycles through the list of all available objects. 
SHIFT + SPACE		Select closest target.
SHIFT + B		Set the current surface target (selected via the Map MFD) as the
			Orient Mode target.  If no target is selected, this command is ignored.
			Note that if you change Map targets you must use Shift-B again to update
			the target.   
SHIFT + NUMPAD 5	Trim all axes
SHIFT + NUMPAD 1	Trim the vertical axis
SHIFT + NUMPAD 2	Trim the lateral axis 
SHIFT + NUMPAD 3	Trim the fore/aft axis
SHIFT + NUMPAD 7	Trim the vertical and lateral axes
SHIFT + NUMPAD 8	Trim the lateral and fore/aft axes
SHIFT + NUMPAD 9	Trim the vertical and fore/aft axes

=== Trimming Relative Velocity ===

The MFD autopilot can trim the relative velocity between your spacecraft and the target
object using the linear thrusters, as well as the main/hover engines.  The user selects what 
axes should be trimmed using the numeric keypad (shift + numkey):

	1) Trim vertical axis
	2) Trim lateral axis
	3) Trim fore/aft axis
	5) Trim all axes (for those of you searching for a method to my numbering scheme, 
			  note that this is the same numeric key used for killrot - this 
			  is not an accident :-))
	7) Trim vertical and lateral axes
	8) Trim lateral and fore/aft axes
	9) Trim vertical and fore/aft axes

When trim is engaged, the label on each affected axis' relative velocity display will turn white.
When the spacecraft is trimmed, the system will automatically disengaged.  It is also possible to
manually disengaged the trim by pressing the trim command for a second time.  Note that this only
works if the two commands are identical - for example, to disengaged a trim on the vertical axis,
SHIFT + 1 would be entered.  If instead, SHIFT + 2 was entered, the trim will remain engaged but 
will switch from the vertical axis to the lateral one.

Note that if available, the MFD will attemp to use main/hover engines if it's determined that
it will take more than three seconds of linear thruster firing to produce the desired trim.  
If you're using a spacecraft that requires an arming of the engine (e.g. NASSP), make sure that
the engine is armed, otherwise the trim will not be sucessfull. 

== Source Code ==

Being a strong believer in Open Source, the source files for the MFD are included in the download.
You are free to use, modify, and redistribute the code within certain, fairly loose, 
guidelines.  Please read Copyright.txt that is included with the source files for full 
details.

== Bugs and Feedback ==

One of my purposes for releasing this version is to get user feedback.  If you use this add-on, and you have either compliments, suggestions, or criticisms (though I hope any criticisms include a suggestion :-) ), contact me at [http://www.orbiter-forum.com Orbiter-Forum].  In particular:

1) What did you like about this MFD (functionality, display, etc)?
2) What did you not like about it?
3) What types of additional functionality do you think that you'd find useful?

== Copyright ==

Copyright 2003 Chris Knestrick, 2008 Tim Blaxland

== Warranty ==

This software is free, and consequently provided AS IS; there is no warranty 
of any kind, and the user is responsible for whatever horrible things may happen,
including, but not limited to hair loss, insmonia, or fatigue. Side effects are
generally mild and include nasuea, headache, dry mouth, and sexual dysfunction.  Consult
your doctor if side effects continue or become bothersome.