PortML.Documents 1.1.80

1. About

PortML stands for Port Markup Language. It is a descriptive language or document which describes container port assets, such as yard blocks, quay cranes, wharves, and AGVs, as a markup code for modelling and simulation.

PortML document follows the PortML specification which is defined in the schema file PortML.xsd. The schema defines all of the datatypes and base infrastructure types.

<b>Note:</b> The coordinate point information is stored as design pixel in PortML document. The actual distance between points must multiply by DesignToActualScale found in PortML Design. The information is stored as PlotUnitScale attribute in PlotScale tag in PortML document.

2. How to Use

using (StreamReader file = new StreamReader("<path to PortML document>"))
{
    try
    {
        string portMLDocument = file.ReadToEnd();

        var parser = new PortML.Documents.PortMLParser();
        var portML = parser.Parse(portMLDocument);
        ...
    }
    catch (Exception ex)
    {
        ...
    }
}

3. Design {#Design}

To retrieve the design metadata from the PortML object, use the following code.

var design = portML.GetDesign();

The code above will return a list of DesignInfo object which contains the following information.

4. Terminal

There will be one and only one Terminal module in the same PortML document. It is to specify the boundary of the terminal and to provide static properties which are general to the entire port system.

To retrieve the terminal information from the PortML object, use the following code.

var terminal = portML.GetTerminal();

If you would like the BoundaryPoints to be in meter, use the following code.

var terminal = portML.GetTerminal(true);

The code above will return a list of TerminalInfo object which contains the following information.

5. Wharf

Wharf is the side of the port terminal where vessels will be parked at.

Quay cranes will be located at the land side of the wharf while vessels will be parked at the sea side. As shown in the following diagram, the direction of the wharf, defined by StartingAt and EndingAt, is important. The wharf direction will decide which side of it is land side and which side of it is sea side.

To retrieve the wharf information from the PortML object, use the following code.

var wharfs = portML.GetAllWharfs();

If you would like the StartingAt, EndingAt to be in meter, use the following code.

var wharfs = portML.GetAllWharfs(true);

The code above will return a list of WharfInfo object which contains the following information.

6. Yard Block

Yard block module is corresponding to the container yard in the sea port terminal.

The starting point and facing direction of a yard block is defined in the way shown in the following diagram. The Facing property defines the direction of the yard block in radian rotating around the StartingAt point. Start Point is located at the top left corner of the yard block when Facing value is 0.

To retrieve the yard block information from the PortML object, use the following code.

var yardBlocks = portML.GetAllYardBlocks();

If you would like the StartingAt, SlotWidth, SlotLength to be in meter, use the following code.

var yardBlocks = portML.GetAllYardBlocks(true);

The code above will return a list of YardBlockInfo object which contains the following information.

7. Traffic Network

To retrieve the traffic network from the PortML object, use the following code.

var trafficNetwork = portML.GetTrafficNetwork();

If you would like the PositioningAt to be in meter, use the following code.

var trafficNetwork = portML.GetTrafficNetwork(true);

7.1 Quay Points

To retrieve the quay point information from the trafficNetwork object, use the following code.

var quayPoints = trafficNetwork.QuayPoints;

The code above will return a list of ControlPointInfo object which contains the following information.

7.2 Yard Points

To retrieve the yard point information from the trafficNetwork object, use the following code.

var yardPoints = trafficNetwork.YardPoints;

The code above will return a list of ControlPointInfo object which contains the following information.

7.3 Quay-Point-to-Yard-Point Distance

To retrieve the distance from each quay point in the traffic network to another yard point, use the following code.

var distanceMatrix = trafficNetwork.PointDistancesFromQuayPointToYardPoint;

The code above will return a list of PointToPointDistanceInfo object which contains the following information.

This distance is calculated using Dijkstra's algorithm in the graph of the traffic network.

7.4 Yard-Point-to-Quay-Point Distance

To retrieve the distance from each yard point in the traffic network to another quay point, use the following code.

var distanceMatrix = trafficNetwork.PointDistancesFromYardPointToQuayPoint;

The code above will return a list of PointToPointDistanceInfo object which contains the following information.

This distance is calculated using Dijkstra's algorithm in the graph of the traffic network.

7.5 Yard-Point-to-Yard-Point Distance

To retrieve the distance from each yard point in the traffic network to another yard point, use the following code.

var distanceMatrix = trafficNetwork.PointDistancesFromYardPointToYardPoint;

The code above will return a list of PointToPointDistanceInfo object which contains the following information.

This distance is calculated using Dijkstra's algorithm in the graph of the traffic network.

8. Quay Crane Statistics

To retrieve the operating time statistics of a quay crane, use the following code.

var quayCraneStatistic = portML.GetQuayCraneStatistics();

The code above will return a dictionary of QuayCraneInfo objects. The key is the quay crane name and the value contains the following information.

9. Yard Crane Statistics

To retrieve the operating time statistics of a yard crane, use the following code.

var yardCraneStatistic = portML.GetYardCraneStatistic();

The code above will return a dictionary of YardCraneInfo objects. The key is the yard crane name and the value contains contains the following information.

10. AGV Parking Lot

AGV Parking Lot is where AGVs will be parked at.

To retrieve the AGV parking lot information from the PortML object, use the following code.

var agvParkingLots = portML.GetAllAGVParkingLots();

If you would like the StartingAt, SlotWidth, SlotLength to be in meter, use the following code.

var agvParkingLots = portML.GetAllAGVParkingLots(true);

The code above will return a list of AGVParkingLotInfo object which contains the following information.

11 PortML Document

PortML document can be retrieved from PortML object by below code:

portML.ToPortMLDocument();

12. Release Notes

28th Feb 2024

• The coordinate points in PortML are stored as drawing pixel.
• Store and retrieve drawing pixel to actual meter scale information in PortML documentation. The information can be found in PlotUnitScale attribute of PlotScale tag.

14th Feb 2024

• Provide PortML document from PortML object through ToPortMLDocument member function

22th Aug 2023

• Bug fix for quay crane statistic collection

18th Oct 2022

• Bug fix for traffic info summary

4th Jul 2022

• The control point tag information may not be unique. Reference ID should be applied for locating control point in PointToPointDistanceInfo
• Support multiple quay crans and yard cranes statistics outputs. Each type of cranes should have its own statistical information.

24th Feb 2022

• Updated TerminalInfo, WharfInfo, YardBlockInfo, ControlPointInfo, and AGVParkingLotInfo to able to return coordinates, slot width, and slot length in meter.

22nd Feb 2022

• Updated YardBlockInfo to provide NumberOfYardCranes.

11th Feb 2022

• Updated TerminalPortMLModule and YardSetPortMLModule to support SINGAPort Studio handling new configuration parameters.

10th Feb 2022

• Introduced DesignInfo with MeterToVector info.
• Updated TerminalInfo to have ClearanceDistance, Forty2TwentyRatio, MaxQcNum, MaxAgvServeEachQC, QcAgvProcessTeu, AgvNum, AgvSpeed info.
• Updated YardBlockInfo to have OperationStackingHeight info.

27th Jan 2022

• Introduced AGVParkingLotInfo.

15th Jan 2022

• Updated the shortest distance retrieval methods to return the tag of control points on the path.

11th Jan 2022

• Updated static properties in Yard Block module.

4th Jan 2022

• Added service time and restore time info of each quay crane and yard crane.

2nd Jan 2022

• Introduced traffic network and distance matrices.

31st Dec 2021

• Introduced TerminalInfo.

30th Dec 2021

• Introduced WharfInfo;
• Introduced YardBlockInfo.

13. Contributors

Domain Experts

• Dr Li Haobin;
• Peng Yuming.

Developers

• Riza Marhaban;
• Carl Chung Yuk Kay;
• Tan Sin Cho.

14. Feedback

Bug reports and contributions are welcome at PortML Contact Us Page.