Reduce floating point errors, stop use of consist durability, improve support for older superelevation parameters, simplify superelevation settings

Author: SteelFill

Source/Documentation/How to Provide Track Profiles for Open Rails Dynamic Track.docm

@@ -952,20 +952,32 @@ and a third standard for 160 kph and up, the required Minimum/MaximumSpeed setti
 Note that the order of the ``ORTSSuperElevation`` blocks is important; they are read from top down
 so the slowest superelevation standard should be on top of all faster superelevation standards.
 
-Open Rails also supports a simpler but less accurate way to define superelevation. It is
-recommended to not use this system as it does not follow the principles of real superelevation
-design, producing less accurate results. However, it has been retained to support prior routes.
+Open Rails also supports a simpler but less modern way to define superelevation based on curve
+radius only, without consideration for underbalance. This method may be appropriate for railroads
+built long in the past and will not produce the best results for modern routes.
 The parameter ``ORTSTrackSuperElevation`` can be added to the .trk file to define a table
 of superelevation values::
 
-   ORTSTrackSuperElevation ( x y .......... )
+    ORTSTrackSuperElevation (
+        x1 y1
+        x2 y2
+        ........
+    )
    
-where x and y are a series of paired parameters specifying the curve radius in metres (x value),
-and the amount of superelevation in metres (y value). The statement will take as many paired 
-values as desired. Each paired set of values must have an x and y value present. If it is desired
+where x and y are a series of paired parameters specifying the curve radius (default meters)
+(x value), and the amount of superelevation (default meters) (y value). The statement will take
+as many paired values as desired, as long as the radius values are in increasing order.
+Each paired set of values must have an x and y value present. If it is desired
 to 'hold' a certain value of SuperElevation for a number of different radii curves, then the same 
 y value needs to be used for succeeding values of curve radius. Where the y value changes between 
-curve radii, then Open Rails will extrapolate the y value between the two points. 
+curve radii, then Open Rails will interpolate the y value between the two points.
+
+Superelevation calculated using ``ORTSSuperElevation`` will generally override any values
+entered in ``ORTSTrackSuperElevation`` unless the ``ORTSSuperElevation`` block did not specify
+a value for ``MaxFreightUnderbalance`` or ``MaxPassengerUnderbalance``. If neither is given,
+superelevation will be replaced with the value given by ``ORTSTrackSuperElevation``, but will
+be adjusted to match the given values of minimum and maximum cant, precision, and runoff. This
+way, it is possible to represent a wide variety of superelevation configurations.
 
 
 Overhead (catenary) wire

Source/Documentation/Manual/features-route.rst

@@ -325,7 +325,7 @@ orderby folder.Key
             numericPerformanceTunerTarget.Enabled = checkPerformanceTuner.Checked;
 
             // Experimental tab
-            numericUseSuperElevation.Value = Settings.UseSuperElevation;
+            checkUseSuperElevation.Checked = Settings.UseSuperElevation;
             numericSuperElevationGauge.Value = Settings.SuperElevationGauge;
             trackLODBias.Value = Settings.LODBias;
             trackLODBias_ValueChanged(null, null);
@@ -515,7 +515,7 @@ void buttonOK_Click(object sender, EventArgs e)
             Settings.PerformanceTunerTarget = (int)numericPerformanceTunerTarget.Value;
 
             // Experimental tab
-            Settings.UseSuperElevation = (int)numericUseSuperElevation.Value;
+            Settings.UseSuperElevation = checkUseSuperElevation.Checked;
             Settings.SuperElevationGauge = (int)numericSuperElevationGauge.Value;
             Settings.LODBias = trackLODBias.Value;
             Settings.SignalLightGlow = checkSignalLightGlow.Checked;

Source/Menu/Options.Designer.cs

@@ -288,7 +288,7 @@ public enum DirectXFeature
 
         // Experimental settings:
         [Default(0)]
-        public int UseSuperElevation { get; set; }
+        public bool UseSuperElevation { get; set; }
         [Default(1435)]
         public int SuperElevationGauge { get; set; }
         [Default(0)]

Source/Menu/Options.cs

@@ -132,7 +132,6 @@ public Tr_RouteFile(STFReader stf)
             if (RouteStart == null) throw new STFException(stf, "Missing RouteStart");
             if (ForestClearDistance == 0 && RemoveForestTreesFromRoads) Trace.TraceWarning("You must define also ORTSUserPreferenceForestClearDistance to avoid trees on roads");
             if (SuperElevation.Count <= 0) SuperElevation.Add(new SuperElevationStandard());
-            else SuperElevationHgtpRadiusM = null; // Disable legacy superelevation system if newer system is defined
         }
 
         public string RouteID;  // ie JAPAN1  - used for TRK file and route folder name
@@ -232,12 +231,13 @@ public class SuperElevationStandard
         public float MaxFreightUnderbalanceM = float.PositiveInfinity;
         public float MaxPaxUnderbalanceM = float.PositiveInfinity;
         public float MinCantM = 0.0125f; // Default 1.25 cm ~ 0.5 inches
-        public float MaxCantM = -1.0f; // Specified by user settings by default
+        public float MaxCantM = 0.15f; // Default limit on superelevation is 15 cm ~ 6 inches
         public float MinSpeedMpS = MpS.FromKpH(25.0f); // Default 25 kmh ~ 15 mph
         public float MaxSpeedMpS = float.PositiveInfinity; // Default unlimited
         public float PrecisionM = 0.005f; // Default 5 mm ~ 0.2 inches
         public float RunoffSlope = 0.003f; // Maximum rate of change of superelevation per track length, default 0.3%
         public float RunoffSpeedMpS = 0.04f; // Maximum rate of change of superelevation per second, default 4 cm / sec ~ 1.5 inches / sec
+        public bool UseLegacyCalculation = true; // Should ORTSTrackSuperElevation be used for superelevation calculations?
 
         public SuperElevationStandard()
         {
@@ -260,6 +260,9 @@ public SuperElevationStandard(STFReader stf)
                 new STFReader.TokenProcessor("maxrunoffspeed", () => { RunoffSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
             });
 
+            // Disable legacy superelevation calculations if sufficient data is given
+            if (MaxFreightUnderbalanceM <= 10.0f || MaxPaxUnderbalanceM <= 10.0f)
+                UseLegacyCalculation = false;
             // Sanity check values of underbalance
             if (MaxFreightUnderbalanceM > 10.0f)
             {

Source/ORTS.Settings/UserSettings.cs

@@ -640,7 +640,7 @@ public Direction Direction
         protected float MaxUnbalancedSuperElevationM;  // Maximum comfortable cant deficiency, read from MSTS Wagon File
         public float SuperElevationAngleRad;
         protected bool IsMaxSafeCurveSpeed = false; // Has equal loading speed around the curve been exceeded, ie are all the wheesl still on the track?
-        protected float ComfortTolerance = 100.0f; // Tolerance for discomfort due to excess curve speed
+        protected float ComfortTolerance = 1.0f; // Tolerance for discomfort due to excess curve speed
         public bool IsCriticalMaxSpeed = false; // Has the critical maximum speed around the curve been reached, is the wagon about to overturn?
         public bool IsCriticalMinSpeed = false; // Is the speed less then the minimum required for the wagon to travel around the curve
         protected float StartCurveResistanceFactor = 2.0f; // Set curve friction at Start = 200%
@@ -1912,9 +1912,8 @@ public virtual void UpdateCurveSpeedLimit(float elapsedClockSeconds)
                 if (s > MaxSafeCurveSpeedMps)
                 {
                     // Consider a tolerance so passengers won't immediately complain, should reduce overkill notifications on routes with jerky track laying
-                    // Tolerance rapidly dies as speed excess increases, though lasts longer with consist durability set higher
                     // Can go negative to punish continuous speeding
-                    ComfortTolerance -= 2.5f * (s / MaxSafeCurveSpeedMps - 1.0f) * elapsedClockSeconds;
+                    ComfortTolerance -= 0.25f * (s / MaxSafeCurveSpeedMps - 1.0f) * elapsedClockSeconds;
 
                     if (!IsMaxSafeCurveSpeed && ComfortTolerance <= 0.0f)
                     {
@@ -1945,10 +1944,9 @@ public virtual void UpdateCurveSpeedLimit(float elapsedClockSeconds)
                         IsMaxSafeCurveSpeed = false; // reset flag for IsMaxSafeCurveSpeed reached - if speed on curve decreases
                     }
                     // Restore passenger tolerance gradually (100 seconds)
-                    // Consist durability affects how large tolerance can grow (min 25, max 100)
-                    ComfortTolerance += (Simulator.CurveDurability + 0.25f) * elapsedClockSeconds;
-                    if (ComfortTolerance > 75.0f * Simulator.CurveDurability + 25.0f)
-                        ComfortTolerance = 75.0f * Simulator.CurveDurability + 25.0f;
+                    ComfortTolerance += elapsedClockSeconds / 100.0f;
+                    if (ComfortTolerance > 1.0f)
+                        ComfortTolerance = 1.0f;
                 }
 
                 // If speed exceeds the overturning speed, then indicated that an error condition has been reached.
@@ -2025,10 +2023,9 @@ public virtual void UpdateCurveSpeedLimit(float elapsedClockSeconds)
                 IsMaxSafeCurveSpeed = false; // reset flag for IsMaxEqualLoadSpeed reached
 
                 // Restore passenger tolerance gradually (100 seconds)
-                // Consist durability affects how large tolerance can grow
-                ComfortTolerance += (Simulator.CurveDurability + 0.25f) * elapsedClockSeconds;
-                if (ComfortTolerance > 75.0f * Simulator.CurveDurability + 25.0f)
-                    ComfortTolerance = 75.0f * Simulator.CurveDurability + 25.0f;
+                ComfortTolerance += elapsedClockSeconds / 100.0f;
+                if (ComfortTolerance > 1.0f)
+                    ComfortTolerance = 1.0f;
             }
 
         }
@@ -2774,7 +2771,7 @@ public void ComputePosition(Traveller traveler, bool backToFront, float elapsedT
                     var y = traveler.Y;
                     var z = traveler.Z + 2048 * (traveler.TileZ - tileZ);
 
-                    Vector3 location = new Vector3(x, y, z) + traveler.CalcElevationPositionOffset(Simulator.Settings.UseSuperElevation > 0, out float r);
+                    Vector3 location = new Vector3(x, y, z) + traveler.CalcElevationPositionOffset(Simulator.Settings.UseSuperElevation, out float r);
                     // This car is flipped, so flip roll direction.
                     r *= -1;
 
@@ -2806,7 +2803,7 @@ public void ComputePosition(Traveller traveler, bool backToFront, float elapsedT
                     var y = traveler.Y;
                     var z = traveler.Z + 2048 * (traveler.TileZ - tileZ);
 
-                    Vector3 location = new Vector3(x, y, z) + traveler.CalcElevationPositionOffset(Simulator.Settings.UseSuperElevation > 0, out float r);
+                    Vector3 location = new Vector3(x, y, z) + traveler.CalcElevationPositionOffset(Simulator.Settings.UseSuperElevation, out float r);
 
                     WheelAxles[k].Part.AddWheelSetLocation(1, o, location.X, location.Y, location.Z, r);
                 }

Source/Orts.Formats.Msts/RouteFile.cs

@@ -128,7 +128,7 @@ public class Simulator
         public bool BreakCouplers;
         public int DayAmbientLight;
         public int CarVibrating;
-        public int UseSuperElevation; //amount of superelevation
+        public bool UseSuperElevation; // Whether or not visual superelevation is enabled
         public SuperElevation SuperElevation;
         public float SuperElevationGauge = 1.435f;//1.435 guage
         public LoadStationsPopulationFile LoadStationsPopulationFile;