Zoning Structure Input Data format (XML)

In this section of the manual we discuss the Zoning structure’s XML input format used by PLANit.

• If you are only interested to see an example file, jump to the Expanded Example.
• XML Schema of macroscopic zoning https://planitmanual.github.io/version//xsd/macroscopiczoninginput.xsd
• XML Schema of intermodal extension https://planitmanual.github.io/version//xsd/macroscopicintermodalinput.xsd

We distinguish between two types of zones in PLANit:

• Origin-Destination zones
• Transfer zones

Origin-Destination Zones are the geographical areas for which we construct travel demand which are loaded onto the network, typically via a single point known as centroids. Centroids are connected to the physical road network via connectoids, i.e., the nodes in the physical network that are marked as eligible ingress/egress points.

Transfer zones on the other hand allow for intermodal trips, where one can transfer between different modes at a transfer zone, or alternatively, access the same mode but transfer to a different routed service (e.g., from one bus line to another). A transfer zone, like a regular zone has a centroid and one or more connectoids. Access to the transfer zone via its connectoids can be restricted to particular modes (for each connectoid), where a connectoid can represent for example the location where a public transport vehicle stops, or an entrance to a train station for pedestrians.

The zoning structure in this input file describes the zones, centroids, and connectoids for a PLANit project.

<macroscopiczoning>

The zoning structure can be described in a stand alone XML file - only providing the zoning structure - or it can be provided as part of a PLANit XML file describing all input components. Either way, all the zoning structure specific information is enclosed within the XML root element <macroscopiczoning>. When part of a larger (single) PLANit input file, the structure should resemble something like the following:

<PLANit	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:gml="http://www.opengis.net/gml" xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/macroscopicinput.xsd">											
	...
	<macroscopiczoning>
		...
	</macroscopiczoning>
	...
</PLANit>

Whereas if, it is a stand-alone file, it should look something like

<macroscopiczoning
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml" xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/macroscopiczoninginput.xsd">
...	
</macroscopiczoning>

This root element contains the (OD) zones and optionally an intermodal extension element that accounts for the transfer zones and related content:

In the remainder of this page, we discuss each of the eligible XML elements in order of expected appearance, its attributes and sub-elements or simple elements (elements without sub-elements). At the bottom of the page an expanded example is provided highlighting all the available options explicitly.

Lastly, we provide the default values for (optional) element(s). These defaults are only relevant when you do not explicitly configure the related elements explicitly in the XML input file. Only then, PLANit will revert to these defaults.

Zoning defaults

No defaults are used in the context of zoning (yet).

XML Elements

This section discusses the XML elements under the <macroscopiczoning> root element in expected order of appearance.

<zones>

Zones is the container element for all available zones. It can have its own spatial reference system, independent of the network if one wishes. However, in most cases you would leave out this attribute to adopts the SRS of the network instead (default behaviour).

This element has the following sub-elements:

<> <zone>

A zone is a single geographic area that is usually constructed because it is deemed to represent a desirable level of travel demand homogeneity. Alternatively, it can be based on historic, political, or other criteria based, boundaries. It is expected to be contiguous with respect to other zones, should not overlap, and should not be bordering on only a single other zone (donut approach).

A zone element may specify an explicit centroid (location) from which travel can commence/cease. If a centroid is not defined a default centroid (without location) is created. The physical road network is accessible via eligible nodes, termed connectoids. Each zone must have a unique (XML) identifier that is made available via an attribute.

This element has the following simple-elements:

This element has the following sub-elements:

In its simplest form the <gml:Polygon> element only defines the exterior via the use of <gml:exterior> and <gml:LinearRing>. the latter has a <gml:coordinates> element prescribing the list of coordinates that represent the ring. For a detailed description of the gml:Polygon, please consult the latest official GML documentation

In PLANit, we do not allow separate SRS definitions per <gml:Polygon>, even though the specification of GML allows this. Therefore, make sure you do not define the srsName= attribute on any <gml:Point> embedded in PLANit XML files.

<!--  example of a GML polygon -->
<gml:Polygon>
	<gml:exterior>
		<gml:LinearRing>
			<gml:coordinates decimal="." cs="," ts="">119.593002319336,-31.6695003509522 119.595306396484,
			31.6650276184082 119.600944519043,-31.6658897399902 119.603385925293,-31.669527053833 
			119.60050201416,-31.6739158630371 119.595664978027,-31.6728610992432 119.593002319336, 
			31.6695003509522
			</gml:coordinates>
		</gml:LinearRing>
	</gml:exterior>
</gml:Polygon>

<><> <centroid>

Point of ingress/egress for all travel demand in the zone. A centroid has an optional geographic location. This location is used to determine the length of the virtual link connecting the centroid to each of its connectoids. When absent, either the connectoids specify a fixed length, or the default length is applied.

Each centroid has a unique (XML) id that is provided as an attribute.

This element has the following simple-elements:

This element has the following sub-elements:

In its simplest form the <gml:Point> element has a single sub-element <gml:pos> containing two doubles separated by a space, see example below. For a detailed description of the gml:point element, please consult the latest official GML documentation

In PLANit, we do not allow separate SRS definitions per <gml:Point>, even though the specification of GML allows this. Therefore, make sure you do not define the srsName= attribute on any <gml:Point> embedded in PLANit XML files.

<!--  example of a centroid with basic gml:point and gml:pos location information -->
<centroid id="1">
	<name>Sydney CBD</name>
	<gml:Point>
		<gml:pos>150.512796 -34.900145</gml:pos>
	</gml:Point>														
</centroid>

<><> <connectoids>

Connectoids define how zones and physical network entities interact. A connectoid for an OD zone must refer to a node present in the physical network. By referencing them here, these nodes are marked as eligible points of entry/exit for travel demand from its parent zone (via its centroid). This element is the container element for such connectoid elements.

This element has the following sub-elements:

<><><> <connectoid>

A (OD) connectoid must refer to a node present in the physical network. This node is marked as an eligible point of entry/exit for travel demand from its parent zone (via the centroid).

The cost associated with the travel for each zone/connectoid combination is based on the VirtualCost configuration in the assignment. It can for example require a length for this connection to determine its cost, e.g., travel time. This length is determined via:

• The connectoid’s length element value (if set),
• otherwise, as-the-crow-flies distance between the centroid’s and node’s geographic locations is used (if available),
• otherwise, the default length is used

Each connectoid must have a unique (XML) identifier that is made available via an attribute.

The modes attribute can look like the following: modes="car","bus" allowing only car and bus modes access. When the modes attribute is not defined it is assumed all modes are allowed access.

This element has the following simple-elements:

<intermodal>

A network with one or more layers and multiple modes can choose to support intermodal travel. Public transport trips are an example of intermodal travel, where one can for example:

• Have a trip using two different bus routes, transferring somewhere half-way at a stop (transfer zone)
• Model train/bus/walk trips, transferring at various points, possibly walking between different stops

We choose not to tailor the format towards public transport because our structure can also be used to model for example:

• goods transport, where goods travel from warehouse to warehouse to customers
• bike-share, ride-share services
• etc…

As a result we have a generic intermodal format where transfers occur at transfer zones that have connectoids allowing access to the transfer zone for one or more modes. modes can enter via one mode and the underlying model can transfer them to another mode, these transfers are only possible at transfer zones, allowing us to model, aggregate, manage different infrastructure layers differently depending on what suits the supported modes best.

This element has the following sub-elements:

<> <transferzones>

Container for all transfer zones defined in the network.

This element has the following sub-elements:

<><> <zone>

A transfer zone is a single geographic area (or point location) that represents an opportunity for modes to transfer between routed services of the same mode (bus line to bus line, train to train, truck to truck, etc.) or alternatively a transfer from one mode to another (bus to train, walk to tram, good to ship, etc.). The intermodal aspect is convered by a transfer zones connectoids where each connectoid-zone combination can have allowable modes and one might enter via one mode (from one network layer) and exits via another mode (from another network layer). The actual transfer itself is part of the underlying model and is not of concern to the transfer zone separating the model from the network/zoning specification.

A transfer zone element may specify an explicit centroid (location). If a centroid is not defined a default centroid (without location) is created. The connections to the network are dealt with via the transferzoneaccess element as each connectoid can provide access to multiple transferzones (and can therefore not be uniquely identified from within a transfer zone).

the type of the transfer zone can be used to make it clear what the purpose of the transfer zone is. Currently the following options are supported:

• "platform"
• "stop_pole"
• "unknown" (default if not specified)

The (transfer) zone element has the following simple-elements as children:

as well as the following sub-elements:

The polygon element is defined the same way as for a regular (OD) zone element

The centroid element is defined the same way as for a regular (OD) centroid element

<> <transferzoneaccess>

Container for access locations (conectoids) for the transfer zones.

This element has the following sub-elements:

<><><> <connectoid>

A (transfer zone) connectoid, unlike an OD connectoid, refers to a link segment present in the physical network to create a point of interaction between its access zone and physical network (layer). This means that a transfer zone connectoid provides directed access. This allows us to explicitly (dis)allow access for directions along a link, e.g., public transport stops on one side of the road.

Apart from this distinction a transfer connectoid largely follows the convention of a regular OD connectoid, only for transfer connectoids, it is more common to explicitly defined mode access and possible access to multiple transfer zones (platforms).

Since a transfer connectoid can potentially connect to multiple transfer zones, setting the length property causes the length to be applied to each transfer zone accessible by this connectoid.

The cost associated with the travel for each zone/connectoid combination is the same as for OD connectoids.

Each connectoid must have a unique (XML) identifier that is made available via an attribute.

The modes attribute works the same as for the OD connectoid

The link segment reference lsref by default will utilise the combination (link segment,downstream node). However, in some special cases this specification is too limited (for example beginning of a public transport line at a node with no incoming links). Therefore one can utilise the location (loc) attribute to indicate the upstream node should be used (link segment, upstream node).

The location loc attribute would normally be left out as its default is set to downstream, it can be explicitly overwritten to upstream. It supports the following two values only:

• upstream use the upstream node as the access point i.c.w. the link segment as restriction
• downstream use the downstream node as the access point i.c.w. the link segment as restriction (default)

The tzrefs should refer to the accessible transfer zones, e.g. tzrefs="1" or in case of multiple tzrefs="1,4,8,2"

Lastly, one can provide additional information on what type of connectoid this is, for example to indicate that it represents a location where vehicles stop, or a location where people enter a waiting area to (dis)embark vehicles. currently, the following types are supported:

• pt_veh_stop indicating a location where public transport vehicles stop
• traveller_access referring to access/egress points for active modes looking to for exmaple (dis)embark a vehicular mode
• unknown when unspecified (default)

This element has the following simple-elements:

<> <transferzonegroups>

Container for groupings of transferzones. While the schema has been defined, currently the parser does not yet support this feature

TO BE IMPLEMENTED

Expanded Example

Below you will find an expanded example where all elements and attributes are explicitly set, to give you an idea of the overall structure of the macroscopic zoning XML. This example does not make sense as an actual input file, it is purely meant to show off all aspects of the file, rather than be used as a practically feasible input file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<macroscopiczoning
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml"											
	 xsi:noNamespaceSchemaLocation="<path_to_Schema>/macroscopiczoninginput.xsd">
	<zones>								
		<zone id="1">										
			<name>Glebe</name>								
			<centroid>										
				<name>Postal office reference point</name>
				<gml:Point>									
					<gml:pos>45.256 -110.45</gml:pos>
				</gml:Point>
			</centroid>
			<connectoids>
				<connectoid noderef="1">
					<name>Broadway parking garage</name>
					<length>0.2</length>
				</connectoid>
				<connectoid noderef="11"/>
			</connectoids>									
			<gml:Polygon>									
				<gml:exterior>
					<gml:LinearRing>
						<gml:coordinates decimal="." cs="," ts="">119.593002319336,-31.6695003509522 119.595306396484,
		         			31.6650276184082 119.600944519043,-31.6658897399902 119.603385925293,-31.669527053833 
		         			119.60050201416,-31.6739158630371 119.595664978027,-31.6728610992432 119.593002319336,
		         			31.6695003509522
		         			</gml:coordinates>
	         			</gml:LinearRing>
				</gml:exterior>
			</gml:Polygon>
		</zone>
		<zone id="2">
			<name>CBD</name>
			<connectoids>
				<connectoid noderef="2" />
			</connectoids>				
		</zone>
	</zones>
	<!-- optional extension for intermal networks -->
	<intermodal>
		<transferzones>
			<zone id="3" type="platform" >
				<name>platform 1</name>						    	
			</zone>
			<zone id="4" type="stop_pole" />
			<zone id="5" type="stop_pole" />						    		
		</transferzones>
		<transferzoneaccess>
			<!-- access to road network for transfer zone 3 -->
			<connectoid tzrefs="3" lsref="4" modes="bus" type="pt_veh_stop"/>
			<!-- access to active network for transfer zone 3 -->
			<connectoid tzrefs="3" lsref="8" modes="bicycle, walk" type="traveller_access"/>
			<!-- example of transfer between different bus routes using two different poles, but same
			stop location for buses -->
			<connectoid tzrefs="4,5" lsref="9" modes="bus" type="pt_veh_stop"/>		
		</transferzoneaccess>
	</intermodal>
</macroscopiczoning>