Bugfixes and support for brake rigging animations

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -1487,6 +1487,53 @@ to the oscillation from center point to an oscillation end point. The file shoul
 one cue point at its beginning and one after the time interval of a complete bell swing 
 forward and backward, and should have a final fadeoff for best result. 
 
+Brake Equipment Animations
+==========================
+
+Open Rails now supports animation of brake rigging components driven by the brake system
+simulation.
+
+Brake Cylinder Animation
+------------------------
+
+On engines and wagons with :ref:`advanced brake cylinder parameters <physics-braking-parameters>`
+`ORTSBrakeCylinderDiameter` and `ORTSBrakeCylinderPistonTravel` defined, Open Rails will
+simulate the motion of the brake cylinders and brake rigging. This simulation can be used
+to drive animations of brake cylinders using animation matricies with names that
+start with `ORTSBRAKECYLINDER`. This animation type should NOT be used for any brake equipment
+that can be actuated by the brake cylinder and the handbrakes. See the section on brake rigging
+animation for details.
+
+Unlike other animation types, the keyframes for brake cylinders do not represent time.
+Instead, the key value represents the level of brake cylinder extension. A value of 0.8
+represents the state where the brake cylinder has taken up the slack in the brake rigging,
+1.0 represents the level of brake cylinder extension at 50 psi/3.5 bar, and the maximum
+value of cylinder extension is 1.6, which should not be possible in normal operation.
+These values are the same regardless of the settings used in the engine or wagon file.
+
+Note that the advanced brake cylinder calculations are only run on air brake systems on the
+player train to save computing power. As such, brake cylinder animations on AI trains
+or brake systems other than air brakes behave in a simplified manner.
+
+Handbrake Animation
+-------------------
+
+Handbrake wheels and levers can also be animated using the same process as two-state animations
+such as mirrors. The matrix name for animated handbrakes must begin with `ORTSHANDBRAKE`.
+
+Brake Rigging and Brake Shoe Animation
+--------------------------------------
+
+For any brake equipment that is actuated by both the handbrake and the brake cylinders (typically,
+this includes brake rigging and brake shoes, but sometimes also includes brake cylinders themselves),
+use animations with a matrix name starting with `ORTSBRAKERIGGING`. For this type of animation, the
+animation state will respond to the brake cylinder travel or the handbrake, whichever input is greater.
+
+The same keyframe rules as brake cylinder animations apply here. The 0.8 key should represent the state
+where the brake shoes have made contact with the friction surface, and no further motion of brake shoes
+should occur after 0.8. Applying the handbrake will drive the animation to the 1.0 state, the same
+as a 50 psi/3.5 bar application of the brakes.
+
 Coupler and Airhose Animation
 =============================
 

Source/Documentation/Manual/physics.rst

@@ -3143,6 +3143,8 @@ notch of the train brake controller, where 0 means no dynamic brake and 1 means
 Native Open Rails Braking Parameters
 ------------------------------------
 
+.. _physics-braking-parameters:
+
 Open Rails has implemented additional specific braking parameters to
 deliver realism in braking performance in the simulation.
 

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/BrakeSystem.cs

@@ -76,6 +76,7 @@ public abstract class BrakeSystem
         public abstract float GetCylPressurePSI();
         public abstract float GetCylVolumeM3();
         public abstract float GetTotalCylVolumeM3();
+        public abstract float GetNormalizedCylTravel();
         public abstract float GetVacResPressurePSI();
         public abstract float GetVacResVolume();
         public abstract float GetVacBrakeCylNumber();

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs

@@ -300,6 +300,11 @@ public override float GetTotalCylVolumeM3()
             return TotalCylVolumeM3;
         }
 
+        public override float GetNormalizedCylTravel()
+        {
+            return CurrentCylTravelM / CylStrokeM;
+        }
+
         public float GetFullServPressurePSI()
         {
             return FullServPressurePSI;
@@ -653,8 +658,8 @@ public override void Initialize()
                     // Other assumptions:
                     // Brake cylinder travel remains at 0 until reaching half the spring counter-pressure
                     // Brake cylinder travel is linear w.r.t. total air in the cylinder line, not entirely accurate but greatly simplifies code
-                    float[] airPV = new float[5];
-                    float[] cylTravel = new float[5];
+                    float[] airPV = new float[7];
+                    float[] cylTravel = new float[7];
 
                     float nomPSI = 50.0f;
 
@@ -683,6 +688,12 @@ public override void Initialize()
 
                     cylTravel[4] = (strokePerPsi * (Math.Max(nomPSI, ReferencePressurePSI) - 50.0f)) + CylStrokeM;
                     airPV[4] = AdvancedBrakeCylinderAir(Math.Max(nomPSI, ReferencePressurePSI), true);
+                    // Absolute maximum cylinder travel limited to 160% of nominal
+                    cylTravel[5] = CylStrokeM * 1.6f;
+                    airPV[5] = AdvancedBrakeCylinderAir((cylTravel[5] - cylTravel[2]) / strokePerPsi);
+
+                    cylTravel[6] = cylTravel[5];
+                    airPV[6] = airPV[5] * 2.0f;
 
                     CylTravelTab = new Interpolator(airPV, cylTravel);
 
@@ -811,7 +822,6 @@ public float CalculateBrakeCylinderPressure(ref float airPV, float dp, float tar
             }
             else if (dp < 0)
             {
-                recalculate = true;
                 if (pressurePSI < 0)
                 {
                     currentAir = 0;
@@ -1407,6 +1417,8 @@ public override void Update(float elapsedClockSeconds)
                         dp = QuickServiceLimitPSI - AutoCylPressurePSI;
                     if (QuickServiceBulbPressurePSI - (dp * volumeRatio) < AutoCylPressurePSI + dp)
                         dp = (QuickServiceBulbPressurePSI - AutoCylPressurePSI) / (1 + volumeRatio);
+                    if (dp < 0)
+                        dp = 0;
                     if (CylSource == 0)
                         AutoCylPressurePSI = CalculateBrakeCylinderPressure(ref AutoCylAirPV, dp, QuickServiceLimitPSI);
                     else
@@ -1737,7 +1749,7 @@ public override void Update(float elapsedClockSeconds)
             if (CylDiameterM > 0 && Car.Train.IsPlayerDriven)
                 CurrentCylTravelM = CylTravelTab[CylAirPV];
             else
-                CurrentCylTravelM = 0;
+                CurrentCylTravelM = CylPressurePSI > BrakeCylinderSpringPressurePSI ? CylStrokeM : 0.0f;
 
             // During braking wheelslide control is effected throughout the train by additional equipment on each vehicle. In the piping to each pair of brake cylinders are fitted electrically operated 
             // dump valves. When axle rotations which are sensed electrically, differ by a predetermined speed the dump valves are operated releasing brake cylinder pressure to both axles of the affected 

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/ManualBraking.cs

@@ -356,6 +356,11 @@ public override float GetTotalCylVolumeM3()
             return 0;
         }
 
+        public override float GetNormalizedCylTravel()
+        {
+            return ManualBrakingCurrentFraction;
+        }
+
         public override float GetVacResVolume()
         {
             return 0;

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/VacuumSinglePipe.cs

@@ -216,6 +216,11 @@ public override float GetTotalCylVolumeM3()
             return TotalCylVolumeM3;
         }
 
+        public override float GetNormalizedCylTravel()
+        {
+            return CylPressurePSIA > VacResPressureAdjPSIA() ? 1.0f : 0.0f;
+        }
+
         public override float GetVacResVolume()
         {
             return VacResVolM3;

Source/RunActivity/Viewer3D/AnimatedPart.cs

@@ -103,6 +103,20 @@ public void SetFrameClamp(float frame)
             SetFrame(frame);
         }
 
+        /// <summary>
+        /// Smoothly changes the animation to a particular frame whilst clamping it to the frame count range.
+        /// </summary>
+        public void UpdateFrameClamp(float frame, ElapsedTime elapsedTime)
+        {
+            float newState;
+            if (Math.Abs(frame - AnimationKey) > 1.0f * elapsedTime.ClockSeconds)
+                newState = AnimationKey + Math.Sign(frame - AnimationKey) * elapsedTime.ClockSeconds;
+            else
+                newState = frame;
+
+            SetFrameClamp(newState);
+        }
+
         /// <summary>
         /// Sets the animation to a particular frame whilst cycling back to the start as input goes beyond the last frame.
         /// </summary>

Source/RunActivity/Viewer3D/RollingStock/MSTSWagonViewer.cs

@@ -80,6 +80,9 @@ public class MSTSWagonViewer : TrainCarViewer
         protected AnimatedPart Item2Continuous;
         protected AnimatedPart Item1TwoState;
         protected AnimatedPart Item2TwoState;
+        protected AnimatedPart BrakeCylinders;
+        protected AnimatedPart Handbrakes;
+        protected AnimatedPart BrakeRigging;
         AnimatedPart UnloadingParts;
 
         public Dictionary<string, List<ParticleEmitterViewer>> ParticleDrawers = new Dictionary<string, List<ParticleEmitterViewer>>();
@@ -341,6 +344,9 @@ from data in effect.Value
             Item2Continuous = new AnimatedPart(TrainCarShape);
             Item1TwoState = new AnimatedPart(TrainCarShape);
             Item2TwoState = new AnimatedPart(TrainCarShape);
+            BrakeCylinders = new AnimatedPart(TrainCarShape);
+            Handbrakes = new AnimatedPart(TrainCarShape);
+            BrakeRigging = new AnimatedPart(TrainCarShape);
 
             if (car.FreightAnimations != null)
                 FreightAnimations = new FreightAnimationsViewer(viewer, car, wagonFolderSlash);
@@ -431,6 +437,9 @@ from data in effect.Value
             RightWindowRear.SetState(MSTSWagon.WindowStates[MSTSWagon.RightWindowRearIndex] >= MSTSWagon.WindowState.Opening);
             Item1TwoState.SetState(MSTSWagon.GenericItem1);
             Item2TwoState.SetState(MSTSWagon.GenericItem2);
+            BrakeCylinders.SetFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel());
+            Handbrakes.SetState(MSTSWagon.GetTrainHandbrakeStatus());
+            BrakeRigging.SetFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f));
             UnloadingParts.SetState(MSTSWagon.UnloadingPartsOpen);
 
             InitializeUserInputCommands();
@@ -617,6 +626,18 @@ void MatchMatrixToPart(MSTSWagon car, int matrix, int bogieMatrix)
             {
                 Item2TwoState.AddMatrix(matrix);
             }
+            else if (matrixName.StartsWith("ORTSBRAKECYLINDER")) // brake cylinder animation
+            {
+                BrakeCylinders.AddMatrix(matrix);
+            }
+            else if (matrixName.StartsWith("ORTSHANDBRAKE")) // handbrake wheel animation
+            {
+                Handbrakes.AddMatrix(matrix);
+            }
+            else if (matrixName.StartsWith("ORTSBRAKERIGGING")) // brake rigging/brake shoes animation
+            {
+                BrakeRigging.AddMatrix(matrix);
+            }
             else
             {
                 if (matrixAnimated && matrix != 0)
@@ -669,6 +690,9 @@ public override void PrepareFrame(RenderFrame frame, ElapsedTime elapsedTime)
             UnloadingParts.UpdateState(MSTSWagon.UnloadingPartsOpen, elapsedTime);
             Item1TwoState.UpdateState(MSTSWagon.GenericItem1, elapsedTime);
             Item2TwoState.UpdateState(MSTSWagon.GenericItem2, elapsedTime);
+            BrakeCylinders.UpdateFrameClamp(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), elapsedTime);
+            Handbrakes.UpdateState(MSTSWagon.GetTrainHandbrakeStatus(), elapsedTime);
+            BrakeRigging.UpdateFrameClamp(Math.Max(MSTSWagon.BrakeSystem.GetNormalizedCylTravel(), MSTSWagon.GetTrainHandbrakeStatus() ? 1.0f : 0.0f), elapsedTime);
             UpdateAnimation(frame, elapsedTime);
 
             var car = Car as MSTSWagon;