Revision
Revision
This “How to” guide describes track profiles for dynamic track implemented in Open Rails as of
V716. Externally defined track profiles for dynamic track were supported in Open Rails beginning with
V402. The purpose of this document is to describe the capabilities in enough detail to design and
implement track profiles for dynamic track.
Contents
Contents ................................................................................................................................................ 1
Track Profiles ........................................................................................................................................ 1
Track Profile Hierarchy ........................................................................................................................ 3
TrProfile ............................................................................................................................................ 4
LOD Control ................................................................................................................................. 5
Pitch Control ................................................................................................................................. 6
LOD .................................................................................................................................................. 7
LODItem ........................................................................................................................................... 8
Polyline ............................................................................................................................................. 9
Vertex .............................................................................................................................................. 10
Track Profile Hierarchy Summary .................................................................................................. 10
Track Profile Files............................................................................................................................... 10
STF-Style ........................................................................................................................................ 10
XML-Style ...................................................................................................................................... 11
Installation........................................................................................................................................... 11
Appendix – More on Pitch Control..................................................................................................... 14
Track Profiles
Track profiles are cross sections of track – rails, ties, ballast, etc. – used to specify the geometry of
construction. Track profiles are used to generate a mesh of triangles that can be rendered to provide a
visual representation of “track.” The generation process involves sweeping (or extruding) the cross
section along the railroad’s path, whether straight or curved. The method is termed generative or
procedural.
Default profile for Open Rails dynamic track. The scale is in meters.
The long horizontal line segment (black) models the ballast surface and ties. Details like rounding
and tie detail are suggested by painting those effects on the texture (image) that is wrapped on the mesh
generated. The two short horizontal line segments (green) model the rail tops. The four short vertical
line segments (red) model the rail sides (left and right, inner and outer).
The three categories are used as levels-of-detail (LODs). Suppose that you have a camera positioned
for an external view of the track, low enough so you can see rail sides and high enough so you can see
rail tops. Imagine that you pull back the camera. When you get far enough back, the rail sides will
disappear. (You probably won’t notice.) You’ll still notice the shine off the rail tops. If you continue
moving back, the rail tops will disappear. And, if you continue back farther, eventually the ballast LOD
will disappear. Then, if you reverse direction and move toward the track sections, the LODs will pop
back in (in the reverse order). All this is designed to relieve the load on the processors for complex
scenes.
The method of LOD control described above is called Component Additive: Component because
each LOD is a model of a component, some number of which represent the complete track model.
Additive because, as the camera moves in toward the model, component items are added. There is
another method available to designers called Complete Replacement. There, each LOD item is a
complete model, more or less detailed than the previous LOD item, and, as an LOD item is added, it
replaces the previous one. This topic will be covered in more detail later.
TrProfile
The TrProfile element is at the head (or root) of the hierarchy. A set of attributes and a collection of
LODItems comprise a TrProfile as children. The attributes are:
xmlns Standard for all track profiles that use XML for their
definition. The MSTS Structured Text File (STF) format may
alternatively be used.
Name A descriptive name for the track profile.
LOD Control
The purpose of LOD control is to handle the way LODs are switched in and out of the rendering
queue as a function of the distance between the camera and the object. Two control schemes are
implemented: ComponentAdditive and CompleteReplacement.
ComponentAdditive – To see how this scheme works, consider the illustration below.
In this example, the blue LOD has a cutoff radius of 700 meters; the green and blue LODs, 1200
and 2000, respectively. That is, when those distances are exceeded, the respective LOD is not added
to the rendering queue (i.e., is not seen). Each LOD models a Component of the object, and the
effect of an observer moving in closer to the camera (from the right end of the distance scale here) is
Additive. That is, as the observer moves closer, each time he hits a cutoff radius boundary, another
component is added.
A good example of this scheme is the default track profile where the red, green, and blue arrows
correspond to ballast and ties (red), rail tops (green), and rail sides (blue). Starting with the camera
close to the object, all three components are seen. As the camera moves away from the object and
the 700-meter range is crossed, the rail sides are no longer rendered. Then, as the camera crosses the
1200-meter range, the rail tops leave the render list. Finally, after the camera crosses the 2000-meter
Here, 700, 1200, and 2000 again divide the camera range space into four regions: 0-700 (blue),
700-1200 (green), 1200-2000 (red), and beyond 2000 (nothing). Here, the rules are different: Only
one LOD is displayed for a given camera position. And that is the LOD that has a CutoffRadius
corresponding to the range that the camera is in, that is, 700 (blue), 1200 (green), and 2000 (red).
Each LOD must constitute an appropriate Complete model for that range (hence the Complete in
CompleteReplacement).
Note that, as the camera crosses a region boundary while moving away from the object, an LOD
leaves the scene and is replaced by another (except for the last – beyond-2000). This accounts for
the Replacement in CompleteReplacement.
Which of these methods should be used is strictly a designer preference. Note that, with either of
these two schemes, it is required that the LOD items be arranged in ascending order of CutoffRadius.
Pitch Control
ChordSpan (described above) is the first level of control of the pitch with which profiles are
generated to define a mesh for a model of a curved section of dynamic track. Pitch refers to the angle
subtended by two adjacent profiles, which is a constant for any particular circular-arc section.
ChordSpan pitch control leaves something to be desired for large-radius curves. Hence, two
alternative methods have been introduced for refinement of ChordSpan control – ChordLength and
ChordDisplacement. The following illustrations define these quantities:
The diagram above is an “eye test.” It depicts a curve, which is supposed to be a solid black arc, but
it is broken up by interference from the green straight line segments which approximate the circular arc.
The dashed black line is tangent to the arc at its point of origin (right). A tiny cross marks the origin of
the arc (right). The curve is of 500-meter radius. The diagram depicts one pitch unit of one degree.
There is a second tiny cross at the top of the left-hand extension line for the 8.7265 dimension. The
second cross marks the point where the curve has deflected one degree (one pitch unit). In fact, the left-
hand extension line has a severe case of the “jaggies” because, superimposed with it is a one-degree
radial line to the center of the arc.
Returning to the description of the structure of a track profile, after the root item, TrProfile, next in
the hierarchy is a list of the one or more LODs that comprise the track profile, arranged in order of
increasing CutoffRadius (see below).
LOD
The only purpose for an LOD is to define the component model for a ComponentAdditive model or
the complete model for a CompleteReplacement model. Each LOD has an associated CutoffRadius that
defines the range of camera positions where the LOD is seen. An LOD has only one attribute:
Polyline
A Polyline element is a contiguous* set of straight
line segments that connect a set of points. For example,
consider the illustration to the right. The part labeled “0”
is not a polyline; it’s a point. “1–2” is a polyline, a
single-segment polyline. “3 – 4 – 5” is a two-segment
polyline. “6 – 7 – 8 – 9 – 6” is a four-segment closed
Vertex
A Vertex, by definition, is at the bottom of the hierarchy tree because it has no children. It has only
attributes, which are as follows:
Position The position vector (x, y, z) at the point relative to the local
origin (root) of the track section.
Normal A unit normal vector (nx, ny, nz) at the point, which is used for
lighting calculations.
TexCoord A texture coordinate (u, v) at the point, which is used for
texture wrapping.
STF-Style
MSTS veterans probably have experience with the complete parenthesis syntax of ENG, WAG, etc.
files. Take a look at what an STF-style track profile file looks like for the default profile (page 12).
* In the future, we intend to extend this to multiple profiles, probably distinctly named.
† Hopefully, experience will reveal the superior style, and one will be deprecated in the future.
Track Profiles for Dynamic Track - 10 / 14 - January 22, 2017
It’s relatively clean when formatted this way, and you may be used to it. The down side is that
validation is minimal, and you may have problems figuring out where you made an error. (But MSTS
veterans don’t make errors.*)
The MSTS-style track profile files have a file extension of “.stf”.
All STF files must have a SIMIS-style header on Line 1 which is specific to profiles. It must be:
“SIMISA@@@@@@@@@@JINX0p0t______” (without the quotation marks).
XML-Style
You’ve already seen what XML-style track profile files look like when viewed with XML Notepad
2007. To see what an XML track profile really looks like, see page 13.
There’s not a lot of difference. The principal difference is that XML uses tags (< … >) to bound
elements and name = value syntax to define attributes. Also, XML bounds all values with quotes. So,
there’s a little bit more typing required by the XML style. But then you’ll probably be using an XML
editor (e.g., XML Notepad 2007).
But wait. There is one additional file required by the XML style – TrProfile.xsd. But there is one of
these provided for you, and you had better not modify it. Modify it, and the code breaks!
TrProfile.xsd defines (in XML) the syntax of a track profile. It drives the validation code in Open
Rails used to check the syntax of your track profile (TrProfile.xml).
All you have to remember is to put your TrProfile.xml and the standard TrProfile.xsd in the
TrackProfiles folder in the root folder of the desired route. (If there is sufficient interest in support for
XML, TrProfile.xsd will be treated as Open Rails “content,” and you won’t have to worry about it.)
Installation
Installation is simple:
1. Select a style: STF or XML.
2.
a. If there is no TrackProfiles folder in the root folder of the desired route, make one.
b. If STF, copy TrProfile.stf to the route’s TrackProfiles folder. If there is a TrProfile.xml
in the folder, delete it, rename it, or move it elsewhere. (TrProfile.xml takes precedence
over TrProfile.stf if both are in the folder.)
c. If XML, copy TrProfile.xml and TrProfile.xsd to the route’s TrackProfiles folder.
3. Start the game. (When the game loads, you’ll notice an additional item logged on the
“Loading …” line. It is “TRP,” which stands for TRackProfile. “Default,” “STF,” or
“XML” is output in parenthesis following the “TRP.”
The vertical axis of the plot represents the pitch angle of a series of straight-line segment used as an
approximation to a circular-arc curve; the horizontal axis represents the radius of the curve. The green
line represents a constant one-degree pitch angle, independent of radius – what you get with a
ChordSpan control scheme.
Look at the blue curve, which is a plot of the pitch angle required to hold a 10-meter chord length as
a function of curve radius. Note that it crosses the one-degree line at about 600 meters radius. (Note
that the radius axis has a logarithmic scale.) This tells you that, above 600 meters radius, you will be
missing a target of 10-meter chord length with a one-degree chord span. Similarly, you will be missing
a target of 12.5-meter chord length (magenta curve) for radii above about 700 meters. If you seek a
target of 34 mm chord displacement (half a rail width), you will miss it with a one-degree chord span for
radii above about 900 meters.
The ChordLength and ChordDisplacement scheme are, in fact, algebraically related. If 𝐿 is the
chord length and 𝑑 is the chord displacement, then:
𝜃 𝜃
𝐿 (1 − cos ) = 2 𝑑 sin
2 2
for any given chord span 𝜃. Thus, 𝐿 and 𝑑 are linearly related for any given chord span, 𝜃. For
example, for a one-degree chord span:
𝑑 = .00218 𝐿
Thus, for a one-degree chord span, a 10-meter chord length would yield a chord displacement of 21.8
mm.