Hahn: CAD-XML-Syntax-Dokumentation (automatischer Import)

2026-07-20T12:50:35Z

CAD-XML-Syntax-Dokumentation (automatischer Import)

Neue Seite

{{DISPLAYTITLE:CAD XML Syntax-Objekt VC_Hintergrundbild}}
Das Hintergrundbild bindet eine Rasterbild-Datei (z. B. gescannter Riss, Orthofoto) lagerichtig in die CAD-Szene ein. Delphi-Klasse ist <code>T2DBackgroundPicture</code> (<code>CAD\GLGeometrics.pas</code>), abgeleitet von <code>T3DBaseObject</code>. '''Achtung: Das XML-Tag heißt <code>VC_Hintergrundbild</code> — OHNE das sonst übliche „CAD" im Namen''' (wie auch <code>VC_Plotrahmen</code>).

== Strukturregel ==
<pre>
<VC_Hintergrundbild>
<VermCadID> … </VermCadID> (siehe VermCadID-Block; CADObjektArt=cadBackgroundPicture)
[Basiselemente] (siehe Basiselemente; Layer ist Pflicht)
[<Verankert>bool</Verankert>]
<HBild_Dateiname>text</HBild_Dateiname> (Dateiname/Pfad der Bilddatei)
<HBild_Centre0>zahl</HBild_Centre0> (Bildmittelpunkt X)
<HBild_Centre1>zahl</HBild_Centre1> (Bildmittelpunkt Y)
<HBild_Centre2>zahl</HBild_Centre2> (Bildmittelpunkt Z)
<HBild_ZLevel>ganzzahl</HBild_ZLevel>
<HBild_Width>zahl</HBild_Width>
<HBild_Height>zahl</HBild_Height>
<HBild_RotAngle>zahl</HBild_RotAngle>
<HBild_ScaleWidth>zahl</HBild_ScaleWidth>
<HBild_ScaleHeight>zahl</HBild_ScaleHeight>
<HBild_SpiegelHor>bool</HBild_SpiegelHor>
<HBild_SpiegelVert>bool</HBild_SpiegelVert>
<HBild_Ausblenden>bool</HBild_Ausblenden>
<HBild_HasMWTRef>bool</HBild_HasMWTRef>
</VC_Hintergrundbild>
</pre>
Geerbte Elemente: [[CAD XML Syntax-VermCadID und GUID-Referenzen|VermCadID-Block]] und [[CAD XML Syntax-Basiselemente|Basiselemente]]; Werteformate: [[CAD XML Syntax-Werte- und Koordinatenformate|Werteformate]].

'''Schreib-Vorbedingung:''' Die eigenen <code>HBild_*</code>-Elemente werden beim Speichern NUR geschrieben, wenn die Textur geladen ist UND die Bilddatei auf der Platte existiert — sonst landen nur VermCadID und Basisdaten in der Datei (und das Objekt überlebt das nächste Laden nicht, siehe Referenzen).

== Elemente ==
Nur die eigenen Elemente von <code>T2DBackgroundPicture</code>:

{| class="wikitable"
! Element !! Typ/Format !! Pflicht !! Default !! Bedeutung
|-
| <code>Verankert</code> || bool || nein || False || Bild ist verankert (nicht verschiebbar); wird beim Einpassen über World-File automatisch gesetzt
|-
| <code>HBild_Dateiname</code> || text || '''ja''' || — || Bilddatei. Geschrieben wird der '''projektrelative''' Pfad, wenn vorhanden (relativ zur Projektdatei), sonst der absolute; die Nutzereinstellung „Absolute Pfade" erzwingt absolute Pfade. Beim Lesen werden Pfade ohne Laufwerksangabe gegen den Projektdatei-Ordner aufgelöst
|-
| <code>HBild_Centre0</code> / <code>HBild_Centre1</code> / <code>HBild_Centre2</code> || zahl (Float) || praktisch ja || 0 || Bildmittelpunkt X / Y / Z in Weltkoordinaten
|-
| <code>HBild_ZLevel</code> || ganzzahl || nein || 0 || Z-Ebene (Zeichenreihenfolge mehrerer Bilder)
|-
| <code>HBild_Width</code> / <code>HBild_Height</code> || zahl (Float) || praktisch ja || — || Bildgröße in Pixeln; historisch Integer — der Leser akzeptiert Float
|-
| <code>HBild_RotAngle</code> || zahl (Float) || nein || 0 || Drehwinkel des Bildes
|-
| <code>HBild_ScaleWidth</code> / <code>HBild_ScaleHeight</code> || zahl (Float) || praktisch ja || — || Skalierungsfaktor Breite / Höhe (Weltmaß pro Pixel-Anteil); bei unverzerrten Bildern identisch
|-
| <code>HBild_SpiegelHor</code> / <code>HBild_SpiegelVert</code> || bool || nein || False || horizontale / vertikale Spiegelung
|-
| <code>HBild_Ausblenden</code> || bool || nein || False || Bild ist ausgeblendet
|-
| <code>HBild_HasMWTRef</code> || bool || nein || False || Bild stammt aus einer Referenz in der MWT-Datei ([[MWT Syntax]])
|}
Beim Lesen wird der Textknoten <code>NAN</code> bei allen Float-Elementen ignoriert (Wert bleibt Default).

== Referenzen ==
Das Hintergrundbild hat keine GUID-Referenzen auf andere CAD-Objekte, aber eine harte '''Datei-Referenz''': In <code>SetReferencesAndUpdate</code> (nach dem Laden) gilt
* leerer Dateiname → „Objekt wird nicht eingelesen" — das Bild wird verworfen;
* Laufwerk oder Datei nicht vorhanden → Logeintrag „Hintergrundbild … konnte nicht gefunden werden. Objekt wird nicht eingelesen" — das Bild wird '''zerstört''' (siehe [[CAD XML Syntax-Lesemechanik und Pflichtfelder|Lesemechanik]]).
Ein gültiges <code>VC_Hintergrundbild</code> setzt also voraus, dass die Bilddatei beim Laden erreichbar ist.

== Minimalform ==
<pre>
<VC_Hintergrundbild>
<VermCadID>
<GUID>{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}</GUID>
<ObjektArt>oaCAD</ObjektArt>
<CADObjektArt>cadBackgroundPicture</CADObjektArt>
</VermCadID>
<Layer>0</Layer>
<HBild_Dateiname>bild.jpg</HBild_Dateiname>
<HBild_Centre0>545000.0</HBild_Centre0>
<HBild_Centre1>5721000.0</HBild_Centre1>
<HBild_Centre2>0</HBild_Centre2>
<HBild_Width>2000</HBild_Width>
<HBild_Height>1500</HBild_Height>
<HBild_ScaleWidth>0.1</HBild_ScaleWidth>
<HBild_ScaleHeight>0.1</HBild_ScaleHeight>
</VC_Hintergrundbild>
</pre>
<code>bild.jpg</code> muss neben der Projektdatei existieren, sonst wird das Objekt beim Laden verworfen.

== Beispiele ==
=== Beispiel (Sachsen, echt) ===
<pre>
<VC_Hintergrundbild>
<VermCadID>
<GUID>{76E4D488-…}</GUID>
<ObjektArt>oaCAD</ObjektArt>
<CADObjektArt>cadBackgroundPicture</CADObjektArt>
</VermCadID>
<Layer>1018</Layer>
<Verankert>-1</Verankert>
<HBild_Dateiname>4267USR3-3.jpg</HBild_Dateiname>
<HBild_Centre0>3332591.62810421</HBild_Centre0>
<HBild_Centre1>5683956.65895749</HBild_Centre1>
<HBild_Centre2>0</HBild_Centre2>
<HBild_ZLevel>0</HBild_ZLevel>
<HBild_Width>21252</HBild_Width>
<HBild_Height>28818</HBild_Height>
<HBild_RotAngle>22.4573631286621</HBild_RotAngle>
<HBild_ScaleWidth>0.0861217868039655</HBild_ScaleWidth>
<HBild_ScaleHeight>0.0861217868039655</HBild_ScaleHeight>
<HBild_SpiegelHor>0</HBild_SpiegelHor>
<HBild_SpiegelVert>0</HBild_SpiegelVert>
<HBild_Ausblenden>0</HBild_Ausblenden>
<HBild_HasMWTRef>0</HBild_HasMWTRef>
</VC_Hintergrundbild>
</pre>

== Verfügbarkeit und Besonderheiten ==
* Verfügbar in '''allen''' Bundesland-Versionen (kein IFDEF); in den drei Beispielprojekten nur in Sachsen belegt (1 Exemplar).
* '''Legacy-Alias <code>HBild_Scale</code>''': einheitlicher Skalierungsfaktor alter Dateien; wird nicht mehr geschrieben (write=False), beim Lesen setzt er '''sowohl''' <code>ScaleWidth</code> als auch <code>ScaleHeight</code>. Folgen in einer alten Datei danach noch <code>HBild_ScaleWidth</code>/<code>HBild_ScaleHeight</code>, überschreiben diese den Wert.
* <code>HBild_Width</code>/<code>HBild_Height</code> wurden früher als Integer geschrieben; aktueller Stand ist Float — der Leser verarbeitet beides.
* Schreibreihenfolge im Manager: Bilder als eigene Gruppe nach den Texten, vor den Plotrahmen.
* Unterstützte Bildformate verarbeitet die FreeImage-Bibliothek (u. a. JPG, TIF, PNG, BMP); World-File-Einpassung (z. B. .jgw/.tfw) setzt <code>Verankert</code> automatisch.

== Quellen im Code ==
* <code>CAD\GLGeometrics.pas:68197-68302</code> — <code>T2DBackgroundPicture.DataToXMLLite</code> (Schreib-Vorbedingung Textur+Datei, alle HBild_*-Elemente)
* <code>CAD\GLGeometrics.pas:68100-68195</code> — <code>InternalCreateFromXML</code> (Lesen inkl. Legacy <code>HBild_Scale</code>, NAN-Behandlung)
* <code>CAD\GLGeometrics.pas:68728-68755</code> — <code>SetReferencesAndUpdate</code> (Dateiname Pflicht, Datei muss existieren)
* <code>CAD\GLGeometrics.pas:69209-69237</code> — <code>SetFileName</code>/<code>GetSaveFileName</code> (relative/absolute Pfadlogik, Einstellung „Absolute Pfade")
* <code>VERMCAD\GlobalConsts.pas</code> — Tag-Konstanten <code>xn_Hintergrundbild</code>=<code>VC_Hintergrundbild</code>, <code>xn_HBild*</code> (write_xn_HBildScale=False)

{{Hilfe:NachOben}}
[[Kategorie:CAD XML Syntax]]

CAD XML Syntax-Objekt VC Hintergrundbild - Versionsgeschichte

Hahn: CAD-XML-Syntax-Dokumentation (automatischer Import)