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.

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.

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="../schema/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="../schema/macroscopiczoninginput.xsd">
...	
</macroscopiczoning>

This root element can contain only a single sub-elements:

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).

Each zone has exactly one centroid from which travel can commence/cease. The physical road network is accessible via eligible nodes, termed connectoids. Each zone must have a unique (external) 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 (external) 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 must refer to nodes 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). As a result, PLANit will create a virtual connectoid between centroid and connectoid to allow the travel demand to enter/exit. This element is the container element for such connectoid elements.

This element has the following sub-elements:

<><><> <connectoid>

A 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). PLANit will create a virtual connection between centroid and connectoid to allow the travel demand to enter/exit.

The cost associated with the travel for each centroid-connectoid combination is based on the VirtualCost configuration in the assignment. Typically, it will require a length for this connection to determine its cost, e.g., travel time. This length is computed via:

• The connectoid’s length element value,
• If no length is provided, as-the-crow-flies distance between the centroid’s and node’s geographic locations is used,
• if geo-spatial information is absent and no length is specified, the default length is used

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

This element has the following simple-elements:

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 srsname="EPSG:4326">								
		<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>
	</zones>
</macroscopiczoning>