Add level of detail override to shape descriptor, add error correction for LODs with a distance of 0 meters

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -529,6 +529,52 @@ matrix with the old name can be found, a warning will be produced and nothing wi
 that the matrix rename step occurs *after* the previously described matrix modifications, so
 the old matrix name must be used by any other .sd parameters that require a matrix name.
 
+LOD Distance Override
+'''''''''''''''''''''
+
+Shape files are generally products of the time they were created, and this includes the level of
+detail distances used. Even if the complexity of the shape is the same, modern shapes tend to
+use longer LOD distances than their legacy counterparts, which can lead to visual inconsistenty.
+The :ref:`"level of detail bias" option<options-lod-bias>` can be used to extend the LOD distance
+of *all* shapes, but this would not solve the inconsistency between shapes.
+
+.. index::
+   single: ESD_ORTSLODOverride
+
+To resolve this without editing shape files themsleves, the ``ESD_ORTSLODOverride ( LODindex LODdistance )``
+parameter can be used in the shape descriptor file to set the LOD distance of the LOD at ``LODindex`` to a value
+of ``LODdistance``, where LODindex is an integer specifying which LOD to edit (NOTE: LOD 0 is the closest LOD, LOD 1 is
+the second closest, and so on) and LODdistance is a decimal measured in units of distance (default meters) specifying
+the maximum view distance of the LOD. The number of LODs and their default distances can be seen in shape viewing programs.
+
+As an example, a shape from 2011 has LOD distances of 100m, 300m, 700m, and 2000m. Because the shape was already of high
+quality, a later product from 2020 used the same shape but with upgraded textures and LODs bumped to 300m, 750m, 1000m and 2000m.
+To upgrade the old shape LOD to match the new shape, the following shape descriptor could be used::
+
+    SIMISA@@@@@@@@@@JINX0t1t______
+
+    Shape ( 50ft_BOX_BNSF722974.s 
+        ESD_Detail_Level ( 0 ) 
+        ESD_Software_DLev ( 3 ) 
+        ESD_Alternative_Texture ( 0 ) 
+        ESD_Bounding_Box ( 
+            -1.539  0.61059 -8.08
+            1.549   3.54    8.08 ) 
+
+        Comment ( New addition: LOD improvement )
+        ESD_ORTSLODOverride (
+            0 300m
+            1 750m
+            2 1000m
+        )
+    ) 
+
+
+Observe how multiple LODs can be edited with a single parameter by specifying additional pairs of LOD indices and distances,
+and how not all LODs need to be present (LOD 3 is 2000m on both the old and new shape, so doesn't need to be changed).
+If a given shape does not have the LOD index specified (eg: LOD 4 does not exist on this shape, as the shape only has 4 LODs)
+then a warning is added to the log and the missing LOD is skipped.
+
 Automatic wagon size calculation
 --------------------------------
 

Source/Documentation/Manual/options.rst

@@ -352,6 +352,8 @@ In more modern routes, content may be assigned to categories between 0 and 49.
 Content builders are advised to reserve values 50 to 99 for objects used in building the route.
 
 
+.. _options-lod-bias:
+
 Level of detail bias
 --------------------
 

Source/Orts.Formats.Msts/ShapeDescriptorFile.cs

@@ -90,6 +90,18 @@ public SDShape(STFReader stf)
                     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); }),
+                    new STFReader.TokenProcessor("esd_ortslodoverride", ()=>{
+                        stf.MustMatch("(");
+                        // Allow for multiple pairs of replaced and replacement values
+                        while (!stf.EndOfBlock())
+                        {
+                            int replaced = stf.ReadInt(null);
+                            float replacement = stf.ReadFloat(STFReader.UNITS.Distance, null);
+                            // Add pair of values so long as we haven't reached the end of block
+                            if (replacement != 0)
+                                ESD_LODOverride.Add(replaced, replacement);
+                        }
+                    }),
                 });
 
                 // Store set of all matrices that got modified
@@ -122,6 +134,8 @@ public SDShape(STFReader stf)
             public Dictionary<string, Vector3> ESD_MatrixScale = new Dictionary<string, Vector3>();
             // Dictionary of <matrix name, matrix rotation x/y/z vector>
             public Dictionary<string, Vector3> ESD_MatrixRotation = new Dictionary<string, Vector3>();
+            // Dictionary of <LOD index, LOD distance>
+            public Dictionary<int, float> ESD_LODOverride = new Dictionary<int, float>();
 
             // Handle parameters concerning replacement of string values
             protected void ParseReplacementStrings(STFReader stf, ref Dictionary<string, string> renamePairs)

Source/RunActivity/Viewer3D/Shapes.cs

@@ -2224,6 +2224,56 @@ void LoadContent()
                         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);
                 }
+
+                // Manipulate LOD settings as defined in the sd file
+                foreach (lod_control lodControl in sFile.shape.lod_controls)
+                {
+                    foreach (KeyValuePair<int, float> lodIndex in sdFile.shape.ESD_LODOverride)
+                    {
+                        if (lodIndex.Key >= 0 && lodIndex.Key < lodControl.distance_levels.Count)
+                        {
+                            lodControl.distance_levels[lodIndex.Key].distance_level_header.dlevel_selection = lodIndex.Value;
+                        }
+                        else // LOD index defined doesn't eist
+                        {
+                            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);
+                        }
+                    }
+                }
+            }
+
+            // Fix for LODs having a LOD distance of 0
+            // This may occur due to improper settings when exporting shape file
+            // To prevent missing scenery, force LOD distance to be something reasonable
+            foreach (lod_control lodControl in sFile.shape.lod_controls)
+            {
+                for (int dLevel = 0; dLevel < lodControl.distance_levels.Count; dLevel++)
+                {
+                    if (lodControl.distance_levels[dLevel].distance_level_header.dlevel_selection <= 0f)
+                    {
+                        // Estimate a reasonable LOD distance based on surrounding LODs
+                        // If there are no other LODs, use 2 km as the LOD distance
+                        float thisLODDistance = 2000f;
+                        float prevLODDistance = -1f;
+                        float nextLODDistance = -1f;
+
+                        if (dLevel + 1 < lodControl.distance_levels.Count)
+                            nextLODDistance = lodControl.distance_levels[dLevel + 1].distance_level_header.dlevel_selection;
+                        if (dLevel - 1 >= 0)
+                            prevLODDistance = lodControl.distance_levels[dLevel - 1].distance_level_header.dlevel_selection;
+
+                        // Both a previous and next LOD were found
+                        if (prevLODDistance >= 0f && nextLODDistance >= 0f)
+                            thisLODDistance = (prevLODDistance + nextLODDistance) / 2.0f;
+                        else if (prevLODDistance >= 0f) // Only a previous LOD was found
+                            thisLODDistance = prevLODDistance * 2.0f;
+                        else if (nextLODDistance >= 0f) // Only a subsequent LOD was found
+                            thisLODDistance = nextLODDistance / 2.0f;
+
+                        lodControl.distance_levels[dLevel].distance_level_header.dlevel_selection = thisLODDistance;
+                    }
+                }
             }
 
             var matrixCount = sFile.shape.matrices.Count;