Automatic merge of T1.5.1-1088-g264349b1ce and 20 pull requests

- Pull request #891 at 9a1d6b2: Auto save
- Pull request #954 at 3efaf6d: Multiple Track Profiles & Superelevation Improvements
- Pull request #959 at 2452cb0: Fix TrackViewer crash on big zoom value
- Pull request #972 at e90a2aa: On Map window color changed switch or signal is not changed
- Pull request #976 at 877cc94:  Increased center of gravity range
- Pull request #839 at d00beb9: First phase of https://blueprints.launchpad.net/or/+spec/additional-cruise-control-parameters
- Pull request #882 at 8f695a4: Blueprint/train car operations UI window
- Pull request #892 at 1f5ba4c: Signal Function OPP_SIG_ID_TRAINPATH
- Pull request #922 at a3bc9e7: Autopilot for timetable mode
- Pull request #953 at a519452: Fix Lights Crash on Corrupt Shapes
- Pull request #962 at 46d0472: Fix pantographs on unpowered cars
- Pull request #970 at 6fa5eed: feat: Remove unnecessary Windows.Forms usage
- Pull request #973 at c35be87: fix: Using singular target framework to allow for different platforms across different projects
- Pull request #974 at 5faea6f: Bug fix for https://bugs.launchpad.net/or/+bug/2076034 Doors remain open in AI trains
- Pull request #975 at b2dd5c0: Bug fix for https://bugs.launchpad.net/or/+bug/2076133 Crash when AI train dissolves near camera
- Pull request #900 at c27f32d: DMI updates
- Pull request #903 at 9dabe97: Downloading route content (Github, zip)
- Pull request #799 at dfc715e: Consolidated wind simulation
- Pull request #876 at f92de76: docs: add source for documents previously on website to source Documentation folder
- Pull request #952 at 8347095: Investigation - Pulsing graphics

Author: openrails-bot

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();
         }
     }