Automatically calculate wagon size and centering

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -403,6 +403,71 @@ OR supports tilting trains. A train tilts when its .con file name contains the
 
 .. image:: images/features-tilting.png
 
+Features to assist content creation
+===================================
+
+OR now includes some features that don't change the functionality of rolling stock, but simplify
+some steps of the content creation process or allow more control over content than was previously
+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.
+
+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. LODs for further distances
+and freight animation shape files have no effect on the automatic sizing. 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.
+
+Automatic wagon centering
+-------------------------
+
+Many MSTS and OR creators have encountered rolling stock shapes that were not correctly centered,
+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: ORTSAutoCenter
+
+To make this 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
+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 is used to auto-center the
+rolling stock, other LODs and freight animations are ignored. If the process fails, a warning
+will be written to the log and the automatic calculation will be skipped.
+
 Freight animations and pickups
 ==============================
 

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

@@ -488,6 +488,112 @@ public virtual void LoadFromWagFile(string wagFilePath)
                 RearAirHose.Connected.ShapeFileName = null;
             }
 
+            // If requested, use the shape file to determine the size of the wagon
+            if ((AutoSize || AutoCenter) && !string.IsNullOrEmpty(MainShapeFileName))
+            {
+                try // Shape file discrepancies might cause errors, we don't want to cause a crash here
+                {
+                    // This might be a bad idea, usually we wait to deal with shape files until within viewing range
+                    // But my hubris has decided we can use for the shape for things other than graphics - Phillip
+                    ShapeFile wagShape = new ShapeFile(wagonFolderSlash + MainShapeFileName, true);
+
+                    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 wagShape.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 = wagShape.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;
+
+                            // Determine the overall transformation matrix from the root to the current matrix by following the hierarchy
+                            do
+                            {
+                                matrix m = wagShape.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 = wagShape.shape.lod_controls[0].distance_levels[0].distance_level_header.hierarchy[mIndex];
+                            } // Keep calculating until we have calculated the root, or until a loop is encountered
+                            while (mIndex > -1 && mIndex != vState.imatrix && mIndex < wagShape.shape.matrices.Count);
+
+                            // 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 = wagShape.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;
+                            }
+                        }
+                    }
+
+                    // Set dimensions of wagon if configured as such
+                    if (AutoSize)
+                    {
+                        CarWidthM = Math.Max((maxes.X - mins.X) + AutoWidthOffsetM, 0.1f);
+                        CarHeightM = Math.Max((maxes.Y - mins.Y) + AutoHeightOffsetM, 0.1f);
+                        CarLengthM = Math.Max((maxes.Z - mins.Z) + AutoLengthOffsetM, 0.1f);
+                    }
+
+                    // Automatically determine the center of gravity offset required to perfectly center the shape (lengthwise)
+                    if (AutoCenter)
+                        InitialCentreOfGravityM.Z = (maxes.Z + mins.Z) / 2.0f;
+                }
+                catch
+                {
+                    Trace.TraceWarning("Could not automatically determine size of shape {0} in wagon {1}, there may be an error in the shape.", MainShapeFileName, wagFilePath);
+                }
+            }
+
             // If trailing loco resistance constant has not been  defined in WAG/ENG file then assign default value based upon orig Davis values
             if (TrailLocoResistanceFactor == 0)
             {
@@ -1287,6 +1393,14 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     CarLengthM = stf.ReadFloat(STFReader.UNITS.Distance, null);
                     stf.SkipRestOfBlock();
                     break;
+                case "wagon(ortsautosize":
+                    AutoSize = true;
+                    stf.MustMatch("(");
+                    AutoWidthOffsetM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    AutoHeightOffsetM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    AutoLengthOffsetM = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                    stf.SkipRestOfBlock();
+                    break;
                 case "wagon(ortslengthbogiecentre": CarBogieCentreLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortslengthcarbody": CarBodyLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortslengthairhose": CarAirHoseLengthM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
@@ -1304,6 +1418,7 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                         stf.SkipRestOfBlock();
                     }
                     break;
+                case "wagon(centerofgravity":
                 case "wagon(centreofgravity":
                     stf.MustMatch("(");
                     InitialCentreOfGravityM.X = stf.ReadFloat(STFReader.UNITS.Distance, null);
@@ -1316,6 +1431,8 @@ public virtual void Parse(string lowercasetoken, STFReader stf)
                     }
                     stf.SkipRestOfBlock();
                     break;
+                case "wagon(ortsautocentre":
+                case "wagon(ortsautocenter": AutoCenter = stf.ReadBoolBlock(false); break;
                 case "wagon(ortsunbalancedsuperelevation": MaxUnbalancedSuperElevationM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;
                 case "wagon(ortsrigidwheelbase":
                     stf.MustMatch("(");
@@ -1723,7 +1840,6 @@ public virtual void Copy(MSTSWagon copy)
             CarLengthM = copy.CarLengthM;
             TrackGaugeM = copy.TrackGaugeM;
             CentreOfGravityM = copy.CentreOfGravityM;
-            InitialCentreOfGravityM = copy.InitialCentreOfGravityM;
             MaxUnbalancedSuperElevationM = copy.MaxUnbalancedSuperElevationM;
             RigidWheelBaseM = copy.RigidWheelBaseM;
             CarBogieCentreLengthM = copy.CarBogieCentreLengthM;

Source/Orts.Simulation/Simulation/RollingStocks/TrainCar.cs

@@ -187,6 +187,10 @@ public static Interpolator SteamHeatBoilerFuelUsageGalukpH()
         public float CarWidthM = 2.5f;
         public float CarLengthM = 40;       // derived classes must overwrite these defaults
         public float CarHeightM = 4;        // derived classes must overwrite these defaults
+        public bool AutoSize = false;       // Are the dimensions of this wagon to be calculated automatically from the shape file?
+        public float AutoWidthOffsetM;
+        public float AutoLengthOffsetM;
+        public float AutoHeightOffsetM;
         public float MassKG = 10000;        // Mass in KG at runtime; coincides with InitialMassKG if there is no load and no ORTS freight anim
         public float InitialMassKG = 10000;
         public bool IsDriveable;
@@ -638,6 +642,7 @@ public Direction Direction
         protected float TrackGaugeM;  // Track gauge - read in MSTSWagon, otherwise uses value given by the route
         protected Vector3 InitialCentreOfGravityM = new Vector3(0, 1.8f, 0); // get centre of gravity - read in MSTSWagon
         public Vector3 CentreOfGravityM = new Vector3(0, 1.8f, 0); // get centre of gravity after adjusted for freight animation
+        protected bool AutoCenter = false; // Should CentreOfGravityM.Z be set automatically to center the wagon?
         public float SuperElevationM; // Super elevation on the curve
         protected float MaxUnbalancedSuperElevationM;  // Maximum comfortable cant deficiency, read from MSTS Wagon File
         public float SuperElevationAngleRad;