Intermodal Converter examples

Here we provide examples on how to convert intermodal networks/zoning. The term intermodal is chosen based on the notation that it represents a network with the option to switch between modes within a trip. This means that it comprises both a PLANit network as well as a PLANit zoning (where the zoning is expected to at least contain transfer zones, e.g., locations where transfers between modes can take place) in terms of the memory model that an intermodal converter deals with.

Like other converters it can take intermodal inputs in one format, reads them, and then convert them into another format by writing them. All converters adopt the same approach in setting up an intermodal converter. It requires an IntermodalReader implementation, an IntermodalWriter implementation, and an IntermodalConverter instance. PLANit provides factory classes for each converter type, such that for intermodal converters the IntermodalConverterFactory can be used create a IntermodalConverter. Then, each implementation of a reader and/or writer also provides their respective factory class for the creation of instances, e.g., the PLANit native format reader/writers can be created via the PlanitIntermodalReaderFactory.create() and PlanitIntermodalWriterFactory.create() methods, respectively. Other supported formats (should) follow the same approach. And if desired, the user can create their own reader/writer imlpementation as well.

Further, each intermodal reader and writer must provide access to user configurable settings in the same way, namely via a .getSettings() method. This allows the user to configure the reader and writer before conducting any conversion. Some settings must be configured otherwise the reader/writer might fail. If this is the case, the factory will provide a .create() method that allows you to immediately provide the mandatory inputs upon creation to pass along to the settings directly (or alternatively they can be manually set afterwards).

Most intermodal reader/writers are in fact wrappers around a combination of an existing network and zoning reader/writer. They are just bundled as an intermodal writer for convenience to support certain common (network + pt) conversions.

Prerequisites:

• It is assumed you are familiar with the data formats of the converters discussed here, otherwise see Data formats

Note that the required Java imports are not listed in these examples as it is expected that the user has access to an IDE (like Eclipse), where this is added to the Java file automatically upon usage.

Minimum example

In this example we simply parse an intermodal network in the PLANit XML format and then persist it again in the same format, with the absolute minimum of configuration. See also Data formats/Input/Default section for more information on the PLANit XML network and zoning data formats.

Compulsory settings

the PLANit reader/writer has the following compulsory settings that must be configured, either by providing them to the factory method, or by configuring them after the instance is created:

reader:

• Input directory, to look for the network/zoning files

writer:

• Output directory, to store the result network/zoning files in

PLANit example

final String inputDir = "<inputDir>";
final String outputDir = "<outputDir>";
      
/* reader */
PlanitIntermodalReader planitReader = PlanitIntermodalReaderFactory.create(inputDir);
            
/* writer */
PlanitIntermodalWriter planitWriter = PlanitIntermodalWriterFactory.create(outputDir);
      
/* convert */
IntermodalConverterFactory.create(planitReader, planitWriter).convert();

MATSim writer example

Here, we parse PLANit intermodal network in the native XML format and then persist it as a MATSim network (file) and a separate public transport (pt) schedule (file), where the pt part accounts for the intermodal aspect.

Currently no pt lines and or services are supported, so only the stop facilities are populated at this stage, allowing for MATSim to conduct a simulation with teleportation for its pt modes. It is likely that lines and services will be supported in future versions.

Under the hood the intermodal MATSim writer utilises a MatsimNetworkWriter and an additional MatsimZoningWriter for the intermodal components. Therefore the configuration of the intermodal writer is performed by first accessing the settings for either underlying writer, e.g. .getSettings().getNetworkSettings(), and then perform the desired configuration analogous to how one would for example configure the MatsimNetworkWriter via .getSettings() directly.

To enhance the quality of the network when viewing it in VIA, we configure the writer such that it produces an additional geometry file that contains the shapes of each link beyond the two extreme nodes. See also Data formats/Input/MATSim section for more information on the MATSim network data format.

Identical to a MATSIM network writer, when creating the MATSim intermodal writer you can explicitly provide the name of the country the network/zoning resides in. This is useful in case you do not wish to use the coordinate reference system (crs) of the network created by the reader, but want PLANit to determine a crs based on the country name provided. If the provided country is not supported, PLANit will revert to the network’s crs. Alternatively, the user can set the desired crs explicitly by creating one and providing it to the writer via .getSettings().setDestinationCoordinateReferenceSystem(). Whenever the destination crs differs from the network’s crs all geometries are transformed in the desired projection when persisting.

Currently the MATSim network only supports PLANit networks with predefined modes via its default mapping, custom PLANit modes have to be manually added to the mapping if they are to be preserved.

The default mode mapping in the MATSim writer maps all public transport modes to a single MATSim mode “pt”. If this is not desired, the user needs to override this mapping manually via the settings.

Compulsory settings

The MATSim writer has the following compulsory settings that must be configured, either by providing them to the factory method, or by configuring them after the instance is created:

• Output directory to store the result network in

MATSim example

final String inputDir = "<inputDir>";
final String outputDir = "<outputDir>";
final String countryName = "<countryName>";
final CoordinateReferenceSystem crs = PlanitCrsUtils.createCoordinateReferenceSystem("<srsName>");
      
/* reader */
PlanitIntermodalReader planitReader = PlanitIntermodalReaderFactory.create(inputDir);

/* writer */
MatsimIntermodalWriter matsimWriter = MatsimIntermodalWriterFactory.create(outputDir, countryName);

/* settings -> detailed geometry for network */
matsimWriter.getSettings().getNetworkSettings().setGenerateDetailedLinkGeometryFile(true);

/* settings -> override destination crs for both network and zoning */
matsimWriter.getSettings().setDestinationCoordinateReferenceSystem(crs);

/* convert */
NetworkConverterFactory.create(planitReader, matsimWriter).convert();

At this stage only writer implementations are available for MATSim, a reader might be added in future versions.

Open Street Map reader simple example

The Open Street Map reader is more than just a reader for Open Street Map (OSM). Because OSM is not specifically meant for creating topological (intermodal) networks and/or traffic assignment, the reader not only parses networks as is, but also adapts them to construct a topologically meaningful (intermodal) network that is compatible the with PLANit memory model and is suitable for assignments. See also Data formats/Input/OSM section for more information on the OSM data format.

To be able to parse OSM intermodal networks, a large number of additional configuration options are made available to the user. These settings are split between settings specific to parsing network infrastructure (road/rail) and settings specific to the public transport (pt) non-road infrastructure extracted from OSM. The public transport infrastructure comprises stations, platforms, bus stops (poles), and vehicle stop locations, e.g., locations where intermodal transfers take place. So, the .settings() allow access to:

• OSM general settings via .getSettings().<method_name>
• OSM network reader specific settings via .getSettings().getNetworkSettings().<method_name>
• OSM public transport specific settings via .getSettings().getPublicTransportSettings().<method_name>

The OsmIntermodalReader implementation is a wrapper around an OsmNetworkReader and an OsmZoningReader, where the former is configured via the .getSettings().getNetworkSettings() providing access to OsmNetworkReaderSettings, while the latter is configured via .getSettings().getPublicTransportSettings() and is responsible for the parsing of the public transport aspects converting them into PLANit compatible entities, namely transfer zones (stations, platforms) and connectoids (pt vehicle stop locations). Please consult the OsmNetworkReader Examples for more comprehensive examples showcasing the configuration of the network aspects of the reader

We cannot show every option in this example, please consult the JavaDoc for detailed documentation on each separate option available

Logging is extensive for this reader. This is because based on warnings/info messages generated, the user is expected to adjust the settings to manually configure/override tagging errors and/or issues the automated conversion/salvaging procedures in the parser flagged. It is therefore recommended to first conduct a trial run with default settings and then gradually update the configuration based on the feedback by the reader.

Compulsory settings

The OSM reader has the following compulsory settings that must be configured, either by providing them to the factory method, or by configuring them after the instance is created:

• Input file path, containing directory and file name to extract network from
• Country name, to discern what driving direction the roads have and what defaults to apply

The country name determines the defaults used by the OSM reader, e.g., what driving direction roundabouts have, what default speed limits to apply to given OSM way types, etc. These defaults are detailed in the Data formats/Input/OSM section. In case the country name is not provided, the Global defaults (right-hand driving) will be applied, but it is discouraged to use because it likely requires overriding the default speed limits for all used road types.

OSM simple example

final String inputFilePath = "<inputDirAndFile>";
final String outputDir = "<outputDir>";
final String countryName = "<countryName>";
      
/* reader */
OsmIntermodalReader osmReader = OsmIntermodalReaderFactory.create(inputFilePath, countryName);

/* exclude particular osm ways via network settings */
osmReader.getSettings().getNetworkSettings().excludeOsmWaysFromParsing(1234, 5678, 9101112);
/* exclude particular osm nodes representing pt infrastructure via pt settings */
osmReader.getSettings().getPublicTransportSettings().excludeOsmNodesById(1234, 5678, 9101112);

/* writer */
PlanitIntermodalWriter planitWriter = PlanitIntermodalWriterFactory.create(outputDir);

/* convert */
IntermodalConverterFactory.create(osmReader, planitWriter).convert();

At this stage only reader implementations are available for OSM, a writer is unlikely to be added in future versions.

Open Street Map reader extended example

See OSM Simple Example as a starting point. This example demonstrates how to configure the public transport aspects of the OSM intermodal parser with some more detail.

Logging is extensive for this reader. This is because based on warnings/info messages generated, the user is expected to adjust the settings to manually configure/override tagging errors and/or issues the automated conversion/salvaging procedures in the parser flagged. It is therefore recommended to first conduct a trial run with default settings and then gradually update the configuration based on the feedback by the reader.

OSM public transport focused example

final String inputFilePath = "<inputDirAndFile>";
final String outputDir = "<outputDir>";
final String countryName = "<countryName>";
      
/* reader */
OsmIntermodalReader osmReader = OsmIntermodalReaderFactory.create(inputFilePath, countryName);

/* Only parse a subset of the OSM file by setting a smaller bounding box (or polygon)*/
osmReader.getSettings().setBoundingBox(144.948083,144.975849,-37.823582, -37.808292);

/* for OSM ways that do not allow bus access absed on tagging, 
 * even thought they have bus stops: Overwrite the OSM way mode access */
osmReader.getSettings().getNetworkSettings().overwriteModeAccessByOsmWayId(193307914, OsmRoadModeTags.BUS);
osmReader.getSettings().getNetworkSettings.overwriteModeAccessByOsmWayId(296601918, OsmRoadModeTags.BUS, OsmRoadModeTags.FOOT);

/* Exclude some stop_positions that would otherwise be wrongfully matched due to unconventional tagging */
osmReader.getSettings().getPublicTransportSettings().excludeOsmNodesById(2266764332, 2751390421, 4059517380);
                              
/* Exclude under construction station to avoid warning */
osmReader.getSettings().getPublicTransportSettings().excludeOsmWaysById(485842787l);
osmReader.getSettings().getPublicTransportSettings().excludeOsmWaysById(715380193l);
        
/* Miniature railway platforms (polygon, so an OSM way entity), 
 * but we exclude miniature railways (by default) */
osmReader.getSettings().getPublicTransportSettings().excludeOsmWaysById(48992994);
osmReader.getSettings().getPublicTransportSettings()..excludeOsmWaysById(48992995);
     
/* for stop_location ids, explicitly set which platform/station/pole it should be mapped, no
 * questions asked
 * Signature: stop_position OSM node id, stop waiting area entity type, waiting area OSM id */
osmReader.getSettings().getPublicTransportSettings().overwriteStopLocationWaitingArea(6072041693, EntityType.Node, 571731242);
osmReader.getSettings().getPublicTransportSettings().overwriteStopLocationWaitingArea(6072041694, EntityType.Node, 571731670);
osmReader.getSettings().getPublicTransportSettings().overwriteStopLocationWaitingArea(6072041692, EntityType.Node, 571731240);
        
/* For waiting area (platform/pole/station) ids, explicitly set an osm way it should use for its 
 * stop_location, no questions asked:
 * Signature: Waiting area OSM id, waiting area entity type, OSM way id */
osmReader.getSettings().getPublicTransportSettings().overwriteWaitingAreaNominatedOsmWayForStopLocation(3184269080, EntityType.Node, 24039633);
osmReader.getSettings().getPublicTransportSettings().overwriteWaitingAreaNominatedOsmWayForStopLocation(480638176, EntityType.Node, 205146922);
osmReader.getSettings().getPublicTransportSettings().overwriteWaitingAreaNominatedOsmWayForStopLocation(480638175, EntityType.Node, 205146922);               

/* writer */
PlanitIntermodalWriter planitWriter = PlanitIntermodalWriterFactory.create(outputDir);

/* convert */
IntermodalConverterFactory.create(osmReader, planitWriter).convert();