Merge pull request #1062 from rwf-rr/train-forces-popup-window

Train Forces popup Window.

Author: cjakeman

Source/Documentation/Manual/driving.rst

@@ -470,6 +470,77 @@ specified by the player:
 
 .. image:: images/driving-train-names-multiplayer.png
 
+Alt-F7 Train Forces
+-------------------
+
+Pressing ``<Alt+F7>`` opens the Train Forces window.
+It shows the forces along the player's train in bar-graph form.
+The window is sized to fit the train (graph), with a minimum size for short trains,
+and a maximum size for very long trains.
+Scrolling may be required to see the end of the train, or the end of the text line.
+
+.. image:: images/driving-trainforces.png
+  :align: center
+  :scale: 80%
+
+The train is shown as a white line; locomotives are shown in blue.
+The front of the train is to the left.
+
+``Coupler Force``
+'''''''''''''''''
+
+Shows the length-wise pull or push force at each coupling, as a colored bar graph.
+Up (positive) is pull, down (negative) is push.
+The scale is determined by the weakest coupler in the train.
+The steps are non-linear, to provide more sensitivity near the breaking point.
+
+Note: Because the graph is scaled by the weakest car,
+a red bar may not mean that the coupler will break.
+When the car has a higher coupler strength, it can tolerate higher forces than the weakest car.
+
+``Derail Force``
+''''''''''''''''
+
+Shows the sideway push or pull at the wheels as a colored bar graph.
+Up (positive) is pull to the inside (stringline), down (negative) is push to the outside (jackknife).
+The scale is determined by the car with the lowest axle-load (lowest vertical force).
+The steps are non-linear, to provide more sensitivity near the derailing point.
+But this is less effective for lateral forces, as the force is proportional to the curve radius,
+which changes in discrete steps (MSTS legacy).
+
+Note: Because the graph is scaled by the most susceptible car,
+a red bar may not mean that the car will derail.
+When the car has a higher vertical force, it can tolerate higher lateral forces than the most susceptible car.
+
+
+``Brake Force``
+'''''''''''''''
+
+Shows the braking force of each car as a bar graph.
+The scale is determined by the car with the smallest brake force (generally lowest weight).
+The steps are non-linear, to provide more sensitivity near the small brake applications.
+As the weight (and thus brake force varies greatly between cars (and especially engines),
+the graph can be quite jagged, even though all brake cylinders have the same pressure.
+Locomotives will show a full bar long before the brakes are fully applied.
+
+Dynamic braking is shown in blue (unless there also is a greater force from the air-brakes).
+
+``Text Line``
+'''''''''''''
+
+The text line at the bottom shows the following information.
+
+- Max Coupler: The current maximum coupler force within the train,
+  and the car (count from front, including locomotives) where the maximum force is.
+- Max Derail: The current maximum derail force within the train,
+  and the car (count from front, including locomotives) where the maximum force is.
+- Low Coupler: The lowest coupler strength within the train.
+- Low Derail: The lowest derail force within the train.
+  This is an estimate, based on the vertical force.
+  Dynamic factors also affect the force needed to derail.
+
+It may be necessary to scroll to see the rightmost parts of the line.
+
 F8 Switch Monitor
 -----------------
 

Source/Documentation/Manual/images/driving-trainforces.png

@@ -782,6 +782,13 @@ public static string FormatForce(float forceN, bool isMetric)
             return String.Format(CultureInfo.CurrentCulture, kilo ? "{0:F1} {1}" : "{0:F0} {1}", force, unit);
         }
 
+        public static string FormatLargeForce(float forceN, bool isMetric)
+        {
+            var force = isMetric ? forceN : N.ToLbf(forceN);
+            var unit = isMetric ? kN : klbf;
+            return String.Format(CultureInfo.CurrentCulture, "{0:F1} {1}", force * 1e-3f, unit);
+        }
+
         public static string FormatTemperature(float temperatureC, bool isMetric, bool isDelta)
         {
             var temperature = isMetric ? temperatureC : isDelta ? C.ToDeltaF(temperatureC) : C.ToF(temperatureC);

Source/Orts.Common/Conversions.cs

@@ -64,6 +64,7 @@ public enum UserCommand
         [GetString("Display Train Car Operations Window")] DisplayTrainCarOperationsWindow,
         [GetString("Display Train Dpu Window")] DisplayTrainDpuWindow,
         [GetString("Display Next Station Window")] DisplayNextStationWindow,
+        [GetString("Display Train Forces Window")] DisplayTrainForcesWindow,
         [GetString("Display Compass Window")] DisplayCompassWindow,
         [GetString("Display Train List Window")] DisplayTrainListWindow,
         [GetString("Display EOT List Window")] DisplayEOTListWindow,

Source/Orts.Common/Input/UserCommand.cs

@@ -518,6 +518,7 @@ static void InitializeCommands(UserCommandInput[] Commands)
             Commands[(int)UserCommand.DisplayTrainOperationsWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Control | KeyModifiers.Alt);
             Commands[(int)UserCommand.DisplayTrainDpuWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Shift);
             Commands[(int)UserCommand.DisplayEOTListWindow] = new UserCommandKeyInput(0x43, KeyModifiers.Control);
+            Commands[(int)UserCommand.DisplayTrainForcesWindow] = new UserCommandKeyInput(0x41, KeyModifiers.Alt);
             Commands[(int)UserCommand.DisplayControlRectangle] = new UserCommandKeyInput(0x3F, KeyModifiers.Control);
 
             Commands[(int)UserCommand.GameAutopilotMode] = new UserCommandKeyInput(0x1E, KeyModifiers.Alt);

Source/Orts.Settings/InputSettings.cs

@@ -386,6 +386,8 @@ public string DirectXFeatureLevel
         public int[] WindowPosition_ComposeMessage { get; set; }
         [Default(new[] { 100, 0 })]
         public int[] WindowPosition_TrainList { get; set; }
+        [Default(new[] { 50, 50 })]
+        public int[] WindowPosition_TrainForces { get; set; }
         [Default("")]
         public string LastViewNotificationDate { get; set; }
 

Source/Orts.Settings/UserSettings.cs

@@ -42,6 +42,9 @@
       <Link>Native\X64\OpenAL32.dll</Link>
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
+    <Content Include="Content\TrainForcesSprites.png">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
     <Content Include="Content\blank.bmp">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>