Add ability to redefine matrix hierarchy in .sd file

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -518,6 +518,68 @@ transformation would be required on the lower-level sub object. It should also b
 changes made to matrices are not purely graphical and could have consequences with some simulation
 systems. Extreme settings may break simulation behavior.
 
+Shape Hierarchy Manipulation
+''''''''''''''''''''''''''''
+
+The hierarchy of a shape file is particularly important in representing the physical structure
+of the depicted object. Each sub object has a single parent sub object, except for the MAIN object which
+is ultimately the (grand)parent of all sub objects. When a sub object's parent moves or rotates,
+the sub object will move or rotate in exactly the same way (after which, its own motion or rotation
+may be added on), which represents some physical connection (such as a hinge or bearing) to the parent
+object. As such, improper hierarchy definition results in unusual or outright missing connections
+between components, such as connecting rod that doesn't move along with the wheels it is supposed to
+be attached to. The hierarchy of the shape can be determined using shape viewing utilities, and
+the correct hierarchy is described in various content creation tutorials for MSTS and OR.
+
+.. index::
+   single: ESD_ORTSMatrixParent
+
+To fix such broken hierarchies without editing the shape file, ``ESD_ORTSMatrixParent ( MATRIXNAME PARENTNAME )``
+can be added to the Shape ( block of the shape descriptor file. The hierarchy will be changed such that
+the matrix called "MATRIXNAME" will have its parent in the hierarchy changed to the matrix called
+"PARENTNAME". If either matrix name can't be found in the shape, a warning will be added to the log file and the
+hierarchy will remain unchanged. It's also possible to cause an infinite loop in the hierarchy where an
+object is its own parent or grandparent; each sub object should have only one chain of parents and grandparents
+that eventually leads back to the MAIN object. Should the configuration cause an infinite loop, a warning will
+be added to the log file. Note that OR won't be able to tell which specific change causes an invalid hierarchy
+as each hierarchy change can influence other hierarchy changes.
+
+As an example, this shape had a hierarchy where every sub object was a child of the main object, breaking
+bogie animations which require wheels to be children of the bogie, not of the main object. With some
+manipulation in the .sd file, the correct hierarchy could be implemented, fixing the bogie animation::
+
+    SIMISA@@@@@@@@@@JINX0t1t______
+
+    Shape ( RhB_Rew_8262.s
+        ESD_Detail_Level ( 0 )
+        ESD_Software_DLev ( 3 )
+        ESD_Alternative_Texture ( 0 )
+        ESD_Bounding_Box ( -1.32 0.1 -8.05 1.32 2.88 8.05 )
+	
+        Comment ( Correcting hierarchy so wheels are below bogies. )
+        ESD_ORTSMatrixParent (
+            WHEELS11 BOGIE1
+            WHEELS12 BOGIE1
+            WHEELS21 BOGIE2
+            WHEELS22 BOGIE2
+        )
+	
+        Comment ( Correcting position offset of wheels due to hierarchy change. )
+        ESD_ORTSMatrixTranslation ( WHEELS11 0m -0.426m -5.45m )
+        ESD_ORTSMatrixTranslation ( WHEELS12 0m -0.426m -5.45m )
+        ESD_ORTSMatrixTranslation ( WHEELS21 0m -0.426m  5.45m )
+        ESD_ORTSMatrixTranslation ( WHEELS22 0m -0.426m  5.45m )
+    )
+
+Note how multiple parent/child relationships can be changed at once by specifying additional pairs of
+matrix names, and that changing the hierarchy required adjusting the translation of many sub objects in order
+for them to appear in the intended locations. The location of a sub object is measured relative to its parent,
+so if the sub object parent is changed, it's position in the 3D world will change as well (unless corrected for,
+as was done here).
+
+Transformation Matrix Name Changes
+''''''''''''''''''''''''''''''''''
+
 .. index::
    single: ESD_ORTSMatrixRename
 
@@ -2551,7 +2613,7 @@ be loaded instead.
 ``ORTSTractionCutOffRelayClosingDelay`` refers to the delay between the closing command of the traction cut-off relay
 and the effective closing of the relay.
 
-.. _features-scripting-powerselectors
+.. _features-scripting-powerselectors:
 
 Pantograph, voltage and power limitation selectors
 --------------------------------------------------

Source/Orts.Formats.Msts/ShapeDescriptorFile.cs

@@ -87,6 +87,7 @@ public SDShape(STFReader stf)
                     new STFReader.TokenProcessor("esd_ortscustomanimationfps", ()=>{ ESD_CustomAnimationFPS = stf.ReadFloatBlock(STFReader.UNITS.Frequency, null); }),
                     new STFReader.TokenProcessor("esd_ortstexturereplacement", ()=>{ ParseReplacementStrings(stf, ref ESD_TextureReplacement); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixrename", ()=>{ ParseReplacementStrings(stf, ref ESD_MatrixRename); }),
+                    new STFReader.TokenProcessor("esd_ortsmatrixparent", ()=>{ ParseReplacementStrings(stf, ref ESD_MatrixParent); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixtranslation", ()=>{ ParseMatrixOverride(STFReader.UNITS.Distance, stf, ref ESD_MatrixTranslation); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixscale", ()=>{ ParseMatrixOverride(STFReader.UNITS.None, stf, ref ESD_MatrixScale); }),
                     new STFReader.TokenProcessor("esd_ortsmatrixrotation", ()=>{ ParseMatrixOverride(STFReader.UNITS.Angle, stf, ref ESD_MatrixRotation); }),
@@ -107,6 +108,8 @@ public SDShape(STFReader stf)
                 // Store set of all matrices that got modified
                 foreach (string mat in ESD_MatrixRename.Keys)
                     ESD_ModifiedMatrices.Add(mat);
+                foreach (string mat in ESD_MatrixParent.Keys)
+                    ESD_ModifiedMatrices.Add(mat);
                 foreach (string mat in ESD_MatrixTranslation.Keys)
                     ESD_ModifiedMatrices.Add(mat);
                 foreach (string mat in ESD_MatrixScale.Keys)
@@ -126,6 +129,8 @@ public SDShape(STFReader stf)
             public Dictionary<string, string> ESD_TextureReplacement = new Dictionary<string, string>();
             // Dictionary of <original matrix name, replacement matrix name>
             public Dictionary<string, string> ESD_MatrixRename = new Dictionary<string, string>();
+            // Dictionary of <matrix name, new matrix parent name>
+            public Dictionary<string, string> ESD_MatrixParent = new Dictionary<string, string>();
             // Set of matrix names that are modified in some way or another
             public HashSet<string> ESD_ModifiedMatrices = new HashSet<string>();
             // Dictionary of <matrix name, matrix translation x/y/z vector>

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

@@ -492,6 +492,9 @@ public virtual void LoadFromWagFile(string wagFilePath)
                             // 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
                             {
@@ -523,8 +526,10 @@ public virtual void LoadFromWagFile(string wagFilePath)
 
                                 // 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];
+
+                                depth++;
                             } // 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);
+                            while (mIndex > -1 && mIndex != vState.imatrix && mIndex < wagShape.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++)

Source/RunActivity/Viewer3D/Shapes.cs

@@ -362,7 +362,9 @@ public void UpdateResultMatrices()
                 int hIndex = Hierarchy[i];
 
                 // Transform the matrix repeatedly for all of its parents
-                while (hIndex > -1 && hIndex < Hierarchy.Length)
+                int depth = 0;
+
+                while (hIndex > -1 && hIndex < Hierarchy.Length && depth < 32)
                 {
                     // Can finish calculating sooner if we already have the result matrix for the next level up
                     if (resultCalculated[hIndex])
@@ -379,6 +381,8 @@ public void UpdateResultMatrices()
                         else
                             break;
                     }
+
+                    depth++;
                 }
 
                 ResultMatrices[i] = res;
@@ -2160,9 +2164,14 @@ void LoadContent()
 
                     if (!found)
                         Trace.TraceWarning("Shape descriptor file {0} specifies texture {1} to be replaced, " +
-                            "but shape {2} does not contain this texture.", (filePath + "d"), tex, filePath);
+                            "but shape {2} does not contain this texture.", DescriptorPath, tex, filePath);
                 }
 
+                int[] modifiedHierarchy = null;
+                // Prepare to consider hierarchy changes
+                if (sdFile.shape.ESD_MatrixParent.Count > 0)
+                    modifiedHierarchy = (int[])sFile.shape.lod_controls?.FirstOrDefault()?.distance_levels?.FirstOrDefault()?.distance_level_header.hierarchy.Clone();
+
                 // Manipulate matrices as defined in the sd file
                 foreach (string matName in sdFile.shape.ESD_ModifiedMatrices)
                 {
@@ -2210,10 +2219,32 @@ void LoadContent()
                                 sFile.shape.matrices[i] = MSTSMatrixFromXNA(newMatrix, sFile.shape.matrices[i].Name);
                             }
 
-                            // Finally, see if this matrix is to be renamed
-                            if (sdFile.shape.ESD_MatrixRename.TryGetValue(matName, out string newName))
+                            // See if this matrix should have its parent changed
+                            if (sdFile.shape.ESD_MatrixParent.TryGetValue(matName, out string newParent))
                             {
-                                sFile.shape.matrices[i].Name = newName;
+                                int thisIndex = i;
+                                int parentIndex = -1;
+
+                                for (int m = 0; m < sFile.shape.matrices.Count; m++)
+                                {
+                                    if (sFile.shape.matrices[m].Name.ToUpper() == newParent.ToUpper())
+                                    {
+                                        parentIndex = m;
+                                        break;
+                                    }
+                                }
+
+                                // Found the new parent matrix, update the temporary hierarchy list accordingly
+                                if (parentIndex >= 0) 
+                                {
+                                    if (modifiedHierarchy != null && thisIndex >= 0 && thisIndex < modifiedHierarchy.Length)
+                                        modifiedHierarchy[thisIndex] = parentIndex;
+                                }
+                                else // Couldn't find new parent matrix
+                                {
+                                    Trace.TraceWarning("Shape descriptor file {0} specifies matrix name {1} to be utilized, " +
+                                        "but shape {2} does not contain this matrix.", DescriptorPath, newParent, filePath);
+                                }
                             }
 
                             found = true;
@@ -2222,7 +2253,68 @@ void LoadContent()
 
                     if (!found)
                         Trace.TraceWarning("Shape descriptor file {0} specifies matrix name {1} to be modified, " +
-                            "but shape {2} does not contain this matrix.", (filePath + "d"), matName, filePath);
+                            "but shape {2} does not contain this matrix.", DescriptorPath, matName, filePath);
+                }
+
+                // Check that hierarchy changes make sense, then apply to shape file
+                if (modifiedHierarchy != null && sdFile.shape.ESD_MatrixParent.Count > 0)
+                {
+                    // Iterate through every hierarchy element to make sure it resolves back to the main object
+                    // If anything in the modified hierarchy fails, do not update the shape hierarchy
+                    bool valid = false;
+
+                    for (int hIndex = 0; hIndex < modifiedHierarchy.Length; hIndex++)
+                    {
+                        int nextIndex = modifiedHierarchy[hIndex];
+                        int depth = 0;
+
+                        while (nextIndex > -1 && nextIndex < modifiedHierarchy.Length && depth < 32)
+                        {
+                            if (nextIndex == hIndex)
+                                break; // We have reached an infinite loop
+                            nextIndex = modifiedHierarchy[nextIndex];
+
+                            depth++;
+                        }
+
+                        // The above calculation should produce a final index of -1
+                        // This means the hierarchy could be traced back to the main shape
+                        if (nextIndex == -1)
+                            valid = true;
+                        else
+                            break;
+                    }
+
+                    if (valid)
+                    {
+                        foreach (lod_control lodControl in sFile.shape.lod_controls)
+                        {
+                            foreach (distance_level distanceLevel in lodControl.distance_levels)
+                            {
+                                // Note: This assumes the hierarchy is the same for every LOD...is this always true?
+                                distanceLevel.distance_level_header.hierarchy = modifiedHierarchy;
+                            }
+                        }
+                    }
+                    else
+                    {
+                        Trace.TraceWarning("Hierarchy changes specified in shape descriptor file {0} " +
+                            "produce an invalid hierarchy when applied to shape {1}, hierarchy has not been updated.", DescriptorPath, filePath);
+                    }
+                }
+
+                // Guarantee that matrix renaming happens after all other operations
+                foreach (KeyValuePair<string, string> renamePair in sdFile.shape.ESD_MatrixRename)
+                {
+                    for (int i = 0; i < sFile.shape.matrices.Count; i++)
+                    {
+                        // Check if this matrix is to be renamed, and rename accordingly
+                        // Ignore case
+                        if (sFile.shape.matrices[i].Name.ToUpper() == renamePair.Key.ToUpper())
+                        {
+                            sFile.shape.matrices[i].Name = renamePair.Value;
+                        }
+                    }
                 }
 
                 // Manipulate LOD settings as defined in the sd file
@@ -2234,10 +2326,10 @@ void LoadContent()
                         {
                             lodControl.distance_levels[lodIndex.Key].distance_level_header.dlevel_selection = lodIndex.Value;
                         }
-                        else // LOD index defined doesn't eist
+                        else // LOD index defined doesn't exist
                         {
                             Trace.TraceWarning("Shape descriptor file {0} specifies LOD index {1} to be modified, " +
-                                "but shape {2} does not have this many LODs.", (filePath + "d"), lodIndex.Key, filePath);
+                                "but shape {2} does not have this many LODs.", DescriptorPath, lodIndex.Key, filePath);
                         }
                     }
                 }