Rework options so superelevation is enabled by default in most cases, rather than always disabled by default

Author: SteelFill

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

@@ -868,15 +868,27 @@ Defining Curve Superelevation
    single: MaxRunOffSpeed
    single: MinimumSpeed
    single: MaximumSpeed
+   single: ORTSForceSuperElevation
+   single: TrackGauge
 
 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.
-
-The superelevation standard defined here will control the simulated level of superelevation on
-each track section on the entire route and, if enabled in the options, the amount of visual
-superelevation generated by the dynamic track system.
-
-To define a superelevation standard, add a ``ORTSSuperElevation`` block to the route's .trk
+is inserted either in the route's root .trk file or in the "Include" .trk file. Before
+starting, the predominant gauge of track on the route should be given using the legacy
+``TrackGauge`` token. The default units used are meters, though other units are supported
+as in other parts of the program. If ``TrackGauge`` is set to 0 (like most MSTS routes)
+or not present in the .trk file, then the default gauge given in the
+:ref:`Superelevation Options <options-superelevation>` will be used for superelevation calculations.
+
+Defining a superelevation standard in the .trk file will control both the simulated level of
+superelevation on each track section on the entire route and the amount of visual
+superelevation generated by the dynamic track system. However, in some cases it may be desired
+to manually influence the use of visual superelevation due to (un)desired graphical effects.
+The token ``ORTSForceSuperElevation`` can be given a true/false value to force enable/disable
+visual superelevation effects regardless of user settings and other ORTS behaviors. Adding
+this token will have no impact on the physical simulation of superelevation, this only forces
+the graphical elements to be enabled or disabled.
+
+To define a superelevation standard, add an ``ORTSSuperElevation`` block to the route's .trk
 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
@@ -925,6 +937,15 @@ defines the superelevation standard used by Union Pacific is given below::
 		MinimumSpeed ( 15mph )
     )
 
+Note that it is also possible to create a superelevation standard which entirely disables superelevation
+on the route, should the real railroad not use superelevation. This can be achieved by setting
+``MaximumCant ( 0 )`` and leaving all other values default. Note that this disables both physics and visual
+superelevation::
+
+    ORTSSuperElevation(
+		MaximumCant ( 0 )
+    )
+
 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``

Source/Documentation/Manual/features-route.rst

@@ -766,16 +766,46 @@ Some experimental features being introduced in Open Rails may be turned on
 and off through the *Experimental* tab of the Options window, as
 described below.
 
+.. _options-superelevation:
+
 Superelevation
 ---------------
 
-If "Use Visual Superelevation" is enabled, ORTS applies superelevation graphics
-to curves on every route. For the best results, you need to enter
-the correct gauge for your route, otherwise the resulting superelevation
-may not be accurate. Note that the physics system will always consider the
-physical effects of superelevation regardless of this setting.
+ORTS implements graphical superelevation (tilting) of tracks using Dynamic Tracks.
+For superelevation to appear, the route must have one (or more) ``<route folder>/TrackProfiles/
+TrProfile.stf`` files. A document describing the creation of track profiles, ``How to
+Provide Track Profiles for Open Rails Dynamic Track.pdf``, can be found in the
+*Menu > Documents* drop-down or the Open Rails ``/Source/Documentation/`` folder. Forum
+discussions about track profiles can also be found on `Elvas Tower
+<http://www.elvastower.com/forums/index.php?/topic/21119-superelevation/
+page__view__findpost__p__115247>`_.
 
-When visual superelevation is selected, two viewing effects occur at runtime:
+However, superelevation will also appear if the route has a superelevation standard
+``ORTSSuperElevation`` :ref:`defined within the route's .trk file <features-route-curve-superelevation>`
+regardless of the use of track profiles. *It is recommended to combine* **both** *track profiles
+and ``ORTSSuperElevation`` for best results*, as dynamic track (ie: superelevation) is rendered
+as Kuju track without any track profiles installed, which may not appear correct.
+
+.. note::
+    
+    This behavior can be overwritten if ``ORTSForceSuperElevation ( 0/1 )`` is present in the .trk file.
+    A setting of 0 will always disable superelevation graphics, while 1 always enables it, regardless
+    of the criteria described here.
+
+To support routes without Track Profiles and without ``ORTSSuperElevation``, the
+"Legacy Superelevation" option can be enabled. This will activate superelevation visuals
+on routes regardless of missing data, which may be appropriate for original MSTS routes but
+will not be aesthetically pleasing for routes using more modern track shapes. Experimentation
+may be required to determine the correct setting, and *editing of routes* (to add data to the
+.trk file and/or to add track profiles) will be required for best results.
+
+.. note::
+    
+    The configuration described here only affects the visual depiction of superelevation.
+    Superelevation is still considered by train physics regardless of the state of the visual system.
+
+When visual superelevation is enabled (either through correct configuration of a route,
+or enabled with the "Legacy Superelevation" option), two viewing effects occur at runtime:
 
 1. If an external camera view is selected, the tracks and the running
    train will be shown inclined towards the inside of the curve.
@@ -785,18 +815,16 @@ When visual superelevation is selected, two viewing effects occur at runtime:
 .. image:: images/options-superelevation_1.png
 .. image:: images/options-superelevation_2.png
 
-The amount of superelevation applied can be customized
-:ref:`from within the route's .trk file <features-route-curve-superelevation>`.
+Note that superelevation usually won't be this distinct. The amount of superelevation
+depends on the track speed limit and curve radius, where higher speeds and tighter curves
+lead to more intense superelevation.
 
-OR implements superelevated tracks using Dynamic Tracks. You can change
-the appearance of tracks by creating one (or more) ``<route folder>/TrackProfiles/
-TrProfile.stf`` files. The document ``How to Provide Track Profiles for
-Open Rails Dynamic Track.pdf`` describing the creation of track profiles
-can be found in the *Menu > Documents* drop-down or the 
-Open Rails ``/Source/Documentation/`` folder. Forum
-discussions about track profiles can also be found on `Elvas Tower
-<http://www.elvastower.com/forums/index.php?/topic/21119-superelevation/
-page__view__findpost__p__115247>`_.
+Additionally, the superelevation physics system requires knoweldge of the gauge of track used on
+the route. Normally, this should be defined with ``TrackGauge``
+:ref:`in the .trk file <features-route-curve-superelevation>`, but many routes have the gauge value
+set to 0, which is not useful. In such a case, the program must use the gauge (in millimeters)
+specified by the "Default Gauge" option. Note this assumes the entire route has the same gauge of track.
+Multi-gauge routes are not fully supported at the moment.
 
 
 .. _options-shape-warnings:

Source/Documentation/Manual/images/options-experimental.png

@@ -95,7 +95,8 @@ rigid wheel base, track gauge and super elevation. The curve resistance
 has its lowest value at the curve's optimal speed. Running at higher or
 lower speed causes higher curve resistance. The worst situation is
 starting a train from zero speed. The track gauge value can be set by
-``ORTSTrackGauge`` parameter, otherwise 1435 mm is used. The rigid wheel base
+``ORTSTrackGauge`` parameter, otherwise the gauge is assumed to be the
+gauge specified in the route's .trk file. The rigid wheel base
 can be also set by ``ORTSRigidWheelBase``, otherwise the value is estimated.
 Further details are discussed later.
 

Source/Documentation/Manual/options.rst

@@ -902,6 +902,9 @@ private void InitializeHelpIcons()
                 (pbControlConfirmations, new Control[] { labelControlConfirmations, comboControlConfirmations }),
                 (pbWebServerPort, new Control[] { labelWebServerPort }),
                 (pbPerformanceTuner, new Control[] { checkPerformanceTuner, labelPerformanceTunerTarget }),
+
+                // Experimental tab
+                (pbSuperElevation, new[] { ElevationText }),
             };
             foreach ((PictureBox pb, Control[] controls) in helpIconControls)
             {
@@ -1060,6 +1063,12 @@ private void HelpIcon_Click(object sender, EventArgs _)
                     pbPerformanceTuner,
                     baseUrl + "/options.html#performance-tuner"
                 },
+
+                // Experimental tab
+                {
+                    pbSuperElevation,
+                    baseUrl + "/options.html#super-elevation"
+                },
             };
             if (urls.TryGetValue(sender, out var url))
             {

Source/Documentation/Manual/physics.rst

@@ -108,6 +108,8 @@ public Tr_RouteFile(STFReader stf)
                 new STFReader.TokenProcessor("ortstracksuperelevation", ()=>{ SuperElevationHgtpRadiusM = new Interpolator(stf); }),
                 // New superelevation standard, will overwrite ORTSTrackSuperElevation
                 new STFReader.TokenProcessor("ortssuperelevation", ()=>{ SuperElevation.Add(new SuperElevationStandard(stf)); }),
+                new STFReader.TokenProcessor("trackgauge", ()=>{ RouteGaugeM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); }),
+                new STFReader.TokenProcessor("ortsforcesuperelevation", ()=>{ SuperElevationMode = stf.ReadBoolBlock(false) ? 1 : 0; }),
                 // images
                 new STFReader.TokenProcessor("graphic", ()=>{ Thumbnail = stf.ReadStringBlock(null); }),
                 new STFReader.TokenProcessor("loadingscreen", ()=>{ LoadingScreen = stf.ReadStringBlock(null); }),
@@ -159,6 +161,8 @@ public Tr_RouteFile(STFReader stf)
         public string DefaultWaterTowerSMS;
         public string DefaultSignalSMS;
 		public float TempRestrictedSpeed = -1f;
+        public float RouteGaugeM; // Track gauge used by this route in meters. FUTURE: Better handling of track gauge to support routes with mixed gauges
+        public int SuperElevationMode = -1; // -1: use simulator setting, 0: force disable visual superelevation, 1: force enable visual superelevation
         public Interpolator SuperElevationHgtpRadiusM; // Superelevation of tracks as a function of radius, deprecated
         public List<SuperElevationStandard> SuperElevation = new List<SuperElevationStandard>();
 
@@ -246,6 +250,7 @@ public class SuperElevationStandard
         public float RunoffSlope = 0.003f; // Maximum rate of change of superelevation per track length, default 0.3%
         public float RunoffSpeedMpS = 0.055f; // Maximum rate of change of superelevation per second, default 55 mm / sec (1.5 inches / sec on imperial routes)
         public bool UseLegacyCalculation = true; // Should ORTSTrackSuperElevation be used for superelevation calculations?
+        public bool DefaultStandard = true; // Is this standard a default (auto-generated) one?
 
         // Initialize new instance with default values (default metric values)
         public SuperElevationStandard(bool metric = true, bool highSpeed = false)
@@ -331,6 +336,8 @@ public SuperElevationStandard(STFReader stf)
                 new STFReader.TokenProcessor("maxrunoffspeed", () => { RunoffSpeedMpS = stf.ReadFloatBlock(STFReader.UNITS.Speed, null); }),
             });
 
+            DefaultStandard = false;
+
             // Disable legacy superelevation calculations if sufficient data is given
             if (MaxFreightUnderbalanceM <= 10.0f || MaxPaxUnderbalanceM <= 10.0f)
                 UseLegacyCalculation = false;

Source/Menu/Options.Designer.cs

@@ -1129,6 +1129,9 @@ public virtual void LoadFromWagFile(string wagFilePath)
 
             if (BrakeSystem == null)
                 BrakeSystem = MSTSBrakeSystem.Create(CarBrakeSystemType, this);
+
+            if (TrackGaugeM <= 0) // Use gauge of route/sim settings if gauge wasn't defined
+                TrackGaugeM = Simulator.RouteTrackGaugeM;
         }
 
         // Compute total mass of wagon including freight animations and variable loads like containers