Ergänzungen zu den XML-Dateiformaten: Unterschied zwischen den Versionen

Aktuelle Version vom 6. Juni 2024, 08:21 Uhr

Hier werden Hinweise zu Stellen in den XML-Dateiformaten gesammelt, die nicht selbsterklärend sind.

Allgemeines

Bei Attributen existiert für jeden Typ ein Standardwert, der verwendet wird, wenn das Attribut nicht vorhanden oder leer (Attribut="") ist. Es folgt daraus, dass das Attribut auch beim Schreiben weggelassen werden kann, wenn sein Wert dem Standardwert entspricht. Zusi macht das konsequent so. Quelle. Der Standardwert ist
- bei Ganzzahlen (integer, integer 64 bit, integer enum, bool) der Wert 0.
- bei Gleitkommazahlen (single) der Wert 0.0.
- bei Zeichenketten (string) die leere Zeichenkette.
- bei Farben (D3DColor) die Farbe R=G=B=A=0.
- bei Datums-/Zeitangaben (date,time) der 30. Dezember 1899, 00:00:00.
Dateipfade (<Datei Dateiname="..."> sind entweder
- Pfade relativ zum Zusi-Datenverzeichnis (RollingStock\Deutschland\Lok.ls3), wobei ein führender Backslash erlaubt ist und ignoriert wird, oder
- wenn sie keinen Backslash enthalten, Dateien im selben Verzeichnis wie die Datei, in der der Pfad steht.

Insbesondere können Dateien, die auf einem anderen Laufwerk als das Zusi-Datenverzeichnis liegen, nicht referenziert werden.

Programmseitig generierte XML-Dateien, die UTF-8-kodiert sind, sollten eine Byte Order Mark (0xEF,0xBB,0xBF) am Anfang enthalten, damit Texteditoren sie zuverlässig als UTF-8 erkennen, siehe UTF-8 Byte Order Mark setzen.
Bei Gleitkommazahlen werden sowohl Punkt als auch Komma als Dezimaltrenner betrachtet. In alten Dateien findet sich im Knoten Info das Attribut DecSep, das aber anscheinend ignoriert wird.

Einheiten

Einige Werte werden in der XML-Datei anders gespeichert, als sie in der Benutzeroberfläche von Zusi angezeigt werden.

Geschwindigkeiten: in der XML-Datei in m/s gespeichert, in der Programmoberfläche (derzeit) in km/h angezeigt. Ausnahme sind die Wert-Attribute in Ereignis-Knoten der Ereignisse "Indusi 1000 Hz" und "Indusi 2000 Hz". Diese werden in der XML-Datei in km/h gespeichert.
Winkel: in der XML-Datei im Bogenmaß gespeichert, in der Programmoberfläche in Grad angezeigt.
Krümmung von Streckenelementen: in der XML-Datei in 1/m gespeichert, im 3D-Editor in 1/km angezeigt.
Überhöhung von Streckenelementen: in der XML-Datei als Winkel im Bogenmaß gespeichert, im Gleisplaneditor und 3D-Editor in Grad und in mm (gemäß eingestelltem Oberbau) angezeigt.

Gleisplan (.st2)

Das Format ist sehr redundant, daher braucht man einige Werte nicht eintragen; sie werden vom Gleisplaneditor ignoriert und selbst berechnet:

<Gerade>: Attribut W beider <PunktWinkel>-Elemente
<Kreisbogen>: Die beiden <PunktWinkel>-Elemente können leer bleiben (aber nicht weggelassen werden). Nur das dritte Element (<Punkt>, der Kreismittelpunkt) ist relevant.
<Klothoide>: Das zweite <PunktWinkel>-Element kann leer bleiben (aber nicht weggelassen werden). Nur das erste Element ist relevant. Es gibt immer den Anfangspunkt der gesamten Klothoide, also den Punkt mit Krümmung 0, an. Bei Klothoidensektoren (KrAnf != 0) entspricht das einem fiktiven Anfangspunkt, der außerhalb des Klothoidensektors liegt.
<Weiche>: Attribut BiegeWinkel der <Biegung>-Elemente

Strecke (.st3)

Zuordnung Norm/Gegen ↔ blau/grün

In der Programmoberfläche werden ausschließlich die Bezeichnungen "blaue und grüne Richtung" verwendet. Diese entsprechen Norm- bzw. Gegenrichtung im Dateiformat. Merkhilfe: grün = Gegenrichtung.

`Nr`-Attribut `NachNorm[Modul]` und `NachGegen[Modul]`-Knoten im `StrElement`-Knoten

Bei NachNorm und NachGegen handelt es sich um die Nummer eines Streckenelements im selben Modul.

Bei NachNormModul und NachGegenModul handelt es sich um die Nummer eines Referenzpunkts im durch den Datei-Kindknoten angegebenen Modul. Der Referenzpunkt ist vom Typ "Modulgrenze" und zeigt in Richtung der Modulgrenze. Existiert so ein Referenzpunkt nicht, erscheint beim Verknüpfen des Streckennetzes die Fehlermeldung Auf Element-Nr. %d folgt Nr. %d in Modul "%s", ist dort aber nicht als Schnittstelle definiert (Verknüpfung nicht hergestellt)

Reihenfolge `NachNorm` und `NachNormModul` bzw. `NachGegen` und `NachGegenModul`

Der 3D-Editor schreibt die Knoten immer in der festen Reihenfolge:

alle NachNorm-Knoten
alle NachGegen-Knoten
alle NachNormModul-Knoten
alle NachGegenModul-Knoten

Ein Mischen von NachXXX und NachXXXModul im selben Streckenelement ist also nicht möglich. Dass in derselben Richtung sowohl Nachfolger im selben als auch in anderen Modulen vorhanden sind, ist ohnehin ein theoretischer Fall, der keine sinnvolle Anwendung hat. Hat ein Element in einer Richtung Nachfolger im selben Modul, so ignoriert die Fahrstraßenerzeugung des 3D-Editors Nachfolger in anderen Modulen bei der Fahrstraßenerzeugung.

`Anschluss`-Attribut des `StrElement`-Knotens

Dieses Attribut kodiert auf effiziente Weise die Richtung der Nachfolgerelemente des eigenen Moduls. (Nachfolgerelemente in einem anderen Modul sind über einen Referenzpunkt angegeben (s.o.), der auch eine Richtungsangabe enthält -- zu beachten ist, dass diese in Richtung der Modulschnittstelle zeigt).

Es handelt sich um eine 16-Bit-Zahl. In den unteren 8 Bits ist die Richtung der (maximal 8) Nachfolgerelemente in Normrichtung (blau) gespeichert, beginnend mit dem niedrigsten Bit für den ersten Nachfolger. In den oberen 8 Bits ist die Richtung der (maximal 8) Nachfolgerelemente in Gegenrichtung (grün) gespeichert. Ein Bit 1 an der entsprechenden Stelle bedeutet, dass der Nachfolger in Gegenrichtung liegt.

Beispiel

Situation (`grünes Ende ==Nr==> blaues Ende`)	Nachfolger von `(2, NORM)`	Nachfolger von `(2, GEGEN)`	Anschluss-Wert von Element Nr. 2
`==1==> ==2==> ==3==>`	`(3, NORM)`	`(1, GEGEN)`	256 = 2⁸
`==1==> ==2==> <==3==`	`(3, GEGEN)`	`(1, GEGEN)`	257 = 2⁸ + 2⁰
`<==1== ==2==> ==3==>`	`(3, NORM)`	`(1, NORM)`	0
`<==1== ==2==> <==3==`	`(3, GEGEN)`	`(1, NORM)`	1 = 2⁰

Pseudocode

Um für ein Element-Richtungs-Tupel (Element, Richtung) die Richtung des i-ten Nachfolgers zu bestimmen, wobei i von 0 indiziert ist:

anschluss_shift := i + (if richtung == GEGEN then 8 else 0)
nachfolger_richtung := if (anschluss >> anschluss_shift) & 1 == 0 then NORM else GEGEN

`FahrstrWeichenlage`-Attribut des `FahrstrWeiche`-Knotens

Dieses Attribut ist, anders als die Nachfolger von Streckenelementen, 1-indiziert.

Speicherreihenfolge der Signalmatrix-Einträge

Die Signalmatrizen sind zeilenweise gespeichert. Die Anzahl Spalten ergibt sich aus der Anzahl VsigBegriff-Knoten, die Anzahl Zeilen aus der Anzahl HsigBegriff-Knoten. Wenn matrix eine Liste der MatrixEintrag-Knoten ist, dann ist matrix[zeile * anz_spalten + spalte] der Matrixeintrag für die angegebene Zeile und Spalte (jeweils 0-indiziert).

Landschaft (.ls3)

Farbwerte bei `Subset`-Knoten

Für Farbangaben gibt es aus historischen Gründen zwei Formate.

ABGR: Die Farbe wird als String "0AABBGGRR" kodiert.
ARGB: Die Farbe wird als String "AARRGGBB" kodiert.

RR/GG/BB/AA steht für die zweistellige Hexadezimalrepräsentation des Rot-/Grün-/Blau-/Alpha-Farbanteils als Zahl zwischen 0 und 255.

Neu geschriebene Dateien sollen das ARGB-Format verwenden. Das ABGR-Format begegnet einem beim Parsen bestehender Dateien des Öfteren. Zur Unterscheidung verwenden die beiden Formate unterschiedliche Attributnamen:

Format	Diffuse	Ambient	Emit (Nachtfarbe)
ABGR	C	CA	E
ARGB	Cd	Ca	Ce

@@ Zeile 1: / Zeile 1: @@
-Hier werden Hinweise zu den XML-Dateiformaten gesammelt, die nicht selbsterklärend sind.
+Hier werden Hinweise zu Stellen in den XML-Dateiformaten gesammelt, die nicht selbsterklärend sind.
 == Allgemeines ==
-* Bei Ganzzahl- und Fließkommazahl-Attributen kann der Wert <code>0</code> bzw. <code>0.0</code> kodiert werden, indem das Attribut vollständig weggelassen wird. In den von Zusi geschriebenen Dateien ist das überall so. [http://forum.zusi.de/viewtopic.php?p=233206#p233206 Quelle]
+* Bei Attributen existiert für jeden Typ ein Standardwert, der verwendet wird, wenn das Attribut nicht vorhanden oder leer (Attribut="") ist. Es folgt daraus, dass das Attribut auch beim Schreiben weggelassen werden kann, wenn sein Wert dem Standardwert entspricht. Zusi macht das konsequent so. [http://forum.zusi.de/viewtopic.php?p=233206#p233206 Quelle.] Der Standardwert ist
+** bei Ganzzahlen (integer, integer 64 bit, integer enum, bool) der Wert <code>0</code>.
+** bei Gleitkommazahlen (single) der Wert <code>0.0</code>.
+** bei Zeichenketten (string) die leere Zeichenkette.
+** bei Farben (D3DColor) die Farbe <code>R=G=B=A=0</code>.
+** bei Datums-/Zeitangaben (date,time) der <code>30. Dezember 1899, 00:00:00</code>.
+* Dateipfade (<code>&lt;Datei Dateiname="..."&gt;</code> sind entweder
+** Pfade relativ zum Zusi-Datenverzeichnis (<code>RollingStock\Deutschland\Lok.ls3</code>), wobei ein führender Backslash erlaubt ist und ignoriert wird, oder
+** wenn sie keinen Backslash enthalten, Dateien im selben Verzeichnis wie die Datei, in der der Pfad steht.
+:Insbesondere können Dateien, die auf einem anderen Laufwerk als das Zusi-Datenverzeichnis liegen, nicht referenziert werden.
 * Programmseitig generierte XML-Dateien, die UTF-8-kodiert sind, sollten eine Byte Order Mark (<code>0xEF,0xBB,0xBF</code>) am Anfang enthalten, damit Texteditoren sie zuverlässig als UTF-8 erkennen, siehe [[UTF-8 Byte Order Mark setzen]].
+* Bei Gleitkommazahlen werden sowohl Punkt als auch Komma als Dezimaltrenner betrachtet. In alten Dateien findet sich im Knoten <code>Info</code> das Attribut <code>DecSep</code>, das aber anscheinend ignoriert wird.
+== Einheiten ==
+Einige Werte werden in der XML-Datei anders gespeichert, als sie in der Benutzeroberfläche von Zusi angezeigt werden.
+* Geschwindigkeiten: in der XML-Datei in m/s gespeichert, in der Programmoberfläche (derzeit) in km/h angezeigt. Ausnahme sind die <code>Wert</code>-Attribute in <code>Ereignis</code>-Knoten der Ereignisse "Indusi 1000 Hz" und "Indusi 2000 Hz". Diese werden in der XML-Datei in km/h gespeichert.
+* Winkel: in der XML-Datei im Bogenmaß gespeichert, in der Programmoberfläche in Grad angezeigt.
+* Krümmung von Streckenelementen: in der XML-Datei in 1/m gespeichert, im 3D-Editor in 1/km angezeigt.
+* Überhöhung von Streckenelementen: in der XML-Datei als Winkel im Bogenmaß gespeichert, im Gleisplaneditor und 3D-Editor in Grad und in mm (gemäß eingestelltem Oberbau) angezeigt.
+== Gleisplan (.st2) ==
+Das Format ist sehr redundant, daher braucht man einige Werte nicht eintragen; sie werden vom Gleisplaneditor ignoriert und selbst berechnet:
+* <code><Gerade></code>: Attribut <code>W</code> beider <code><PunktWinkel></code>-Elemente
+* <code><Kreisbogen></code>: Die beiden <code><PunktWinkel></code>-Elemente können leer bleiben (aber nicht weggelassen werden). Nur das dritte Element (<code><Punkt></code>, der Kreismittelpunkt) ist relevant.
+* <code><Klothoide></code>: Das zweite <code><PunktWinkel></code>-Element kann leer bleiben (aber nicht weggelassen werden). Nur das erste Element ist relevant. Es gibt immer den Anfangspunkt der gesamten Klothoide, also den Punkt mit Krümmung 0, an. Bei Klothoidensektoren (<code>KrAnf</code> != 0) entspricht das einem fiktiven Anfangspunkt, der außerhalb des Klothoidensektors liegt.
+* <code><Weiche></code>: Attribut <code>BiegeWinkel</code> der <code><Biegung></code>-Elemente
 == Strecke (.st3) ==
-=== Zuordnung Norm/Gegen -> blau/grün ===
+=== Zuordnung Norm/Gegen ↔ blau/grün ===
 In der Programmoberfläche werden ausschließlich die Bezeichnungen "blaue und grüne Richtung" verwendet. Diese entsprechen Norm- bzw. Gegenrichtung im Dateiformat. Merkhilfe: '''g'''rün = '''G'''egenrichtung.
@@ Zeile 16: / Zeile 42: @@
 Bei <code>NachNorm</code> und <code>NachGegen</code> handelt es sich um die Nummer eines ''Streckenelements'' im selben Modul.
-Bei <code>NachNormModul</code> und <code>NachGegenModul</code> handelt es sich um die Nummer eines ''Referenzpunkts'' im durch den <code>&lt;datei&gt;</code>-Kindknoten angegebenen Modul.
+Bei <code>NachNormModul</code> und <code>NachGegenModul</code> handelt es sich um die Nummer eines ''Referenzpunkts'' im durch den <code>Datei</code>-Kindknoten angegebenen Modul. Der Referenzpunkt ist vom Typ "Modulgrenze" und zeigt in Richtung der Modulgrenze. Existiert so ein Referenzpunkt nicht, erscheint beim Verknüpfen des Streckennetzes die Fehlermeldung ''Auf Element-Nr. %d folgt Nr. %d in Modul "%s", ist dort aber nicht als Schnittstelle definiert (Verknüpfung nicht hergestellt)''
+=== Reihenfolge <code>NachNorm</code> und <code>NachNormModul</code> bzw. <code>NachGegen</code> und <code>NachGegenModul</code> ===
+Der 3D-Editor schreibt die Knoten immer in der festen Reihenfolge:
+# alle <code>NachNorm</code>-Knoten
+# alle <code>NachGegen</code>-Knoten
+# alle <code>NachNormModul</code>-Knoten
+# alle <code>NachGegenModul</code>-Knoten
+Ein Mischen von <code>NachXXX</code> und <code>NachXXXModul</code> im selben Streckenelement ist also nicht möglich. Dass in derselben Richtung sowohl Nachfolger im selben als auch in anderen Modulen vorhanden sind, ist ohnehin ein theoretischer Fall, der keine sinnvolle Anwendung hat. Hat ein Element in einer Richtung Nachfolger im selben Modul, so ignoriert die Fahrstraßenerzeugung des 3D-Editors Nachfolger in anderen Modulen bei der Fahrstraßenerzeugung.
 === <code>Anschluss</code>-Attribut des <code>StrElement</code>-Knotens ===
-Dieses Attribut kodiert auf effiziente Weise die Richtung der Nachfolgerelemente ''des eigenen Moduls''. Bei Nachfolgern in anderen Modulen wird die Richtung stattdessen durch die Richtung des Referenzpunkts bestimmt.
+Dieses Attribut kodiert auf effiziente Weise die Richtung der Nachfolgerelemente ''des eigenen Moduls''. (Nachfolgerelemente in einem anderen Modul sind über einen Referenzpunkt angegeben (s.o.), der auch eine Richtungsangabe enthält -- zu beachten ist, dass diese in Richtung der Modulschnittstelle zeigt).
 Es handelt sich um eine 16-Bit-Zahl. In den unteren 8 Bits ist die Richtung der (maximal 8) Nachfolgerelemente in Normrichtung (blau) gespeichert, beginnend mit dem niedrigsten Bit für den ersten Nachfolger. In den oberen 8 Bits ist die Richtung der (maximal 8) Nachfolgerelemente in Gegenrichtung (grün) gespeichert. Ein Bit 1 an der entsprechenden Stelle bedeutet, dass der Nachfolger in ''Gegen''richtung liegt.
-Pseudocode: Um für ein Element-Richtungs-Tupel <code>(Element, Richtung)</code> die Richtung des <code>i</code>-ten Nachfolgers zu bestimmen, wobei <code>i</code> von 0 indiziert ist:
+==== Beispiel ====
+{| class="wikitable"
+|- class="hintergrundfarbe6"
+! Situation (<code>grünes Ende ==Nr==&gt; blaues Ende</code>)
+! Nachfolger von <code>(2, NORM)</code>
+! Nachfolger von <code>(2, GEGEN)</code>
+! Anschluss-Wert von Element Nr. 2
+|-
+| <code>==1==&gt; '''==2==&gt;''' ==3==&gt;</code>
+| <code>(3, NORM)</code>
+| <code>(1, <span style="color:blue">GEGEN</span>)</code>
+| 256 = <span style="color:blue">2<sup>8</sup></span>
+|-
+| <code>==1==&gt; '''==2==&gt;''' &lt;==3==</code>
+| <code>(3, <span style="color:maroon">GEGEN</span>)</code>
+| <code>(1, <span style="color:blue">GEGEN</span>)</code>
+| 257 = <span style="color:blue">2<sup>8</sup></span> + <span style="color:maroon">2<sup>0</sup></span>
+|-
+| <code>&lt;==1== '''==2==&gt;''' ==3==&gt;</code>
+| <code>(3, NORM)</code>
+| <code>(1, NORM)</code>
+| 0
+|-
+| <code>&lt;==1== '''==2==&gt;''' &lt;==3==</code>
+| <code>(3, <span style="color:maroon">GEGEN</span>)</code>
+| <code>(1, NORM)</code>
+| 1 = <span style="color:maroon">2<sup>0</sup></span>
+|-
+|}
+==== Pseudocode ====
+Um für ein Element-Richtungs-Tupel <code>(Element, Richtung)</code> die Richtung des <code>i</code>-ten Nachfolgers zu bestimmen, wobei <code>i</code> von 0 indiziert ist:
 <pre>
@@ Zeile 33: / Zeile 102: @@
 === <code>FahrstrWeichenlage</code>-Attribut des <code>FahrstrWeiche</code>-Knotens ===
-Dieses Attribut ist, anders als viele andere Werte in Streckendateien, '''1'''-indiziert.
+Dieses Attribut ist, anders als die Nachfolger von Streckenelementen, '''1'''-indiziert.
+=== Speicherreihenfolge der Signalmatrix-Einträge ===
+Die Signalmatrizen sind zeilenweise gespeichert. Die Anzahl Spalten ergibt sich aus der Anzahl <code>VsigBegriff</code>-Knoten, die Anzahl Zeilen aus der Anzahl <code>HsigBegriff</code>-Knoten. Wenn <code>matrix</code> eine Liste der <code>MatrixEintrag</code>-Knoten ist, dann ist <code>matrix[zeile * anz_spalten + spalte]</code> der Matrixeintrag für die angegebene Zeile und Spalte (jeweils 0-indiziert).
+== Landschaft (.ls3) ==
+=== Farbwerte bei <code>Subset</code>-Knoten ===
+Für Farbangaben gibt es aus historischen Gründen zwei Formate.
+* ABGR: Die Farbe wird als String "0AABBGGRR" kodiert.
+* ARGB: Die Farbe wird als String "AARRGGBB" kodiert.
+RR/GG/BB/AA steht für die zweistellige Hexadezimalrepräsentation des Rot-/Grün-/Blau-/Alpha-Farbanteils als Zahl zwischen 0 und 255.
+Neu geschriebene Dateien sollen das ARGB-Format verwenden. Das ABGR-Format begegnet einem beim Parsen bestehender Dateien des Öfteren. Zur Unterscheidung verwenden die beiden Formate unterschiedliche Attributnamen:
+{| class="wikitable"
+|- class="hintergrundfarbe6"
+! Format
+! Diffuse
+! Ambient
+! Emit (Nachtfarbe)
+|-
+| ABGR
+| C
+| CA
+| E
+|-
+| ARGB
+| Cd
+| Ca
+| Ce
+|-
+|}

Ergänzungen zu den XML-Dateiformaten: Unterschied zwischen den Versionen

Aktuelle Version vom 6. Juni 2024, 08:21 Uhr

Inhaltsverzeichnis

Allgemeines

Einheiten

Gleisplan (.st2)

Strecke (.st3)

Zuordnung Norm/Gegen ↔ blau/grün

`Nr`-Attribut `NachNorm[Modul]` und `NachGegen[Modul]`-Knoten im `StrElement`-Knoten

Reihenfolge `NachNorm` und `NachNormModul` bzw. `NachGegen` und `NachGegenModul`

`Anschluss`-Attribut des `StrElement`-Knotens

Beispiel

Pseudocode

`FahrstrWeichenlage`-Attribut des `FahrstrWeiche`-Knotens

Speicherreihenfolge der Signalmatrix-Einträge

Landschaft (.ls3)

Farbwerte bei `Subset`-Knoten

Navigationsmenü

Ergänzungen zu den XML-Dateiformaten: Unterschied zwischen den Versionen

Aktuelle Version vom 6. Juni 2024, 08:21 Uhr

Allgemeines

Einheiten

Gleisplan (.st2)

Strecke (.st3)

Zuordnung Norm/Gegen ↔ blau/grün

Nr-Attribut NachNorm[Modul] und NachGegen[Modul]-Knoten im StrElement-Knoten

Reihenfolge NachNorm und NachNormModul bzw. NachGegen und NachGegenModul

Anschluss-Attribut des StrElement-Knotens

Beispiel

Pseudocode

FahrstrWeichenlage-Attribut des FahrstrWeiche-Knotens

Speicherreihenfolge der Signalmatrix-Einträge

Landschaft (.ls3)

Farbwerte bei Subset-Knoten

Navigationsmenü

Suche

`Nr`-Attribut `NachNorm[Modul]` und `NachGegen[Modul]`-Knoten im `StrElement`-Knoten

Reihenfolge `NachNorm` und `NachNormModul` bzw. `NachGegen` und `NachGegenModul`

`Anschluss`-Attribut des `StrElement`-Knotens

`FahrstrWeichenlage`-Attribut des `FahrstrWeiche`-Knotens

Farbwerte bei `Subset`-Knoten