Merge pull request #954 from SteelFill/multi_track_profiles

Multiple Track Profiles & Superelevation Rewrite

Author: cjakeman

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

@@ -64,12 +64,16 @@ Volumetric Flow         m^3/s           air flow    m^3/s
 \                                                   L/min
 \                                                   L/s
 Speed                   m/s             other       m/s         m/s             meter per second
+\                                                   cm/s                        centimeters per second
+\                                                   mm/s                        millimeters per second
 \                                                   km/h
 \                                                   kph         kph             kilometer per hour
-\                                                   kmh         kmh             misspelling accepted by MSTS
-\                                       kmph
-\                       mph             dynamic     mph         mph             miles per hour 
-                                        brake
+\                                                   kmh         kmh,            misspelling accepted by MSTS
+                                                                kmph
+\                       mph             dynamic     mph         mph             miles per hour, 
+                                        brake                                   legacy dynamic brake parameters use mph default
+\                                                   ft/s                        feet per second
+\                                                   in/s                        inches per second
 Frequency               Hz                          Hz                          Hertz
 \                                                   rps                         revolutions per second
 \                                                   rpm

Source/Documentation/Manual/appendices.rst

@@ -22,7 +22,7 @@ Rolling Stock
 - 3D cabs add realism.
 - OR graphics renders the results of the rolling stock developers at higher 
   resolution.
-- Rolling stock running on super-elevated track improves gaming experience.
+- Rolling stock running on superelevated track improves gaming experience.
 
 Routes
 ======

Source/Documentation/Manual/developing.rst

@@ -858,24 +858,147 @@ Defining Curve Superelevation
 
 .. index::
    single: ORTSTrackSuperElevation
+   single: ORTSSuperElevation
+   single: MaxFreightUnderbalance
+   single: MaxPassengerUnderbalance
+   single: MinimumCant
+   single: MaximumCant
+   single: Precision
+   single: MaxRunOffSlope
+   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.
+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
+  that should be allowed for trains travelling at the freight speed limit. Larger allowed underbalance
+  results in less extreme superelevation. (Default 100 mm for metric routes, 2 in for imperial routes.)
+- ``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 150 mm / 3 in.)
+  For comfort reasons, the underbalance values should be equal to or less than the
+  ``ORTSUnbalancedSuperElevation`` value used by the rolling stock on the route. If the superelevation
+  required to achieve the max passenger underbalance is different from that required for freight, the
+  curve will use whichever superelevation is larger (the actual amount of underbalance may be lower).
+- ``MinimumCant`` -- If a curve needs superelevation, the amount of superelevation will be no lower than
+  this value (given in units of length). (Default 10 mm / 0.5 in.)
+- ``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, as
+  exceeding the limit could result in excessive curve force or even trains toppling over at low speeds.
+  (Default 180 mm / 6 in.)
+- ``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
+  multiple of ``Precision``. (Default 5 mm / 0.25 in.)
+- ``MaxRunOffSlope`` -- Sets a limit on the amount of change in superelevation per unit length along a curve
+  (quantity is unitless). This allows for smooth transition between flat and superelevated track at low speeds.
+  (Default 0.003.)
+- ``MaxRunOffSpeed`` -- Sets a limit on the amount of change in superelevation per second (units of speed) when
+  travelling at the max speed for the curve. This allows for smooth transition between flat and superelevated
+  track at high speeds. (Default 55 mm/sec / 1.5 in/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
+for each curve based on the curve radius and speed limits. An example ``ORTSSuperElevation`` block which
+defines the superelevation standard used by Union Pacific is given below::
+
+    ORTSSuperElevation(
+		MaxFreightUnderbalance ( 1in )
+		MaxPassengerUnderbalance ( 3in )
+		MinimumCant ( 0.25in )
+		MaximumCant ( 5in )
+		Precision ( 0.25in )
+		MaxRunOffSlope ( 0.0019 )
+		MaxRunOffSpeed ( 1.25in/s )
+		MinimumSpeed ( 15mph )
+    )
 
-It should be noted that currently this information only applies to physics calculations 
-for superelevation. The visual movement of the train due to superelevation is set within 
-the option menu.
+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::
 
-The values are assigned by inserting the following parameter::
+    ORTSSuperElevation(
+		MaximumCant ( 0 )
+    )
 
-   ORTSTrackSuperElevation ( x y .......... )
+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 way to define superelevation based on curve radius only, resulting
+in the same superelevation regardless of track speed. If a railroad uses this simplified method, they
+would provide a table of track curve radii and the superelevation used at that radius (usually also
+including a maximum speed for the curve). This table can then be provided to OR using the
+``ORTSTrackSuperElevation`` parameter in the .trk file::
+
+    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
-to 'hold' a certain value of SuperElevation for a number of different radii curves, then the same 
+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

@@ -40,6 +40,7 @@ What's been improved
 - controls for electric locos
 - air brake features for both European and American brake systems 
 - accurate friction simulation for 4 types of brake shoes
+- superelevation system rewritten to be smoother and more configurable
 
 
 Other changes

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

@@ -736,16 +736,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.
 
-Super-elevation
+.. _options-superelevation:
+
+Superelevation
 ---------------
 
-If the value set for *Level* is greater than zero, ORTS supports super-elevation 
-for long curved tracks. The value *Minimum Length* determines
-the length of the shortest curve to have super-elevation. You need to
-choose the correct gauge for your route, otherwise some tracks may not be
-properly shown.
+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 super-elevation 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.
@@ -755,15 +785,16 @@ When super-elevation is selected, two viewing effects occur at runtime:
 .. image:: images/options-superelevation_1.png
 .. image:: images/options-superelevation_2.png
 
-OR implements super-elevated tracks using Dynamic Tracks. You can change
-the appearance of tracks by creating a ``<route folder>/TrackProfiles/
-TrProfile.stf`` file. 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>`_.
+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.
+
+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: