TT:itinerary: Difference between revisions

From railML 3 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(formatting)
(Changed the example so that only the necessary complexity is shown here. the previous example contained some issues that were introduced by decoupling and made understanding of the example harder than necessary)
Line 14: Line 14:
==== Interpreting path ====
==== Interpreting path ====
This example is based on {{site|1=https://www.railml.org/en/example-data.html|2=the Advanced example infrastructure}}.
This example is based on {{site|1=https://www.railml.org/en/example-data.html|2=the Advanced example infrastructure}}.
This example will show how to combine base itineraries to form new itineraries.


Below {{TT:Tag|itinerary|ex=1|wiki=3}} "it-11" combines {{TT:Tag|baseItinerary|ex=1|wiki=3}}s "bi-1" and "bi-7". This allows to go from Arnau to Kudowa.
{{scrollbox|
<syntaxhighlight lang=xml>
<syntaxhighlight lang=xml>
       <itinerary id="it-11">
<infrastructure>
        <range baseItineraryRef="bi-1" start="bp-1" end="bp-2" offset="-PT5M"/>
...
        <range baseItineraryRef="bi-7" start="bp-22" end="bp-23"/>
<operationalPoints>
      </itinerary>
  <operationalPoint id="op-3">
    <name language="de" name="Cranz"/>
  </operationalPoint>
  <operationalPoint id="op-4">
    <name language="de" name="Dunja"/>
  </operationalPoint>
  <operationalPoint id="op-5">
    <name language="de" name="Eimber"/>
  </operationalPoint>
  <operationalPoint id="op-6">
    <name language="de" name="Funera"/>
  </operationalPoint>
  <operationalPoint id="op-7">
    <name language="de" name="Grestin"/>
  </operationalPoint>
  <operationalPoint id="op-9">
    <name language="de" name="Intersee"/>
  </operationalPoint>
  <operationalPoint id="op-11">
    <name language="de" name="Kudowa"/>
  </operationalPoint>
</operationalPoints>
...
</infrastructure>
...
<timetable>
...
<baseItineraries>
...
<baseItinerary id="bi-4">
  <baseItineraryPoint id="bp-8" locationRef="op-5">
    <times scope="operational">
      <departure time="11:44:30"/>
    </times>
    <stop>
       <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-9" locationRef="op-4">
    <times scope="operational">
      <arrival time="11:54:30"/>
      <departure time="11:55:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-10" locationRef="op-3">
    <times scope="operational">
      <arrival time="11:58:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary>
...   
<baseItinerary id="bi-5">
  <baseItineraryPoint id="bp-11" locationRef="op-3">
    <times scope="operational">
      <departure time="12:01:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-12" locationRef="op-6">
    <times scope="operational">
      <arrival time="12:03:30"/>
      <departure time="12:04:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-13" locationRef="op-7">
    <times scope="operational">
      <arrival time="12:09:30"/>
      <departure time="12:11:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-14" locationRef="op-9">
    <times scope="operational">
      <arrival time="12:12:30"/>
      <departure time="12:12:30"/>
    </times>
    <pass/>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-15" locationRef="op-11">
    <times scope="operational">
      <arrival time="12:15:30"/>
    </times>
    <trackRef ref="tk-11"/>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary>
...
</baseItineraries>
<itineraries>
...
<itinerary id="it-7">
  <range baseItineraryRef="bi-4" start="bp-8" end="bp-10" offset="-PT11M"/>
  <!-- shortened base itinerary -->
  <range baseItineraryRef="bi-5" start="bp-11" end="bp-13" offset="-PT11M"/>
</itinerary>
...
</itineraries>
</timetable>
</syntaxhighlight>
</syntaxhighlight>
|height=200px}}
The following conditions are true:
* <range> children of "it-11" so to say "intersect": both "bp-2" and "bp-22" refer with {{@|locationRef|TT:baseItineraryPoint}} to Cranz.
<range> children of "it-11" should be interpreted as follows: Train arrives at "bp-2" and departs from "bp-22". Arrival fact is indicated by attribute range/@end="bp-2". Departure fact is indicated by attribute range/@start="bp-22".
Definition of "bp-2" and "bp-22" differs on itself, thus microscopic description of a path should be interpreted as follows: Train arrives at "tk-5" and departs from "tk-6". From the definition of {{IS:Tag|track|ex=1|wiki=3}}s it can be seen that "tk-5" and "tk-6" are parts of "tk-4". This is indicated with {{@|belongsToParent|IS:track}} attribute.
More specific connections between parts of a track can be defined in the [[IS:topology]] part of the {{IS:Tag|infrastructure|ex=1|wiki=3}} subschema.
==== Interpreting times ====
As soon as "bi-1" has @offset="-PT5M" at "it-11", it means that arrival time="11:59:00" (e.g. for commercial trains) is moved 59 - 5 = 54 minutes i.e. new arrival time is "11:55:00". "bi-7" has no offset, therefore departure time is "11:59:00". Together this constitutes stop time of 5 minutes for "combined" {{TT:Tag|itinerary|ex=1|wiki=3}} "it-11".


==== Source code excerpts ====


{{IS:Tag|operationalPoint|ex=1|wiki=3}}s source code is below.
The above example of {{TT:Tag|itinerary|wiki=3}} "it-7" combines {{TT:Tag|baseItinerary|wiki=3}}s "bi-4" and a part of "bi-5". Together they describe the path from Eimber to Grestin.
Originally the {{TT:Tag|baseItinerary}} "bi-4" describes a path from Eimber via Dunja to Cranz, while {{TT:Tag|baseItinerary}} "bi-5" describes a path from Cranz to Kudowa, over the intermediate operating {{IS:Tag|operationalPoint}}s Funera, Grestin and Intersee. For {{TT:Tag|itinerary}} "it-7" only the first 3 {{TT:Tag|baseItineraryPoint}}s of {{TT:Tag|baseItinerary}} "bi-5" are used. This is indicated by the {{@|end}} attribute of the {{TT:Tag|itinerary:range}}.  


{{scrollbox|
In order to combine 2 {{TT:Tag|baseItinerary}}s the intersecting {{TT:Tag|baseItineraryPoint}}s are expected to reference the same {{IS:Tag|operationalPoint}} in this case Cranz. The resulting itinerary combines the information of the intersecting {{TT:Tag|baseItineraryPoint}}s. Information regarding the arrival is taken from the last {{TT:Tag|baseItineraryPoint}} of the ending {{TT:Tag|baseItinerary}} (segment), while information regarding the departure is taken from the first {{TT:Tag|baseItineraryPoint}} of the starting {{TT:Tag|baseItinerary}} (segment).
<syntaxhighlight lang=xml>
        <operationalPoint id="op-1">
          <name language="de" name="Arnau"/>
          <designator entry="OAR" register="_RML"/>
          <opEquipment>
            <ownsInfrastructureElement ref="pf-1"/>
            <ownsInfrastructureElement ref="sp-1"/>
            <ownsInfrastructureElement ref="sp-2"/>
            <ownsInfrastructureElement ref="sp-3"/>
            <ownsInfrastructureElement ref="sp-4"/>
            <ownsInfrastructureElement ref="tk-1"/>
            <ownsInfrastructureElement ref="tk-2"/>
          </opEquipment>
        </operationalPoint>
        <operationalPoint id="op-3">
          <name language="de" name="Cranz"/>
          <designator entry="OC" register="_RML"/>
          <opEquipment>
            <ownsInfrastructureElement ref="pf-2"/>
            <ownsInfrastructureElement ref="pf-3"/>
            <ownsInfrastructureElement ref="pf-4"/>
            <ownsInfrastructureElement ref="sp-5"/>
            <ownsInfrastructureElement ref="sp-6"/>
            <ownsInfrastructureElement ref="sp-7"/>
            <ownsInfrastructureElement ref="sp-8"/>
            <ownsInfrastructureElement ref="sp-9"/>
            <ownsInfrastructureElement ref="sp-10"/>
            <ownsInfrastructureElement ref="sp-11"/>
            <ownsInfrastructureElement ref="sp-12"/>
            <ownsInfrastructureElement ref="tk-3"/>
            <ownsInfrastructureElement ref="tk-4"/>
            <ownsInfrastructureElement ref="tk-5"/>
            <ownsInfrastructureElement ref="tk-6"/>
            <ownsInfrastructureElement ref="tk-7"/>
          </opEquipment>
        </operationalPoint>
        <operationalPoint id="op-5">
          <name language="de" name="Eimber"/>
          <designator entry="OEI" register="_RML"/>
        </operationalPoint>
        <operationalPoint id="op-6">
          <name language="de" name="Funera"/>
          <designator entry="OFN" register="_RML"/>
          <opEquipment>
            <ownsInfrastructureElement ref="pf-7"/>
            <ownsInfrastructureElement ref="sp-15"/>
            <ownsInfrastructureElement ref="sp-16"/>
          </opEquipment>
        </operationalPoint>
        <operationalPoint id="op-11">
          <name language="de" name="Kudowa"/>
          <designator entry="OXK" register="_RML"/>
          <opEquipment>
            <ownsInfrastructureElement ref="pf-10"/>
            <ownsInfrastructureElement ref="sp-19"/>
            <ownsInfrastructureElement ref="sp-20"/>
            <ownsInfrastructureElement ref="sp-21"/>
            <ownsInfrastructureElement ref="sp-22"/>
            <ownsInfrastructureElement ref="tk-10"/>
            <ownsInfrastructureElement ref="tk-11"/>
          </opEquipment>
        </operationalPoint>
</syntaxhighlight>
|height=200px}}


{{IS:Tag|track|ex=1|wiki=3}}s source code  is below.
The resulting {{TT:Tag|itinerary}} schedule looks like this:


{{scrollbox|
{| class="wikitable
<syntaxhighlight lang=xml>
!{{IS:Tag|operationalPoint}}
        <track type="sidingTrack" id="tk-4">
!Arrival time
          <name language="de" name="1"/>
!Departure time
          <designator entry="OC1" register="_RML"/>
|-
        </track>
|Eimber
        <track type="sidingTrack" id="tk-5">
| -
          <name language="de" name="1a"/>
|11:33:30
          <designator entry="OC1A" register="_RML"/>
|-
          <belongsToParent ref="tk-4"/>
|Dunja
        </track>
|11:43:30
        <track type="sidingTrack" id="tk-6">
|11:44:30
          <name language="de" name="1b"/>
|-
          <designator entry="OC1B" register="_RML"/>
|Cranz
          <belongsToParent ref="tk-4"/>
|11:47:30
        </track>
|11:50:30
</syntaxhighlight>
|-
|height=200px}}
|Funera
|11:52:30
|11:53:30
|-
|Grestin
|11:58:30
| -
|}


{{TT:Tag|baseItinerary|ex=1|wiki=3}}s source code  is below.
Please note that the last station is not listed with a departure time although the matching {{TT:Tag|baseItineraryPoint}} does specify a departure time. The reason for this is that the range of "bi-5" which is imported into the {{TT:Tag|itinerary}} "it-7" ends in Grestin. This means that any further information included in the {{TT:Tag|baseItinerary}} is not considered in the resulting itinerary.


{{scrollbox|
Please also note that the listed times above are shifted by -11 min. This is a result of the offset specified at the range importing the two {{TT:Tag|baseItinerary}}s into the "it-7".
<syntaxhighlight lang=xml>
      <!-- From Arnau to Cranz -->
      <baseItinerary id="bi-1">
        <baseItineraryPoint id="bp-1" locationRef="op-1">
          <times scope="commercial">
            <departure time="11:52:00"/>
          </times>
          <times scope="operational">
            <departure time="11:52:30"/>
          </times>
          <followupSections>
            <followupSection>
              <minimalTime runTime="PT4M"/>
              <reserves>
                <reserve reserve="PT1M" type="qualityByRailwayUndertaking">
                  <rule>
                    <timeBasedRule supplementInPercent="25"/>
                  </rule>
                </reserve>
                <reserve reserve="PT1M" type="trackworkByInfrastructureManager"/>
              </reserves>
            </followupSection>
          </followupSections>
          <trackRef ref="tk-2"/>
          <stop>
            <platformEdgeRefs>
              <platformEdgeRef ref="pe-3"/>
            </platformEdgeRefs>
            <stoppingPlaceRef ref="sp-3"/>
            <isCommercial/>
          </stop>
        </baseItineraryPoint>
        <baseItineraryPoint id="bp-2" locationRef="op-3">
          <times scope="commercial">
            <arrival time="11:59:00"/>
          </times>
          <times scope="operational">
            <arrival time="11:58:30"/>
          </times>
          <trackRef ref="tk-5"/>
          <stop>
            <platformEdgeRefs>
              <platformEdgeRef ref="pe-15"/>
            </platformEdgeRefs>
            <stoppingPlaceRef ref="sp-7"/>
            <isCommercial/>
          </stop>
        </baseItineraryPoint>
      </baseItinerary>
      <!-- From Eimber to Kudowa (Express) -->
      <baseItinerary id="bi-7">
        <baseItineraryPoint id="bp-21" locationRef="op-5">
          <times scope="commercial">
            <departure time="11:48:00"/>
          </times>
          <times scope="operational">
            <departure time="11:48:30"/>
          </times>
          <followupSections>
            <followupSection>
              <minimalTime runTime="PT7M30S"/>
              <reserves>
                <reserve reserve="PT2M30S" type="qualityByRailwayUndertaking">
                  <rule>
                    <timeBasedRule supplementInPercent="25"/>
                  </rule>
                </reserve>
              </reserves>
            </followupSection>
          </followupSections>
          <stop>
            <passengerTextInfos>
              <passengerTextInfoRef ref="pt-01"/>
            </passengerTextInfos>
            <announcements>
              <announcementRef ref="an-01"/>
            </announcements>
            <isCommercial/>
          </stop>
        </baseItineraryPoint>
        <baseItineraryPoint id="bp-22" locationRef="op-3">
          <times scope="commercial">
            <arrival time="11:59:00"/>
            <departure time="12:01:00"/>
          </times>
          <times scope="operational">
            <arrival time="11:58:30"/>
            <departure time="12:01:30"/>
          </times>
          <trackRef ref="tk-6"/>
          <stop>
            <activities>
              <activityLoad id="al01" minDuration="PT2M"/>
            </activities>
            <platformEdgeRefs>
              <platformEdgeRef ref="pe-16"/>
            </platformEdgeRefs>
            <stoppingPlaceRef ref="sp-10"/>
            <isCommercial/>
          </stop>
        </baseItineraryPoint>
        <baseItineraryPoint id="bp-23" locationRef="op-11">
          <times scope="commercial">
            <arrival time="12:10:00"/>
          </times>
          <times scope="operational">
            <arrival time="12:09:30"/>
          </times>
          <followupSections>
            <followupSection>
              <minimalTime runTime="PT6M"/>
              <reserves>
                <reserve reserve="PT2M" type="qualityByRailwayUndertaking">
                  <rule>
                    <timeBasedRule supplementInPercent="25"/>
                  </rule>
                </reserve>
              </reserves>
            </followupSection>
          </followupSections>
          <trackRef ref="tk-10"/>
          <stop>
            <platformEdgeRefs>
              <platformEdgeRef ref="pe-14"/>
            </platformEdgeRefs>
            <stoppingPlaceRef ref="sp-22"/>
            <isCommercial/>
          </stop>
        </baseItineraryPoint>
      </baseItinerary>
</syntaxhighlight>
|height=200px}}


==== Visualization ====
==== Visualization ====


[[File:2024-07-29_railML_itineary.png|1500px]]
[[File:2024-07-29_railML_itineary.png|1500px]]
The blue arrow represents {{TT:Tag|baseItinerary}} "bi-4", while the green arrows represent {{TT:Tag|baseItinerary}} "bi-5". The darker green arrow represents the part of "bi-5" that is imported into {{TT:Tag|itinerary}} "it-7", while the lighter green arrow represents the part that is not imported.


{{importComment}}
{{importComment}}

Revision as of 17:08, 30 July 2024

Introduction

Documentation

Syntax

Autoexport from the XML-Schema for element TT:itinerary of railML® version 3.2
Documentation An Itinerary is created based upon one or several base itineraries. The base itineraries can be cut into parts and recombined for that. Additionally they can be transposed in time.
Subschema timetable
Parents* itineraries
Children range (1..*)
Attributes:
  • id: unique identifier (obligatory; xs:string; patterns: (urn:uuid:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}}); compare: Dev:Identities
*Notice:
Elements may have different parent elements. As a consequence they may be used in different contexts.
Please, consider this as well as a user of this wiki as when developing this documentation further.
Aspects that are only relevant with respect to one of several parents should be explained exclusively in the documentation of the respective parent element.

 

This element does not appear in railML® 3.1 within the TT subschema. It is available only in railML® 3.2. Do not hesitate to contact railML.org for further questions.


Changes 3.1→3.2

Introduced with version 3.2.

Semantics

Best Practice / Examples

Combining base itineraries

Interpreting path

This example is based on the Advanced example infrastructure (link to the railML® website). This example will show how to combine base itineraries to form new itineraries. 

<infrastructure>
...
<operationalPoints>
  <operationalPoint id="op-3">
    <name language="de" name="Cranz"/>
  </operationalPoint>
  <operationalPoint id="op-4">
    <name language="de" name="Dunja"/>
  </operationalPoint>
  <operationalPoint id="op-5">
    <name language="de" name="Eimber"/>
  </operationalPoint>
  <operationalPoint id="op-6">
    <name language="de" name="Funera"/>
  </operationalPoint>
  <operationalPoint id="op-7">
    <name language="de" name="Grestin"/>
  </operationalPoint>
  <operationalPoint id="op-9">
    <name language="de" name="Intersee"/>
  </operationalPoint>
  <operationalPoint id="op-11">
    <name language="de" name="Kudowa"/>
  </operationalPoint>
</operationalPoints>
...
</infrastructure>
...
<timetable>
...
<baseItineraries>
...
<baseItinerary id="bi-4">
  <baseItineraryPoint id="bp-8" locationRef="op-5">
    <times scope="operational">
      <departure time="11:44:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-9" locationRef="op-4">
    <times scope="operational">
      <arrival time="11:54:30"/>
      <departure time="11:55:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-10" locationRef="op-3">
    <times scope="operational">
      <arrival time="11:58:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary> 
...     
<baseItinerary id="bi-5">
  <baseItineraryPoint id="bp-11" locationRef="op-3">
    <times scope="operational">
      <departure time="12:01:30"/>
    </times>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-12" locationRef="op-6">
    <times scope="operational">
      <arrival time="12:03:30"/>
      <departure time="12:04:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-13" locationRef="op-7">
    <times scope="operational">
      <arrival time="12:09:30"/>
      <departure time="12:11:30"/>
    </times>
    <stop>
      <isCommercial onRequest="true"/>
    </stop>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-14" locationRef="op-9">
    <times scope="operational">
      <arrival time="12:12:30"/>
      <departure time="12:12:30"/>
    </times>
    <pass/>
  </baseItineraryPoint>
  <baseItineraryPoint id="bp-15" locationRef="op-11">
    <times scope="operational">
      <arrival time="12:15:30"/>
    </times>
    <trackRef ref="tk-11"/>
    <stop>
      <isCommercial/>
    </stop>
  </baseItineraryPoint>
</baseItinerary>
...
</baseItineraries>
<itineraries>
...
<itinerary id="it-7">
  <range baseItineraryRef="bi-4" start="bp-8" end="bp-10" offset="-PT11M"/>
  <!-- shortened base itinerary -->
  <range baseItineraryRef="bi-5" start="bp-11" end="bp-13" offset="-PT11M"/>
</itinerary>
...
</itineraries>
</timetable>


The above example of <itinerary> "it-7" combines <baseItinerary>s "bi-4" and a part of "bi-5". Together they describe the path from Eimber to Grestin. Originally the <baseItinerary> "bi-4" describes a path from Eimber via Dunja to Cranz, while <baseItinerary> "bi-5" describes a path from Cranz to Kudowa, over the intermediate operating <operationalPoint>s Funera, Grestin and Intersee. For <itinerary> "it-7" only the first 3 <baseItineraryPoint>s of <baseItinerary> "bi-5" are used. This is indicated by the @end attribute of the <itinerary:range>.

In order to combine 2 <baseItinerary>s the intersecting <baseItineraryPoint>s are expected to reference the same <operationalPoint> in this case Cranz. The resulting itinerary combines the information of the intersecting <baseItineraryPoint>s. Information regarding the arrival is taken from the last <baseItineraryPoint> of the ending <baseItinerary> (segment), while information regarding the departure is taken from the first <baseItineraryPoint> of the starting <baseItinerary> (segment).

The resulting <itinerary> schedule looks like this:

<operationalPoint> Arrival time Departure time
Eimber - 11:33:30
Dunja 11:43:30 11:44:30
Cranz 11:47:30 11:50:30
Funera 11:52:30 11:53:30
Grestin 11:58:30 -

Please note that the last station is not listed with a departure time although the matching <baseItineraryPoint> does specify a departure time. The reason for this is that the range of "bi-5" which is imported into the <itinerary> "it-7" ends in Grestin. This means that any further information included in the <baseItinerary> is not considered in the resulting itinerary.

Please also note that the listed times above are shifted by -11 min. This is a result of the offset specified at the range importing the two <baseItinerary>s into the "it-7".

Visualization

2024-07-29 railML itineary.png

The blue arrow represents <baseItinerary> "bi-4", while the green arrows represent <baseItinerary> "bi-5". The darker green arrow represents the part of "bi-5" that is imported into <itinerary> "it-7", while the lighter green arrow represents the part that is not imported.


Additional Information

Notes

Open Issues

Retrieved from "https://wiki3.railml.org/index.php?title=TT:itinerary&oldid=9634"