Merge branch 'master' into gltf2

Author: pzgulyas

Docs/Architecture.md

@@ -29,6 +29,22 @@ The threading in Open Rails has two key threads working together (Render and Upd
 - Web Server process
   - Handle all web and API requests
 
+## Projects, assemblies, namespaces
+
+Open Rails is made up of several component projects which are organised into subdirectories with the following naming pattern:
+
+- `Orts.Component\Orts.Component.csproj` (project file)
+- `Orts.Component.dll` (assembly name)
+- `Orts.Component` (default namespace)
+
+The namespaces used within code files should match the directory structure like this:
+
+| *Filename* | *Namespace*
+|---|---|
+| `Orts.Component\File.cs` | `Orts.Component` |
+| `Orts.Component\Section\File.cs` | `Orts.Component.Section` |
+| `Orts.Component\Section\Subsection\File.cs` | `Orts.Component.Section.Subsection` |
+
 ## Simulator object relationships
 
 This tree is a summary of the important object relationships (aggregation) inside the simulation. Each entry is a class whose instances can be accessed from the parent item.

Docs/Readme.md

@@ -10,7 +10,7 @@ Open Rails is a free train simulator supporting the world's largest range of dig
 ## Documentation
 
 * [Read the FAQ](http://www.openrails.org/learn/faq/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
-* [Read the manual online](https://open-rails.readthedocs.io/en/1.3.1/) or the PDF included with the program, found in the main menu under "Documents"
+* [Read the manual online](https://open-rails.readthedocs.io/en/latest/) or the PDF included with the program, found in the main menu under "Documents"
 * [Get additional materials, including tutorials, from our website](http://www.openrails.org/learn/manual-and-tutorials/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
 * [Read more about the project on our website](http://www.openrails.org/discover/open-rails/?utm_campaign=documentation&utm_source=readme&utm_medium=referral)
 

Source/Documentation/Manual/physics.rst

@@ -254,7 +254,23 @@ simplicity, only one axle model is computed (and animated). A tilting
 feature and the independent axle adhesion model will be introduced in the
 future.
 
-The heart of the model is the slip characteristics (picture below).
+The advanced adhesion model uses two alternate algorithms to calculate the 
+wheel adhesion. The first model is based upon an algorithm by Pacha, whilst the second 
+uses an algorithm developed by Polach. The Polach algorithm provides 
+a more accurate outcome and facilitates the future inclusion of track conditions. 
+However due to the number of algorithm steps required to calculate the wheel adhesion 
+value, it is more CPU load intensive then the Pacha one. This can produce low 
+frame rates for the screen display in machines with low performance specifications. 
+
+Hence OR automatically senses the CPU load, and switches to the Pacha algorithm at 
+high loads and to the Polach algorithm under lower CPU loads. In this way OR attempts 
+to support the operation of lower specification computers. When OR is using the 
+Pacha algorithm, the "Wheel Adh (Max)" values will both read 99%, whereas when the 
+Polach algorithm is being used these values will be around the expected values of 30-55%.
+
+
+
+The heart of the adhesion algorithm is the slip characteristics (pictured below).
 
 .. image:: images/physics-adhesion-slip.png
    :align: center

Source/ORTS.Common/Conversions.cs

@@ -595,6 +595,15 @@ public static string FormatSpeedDisplay(float speed, bool isMetric)
                 "{0:F1} {1}", MpS.FromMpS(speed, isMetric), isMetric ? kmph : mph);
         }
 
+        /// <summary>
+        /// Formatted localized speed string, used to display tracking speed, with 2 decimal precision
+        /// </summary>
+        public static string FormatVeryLowSpeedDisplay(float speed, bool isMetric)
+        {
+            return String.Format(CultureInfo.CurrentCulture,
+                "{0:F2} {1}", MpS.FromMpS(speed, isMetric), isMetric ? kmph : mph);
+        }
+
         /// <summary>
         /// Formatted localized speed string, used to display speed limits, with 0 decimal precision
         /// </summary>

Source/Orts.Formats.Msts/TrackDatabaseFile.cs

@@ -902,7 +902,7 @@ public enum trItemType
         public float PX { get; set; }
         /// <summary>Appears to be a copy of X in Sdata, but only for X and Z</summary>
         public float PZ { get; set; }
-        /// <summary>Extra data 1, related to location along section</summary>
+        /// <summary>Distance of a track item along its containing track section and measured from the origin of the section</summary>
         public float SData1 { get; set; }
         /// <summary>Extra data 2</summary>
         public string SData2 { get; set; }

Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs

@@ -301,10 +301,9 @@ public override void LoadFromWagFile(string wagFilePath)
                     {
                         Trace.TraceInformation("MaxRailOutputPower (BASIC Config): set at arbitary value = {0}", FormatStrings.FormatPower(LocomotiveMaxRailOutputPowerW, IsMetric, false, false));
                     }
-
                 }
 
-                
+
                 if (MaximumDieselEnginePowerW == 0)
                 {
                     MaximumDieselEnginePowerW = LocomotiveMaxRailOutputPowerW;  // If no value set in ENG file, then set the Prime Mover power to same as RailOutputPower (typically the MaxPower value)
@@ -313,7 +312,6 @@ public override void LoadFromWagFile(string wagFilePath)
                         Trace.TraceInformation("Maximum Diesel Engine Prime Mover Power set the same as MaxRailOutputPower {0} value", FormatStrings.FormatPower(MaximumDieselEnginePowerW, IsMetric, false, false));
 
                 }
-
             }
 
             // Check that maximum force value has been set
@@ -330,40 +328,42 @@ public override void LoadFromWagFile(string wagFilePath)
                 }
                 else
                 {
-                    float ThrottleSetting = 1.0f; // Must be at full throttle for these calculations
+                    float throttleSetting = 1.0f; // Must be at full throttle for these calculations
                     float StartingSpeedMpS = 0.1f; // Assumed starting speed for diesel - can't be zero otherwise error will occurr
-                    float MaxForceN = TractiveForceCurves.Get(ThrottleSetting, StartingSpeedMpS);
+                    MaxForceN = TractiveForceCurves.Get(throttleSetting, StartingSpeedMpS);
 
                     if (Simulator.Settings.VerboseConfigurationMessages)
                         Trace.TraceInformation("Maximum Force set to {0} value, calcuated from Tractive Force Tables", FormatStrings.FormatForce(MaxForceN, IsMetric));
                 }
-
-
             }
 
 
-            // Check force assumptions set for diesel
-            if (Simulator.Settings.VerboseConfigurationMessages)
+            // Check force assumptions set for diesel   
+            CalculatedMaxContinuousForceN = 0;
+            float ThrottleSetting = 1.0f; // Must be at full throttle for these calculations
+            if (TractiveForceCurves == null)  // Basic configuration - ie no force and Power tables, etc
             {
-                CalculatedMaxContinuousForceN = 0;
-                float ThrottleSetting = 1.0f; // Must be at full throttle for these calculations
-                if (TractiveForceCurves == null)  // Basic configuration - ie no force and Power tables, etc
+                CalculatedMaxContinuousForceN = ThrottleSetting * LocomotiveMaxRailOutputPowerW / SpeedOfMaxContinuousForceMpS;
+
+                if (Simulator.Settings.VerboseConfigurationMessages)
                 {
-                    CalculatedMaxContinuousForceN = ThrottleSetting * LocomotiveMaxRailOutputPowerW / SpeedOfMaxContinuousForceMpS;
                     Trace.TraceInformation("Diesel Force Settings (BASIC Config): Max Starting Force {0}, Calculated Max Continuous Force {1} @ speed of {2}", FormatStrings.FormatForce(MaxForceN, IsMetric), FormatStrings.FormatForce(CalculatedMaxContinuousForceN, IsMetric), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
                     Trace.TraceInformation("Diesel Power Settings (BASIC Config): Prime Mover {0}, Max Rail Output Power {1}", FormatStrings.FormatPower(MaximumDieselEnginePowerW, IsMetric, false, false), FormatStrings.FormatPower(LocomotiveMaxRailOutputPowerW, IsMetric, false, false));
 
                     if (MaxForceN < MaxContinuousForceN)
                     {
                         Trace.TraceInformation("!!!! Warning: Starting Tractive force {0} is less then Calculated Continuous force {1}, please check !!!!", FormatStrings.FormatForce(MaxForceN, IsMetric), FormatStrings.FormatForce(CalculatedMaxContinuousForceN, IsMetric), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
                     }
-
                 }
-                else // Advanced configuration - 
+
+            }
+            else // Advanced configuration - 
+            {
+                float StartingSpeedMpS = 0.1f; // Assumed starting speed for diesel - can't be zero otherwise error will occurr
+                float StartingForceN = TractiveForceCurves.Get(ThrottleSetting, StartingSpeedMpS);
+                CalculatedMaxContinuousForceN = TractiveForceCurves.Get(ThrottleSetting, SpeedOfMaxContinuousForceMpS);
+                if (Simulator.Settings.VerboseConfigurationMessages)
                 {
-                    float StartingSpeedMpS = 0.1f; // Assumed starting speed for diesel - can't be zero otherwise error will occurr
-                    float StartingForceN = TractiveForceCurves.Get(ThrottleSetting, StartingSpeedMpS);
-                    CalculatedMaxContinuousForceN = TractiveForceCurves.Get(ThrottleSetting, SpeedOfMaxContinuousForceMpS);
                     Trace.TraceInformation("Diesel Force Settings (ADVANCED Config): Max Starting Force {0}, Calculated Max Continuous Force {1}, @ speed of {2}", FormatStrings.FormatForce(StartingForceN, IsMetric), FormatStrings.FormatForce(CalculatedMaxContinuousForceN, IsMetric), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
                     Trace.TraceInformation("Diesel Power Settings (ADVANCED Config): Prime Mover {0}, Max Rail Output Power {1} @ {2} rpm", FormatStrings.FormatPower(DieselEngines.MaxPowerW, IsMetric, false, false), FormatStrings.FormatPower(DieselEngines.MaximumRailOutputPowerW, IsMetric, false, false), MaxRPM);
 
@@ -372,34 +372,43 @@ public override void LoadFromWagFile(string wagFilePath)
                         Trace.TraceInformation("!!!! Warning: Calculated Starting Tractive force {0} is less then Calculated Continuous force {1}, please check !!!!", FormatStrings.FormatForce(StartingForceN, IsMetric), FormatStrings.FormatForce(CalculatedMaxContinuousForceN, IsMetric), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
                     }
                 }
+            }
+
+            // Check that MaxPower value is realistic - Calculate power - metric - P = F x V
+            float CalculatedContinuousPowerW = MaxContinuousForceN * SpeedOfMaxContinuousForceMpS;
+            if (MaxPowerW < CalculatedContinuousPowerW && Simulator.Settings.VerboseConfigurationMessages)
+            {
+                Trace.TraceInformation("!!!! Warning: MaxPower {0} is less then continuous force calculated power {1} @ speed of {2}, please check !!!!", FormatStrings.FormatPower(MaxPowerW, IsMetric, false, false), FormatStrings.FormatPower(CalculatedContinuousPowerW, IsMetric, false, false), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
+            }
 
-                // Check that MaxPower value is realistic - Calculate power - metric - P = F x V
-                float CalculatedContinuousPowerW = MaxContinuousForceN * SpeedOfMaxContinuousForceMpS;
-                if (MaxPowerW < CalculatedContinuousPowerW)
+            if (!DieselEngines.HasGearBox)
+            {
+                // Check Adhesion values
+                var calculatedmaximumpowerw = CalculatedMaxContinuousForceN * SpeedOfMaxContinuousForceMpS;
+                var maxforcekN = MaxForceN / 1000.0f;
+                var designadhesionzerospeed = maxforcekN / (Kg.ToTonne(DrvWheelWeightKg) * 10);
+                if (Simulator.Settings.VerboseConfigurationMessages)
                 {
-                    Trace.TraceInformation("!!!! Warning: MaxPower {0} is less then continuous force calculated power {1} @ speed of {2}, please check !!!!", FormatStrings.FormatPower(MaxPowerW, IsMetric, false, false), FormatStrings.FormatPower(CalculatedContinuousPowerW, IsMetric, false, false), FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
+                    Trace.TraceInformation("Zero Adhesion - zeroadhesion {0} maxForcekN {1} Driveweight {2}", designadhesionzerospeed, maxforcekN, DrvWheelWeightKg);
                 }
-
-                if (!DieselEngines.HasGearBox)
+                var calculatedmaxcontinuousforcekN = CalculatedMaxContinuousForceN / 1000.0f;
+                var designadhesionmaxcontspeed = calculatedmaxcontinuousforcekN / (Kg.ToTonne(DrvWheelWeightKg) * 10);
+                var zerospeed = 0;
+                var configuredadhesionzerospeed = (Curtius_KnifflerA / (zerospeed + Curtius_KnifflerB) + Curtius_KnifflerC);
+                var configuredadhesionmaxcontinuousspeed = (Curtius_KnifflerA / (SpeedOfMaxContinuousForceMpS + Curtius_KnifflerB) + Curtius_KnifflerC);
+                var dropoffspeed = calculatedmaximumpowerw / (MaxForceN);
+                var configuredadhesiondropoffspeed = (Curtius_KnifflerA / (dropoffspeed + Curtius_KnifflerB) + Curtius_KnifflerC);
+                if (Simulator.Settings.VerboseConfigurationMessages)
                 {
-                    // Check Adhesion values
-                    var calculatedmaximumpowerw = CalculatedMaxContinuousForceN * SpeedOfMaxContinuousForceMpS;
-                    var maxforcekN = MaxForceN / 1000.0f;
-                    var designadhesionzerospeed = maxforcekN / (Kg.ToTonne(DrvWheelWeightKg) * 10);
-                    var calculatedmaxcontinuousforcekN = CalculatedMaxContinuousForceN / 1000.0f;
-                    var designadhesionmaxcontspeed = calculatedmaxcontinuousforcekN / (Kg.ToTonne(DrvWheelWeightKg) * 10);
-                    var zerospeed = 0;
-                    var configuredadhesionzerospeed = (Curtius_KnifflerA / (zerospeed + Curtius_KnifflerB) + Curtius_KnifflerC);
-                    var configuredadhesionmaxcontinuousspeed = (Curtius_KnifflerA / (SpeedOfMaxContinuousForceMpS + Curtius_KnifflerB) + Curtius_KnifflerC);
-                    var dropoffspeed = calculatedmaximumpowerw / (MaxForceN);
-                    var configuredadhesiondropoffspeed = (Curtius_KnifflerA / (dropoffspeed + Curtius_KnifflerB) + Curtius_KnifflerC);
-
                     Trace.TraceInformation("Slip control system: {0}, Traction motor type: {1}", SlipControlSystem.ToString(), TractionMotorType.ToString()); // Slip control
 
                     Trace.TraceInformation("Apparent (Design) Adhesion: Zero - {0:N2} @ {1}, Max Continuous Speed - {2:N2} @ {3}, Drive Wheel Weight - {4}", designadhesionzerospeed, FormatStrings.FormatSpeedDisplay(zerospeed, IsMetric), designadhesionmaxcontspeed, FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric), FormatStrings.FormatMass(DrvWheelWeightKg, IsMetric));
                     Trace.TraceInformation("OR Calculated Adhesion Setting: Zero Speed - {0:N2} @ {1}, Dropoff Speed - {2:N2} @ {3}, Max Continuous Speed - {4:N2} @ {5}", configuredadhesionzerospeed, FormatStrings.FormatSpeedDisplay(zerospeed, IsMetric), configuredadhesiondropoffspeed, FormatStrings.FormatSpeedDisplay(dropoffspeed, IsMetric), configuredadhesionmaxcontinuousspeed, FormatStrings.FormatSpeedDisplay(SpeedOfMaxContinuousForceMpS, IsMetric));
                 }
+            }
 
+            if (Simulator.Settings.VerboseConfigurationMessages)
+            {
                 Trace.TraceInformation("===================================================================================================================\n\n");
             }