Support for multiple superelevation standards

Author: SteelFill

Source/Documentation/Manual/features-route.rst

@@ -867,6 +867,7 @@ Defining Curve Superelevation
    single: MaxRunOffSlope
    single: MaxRunOffSpeed
    single: MinimumSpeed
+   single: MaximumSpeed
 
 This feature allows curves within the route to be assigned a value for superelevation. It
 is inserted either in the route's root .trk file or in the "Include" .trk file.
@@ -879,7 +880,8 @@ To define a superelevation standard, add a ``ORTSSuperElevation`` block to the r
 file and add some (or all) of the following parameters inside the ``ORTSSuperElevation`` block:
 
 - ``MaxFreightUnderbalance`` -- The maximum amount (using units of length) of cant deficiency/underbalance
-  that should be allowed for trains travelling at the freight speed limit. (Default 5 cm ~ 2 inches.)
+  that should be allowed for trains travelling at the freight speed limit. Larger allowed underbalance
+  results in less extreme superelevation. (Default 5 cm ~ 2 inches.)
 - ``MaxPassengerUnderbalance`` -- The maximum amount (using units of length) of cant deficiency/underbalance
   that should be allowed for trains travelling at the passenger speed limit. (Default 7.5 cm ~ 3 inches.)
   For comfort reasons, the underbalance values should be equal to or less than the
@@ -889,7 +891,8 @@ file and add some (or all) of the following parameters inside the ``ORTSSuperEle
 - ``MinimumCant`` -- If a curve needs superelevation, the amount of superelevation will be no lower than
   this value (given in units of length). (Default 1.25 cm ~ 0.5 inches.)
 - ``MaximumCant`` -- Sets the maximum amount of superelevation (units of length) that any curve is allowed
-  to have, regardless of other factors. Usually curves should be designed to avoid reaching this limit.
+  to have, regardless of other factors. Usually curves should be designed to avoid reaching this limit, as
+  exceeding the limit could result in excessive curve force or even trains toppling over at low speeds.
   (Default is determined by the superelevation setting in the options menu. Level 0 = 7 cm, level 10 = 17 cm.)
 - ``Precision`` -- Determines the accuracy (in length) to which the superelevation is maintained. If
   the superelevation required by a curve is not a nice number, it will be rounded up to the nearest
@@ -902,6 +905,9 @@ file and add some (or all) of the following parameters inside the ``ORTSSuperEle
   track at high speeds. (Default 4 cm/sec ~ 1.5 inches/sec.)
 - ``MinimumSpeed`` -- The minimum speed limit required for superelevation to be added to a curve. Useful for
   preventing superelevation from being generated in yards. (Default 25 kmh ~ 15 mph.)
+- ``MaximumSpeed`` -- The maximum speed limit allowed for superelevation to be added to a curve. This
+  is only useful if a route needs multiple sets of superelevation settings. See section below for a
+  description on use of multiple superelevation standards. (Default unlimited.)
 
 Any parameters not specified will use the default values, which are suitable for most medium-speed routes.
 Upon route loading, the given parameters will be used to calculate the appropriate amount of superelevation
@@ -919,6 +925,33 @@ defines the superelevation standard used by Union Pacific is given below::
 		MinimumSpeed ( 15mph )
     )
 
+More than one ``ORTSSuperElevation`` block can be added to the .trk file to facilitate routes that require
+different superelevation standards for different track speeds (for example, a route with both standard speed
+160 kmh tracks and dedicated 300 kmh high speed tracks). If a track has a speed limit below ``MinimumSpeed``
+or above ``MaximumSpeed``, the track will skip the superelevation standard defined and check the next standard in
+the .trk file to see if the speed limit is in between the min and max of that standard. Only if the track
+speed is out of bounds for every superelevation standard will no superelevation be applied at all. For
+example, to have 3 different types of superelevation on one route, one from 25-60 kmh, another from 60-160 kmh,
+and a third standard for 160 kph and up, the required Minimum/MaximumSpeed settings would look like this::
+
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 25km/h )
+		MaximumSpeed ( 60km/h )
+    )
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 60km/h )
+		MaximumSpeed ( 160km/h )
+    )
+    ORTSSuperElevation(
+        ...
+		MinimumSpeed ( 160km/h )
+    )
+
+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.

Source/Orts.Formats.Msts/RouteFile.cs

@@ -105,7 +105,8 @@ public Tr_RouteFile(STFReader stf)
 				new STFReader.TokenProcessor("ortsuserpreferenceremoveforesttreesfromroads", ()=>{ RemoveForestTreesFromRoads = stf.ReadBoolBlock(false); }),
                 // values for superelevation
                 new STFReader.TokenProcessor("ortstracksuperelevation", ()=>{ SuperElevationHgtpRadiusM = new Interpolator(stf); }),
-                new STFReader.TokenProcessor("ortssuperelevation", ()=>{ SuperElevationHgtpRadiusM = null; SuperElevation = new SuperElevationStandard(stf); }),
+                // New superelevation standard, will overwrite ORTSTrackSuperElevation
+                new STFReader.TokenProcessor("ortssuperelevation", ()=>{ SuperElevationHgtpRadiusM = null; SuperElevation.Add(new SuperElevationStandard(stf)); }),
                 // images
                 new STFReader.TokenProcessor("graphic", ()=>{ Thumbnail = stf.ReadStringBlock(null); }),
                 new STFReader.TokenProcessor("loadingscreen", ()=>{ LoadingScreen = stf.ReadStringBlock(null); }),
@@ -130,7 +131,7 @@ public Tr_RouteFile(STFReader stf)
             if (Description == null) throw new STFException(stf, "Missing Description");
             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 == null) SuperElevation = new SuperElevationStandard();
+            if (SuperElevation.Count <= 0) SuperElevation.Add(new SuperElevationStandard());
         }
 
         public string RouteID;  // ie JAPAN1  - used for TRK file and route folder name
@@ -151,7 +152,7 @@ public Tr_RouteFile(STFReader stf)
         public string DefaultSignalSMS;
 		public float TempRestrictedSpeed = -1f;
         public Interpolator SuperElevationHgtpRadiusM; // Superelevation of tracks as a function of radius, deprecated
-        public SuperElevationStandard SuperElevation;
+        public List<SuperElevationStandard> SuperElevation = new List<SuperElevationStandard>();
 
         // Values for calculating Tunnel Resistance - will override default values.
         public float SingleTunnelAreaM2; 
@@ -227,14 +228,15 @@ public string ENVFileName(SeasonType seasonType, WeatherType weatherType)
 
     public class SuperElevationStandard
     {
-        public float SuperElevationMaxFreightUnderbalanceM = 0.05f; // Default 5 cm ~ 2 inches
-        public float SuperElevationMaxPaxUnderbalanceM = 0.075f; // Default 7.5 cm ~ 3 inches
-        public float SuperElevationMinCantM = 0.0125f; // Default 1.25 cm ~ 0.5 inches
-        public float SuperElevationMaxCantM; // Specified by user settings by default
-        public float SuperElevationMinSpeedMpS = MpS.FromKpH(25.0f); // Default 25 kmh ~ 15 mph
-        public float SuperElevationPrecisionM = 0.005f; // Default 5 mm ~ 0.2 inches
-        public float SuperElevationRunoffSlope = 0.003f; // Maximum rate of change of superelevation per track length, default 0.3%
-        public float SuperElevationRunoffSpeedMpS = 0.04f; // Maximum rate of change of superelevation per second, default 4 cm / sec ~ 1.5 inches / sec
+        public float MaxFreightUnderbalanceM = 0.05f; // Default 5 cm ~ 2 inches
+        public float MaxPaxUnderbalanceM = 0.075f; // Default 7.5 cm ~ 3 inches
+        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 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 SuperElevationStandard()
         {
@@ -244,16 +246,16 @@ public SuperElevationStandard(STFReader stf)
         {
             stf.MustMatch("(");
             stf.ParseBlock(new STFReader.TokenProcessor[] {
-                new STFReader.TokenProcessor("maxfreightunderbalance", () => { SuperElevationMaxFreightUnderbalanceM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
-                new STFReader.TokenProcessor("maxpassengerunderbalance", () => { SuperElevationMaxPaxUnderbalanceM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
-                new STFReader.TokenProcessor("minimumcant", () => { SuperElevationMinCantM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
-                new STFReader.TokenProcessor("maximumcant", () => { SuperElevationMaxCantM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
-                new STFReader.TokenProcessor("minimumspeed", () => { SuperElevationMinSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
-                new STFReader.TokenProcessor("precision", () => { SuperElevationPrecisionM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
-                new STFReader.TokenProcessor("maxrunoffslope", () => { SuperElevationRunoffSlope = stf.ReadFloatBlock(STFReader.UNITS.None, null); }),
-                new STFReader.TokenProcessor("maxrunoffspeed", () => { SuperElevationRunoffSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
+                new STFReader.TokenProcessor("maxfreightunderbalance", () => { MaxFreightUnderbalanceM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("maxpassengerunderbalance", () => { MaxPaxUnderbalanceM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("minimumcant", () => { MinCantM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("maximumcant", () => { MaxCantM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("minimumspeed", () => { MinSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
+                new STFReader.TokenProcessor("maximumspeed", () => { MaxSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
+                new STFReader.TokenProcessor("precision", () => { PrecisionM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("maxrunoffslope", () => { RunoffSlope = stf.ReadFloatBlock(STFReader.UNITS.None, null); }),
+                new STFReader.TokenProcessor("maxrunoffspeed", () => { RunoffSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
             });
-            stf.SkipRestOfBlock();
         }
     }