Railway Track

Railway Track is a graphical space markup element that represents a continuous rail track (i.e. the one that does not contain any switches) of arbitrary shape. Track may contain multiple linear and/or curved segments. A single track is automatically placed inside a railway network which can be extended further by adding and connecting more tracks.

The track knows switches at the either end, if there are any. If there is no switch at one of the sides (an open-ended track), and a rail car exits the track at that side, the car leaves the rail yard model.

The track knows all cars that are (fully or partially) located on it, and you can obtain those cars using the track API.

Cars on a track

Track blocking and reservation

The track API offers a range of functions to block tracks, i.e. make them unavailable for all trains, or reserve tracks, i.e. make them available only for the specified trains. The behaviour of the train when the track becomes unavailable depends on the train's state at the time of the blocking or reservation:

Note: If the train is moving along the track which at that moment becomes reserved for another train, an error will occur.

Note: The track cannot be reserved twice. If you try to reserve a track with an existing reservation, an error will occur.

Tracks remain blocked until the unblock() function is called. The reservation is removed automatically after the specified trains have passed the track that was reserved for them, or it can be removed by calling the cancelReservation() function.

Demo model: Railway Track Reservation


Demo model: Blocking Railway Tracks


Demo model: Level Junction

To draw a railway track

  1. Double-click the Railway Track element in the Space Markup section of the Rail Library palette.
  2. The icon of the element should turn into . It means that the drawing mode is activated and now you can draw railway track in the graphical editor point by point.
  3. Click in the graphical editor to draw the first point of the track. Do more clicks to add more points.
  4. To draw a curved segment, do not release the mouse button while clicking, but move the mouse with the left mouse button pressed.

  5. Finally put the final point of the track with the double-click.

  6. You can make changes to the railway track even when it is finished. Select the track in the graphical editor, click an editing point and drag it without releasing the left mouse button. These connecting parts of the track will be changing as you drag the point. Release when finished adjusting the form of the railway track.

  7. The editing points can be added or removed by double-clicking anywhere on the railway track. If you double-click the end point of the first or last segment, this segment will be deleted.
  8. You can edit the track by making segments linear or curved on any stage of drawing.

You can continue drawing the railway track after you finished it with the double-click.

To add a segment to the railway track

  1. Right-click the track you have drawn and select Append line from the context menu. You can append a line to any end point of the track by clicking this point.

  2. You are now in the drawing mode again. You can add as many new segments as you need, both linear and curved.
  3. Put the final point of the railway track with the double-click.

You can change a linear line to curved and vice versa as well as edit the curve shape anytime.

To change a curved line into linear
  1. Click a railway track in the graphical editor to select it.
  2. Hit Ctrl button on your keyboard and hold it. At the same time click a point on the curved segment and drag the point without releasing the button.
  3. Release the buttons when the line is linear and has the required shape.

To change a linear line into curved
  1. Right-click the railway track and select Edit using guiding lines from the context menu. The guiding lines will appear for editing points. Click an editing line point and drag it around without releasing the mouse button.

  2. Right-click the track and deselect Edit using guiding lines from the context menu to switch off this editing mode.

Several railway tracks can be connected together, with or without the use of a railway switch. You can disconnect the track segments too.

To connect two or more railway tracks into one track

  1. When you connect two railway tracks at their end points, they become one track. In the example below, the option Append line was used to connect railwayTrack1 to railwayTrack.

  2. The connecting point where the two tracks merge is highlighted with the cyan color. Two shapes have now become one element, railwayTrack1. The former segments of railwayTrack have inherited the name and the direction.

  3. As long as you connect the railway tracks by their edge segments, they will merge into one track.

To connect two or more railway tracks with a switch

  1. You can connect railway tracks with a railway switch if you draw a segment that connects anywhere to the path and not to its end point. In the example below, the element railwayTrack was connected to railwayTrack1 in the middle. Multiple railway tracks can be connected with each other this way.

  2. The railway switch will appear itself in the place of connection. It is highlighted in the cyan color. Now you have created a railway network with several tracks in it. In the example below, the railway switch breaks the track into parts, railwayTrack1 and railwayTrack2 while railwayTrack does not merge with railwayTrack1, but remains a separate track.

    You can connect in one railway switch as many tracks as you need.
  3. The first click selects all elements of this railway network, make one more click to select railway switch and edit its properties. If you right-click the railway switch and select Delete from the context menu, the railway tracks will be connected graphically, but they will not be a railway network anymore.

You might want to split the railway track into several tracks by segments.

To disconnect the railway track segments

  1. Right-click the railway track in the graphical editor and select the option Split into two shapes from the context menu.
  2. When the editing points are highlighted, click an editing point where you want to break the track. The railway track will be split immediately even if the segments look connected in the graphical editor, you can select one or another to check that they are separate tracks now.

Properties

General

Name – The name of the track. The name is used to identify and access the track from code and flowchart blocks properties.

Ignore – If selected, the track is excluded from the model.

Visible on upper agent – If selected, the track is also visible on the upper agent where this agent lives.

Lock – If selected, the railway track is locked. Locked shapes do not react to mouse clicks - it is impossible to select them in the graphical editor until you unlock them. It is frequently needed when you want to prevent editing this shape while drawing other shapes over it.

Visible – Here you specify whether the shape is visible on animation at model runtime, or not. Using the control, choose yes or no.

Bidirectional - Here you can enable movement on the railway track in both directions.

Appearance

Type – The type of the element is Railroad.

Track gauge – The spacing of the rails on a railway track, which is measured between the inner faces of the load-bearing rails.

Position

X – X-coordinate of the track's start point.

Y – Y-coordinate of the track's start point.

Z – [Enabled if Show in 3D option is selected] Z-coordinate of the track's start point.

Points

The table located in the Points property section enables users to view and adjust coordinates of the track turning points.

Here you define relative coordinates, not the absolute ones. The first point always has coordinates (0, 0, 0) that can not be changed.
Other rows of the table define relative coordinates of the successive points. Coordinates of each point are actually offsets of the corresponding point from the start point along X, Y (and optionally Z) axes correspondingly.

Advanced

Show in - Here you can choose whether you want the shape to be shown both in 2D and 3D animation, or in 2D only, or in 3D only.

Show name – If selected, the track's name is displayed on the graphical diagram.

Track orientation

The track has start point and end point, and therefore has orientation. The exact position on the track may be defined by the specific markup element Position on Track.

To know the direction of the track, select it in the graphical diagram by a mouse click.

To change the direction of the track

  1. Right-click the track in the graphical diagram and choose Change direction from the context menu. You will see that the arrows changed their directions.

Functions

Cars

Function

Description

int nCars()

Returns the number of cars on the track (including cars that are only partially there).

Agent getFirstCar()

Returns the car closest to the beginning of the track, or null if the track is empty.

Agent getLastCar()

Returns the car closest to the end of the track, or null if the track is empty.

Agent getCar(int index)

Returns a car on the track with a given index counted from the beginning of the track. All cars count: moving, standing, coupled, and cars that are only partially on this track.

Parameter:
index - the index of the car

List<Agent> getCars()

Returns the list of rail cars that are located on this track including the cars that are only partially on this track.

List<Agent> getTrains()

Returns the list of trains that are located on this track including the trains that are only partially on this track.

boolean isEmpty()

Tests if the track is empty, i.e. there are no cars that are (even partially) on the track. Returns true if the track is empty, false otherwise.

double getFreeSpace(boolean fromstart)

Tests the availability of space on the track. If there are no cars on the track, returns infinity. If there are cars, returns the distance from the track start or end point (depending on the fromstart parameter) to the nearest car. If there is a car that has partially entered or exited the track at a given side, the functions returns a negative value.

Parameter:
fromstart - if true, space is checked from the start point of the track, otherwise from the end point


Switches

Function

Description

RailwaySwitch getStartSwitch()

Returns switch ( Switch object) at the beginning of the track.

RailwaySwitch getEndSwitch()

Returns switch at the end of the track.

RailwaySwitch getSwitch(boolean atend)

Returns the switch at the beginning or at the end of the track.

Parameter:
atend - if true - the switch at the end is returned, otherwise at the beginning

RailwaySwitch getOtherSwitch(RailwaySwitch sw)

If the given switch is a 'start switch' of this track, the function returns current track's 'end switch', otherwise it returns 'source switch'. Note that this function doesn't check that the given is either 'start switch' or 'end switch': this is the responsibility of the user calling this function.

Parameter:
sw - the switch (one of the track endings)


Blocks and reservations

Function

Description

void block()

Blocks the track. Trains located on this track at the moment of blocking can leave the track but cannot re-enter it unless the block has been removed.

void unblock()

Unblocks the track.

boolean isBlocked()

Checks whether the track is blocked. If the function returns true, the track is blocked. If false - the track is not blocked.

void setBlocked(boolean blocked)

Sets the track's "blocked" status.

Parameter:
blocked - if true, the track will be blocked; if false - the track will be unblocked.

void reserveFor(Agent... trains)

Reserves the track so that only the given trains can move through it.

Parameter:
trains - trains that are allowed to move through the track.

List<Agent> reservations()

Returns the list of trains that this track has been reserved for.

void cancelReservation()

Cancels existing reservations for the track. Any train will be able to move through the track provided that this track is not blocked.

boolean isAvailableFor(Agent train)

Checks if the given train can move through the track. The function checks for both blocking and reservation.

Parameter:
train - if true, the given train can move through the track; if false - the train cannot move through the track.


Location

Function

Description

RailwayNetwork getRailYard()

Returns rail yard (railway network) this track belongs to, or null if it is not a part of a rail yard.


Dimensions

Function

Description

double length()

Returns the length of the track in pixels.

double length(LengthUnits units)

Returns the length of the track in specified length units.

Parameter:
units - a constant defining the length units

double getWidth()

Returns the width of the track, measured in pixels.

double getWidth(LengthUnits units)

Returns the width of the track, measured in given units.

Parameter:
units - a constant defining the length units

void setWidth(double width)

Sets the width of the track, 0 means thinest possible.

Parameter:
width -
the new width of the track, in pixels

void setWidth(double width, LengthUnits units)

Sets the width of the track, 0 means thinest possible.

Parameters:
width -
the new width of the track, measured in given units
units - a constant defining the length units


Level

Function

Description

Level getLevel()

Returns the level on which this track is located.


Appearance

Function

Description

Texture getTexture()

Returns the texture of the shape, if the shape has texture.

Color getColor()

Returns the color of the shape, or null if shape has no color or if it has texture (in this case getTexture() should be used instead).

void setColor(Color color)

Sets the color of the shape.

Parameters:
color - the new color, if null the track is not drawn

void setColor(Paint color)

Sets the texture of the shape.

Parameter:
color -
the new color, if null the track is not drawn


Visibility

Function

Description

boolean isVisible()

Returns the visibility of the track. If it returns true, the track is visible, if false - not visible.

void setVisible(boolean v)

Sets the visibility of the track.

Parameter:
v - visibility of the track. If true, track is visible, if false - not visible.


Removal

Function

Description

void remove()

Removes this track from the presentation. If the track is not a part of presentation, the function does nothing. Note, that removal from the presentation does not necessarily mean removing from the model logic, since logical networks and routes may have been created before the removal and survive it.


Related topics

Railway network

Railway switch

Position on track

Rail Library

API reference: RailwayTrack class