RailCar

Rail cars are created by TrainSource objects within trains and are fully controlled by trains during their whole lifetime in the rail yard. 

From the Rail Library viewpoint there is no difference between a car and a locomotive or between cargo and passenger car, but you can make such distinction in your model, for example, you can specify different dimensions, assign different animation shapes, or create different rail car types with different properties and functions.

How-To video: Setting up a freight train

A rail car has length and two sides: front and rear. The length of the rail car can only be set up at the time of its creation (e.g. in the Car length or in the Car setup code of TrainSource) and cannot be changed later on. You can get the location (track, orientation on track, and offset) of the either side of the car. You can ask the car to “call back” and execute a custom action at the specified point of a given track. Arbitrary information can be passed to the callback code.


Rail cars in 2D

Rail cars in 3D

To create a custom rail car type

  1. Open the Rail Library palette and drag the Rail Car Type element onto the agent type diagram, e.g. Main.

  2. The New agent wizard window will open. Specify Agent type name. Click Next to proceed to the next step.

  3. Now you can select 3D or 2D animation figure for the car. Select None if you do not need a car animation or if you would like to add your own animation figure later.

  4. Here you can define the parameters of the rail car. Click < add new... > and specify the parameter name, type and default value. To remove a parameter from the list, click the button . You can always add more parameters onto the rail car diagram after you finish creating it.

  5. Click Finish. AnyLogic will automatically open new rail car type diagram. You can find the animation figure in the axis origin. 

  6. Now you can use the new car type in the Rail Library blocks parameters, for instance, in TrainSource properties:

Functions

General API (functions always available no matter whether the car is controlled by a Train or not)

Constructors and initial setup

RailCar() - Creates a new rail car of length = 14m, width = 4m, speed = 10m/sec, and a random color.

RailCar( double length ) - Creates a new rail car of a given length, width = 4m, speed = 10m/sec, and a random color.
        Parameter: length the length of the car in meters.

RailCar( double length, double width ) - Creates a new rail car with given length and width, speed = 10m/sec, and a random color.
        Parameters: length the length of the car in meters.
                          width the width of the car in meters.

The visual appearance

void setLength(double length) - Sets the length of the car. Can only be done before the car is added to the rail yard.
        Parameter: length the length of the car in meters

double getLength() - Returns the length of the car in meters.

void setWidth( double width ) - Sets the width of the car in meters.
        Parameter: width the new width of the car in meters

void setWidth( double width, LengthUnits units ) - Sets the width of the car in specified length units..
        Parameters: width the new width of the car
             units - one of length unit constants

double getWidth() - Returns the width of the car in meters.

double getWidth( LengthUnits units ) - Returns the width of the car in specified length units.
        Parameter: units - one of length unit constants

void setColor( Color color ) - Sets the color of the car. Although the color is always stored in a RailCar object, it only applies to the default animation.
        Parameter: color the new color

Color getColor() - Returns the color of the car.

void setShape( Shape shape ) - Sets a custom 2D or 3D shape that will be used to animate this car.

Shape getShape() - Returns a custom shape that is used to animate the car, or null.

void highlight( boolean yes ) - Highlights or dehighlights the rail car.
        Parameter: yes - true for highlighted status, false for regular

boolean isHighlighted() - Tests if the rail car is currently highlighted. Returns true if highlighted, false otherwise

Information about the car

Agent getCoupledCar( boolean infront ) - Returns the car coupled with this one at a given side, or null.
        Parameter: infront - if true, this is front side, otherwise rear side

boolean getDirection() - Returns the direction in which the car is moving (or was moving last time): true if forward (front before rear), false if reverse

Agent getTrain() - Returns the train the car belongs to, or null.

boolean isFirst() - Checks if this if the first car in a sequence of coupled cars (which does not necessarily form a Train object), i.e. if there is no coupled car moving before this car. If the car is not moving, the result is undefined. Returns true if this is the first car in a sequence (or a standalone car), false otherwise.

boolean isLast() - Checks if this if the last car in a sequence of coupled cars (which does not necessarily form a Train object), i.e. if there is no coupled car moving after this car. If the car is not moving, result is undefined. Returns true if this is the last car in a sequence (or a standalone car), false otherwise

double getSpeed() - Returns the speed of the car in meters per second. Nonzero speed does not mean the car is moving.

double getSpeed( SpeedUnits units ) - Returns the speed of the car in given speed units. Nonzero speed does not mean the car is moving.
        Parameter: units - one of speed unit constants

RailwayTrack getTrack( boolean infront ) - Returns the track on which a given side of car is currently located.
        Parameter: infront - if true, this is front side, otherwise rear side

double getOffset( boolean infront ) - Returns the offset of a given side of car relative to the track start point in meters: 0 - the beginning of the track.
        Parameter: infront - if true, this is front side, otherwise rear side

boolean getOrientation( boolean infront ) - Tests if the car has same orientation as the track on which a given side of the car is located. Returns true if the car has same orientation as the track.
        Parameter: infront - if true, this is front side, otherwise rear side

boolean isForwardOnTrack( boolean infront ) - Returns the direction of the car movement relative to the track on which one (or both) sides of car are located. Returns true if car direction is same as track (start->end).
        Parameter: infront - if true, this is front side, otherwise rear side

boolean isMoving() - Tests if the car is currently moving. Returns true if moving, false if not

double getX( boolean infront ) - Returns the x coordinate of a given side of the car relative to the rail yard group of shapes in pixels.
        Parameter: infront - if true, this is front side, otherwise rear side

double getY( boolean infront ) - Returns the y coordinate of a given side of the car relative to the rail yard group of shapes in pixels.
        Parameter: infront - if true, this is front side, otherwise rear side

double getDistanceDriven() - Returns the distance driven by the rail car in meters since its creation or since the last call of resetDistanceDriven().

void resetDistanceDriven() - Resets the distance driven by the rail car to zero.

RailwayNetwork getRailYard() - Returns the rail yard where the car is currently in.

Callbacks

void callbackAt( RailwayTrack track, double offset, Object info ) - Requests the rail car to execute a callback (parameter onAtCallback of the RailSettings) at the specified point, namely when its side that moves in front reaches that point. Just before the callback this request is discarded (although in the callback code the user may request another one). Each new request discards a previous one. You can pass arbitrary information (Object) to the callback code to identify what kind of event it is.
        Parameters: track - the track to execute callback at
              offset - offset on the track to execute callback at, meters
                            info - arbitrary Java object that will be passed to the callback code

void callbackAt( RailwayTrack track, double offset ) - Same as callbackAt( track, offset, null ).
        Parameters: track - the track to execute callback at
              offset
- offset on the track to execute callback at, meters

void callbackAt( RailwayTrack track, PositionOnTrack pointOnTrack, Object info ) - Same as callbackAt( track, offset, info ) where the offset is the offset of intersection of the track and a given position on track.
        Parameters: track - the track to execute callback at
              pointOnTrack - Position on Track element that crosses the track
                            info - arbitrary Java object that will be passed to the callback code

void callbackAt( RailwayTrack track, PositionOnTrack pointOnTrack ) - Same as callbackAt( track, pointOnTrack, null ).
        Parameters: track - the track to execute callback at
              pointOnTrack - Position on Track element that crosses the track

Low-level API (these functions are not available when car is a part of a Train)

Disposal

void dispose() - Completely disposes the car, i.e. removes it from the yard no matter where it was. The car must be not moving and must not belong to a Train. This function is also called by TrainDispose.

Movement

void stop() - Stops the car. If it is stopped, does nothing. The car must not be a part of a train.

void go( boolean forward ) - Starts the car motion (or changes its direction). The speed must be positive.
        Parameter: forward - if true, the car will move forward (front side before rear), otherwise reverse

void couple( boolean infront ) - Couples the car with another car that is on a given side. The car must not be a part of a train.
        Parameter: infront - if true, couple at front side, otherwise at rear

void decouple( boolean infront ) - Decouples the car from another car on a given side. Signals error if the car is not coupled here. The car must not be a part of a train.
        Parameter: infront - if true, decouple at front side, otherwise at rear

void setSpeed( double s ) - Sets the new speed of the car in meters per second. It applies immediately even if the car is moving. If the speed is set to 0, the car stops if it was moving. The car must not be a part of a train.
        Parameter: s - the new speed in meters per second

void setSpeed( double s, SpeedUnits units ) - Sets the new speed of the car in given speed units. It applies immediately even if the car is moving. If the speed is set to 0, the car stops if it was moving. The car must not be a part of a train.
        Parameters: s - the new speed in given units
             units - one of speed unit constants