Merge pull request #440 from peternewell/derail_notification#2

Addition of Derail Coefficient and further coupler animation
https://blueprints.launchpad.net/or/+spec/advanced-coupler

Author: cjakeman

Source/Documentation/Manual/features-rollingstock.rst

@@ -606,6 +606,45 @@ 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. 
 
+Coupler and Airhose Animation
+=============================
+
+Open Rails supports animation of couplers and air hoses. Coupler animation will move the 
+couplers and air hoses as the train moves and the coupler slack increases or decreases. 
+Couplers will also rotate as the train travels around a curve.
+
+To implement this separate models need to be provided for the couplers and air hoses. A 
+separate model for the coupled and uncoupled state is suggested.
+
+To enable coupler animation the following parameters need to be included in the coupler 
+code section of the WAG file:
+
+``FrontCouplerAnim`` - Coupler shape to be displayed at the front of the car when it is coupled.
+``FrontCouplerOpenAnim`` - Coupler shape to be displayed at the front of the car when it is uncoupled.
+``RearCouplerAnim`` - Coupler shape to be displayed at the rear of the car when it is coupled.
+``RearCouplerOpenAnim`` - Coupler shape to be displayed at the rear of the car when it is uncoupled
+
+All four of the above will have the following format:
+
+CouplerAnimation ( couplershape.s, x, y, z ) where the coupler shape file name is included along with 
+x, y, z values that offset the coupler in the three axis.
+
+For the airhose animation the following parameters must be included in the coupler code section of 
+the WAG file:
+
+``FrontAirHoseAnim`` - Air hose shape to be displayed at the front of the car when it is coupled.
+``FrontAirHoseDisconnectedAnim`` - Air hose shape to be displayed at the front of the car when it is uncoupled.
+``RearAirHoseAnim`` - Air hose shape to be displayed at the rear of the car when it is coupled.
+``RearAirHoseDisconnectedAnim`` - Air hose shape to be displayed at the rear of the car when it is uncoupled.
+
+Each of these parameters will have the same format as indicated above for the coupler shapes.
+
+Open rails uses some defaults to calculate the required movement and angles for coupler and air hose 
+shape movement, however for greater accuracy the modeler can add specific values such as 
+``ORTSLengthAirHose``. In addition the length values suggested in the Derailment Coefficient should 
+also be added.
+
+
 C# engine scripting
 ===================
 .. _features-scripting-csharp:

Source/Documentation/Manual/physics.rst

@@ -139,6 +139,33 @@ the typical outcomes for bearing temperature heating or cooling effects.
 A special smoke effect,  ``BearingHotboxFX``, can be added adjacent to the wagon hot box. 
 This will be triggered if the bearing overheats.
 
+Derailment Coefficient
+----------------------
+
+The derailment coefficient indicates the likelihood that a car or wagon will derail, 
+and is the ratio of the lateral force to vertical force acting on the wagon. This concept was 
+first proposed by Nadal.
+
+The higher the coefficient the higher the risk that a derailment will occur. Most railway 
+companies tend to operate at a coefficient value of less then 0.8 as this gives a desireable 
+safety margin for the car.
+
+The OR calculated derailment coefficient is displayed in the Force Information HuD. The 
+coefficient value will change colour to indicate the likelihood of the car derailing. White 
+indicates normal operation, yellow provides a warning indication, whilst red indicates that 
+derailment is extremely likely.
+
+Open Rails uses some standard defaults that it uses to calculate the derailment coefficient, 
+however if the modeler desires greater accuracy the following parameters can be added to the 
+WAG/ENG file in the wagon section:
+
+``ORTSLengthBogieCentre`` - length between bogie centres.
+``ORTSLengthCarBody`` - Length between car ends.
+``ORTSLengthCouplerFace`` - length between coupler faces.
+
+``ORTSNumAxles`` - number of axles on the car.
+``ORTSNumBogies`` - number of bogies on the car.
+
 .. _physics-adhesion:
 
 Adhesion of Locomotives -- Settings Within the Wagon Section of ENG files

Source/Orts.Simulation/Simulation/RollingStocks/MSTSWagon.cs

@@ -419,6 +419,18 @@ public virtual void LoadFromWagFile(string wagFilePath)
                 RearCouplerShapeFileName = null;
             }
 
+            if (FrontAirHoseShapeFileName != null && !File.Exists(wagonFolderSlash + FrontAirHoseShapeFileName))
+            {
+                Trace.TraceWarning("{0} references non-existent shape {1}", WagFilePath, wagonFolderSlash + FrontAirHoseShapeFileName);
+                FrontAirHoseShapeFileName = null;
+            }
+
+            if (RearAirHoseShapeFileName != null && !File.Exists(wagonFolderSlash + RearAirHoseShapeFileName))
+            {
+                Trace.TraceWarning("{0} references non-existent shape {1}", WagFilePath, wagonFolderSlash + RearAirHoseShapeFileName);
+                RearAirHoseShapeFileName = null;
+            }
+
             // If trailing loco resistance constant has not been  defined in WAG/ENG file then assign default value based upon orig Davis values
             if (TrailLocoResistanceFactor == 0)
             {
@@ -436,6 +448,40 @@ public virtual void LoadFromWagFile(string wagFilePath)
                 }
             }
 
+            // Initialise car body lengths. Assume overhang is 2.0m each end, and bogie centres are the car length minus this value
+
+            if (CarCouplerFaceLengthM == 0)
+            {
+                CarCouplerFaceLengthM = CarLengthM;
+            }
+
+            if (CarBodyLengthM == 0)
+            {
+                CarBodyLengthM = CarCouplerFaceLengthM - 0.8f;
+            }
+
+            if (CarBogieCentreLengthM == 0)
+            {
+                CarBogieCentreLengthM = (CarCouplerFaceLengthM - 4.3f);
+            }
+
+            if (CarAirHoseLengthM == 0)
+            {
+                CarAirHoseLengthM = Me.FromIn(26.25f); // 26.25 inches
+            }
+
+            var couplerlength = ((CarCouplerFaceLengthM - CarBodyLengthM) / 2) + 0.1f; // coupler length at rest, allow 0.1m also for slack
+
+            if (CarAirHoseLengthM < couplerlength)
+            {
+                CarCouplerFaceLengthM = CarBodyLengthM + (0.4f * 2.0f); // Assume a coupler length of 400mm at each end and add to car body length
+
+                if (Simulator.Settings.VerboseConfigurationMessages)
+                {
+                    Trace.TraceInformation("Coupler length exceeded brake air hose length, so  ORTSLengthCouplerFace decreased to {0}", CarCouplerFaceLengthM);
+                }
+            }
+            
             // Ensure Drive Axles is set to a default if no OR value added to WAG file
             if (WagonNumAxles == 0)
             {
@@ -964,6 +1010,10 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     CarLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
                     stf.SkipRestOfBlock();
                     break;
+                case "wagon(ortslengthbogiecentre": CarBogieCentreLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
+                case "wagon(ortslengthcarbody": CarBodyLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
+                case "wagon(ortslengthairhose": CarAirHoseLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
+                case "wagon(ortslengthcouplerface": CarCouplerFaceLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortstrackgauge":
                     stf.MustMatch("(");
                     TrackGaugeM = stf.ReadFloat(STFReader.UNITS.Distance, null);
@@ -1121,6 +1171,15 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     stf.SkipRestOfBlock();
                     break;
 
+                case "wagon(coupling(frontairhoseanim":
+                    stf.MustMatch("(");
+                    FrontAirHoseShapeFileName = stf.ReadString();
+                    FrontAirHoseAnimWidthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    FrontAirHoseAnimHeightM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    FrontAirHoseAnimLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    stf.SkipRestOfBlock();
+                    break;
+
                 case "wagon(coupling(rearcoupleranim":
                     stf.MustMatch("(");
                     RearCouplerShapeFileName = stf.ReadString();
@@ -1130,7 +1189,16 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     stf.SkipRestOfBlock();
                     break;
 
-               case "wagon(coupling(spring(ortstensionstiffness":
+                case "wagon(coupling(rearairhoseanim":
+                    stf.MustMatch("(");
+                    RearAirHoseShapeFileName = stf.ReadString();
+                    RearAirHoseAnimWidthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    RearAirHoseAnimHeightM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    RearAirHoseAnimLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    stf.SkipRestOfBlock();
+                    break;
+
+                case "wagon(coupling(spring(ortstensionstiffness":
                     stf.MustMatch("(");
                     Couplers[CouplerCountLocation].SetTensionStiffness(stf.ReadFloat(STFReader.UNITS.Force, null), stf.ReadFloat(STFReader.UNITS.Force, null));
                     stf.SkipRestOfBlock();
@@ -1156,6 +1224,25 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     stf.SkipRestOfBlock();
                     break;
 
+                case "wagon(coupling(frontairhosediconnectedanim":
+                    stf.MustMatch("(");
+                    FrontAirHoseDisconnectedShapeFileName = stf.ReadString();
+                    FrontAirHoseDisconnectedAnimWidthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    FrontAirHoseDisconnectedAnimHeightM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    FrontAirHoseDisconnectedAnimLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    stf.SkipRestOfBlock();
+                    break;
+                    
+                case "wagon(coupling(rearairhosediconnectedanim":
+                    stf.MustMatch("(");
+                    RearAirHoseDisconnectedShapeFileName = stf.ReadString();
+                    RearAirHoseDisconnectedAnimWidthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    RearAirHoseDisconnectedAnimHeightM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    RearAirHoseDisconnectedAnimLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    stf.SkipRestOfBlock();
+                    break;
+
+
                 case "wagon(coupling(spring(ortscompressionstiffness":
                     stf.MustMatch("(");
                     Couplers[CouplerCountLocation].SetCompressionStiffness(stf.ReadFloat(STFReader.UNITS.Force, null), stf.ReadFloat(STFReader.UNITS.Force, null));
@@ -1247,7 +1334,7 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                 case "wagon(orts3dcab": Parse3DCab(stf); break;
                 case "wagon(numwheels": MSTSWagonNumWheels= stf.ReadFloatBlock(STFReader.UNITS.None, 4.0f); break;
                 case "wagon(ortsnumberaxles": WagonNumAxles = stf.ReadIntBlock(null); break;
-
+                case "wagon(ortsnumberbogies": WagonNumBogies = stf.ReadIntBlock(null); break;
                 case "wagon(ortspantographs":
                     Pantographs.Parse(lowercasetoken, stf);
                     break;
@@ -1322,6 +1409,27 @@ public virtual void Copy(MSTSWagon copy)
             RearCouplerOpenAnimHeightM = copy.RearCouplerOpenAnimHeightM;
             RearCouplerOpenAnimLengthM = copy.RearCouplerOpenAnimLengthM;
             RearCouplerOpenFitted = copy.RearCouplerOpenFitted;
+
+            FrontAirHoseShapeFileName = copy.FrontAirHoseShapeFileName;
+            FrontAirHoseAnimWidthM = copy.FrontAirHoseAnimWidthM;
+            FrontAirHoseAnimHeightM = copy.FrontAirHoseAnimHeightM;
+            FrontAirHoseAnimLengthM = copy.FrontAirHoseAnimLengthM;
+            
+            FrontAirHoseDisconnectedShapeFileName = copy.FrontAirHoseDisconnectedShapeFileName;
+            FrontAirHoseDisconnectedAnimWidthM = copy.FrontAirHoseDisconnectedAnimWidthM;
+            FrontAirHoseDisconnectedAnimHeightM = copy.FrontAirHoseDisconnectedAnimHeightM;
+            FrontAirHoseDisconnectedAnimLengthM = copy.FrontAirHoseDisconnectedAnimLengthM;
+            
+            RearAirHoseShapeFileName = copy.RearAirHoseShapeFileName;
+            RearAirHoseAnimWidthM = copy.RearAirHoseAnimWidthM;
+            RearAirHoseAnimHeightM = copy.RearAirHoseAnimHeightM;
+            RearAirHoseAnimLengthM = copy.RearAirHoseAnimLengthM;
+            
+            RearAirHoseDisconnectedShapeFileName = copy.RearAirHoseDisconnectedShapeFileName;
+            RearAirHoseDisconnectedAnimWidthM = copy.RearAirHoseDisconnectedAnimWidthM;
+            RearAirHoseDisconnectedAnimHeightM = copy.RearAirHoseDisconnectedAnimHeightM;
+            RearAirHoseDisconnectedAnimLengthM = copy.RearAirHoseDisconnectedAnimLengthM;
+
             CarWidthM = copy.CarWidthM;
             CarHeightM = copy.CarHeightM;
             CarLengthM = copy.CarLengthM;
@@ -1330,10 +1438,15 @@ public virtual void Copy(MSTSWagon copy)
             InitialCentreOfGravityM = copy.InitialCentreOfGravityM;
             UnbalancedSuperElevationM = copy.UnbalancedSuperElevationM;
             RigidWheelBaseM = copy.RigidWheelBaseM;
+            CarBogieCentreLengthM = copy.CarBogieCentreLengthM;
+            CarBodyLengthM = copy.CarBodyLengthM;
+            CarCouplerFaceLengthM = copy.CarCouplerFaceLengthM;
+            CarAirHoseLengthM = copy.CarAirHoseLengthM;
             AuxTenderWaterMassKG = copy.AuxTenderWaterMassKG;
             TenderWagonMaxCoalMassKG = copy.TenderWagonMaxCoalMassKG;
             TenderWagonMaxWaterMassKG = copy.TenderWagonMaxWaterMassKG;
             WagonNumAxles = copy.WagonNumAxles;
+            WagonNumBogies = copy.WagonNumBogies;
             MSTSWagonNumWheels = copy.MSTSWagonNumWheels;
             MassKG = copy.MassKG;
             InitialMassKG = copy.InitialMassKG;