Merge pull request #369 from cjakeman/external-clocks

Copies ExtClock from OR New Year MG

Author: YoRyan

Source/Contrib/DataConverter/ClockConverter.cs

@@ -0,0 +1,123 @@
+// COPYRIGHT 2016 by the Open Rails project.
+// 
+// This file is part of Open Rails.
+// 
+// Open Rails is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// 
+// Open Rails is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+// 
+// 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 Newtonsoft.Json;
+using Orts.Formats.Msts;
+using Orts.Formats.OR;
+using Orts.Parsers.Msts;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Xml.Linq;
+
+namespace Orts.DataConverter
+{
+    class ClockConverter : IDataConverter
+    {
+        public ClockConverter()
+        {
+        }
+
+        public void ShowConversions()
+        {
+            //                "1234567890123456789012345678901234567890123456789012345678901234567890123456789"
+            //                "               Input  Output              Description"
+            Console.WriteLine("openrails/clocks.dat  animated.clocks-or  Converts from STF to JSON");
+        }
+
+        /// <summary>
+        /// Not clear what happens if conversion fails.
+        /// </summary>
+        /// <param name="conversion"></param>
+        /// <returns></returns>
+        public bool DoConversion(DataConversion conversion)
+        {
+            // We can convert from .dat files.
+            if (conversion.Input.EndsWith(@"openrails\clocks.dat") == false)
+            {
+                return false;
+            }
+            // We can convert to .clocks-or files.
+            if (conversion.Output.Any(r => r.EndsWith("clocks-or")) == false
+                || conversion.Output.Count != 1)
+            {
+                return false;
+            }
+            if (File.Exists(conversion.Input) == false)
+            {
+                throw new FileNotFoundException("", conversion.Input);
+            }
+
+            var clockLists = new List<ClockList>();
+            try
+            {
+                var inFilePath = Path.GetFullPath(conversion.Input);
+
+                // Shorten the path to get the route
+                var routeLength = inFilePath.Length - @"openrails\clocks.dat".Length;
+                var routePath = inFilePath.Substring(0, routeLength);
+
+                clockLists = ParseInput(conversion, routePath);
+            }
+            catch (Orts.Parsers.Msts.STFException e)
+            {
+                Console.WriteLine("Parse error in " + conversion.Input + e.Message);
+                throw; // re-throw exception without losing the stack trace
+            }
+
+            var jso = new List<ClockShape>();
+
+            try
+            {
+                GenerateOutput(conversion, clockLists, jso);
+            }
+            catch (Exception e)
+            {
+                Console.WriteLine("Error generating " + conversion.Output + e.Message);
+                throw; // re-throw exception without losing the stack trace
+            }
+
+            return true;
+        }
+
+        private static List<ClockList> ParseInput(DataConversion conversion, string routePath)
+        {
+            var clockLists = new List<ClockList>();
+            {
+                using (STFReader stf = new STFReader(conversion.Input, false))
+                {
+                    var clockBlock = new ClockBlock(stf, routePath + @"shapes\", clockLists, "Default");
+                }
+            }
+            return clockLists;
+        }
+
+        private static void GenerateOutput(DataConversion conversion, List<ClockList> clockLists, List<ClockShape> jso)
+        {
+            var clockList = clockLists.First();
+            for (var i = 0; i < clockList.ClockType.Count(); i++)
+            {
+                var item = new ClockShape(clockList.ShapeNames[i], clockList.ClockType[i]);
+                jso.Add(item);
+            }
+
+            File.WriteAllText(conversion.Output.First(), JsonConvert.SerializeObject(jso, Formatting.Indented));
+        }
+    }
+}

Source/Contrib/DataConverter/DataConverter.csproj

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
   <PropertyGroup>
@@ -40,20 +40,33 @@
     <LangVersion>7.3</LangVersion>
   </PropertyGroup>
   <ItemGroup>
+    <Reference Include="Newtonsoft.Json, Version=11.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed, processorArchitecture=MSIL">
+      <SpecificVersion>False</SpecificVersion>
+      <HintPath>..\..\3rdPartyLibs\Newtonsoft.Json.dll</HintPath>
+    </Reference>
     <Reference Include="System" />
     <Reference Include="System.Xml" />
     <Reference Include="System.Xml.Linq" />
   </ItemGroup>
   <ItemGroup>
     <Compile Include="Program.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="ClockConverter.cs" />
     <Compile Include="TerrainConverter.cs" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\Orts.Formats.Msts\Orts.Formats.Msts.csproj">
       <Project>{570709FA-0C8A-4B1D-BA2D-D9455AFD9B5C}</Project>
       <Name>Orts.Formats.Msts</Name>
     </ProjectReference>
+    <ProjectReference Include="..\..\Orts.Formats.OR\Orts.Formats.OR.csproj">
+      <Project>{0d8d312b-2c02-4b77-a795-566394a9db95}</Project>
+      <Name>Orts.Formats.OR</Name>
+    </ProjectReference>
+    <ProjectReference Include="..\..\Orts.Parsers.Msts\Orts.Parsers.Msts.csproj">
+      <Project>{8a84696c-3559-49b8-b27f-bb6932d8a1c6}</Project>
+      <Name>Orts.Parsers.Msts</Name>
+    </ProjectReference>
   </ItemGroup>
   <ItemGroup>
     <None Include="app.config" />
@@ -66,4 +79,4 @@
   <Target Name="AfterBuild">
   </Target>
   -->
-</Project>
+</Project>

Source/Contrib/DataConverter/Program.cs

@@ -25,12 +25,13 @@ namespace Orts.DataConverter
 {
     class Program
     {
+        //TODO Add a return code for success or not
         static void Main(string[] args)
         {
             var converters = new List<IDataConverter>()
-            {
-                new TerrainConverter()
-            };
+                { new TerrainConverter()
+                , new ClockConverter()
+                };
 
             try
             {
@@ -44,6 +45,7 @@ static void Main(string[] args)
                 foreach (var conversion in conversions)
                 {
                     var valid = false;
+                    // Apply each converter in turn to the conversion
                     foreach (var converter in converters)
                     {
                         if (converter.DoConversion(conversion))
@@ -54,6 +56,7 @@ static void Main(string[] args)
                             {
                                 Console.WriteLine("--> {0}", output);
                             }
+                            // After a successful conversion, do not apply any more converters.
                             break;
                         }
                     }
@@ -74,6 +77,10 @@ static void Main(string[] args)
                 Console.WriteLine();
                 ShowHelp(converters);
             }
+            catch (Orts.Parsers.Msts.STFException)
+            {
+                // End with failure
+            }
         }
 
         static void ShowHelp(List<IDataConverter> converters)
@@ -89,7 +96,7 @@ static void ShowHelp(List<IDataConverter> converters)
             Console.WriteLine("  Multiple outputs may be specified for each input.");
             Console.WriteLine();
             Console.WriteLine("  Available file format conversions");
-            Console.WriteLine("    Input   Output  Description");
+            Console.WriteLine("               Input  Output              Description");
             foreach (var converter in converters)
             {
                 converter.ShowConversions();
@@ -113,7 +120,7 @@ static List<DataConversion> GetConversions(string[] args)
                         {
                             throw new InvalidCommandLineException("Expected input filename; got option " + args[i]);
                         }
-                        conversions.Add(new DataConversion(args[i]));
+                        conversions.Add(new DataConversion(args[i].ToLowerInvariant()));
                         break;
                     case "/output":
                         if (conversions.Count == 0)
@@ -139,7 +146,7 @@ static List<DataConversion> GetConversions(string[] args)
                         {
                             throw new InvalidCommandLineException("Expected output filename; got option " + args[i]);
                         }
-                        conversions.Last().Output.Add(args[i]);
+                        conversions.Last().Output.Add(args[i].ToLowerInvariant());
                         break;
                 }
             }

Source/Contrib/DataConverter/TerrainConverter.cs

@@ -34,9 +34,9 @@ public TerrainConverter()
         public void ShowConversions()
         {
             //                "1234567890123456789012345678901234567890123456789012345678901234567890123456789"
-            //                "    Input   Output  Description"
-            Console.WriteLine("    t       dae     Creates a set of COLLADA files for the tile's terrain.");
-            Console.WriteLine("    w       dae     Creates a set of COLLADA files for the tile's terrain.");
+            //                "               Input  Output              Description"
+            Console.WriteLine("                 *.t  *.dae               Creates a set of COLLADA files for the tile's terrain.");
+            Console.WriteLine("                 *.w  *.dae               Creates a set of COLLADA files for the tile's terrain.");
         }
 
         public bool DoConversion(DataConversion conversion)

Source/Documentation/Manual/features-route.rst

@@ -804,3 +804,124 @@ property::
 
 The value is the fade time in seconds. Use ``0`` to disable the effect 
 completely.
+
+Animated clocks
+===============
+
+.. image:: images/features-animated-clock4.png
+
+Animated clocks that show the simulation time can be added or retro-fitted to a route. 
+The clocks can have a second-hand that ticks each second, or one that moves smoothly or none at all.
+Typically clocks could be station clocks, church tower clocks or clocks at other public buildings. 
+They are placed as normal static shapes in a route, similar to other shapes such as houses or trees.
+
+Note: Loco cabs already have provision for both analogue and digital clocks.
+
+Overview
+--------
+
+You will need:
+
+#. Shape and Texture Files
+
+   A shape file which defines each shape of clock, its hands and their animation and the texture files used by the shape.
+
+#. Reference File
+
+   For each shape of clock in the route, a reference to the shape file in the reference file.
+
+#. Animated Clocks List File
+
+   A file listing the shape file for each clock that Open Rails is to animate.
+
+#. World File
+ 
+   The location of each clock in the world must be given in the world file.
+
+Details
+-------
+
+#. Shape and Texture Files
+
+   Create a clock just like any other shape. The hands of the clock must be sub-objects within the shape. 
+   They must have specific names and an animation.	
+   
+   Open Rails looks for the following names of clock hands in the shape file and animates them according to the simulation time.	
+   
+   The names for the clock hands must start with:	
+  
+   - "ORTS_HHand_Clock" for the hour hand
+   - "ORTS_MHand_Clock" for the minute hand
+   - "ORTS_SHand_Clock" for the second hand
+   - "ORTS_CHand_Clock" for the centi-second hand
+     
+   This last is used to provide a smooth movement in hundredths of a second whereas the second hand ticks forward once a second.	
+   It is suggested to use either the second hand or the centisecond hand or neither.	
+	
+   .. image:: images/features-animated-clock5.png
+   
+   If a clock is to have several hands of the same type, simply append a number to the names of the hands, like this:
+
+   .. image:: images/features-animated-clock6.png
+
+   The animation requires 4 key frames at the 12, 3, 6 and 9 positions and calculates the intermediate 
+   positions using linear interpolation. 	
+   
+   .. image:: images/features-animated-clock3.png
+					
+   For example: ::
+
+	  anim_node ORTS_HHand_Clock01 (				
+		  controllers ( 1			
+			  tcb_rot ( 5		
+				  slerp_rot ( 0  0     0 0 -1 )	
+				  slerp_rot ( 1 -0.707 0 0 -0.707 )	
+				  slerp_rot ( 2 -1     0 0  0 )	
+				  slerp_rot ( 3 -0.707 0 0  0.707 )	
+				  slerp_rot ( 4  0     0 0  1 )	
+				)	
+			)		
+		)
+
+   Finally, move the clock shape and its textures into the corresponding folders SHAPES and TEXTURES of your route, 
+   such as ROUTES\\<route_name>\\SHAPES\\clocks.s
+
+#. Reference File
+
+   Add a reference to the shape file into the reference file ROUTES\\<route_name>\\<route_name>.ref
+   Make sure that this reference begins with the "Static" keyword.::
+
+    Static (	
+	    Filename    ( "ChurchClock.s" )
+	    Class       ( "Clocks" )
+	    Align       ( None )
+	    Description ( "ChurchClock" )
+    )	
+
+#. Animated Clocks List File
+
+   Create a file ROUTES\\<route_name>\\animated.clocks-or file the file for each shape of clock that Open Rails will animate.
+   The type parameter is always "analog" as "digital" types are not yet supported.::		
+   
+      [
+         {
+            "Name": "Clock01.s",
+            "ClockType": "analog"
+         },
+         {
+            "Name": "ChurchClock.s",
+            "ClockType": "analog"
+         },
+         {
+            "Name": "PlatformClock.s",
+            "ClockType": "analog"
+         }
+      ]
+
+#. World File
+
+   Use a route editor to locate the clocks in the world file. 
+   
+   Note: Do not insert the shapes as animated ones. 
+   Otherwise, if MSTS is used to view the route then the hands of the clock will rotate wildly.
+   In Open Rails they will match the simulation time anyway.