openrails
diff --git a/‎Source/Documentation/Manual/features-rollingstock.rst‎
Lines changed: 76 additions & 26 deletions b/‎Source/Documentation/Manual/features-rollingstock.rst‎
Lines changed: 76 additions & 26 deletions
diff --git a/‎Source/Orts.Formats.Msts/ShapeFile.cs‎
Lines changed: 93 additions & 0 deletions b/‎Source/Orts.Formats.Msts/ShapeFile.cs‎
Lines changed: 93 additions & 0 deletions
@@ -411,34 +411,84 @@ some steps of the content creation process or allow more control over content th
 possible. The goal of these features is to save content creators' time, give additional power to
 creators, and to simplify the installation process for end users.
 
-Advanced articulation control
------------------------------
-
-A wide variety of modern rolling stock uses articulation, in which multiple rail vehicles
-share a single "Jacobs Bogie". Open Rails offers partial support for such passenger and
-freight units by allowing one wagon to include a bogie in its 3D model while the next
-wagon removes the bogie from its 3D model. Ideally, OR will then add an invisible bogie
-to the end of the wagon without the bogie to emulate "sharing" the bogie with the previous
-wagon.
-
-However, this automatic system is limited. OR will check for wheels in the wagon's 3D
-model and will assume the wagon is articulated at one end if there are no wheels towards
-that end of the 3D model. This approach will only be used on 3D models with 3, 2, or 0 axles
-(the 1-axle case is excluded for compatibility reasons) and won't be used on locomotives.
-In some cases, this approach will result in false negative or false positive detection
-of articulation. Should the automatic articulation method not produce the expected track
-following behavior, it is now possible to manually define whether a wagon or engine
-should use the articulation behavior.
+Automatic wagon size calculation
+--------------------------------
+
+Determining the appropriate values to enter in the ``Size ( w, h, l )`` parameter of an engine or
+wagon can be tedious, as reasonable settings for the simulated width, height, and length of rolling
+stock depend on measurements of the 3D model used. Many content creators have entered largely
+arbitrary values of width and height into the size parameter, only adjusting the length value to
+give correct coupler alignement.
+
+.. index::
+   single: ORTSAutoSize
+
+To simplify this process, and produce more reasonable dimensions for rolling stock, OR can now
+automatically calculate the dimensions of rolling stock based on the shape file used. Enter
+``ORTSAutoSize`` in the Wagon section of an engine or wagon to allow OR to determine
+the width, height, and length of the rolling stock based on the dimensions of the main shape file,
+ignoring any values entered manually in the MSTS Size parameter.
+
+``ORTSAutoSize`` accepts 3 (optional) arguments, default units in meters, corresponding to offsets from the
+shape's width, height, and length respectively. For example, ``ORTSAutoSize ( 0.1m, -0.2m, -0.18m )``
+would tell OR to automatically determine the wagon's dimensions from the shape file, then subsequently
+add 0.1 meters to the width, subtract 0.2 meters from the height, and subtract 0.18 meters from the length,
+using the resulting values to set the simulated size of the wagon. In most cases, the width and height
+arguments can be set to 0, and the length argument adjusted to produce the desired coupler spacing. If
+no arguments are specified (ie: ``ORTSAutoSize ()`` was entered in the Wagon section) then all three
+offsets are assumed to be 0 meters.
+
+Note that automatic sizing uses the nearest LOD of the main shape file and attached freight animations. LODs for further
+distances have no effect on the automatic sizing. Freight animations using the ``ShapeHierarchy`` feature are also
+skipped due to potential unintended behaviors. :ref:`Shape descriptor overrides <features-shape-manipulation>`
+are also not considered at this phase, so if any changes are made in the .sd file, this feature may not provide
+good results. This method also works best for rolling stock with standard buffers/couplers on each end.
+Automatic sizing generally can't produce reasonable results 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.
+
+Improved wagon alignment tools
+------------------------------
+
+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 "nudge" the wagon shape
+until it is centered.
+
+.. index::
+   single: ORTSShapeNudge
+
+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 accepts this offset
+with the parameter ``ORTSShapeNudge ( z )``, which can be set to *any length offset without limit*.
+
+.. index::
+   single: CentreOfGravity
+
+However, this does not entirely replace ``CentreOfGravity``. The Y (height) value of the CoG is
+still used by the physics system and should still be defined. In this case, simply use
+``CentreOfGravity ( y )`` where y is the CoG height in meters (or other units, as desired).
+Unlike entering all 3 values for the CoG, entering only the Y value will NOT affect the alignment
+of the 3D model, allowing the "physical" CoG to be entered separately from the "visual" CoG.
 
 .. index::
-   single: ORTSFrontArticulation
-   single: ORTSRearArticulation
-
-To forcibly enable the articulation behavior at the front of the rail vehicle, use
-``ORTSFrontArticulation ( 1 )`` and at the rear use ``ORTSRearArticulation ( 1 )``.
-Conversely, use ``ORTSFrontArticulation ( 0 )`` or ``ORTSRearArticulation ( 0 )`` to
-force disable articulation behavior. Entering a value of -1 provides the default
-automatic behavior.
+   single: ORTSAutoCenter
+
+And, for the sake of simplicity, it may be desired to just 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 ( x y z )`` but
+will not change the X or Y components. Should no re-centering be required, none will be applied.
+
+Some rolling stock will not align correctly when auto-centered. As with ``ORTSAutoSize``, this
+feature should be employed on rolling stock with standard buffers or couplers, and will
+not produce suitable results for articulated rolling stock or stock with different coupler
+types at each end. Only the highest detail LOD of the main shape and freight animations are
+used, the .sd file is not checked. If the process fails, a warning will be written to the
+log and the automatic calculation will be skipped.
 
 Freight animations and pickups
 ==============================
 
@@ -15,6 +15,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Open Rails.  If not, see <http://www.gnu.org/licenses/>.
 
+using Microsoft.Xna.Framework;
 using Orts.Parsers.Msts;
 using System;
 using System.Collections.Generic;
@@ -109,7 +110,99 @@ public void ReadAnimationBlock(string orFileName)
             file.VerifyEndOfBlock();
         }
 
+        /// <summary>
+        /// Determines the corners of the 'bounding box' for the shape
+        /// </summary>
+        /// <returns>Two Vector3s, the first measuring the minimum extent of the shape,
+        /// the second measuring the maximum extent of the shape</returns>
+        public (Vector3, Vector3) GetBoundingLimits()
+        {
+            Vector3 mins = new Vector3(float.PositiveInfinity);
+            Vector3 maxes = new Vector3(float.NegativeInfinity);
+
+            // Determine size specifically for LOD0's (nearest LOD) sub objects
+            foreach (sub_object subObj in shape.lod_controls[0].distance_levels[0].sub_objects)
+            {
+                // Use vertex sets in the sub object to determine which vertices to check
+                foreach (vertex_set vSet in subObj.vertex_sets)
+                {
+                    // Use the vertex state used by this vertex set to determine the matrix used
+                    vtx_state vState = shape.vtx_states[vSet.VtxStateIdx];
+
+                    // The index of the matrix used by this vertex state
+                    int mIndex = vState.imatrix;
+
+                    // The 'actual' XNA matrix used to determine the vertex transformation
+                    Matrix mat = Matrix.Identity;
+
+                    // How deep are we in the hierarchy? Set a limit to prevent infinite loops
+                    int depth = 0;
 
+                    // Determine the overall transformation matrix from the root to the current matrix by following the hierarchy
+                    do
+                    {
+                        matrix m = shape.matrices[mIndex];
+
+                        // Convert the shape file matrix to an XNA matrix
+                        Matrix matTransform = new Matrix
+                        {
+                            M11 = m.AX,
+                            M12 = m.AY,
+                            M13 = m.AZ, //
+                            M14 = 0,
+                            M21 = m.BX,
+                            M22 = m.BY,
+                            M23 = m.BZ, //
+                            M24 = 0,
+                            M31 = m.CX, //
+                            M32 = m.CY, //
+                            M33 = m.CZ,
+                            M34 = 0,
+                            M41 = m.DX,
+                            M42 = m.DY,
+                            M43 = m.DZ, //
+                            M44 = 1.0f
+                        };
+
+                        // Add the effect of this transformation to the overall transformation 
+                        mat = mat * matTransform;
+
+                        // Determine the index of the next highest matrix in the hierarchy
+                        mIndex = shape.lod_controls[0].distance_levels[0].distance_level_header.hierarchy[mIndex];
+
+                        depth++;
+                    } // Keep calculating until we have calculated the root, or until a loop is encountered
+                    while (mIndex > -1 && mIndex != vState.imatrix && mIndex < shape.matrices.Count && depth < 32);
+
+                    // Determine position of every vertex in this set from point position and tranformed by the matrix
+                    for (int i = vSet.StartVtxIdx; i < vSet.StartVtxIdx + vSet.VtxCount; i++)
+                    {
+                        // Determine vertex position from vertex index and point index
+                        point p = shape.points[subObj.vertices[i].ipoint];
+                        Vector3 pPos = new Vector3(p.X, p.Y, p.Z);
+
+                        pPos = Vector3.Transform(pPos, mat);
+
+                        if (pPos.X < mins.X)
+                            mins.X = pPos.X;
+                        if (pPos.X > maxes.X)
+                            maxes.X = pPos.X;
+
+                        if (pPos.Y < mins.Y)
+                            mins.Y = pPos.Y;
+                        if (pPos.Y > maxes.Y)
+                            maxes.Y = pPos.Y;
+
+                        if (pPos.Z < mins.Z)
+                            mins.Z = pPos.Z;
+                        if (pPos.Z > maxes.Z)
+                            maxes.Z = pPos.Z;
+                    }
+                }
+            }
+
+            return (mins, maxes);
+        }
     }
 
     public class shape