Add parameters to define center of gravity dimensions individually

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -444,18 +444,38 @@ stock with standard buffers/couplers on each end. Automatic sizing generally can
 for articulated rolling stock. And should something go wrong with the shape file causing automatic sizing to fail,
 OR will revert to the values entered in the ``Size`` parameter.
 
-Automatic wagon centering
--------------------------
+Improved wagon alignment tools
+------------------------------
 
-Many MSTS and OR creators have encountered rolling stock shapes that were not correctly centered,
+Many MSTS and OR creators have encountered rolling stock shapes that were not correctly aligned,
 resulting in couplers/buffers clipping at one end of the wagon and separating at the other end.
 Normally, this would require inspecting the 3D model to determine exactly how off-center it was
 and carefully setting the Z value of ``CentreOfGravity ( x, y, z )`` to re-center the model.
 
+.. index::
+   single: ORTSCentreOfGravity_X
+   single: ORTSCentreOfGravity_Y
+   single: ORTSCentreOfGravity_Z
+
+In some cases, this approach could still be insufficient as the Z offset is limited to 2 meters in
+order to prevent unusual behaviors with some MSTS models that used unreasonably large Z offsets.
+To facilitate models that need large offsets without introducing errors, OR now has parameters
+to define the CoG dimensions individually without any artifical limits added afterward.
+To set the horizontal, vertical, and lengthwise CoG offset ``ORTSCentreOfGravity_X``, ``ORTSCentreOfGravity_Y``,
+and ``ORTSCentreOfGravity_Z`` respectively can be entered in the Wagon section of an engine or wagon.
+
+If placed later in the file than the original ``CentreOfGravity`` parameter, the data entered in the X/Y/Z
+parameters will overwrite the original data, but only for the specific X/Y/Z component provided. For
+example, if ``ORTSCentreOfGravity_Z ( -1m )`` is placed after ``CentreOfGravity ( 0m 2.5m 0.5m )`` the
+resulting CoG offset will actually be 0m, 2.5m, -1m, overwriting the original 0.5m Z offset while
+leaving the X and Y components unchanged.
+
 .. index::
    single: ORTSAutoCenter
 
-To make this easier, OR now includes the ``ORTSAutoCenter`` parameter. When ``ORTSAutoCenter ( 1 )``
+However, in many cases it is desireable to simply center the 3D model lengthwise such that the
+couplers/buffers are equidistant from the centerpoint of the model. To make this specific case
+easier, OR now includes the ``ORTSAutoCenter`` parameter. When ``ORTSAutoCenter ( 1 )``
 is included in the Wagon section of an engine or wagon, OR will inspect the main shape file used by
 the wagon to determine the exact Z value of CentreOfGravity required to re-center the shape in the
 simulation. This will overwrite the manually entered Z component of ``CentreOfGravity`` but will

Source/Orts.Simulation/Simulation/RollingStocks/MSTSWagon.cs

@@ -1347,6 +1347,12 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     }
                     stf.SkipRestOfBlock();
                     break;
+                case "wagon(ortscenterofgravity_x":
+                case "wagon(ortscentreofgravity_x": InitialCentreOfGravityM.X = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
+                case "wagon(ortscenterofgravity_y":
+                case "wagon(ortscentreofgravity_y": InitialCentreOfGravityM.Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
+                case "wagon(ortscenterofgravity_z":
+                case "wagon(ortscentreofgravity_z": InitialCentreOfGravityM.Z = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortsautocentre":
                 case "wagon(ortsautocenter": AutoCenter = stf.ReadBoolBlock(false); break;
                 case "wagon(ortsunbalancedsuperelevation": MaxUnbalancedSuperElevationM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/FreightAnimations.cs

@@ -109,6 +109,7 @@ public FreightAnimations(STFReader stf, MSTSWagon wagon)
                 new STFReader.TokenProcessor("emptymaxbrakeforce", ()=>{ EmptyMaxBrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
                 new STFReader.TokenProcessor("emptymaxbrakeshoeforce", ()=>{ EmptyMaxBrakeShoeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
                 new STFReader.TokenProcessor("emptymaxhandbrakeforce", ()=>{ EmptyMaxHandbrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
+                new STFReader.TokenProcessor("emptycenterofgravity_y", ()=>{ EmptyCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
                 new STFReader.TokenProcessor("emptycentreofgravity_y", ()=>{ EmptyCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
                 new STFReader.TokenProcessor("emptybrakerelayvalveratio", ()=>{ EmptyRelayValveRatio = stf.ReadFloatBlock(STFReader.UNITS.None, -1); }),
                 new STFReader.TokenProcessor("emptybrakerelayvalveinshot", ()=>{ EmptyInshotPSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, -1); }),
@@ -1021,6 +1022,7 @@ public FreightAnimationContinuous(STFReader stf, MSTSWagon wagon)
                 new STFReader.TokenProcessor("fullmaxbrakeforce", ()=>{ FullMaxBrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
                 new STFReader.TokenProcessor("fullmaxbrakeshoeforce", ()=>{ FullMaxBrakeShoeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
                 new STFReader.TokenProcessor("fullmaxhandbrakeforce", ()=>{ FullMaxHandbrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
+                new STFReader.TokenProcessor("fullcenterofgravity_y", ()=>{ FullCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
                 new STFReader.TokenProcessor("fullcentreofgravity_y", ()=>{ FullCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
                 new STFReader.TokenProcessor("fullbrakerelayvalveratio", ()=>{ FullRelayValveRatio = stf.ReadFloatBlock(STFReader.UNITS.None, -1); }),
                 new STFReader.TokenProcessor("fullbrakerelayvalveinshot", ()=>{ FullInshotPSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, -1); })
@@ -1147,6 +1149,7 @@ public FreightAnimationStatic(STFReader stf)
             new STFReader.TokenProcessor("fullmaxbrakeforce", ()=>{ FullStaticMaxBrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
             new STFReader.TokenProcessor("fullmaxbrakeshoeforce", ()=>{ FullStaticMaxBrakeShoeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
             new STFReader.TokenProcessor("fullmaxhandbrakeforce", ()=>{ FullStaticMaxHandbrakeForceN = stf.ReadFloatBlock(STFReader.UNITS.Force, -1); }),
+            new STFReader.TokenProcessor("fullcenterofgravity_y", ()=>{ FullStaticCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
             new STFReader.TokenProcessor("fullcentreofgravity_y", ()=>{ FullStaticCentreOfGravityM_Y = stf.ReadFloatBlock(STFReader.UNITS.Distance, -1); }),
             new STFReader.TokenProcessor("fullbrakerelayvalveratio", ()=>{ FullStaticRelayValveRatio = stf.ReadFloatBlock(STFReader.UNITS.None, -1); }),
             new STFReader.TokenProcessor("fullbrakerelayvalveinshot", ()=>{ FullStaticInshotPSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, -1); })