Difference between revisions of "Panel2.cfg"

■ 1. Overview

The panel2.cfg file allows to create 2D panels by defining which elements to use, like lamps, needles, etc., what they are intended to display and where they are to be placed.

The panel2.cfg file is a plain text file encoded in any arbitrary encoding, however, UTF-8 with a byte order mark is the preferred choice. The parsing model for numbers is Loose, however, you are encouraged to produce Strict output nonetheless. The file is required to be located inside the train folder and is expected to be named panel2.cfg. The file is interpreted on a per-line basis, from top to bottom.

➟ See also the quick reference for the panel2.cfg...

■ 2. Syntax

Each line in the file can be empty (or solely consist of white spaces) and will be ignored, can mark the beginning of a new section or contain key-value pairs inside a section. All key-value pairs relate to the last section opened.

A new section is opened by starting the line with an opening bracket (U+005B) and ending it with a closing bracket (U+005D). The text in-between the brackets indicates the name of the section and is case-insensitive. White spaces at the beginning and the end of the line are ignored, as well as at the beginning and the end of the name of the section. Thus, the beginning of the section has the following form:

A key-value pair is indicated by giving the key, an equals sign (U+003D) and then the value. The key is case-insensitive. White spaces at the beginning and the end of the line are ignored, as well as in front and after the equals sign. Alternatively, white spaces surrounding the key and the value are ignored. Thus, a key-value pair as the following form:

Some values are further split into multiple parts, separated by commas (U+002C).

You can use comments anywhere at the end of a line. A comment is started by a semicolon (U+003B). Comments, if present, are stripped away from all lines before these are processed.

■ 3. The This section

The This section defines the background image to use for the panel and which resolution the panel has. Only one This section may be used within the file.

This starts the section.

Defines which pixel in the background image corresponds to the center of the screen for the default camera position. The relation between Center and Origin influences the yaw and pitch of the cab alignment.

Defines which pixel in the background image corresponds to the vanishing point for the default camera position. This is the point to which the two rails converge at the horizon on a straight piece of track. The relation between Center and Origin influences the yaw and pitch of the cab alignment.

File:Illustration center origin.png

■ 4. The PilotLamp section

The PilotLamp section creates an indicator that can be made visible or invisible. You can use as many of these sections as required.

The DaytimeImage is required to be specified if you make use of the PilotLamp section. The Subject used needs to return 1 if the PilotLamp is to be made visible, otherwise it will be invisible.

This starts the section.

■ 5. The Needle section

The Needle section creates a rotating element, or needle. You can use as many of these sections as required.

The image used for the Needle, defined by DaytimeImage (required) or NighttimeImage (optional), will be rotated around a defined Origin and optionally scaled if Radius is used. The needle depicted in the image should be pointing up.

This starts the section.

The Y value in the Origin key-value pair defines the vertical point of rotation, but also defines the actual radius of the element in the bitmap's own pixel coordinates. If ValueInPixels is set to a different value than this actual radius, the image will be scaled by a factor of Radius / Y, while preserving the Origin-Center relation. If you do not want to scale the image, set ValueInPixels to the same value as Y in the Origin key-value pair, or omit Radius altogether.

Multiplies the images by the color specified by HexColor. Setting HexColor to #FFFFFF (white) preserves the original color of the images, while setting HexColor to #000000 (black) produces black images. Pixels defined as being transparent via TransparentColor are not affected.

Defines the natural frequency. In an undamped oscillatory system, this is the angular frequency in radians per second. As soon as damping is performed, the frequency will decrease with convergence of the oscillator. A natural frequency of 0 will not allow any rotation to be performed. Higher values roughly correspond to radians per second. If specified, DampingRatio should also be specified.

Defines the damping ratio for the oscillatory system. Values between 0 and 1 represent under-damping, 1 represents critical damping and values above 1 represent over-damping. Compare the following illustration in which the angle of rotation changes from 0 to 1 over time:
File:300px-2nd Order Damping Ratios.svg.png
If specified, NaturalFreq should also be specified.

■ 6. The DigitalNumber section

The DigitalNumber section creates an indicator that can switch between multiple states, useful to build up a display of decimal digits. You can use as many of these sections as required.

The image used for the DigitalNumber, defined by DaytimeImage (required) and NighttimeImage (optional), is comprised of the individual states, which are stacked vertically, anchored at the top of the image. The width of a single state is equal to the width of the image, while the height of a single state is defined by Interval (required). The Subject used needs to return an integer from 0 (first element) to n-1 (last element), where n is the number of elements. If a value outside of that range is returned by Subject, the DigitalNumber will be made invisible.

This starts the section.

■ 7. The DigitalGauge section

The DigitalGauge section creates a solid-color square of which only a radial section is shown at a time. You can use as many of these sections as required.

There are three important angles to consider. The InitialAngle defines which angle corresponds to the Minimum value, while LastAngle defines which angle corresponds to the Maximum value. The current value at a given time corresponds to the current angle. The solid-color square will only show the part that is between the current angle and the LastAngle. If InitialAngle is less than LastAngle, the solid-color square will wind clockwise. If InitialAngle is greater than LastAngle, the solid-color square will wind counter-clockwise.

The subject needs to return a value that meaningfully works together with the Minimum and Maximum settings.

File:Illustration digitalgauge 1.png

File:Illustration digitalgauge 2.png

This starts the section.

If Radius is negative, it is treated as if it was positive, but the entire LED is rotated by 180 degrees.

■ 8. The Timetable section

The Timetable section defines where to place custom timetables. The actual images are loaded via the route file. Only one Timetable section may be used within the file.

This starts the section.

■ 9. Available subjects

A subject is composed of a base subject and an optional subject suffix. The subject controls what information is fed to the element that uses the subject. For example, a Needle can use the subject kmph to be fed with the current speed of the train in kilometers per hour, or with the mr subject to show the main reservoir pressure.

● Base subjects

If atsi is used with the built-in safety systems ATS and ATC, the following mapping for i applies:

● Suffixes

Example: kmphd1 can be used to feed a DigitalNumber with the tens of the current speed of the train in kilometers per hour. The image used by the DigitalNumber will thus need to be composed of images from 0 to 10 in order to show all possible states kmphd1 can return, where images 0 through 9 correspond to the digits, and 10 corresponds to an image shown at the tens when the speed is below 10 km/h (e.g. another 0-digit, or blank space).