mirror of
https://github.com/qelectrotech/qelectrotech-source-mirror.git
synced 2026-09-20 15:24:14 +02:00
Document EDZ import: zero wiki coverage of a whole import format
sources/import/edz/ is ~1,150 lines (excluding the vendored LZMA SDK) implementing import of EPLAN Data Portal parts, and the word 'EDZ' appeared nowhere on the wiki -- not a passing mention, not a features bullet, nothing. The module already carries a thorough developer README; this restructures it for the wiki rather than writing from scratch, verified line-by-line against the source: the menu path, the exact field mapping (manufacturer, order number, description and comment land in the same four element-information fields the BOM already reads), the zip-vs-7z format detection and its current 7z-only limitation, and the point most likely to surprise a user -- the imported symbol is a generic generated rectangle, not a copy of the EPLAN macro's geometry, because that geometry is tokenised EPLAN PXF referencing EPLAN's own libraries with nothing portable in it. Also carries the module's EPLAN Data Portal Terms of Use notice forward, framed as a description of what QET's reader does (parses only portable factual data, reproduces no EPLAN-proprietary geometry) rather than legal advice about the reader's own situation. EN/FR/DE.
ispyisail
+2
@@ -32,6 +32,8 @@
|
||||
|
||||
**[Title block templates](title_blocks)** — the .titleblock format
|
||||
|
||||
**[Importing EPLAN parts (.edz)](edz_import)** — EPLAN Data Portal
|
||||
|
||||
**[The project database](project_database)** — the in-memory SQLite cache
|
||||
|
||||
</details>
|
||||
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
# EPLAN-Teile importieren (`.edz`)
|
||||
|
||||
QET kann ein Teil aus dem **EPLAN Data Portal** importieren — dem
|
||||
De-facto-Bauteilkatalog der Elektro-CAD (ifm, Phoenix Contact, Siemens,
|
||||
Rittal, Weidmüller, Schneider und weitere) — direkt in eine
|
||||
Elementesammlung. Portal-Teile werden als `.edz`-Dateien ausgeliefert; diese
|
||||
Funktion liest die sachlichen Daten daraus und erzeugt ein QET-Element.
|
||||
|
||||
> **Das ist kein Symbolimport.** Das Ergebnis ist ein funktionsfähiges,
|
||||
> korrekt beschriftetes Element mit den richtigen Klemmen — keine Kopie des
|
||||
> EPLAN-Symbols des Herstellers. Siehe §3.
|
||||
|
||||
Quelle: `sources/import/edz/` — das Modul trägt ein eigenes
|
||||
Entwickler-README, auf dem diese Seite beruht.
|
||||
|
||||
---
|
||||
|
||||
## 1. Verwendung
|
||||
|
||||
Rechtsklick auf einen **beschreibbaren** Sammlungsordner im Elementpanel →
|
||||
**EPLAN-Teil importieren (.edz)…** → Datei wählen. Das erzeugte Element wird
|
||||
in diesen Ordner geschrieben, und das Panel lädt neu.
|
||||
|
||||
Unterstützt werden heute nur `.edz`-Dateien im **7-Zip-Format**. Manche
|
||||
EPLAN-Exporte verwenden stattdessen das Zip-Format (Signatur `PK\x03\x04`
|
||||
statt der von 7z); QET erkennt das und meldet es, statt still zu scheitern,
|
||||
kann es aber noch nicht importieren.
|
||||
|
||||
---
|
||||
|
||||
## 2. Was importiert wird
|
||||
|
||||
Eine `.edz` ist ein Archiv mit einer Teiledefinition (`part.xml`), einem
|
||||
EPLAN-Makro (`.ema`), einem Produktbild und Metadaten. QET liest nur die
|
||||
**portablen** Teiledaten — die Fakten, nicht die EPLAN-eigene
|
||||
Symbolgeometrie:
|
||||
|
||||
| Aus der `.edz` | Wird zu |
|
||||
|---|---|
|
||||
| Jede `<functiontemplate>` mit physischem Anschluss | eine QET-Klemme |
|
||||
| Pinbezeichnung (z. B. `1`, `PE`) | die Beschriftung der Klemme |
|
||||
| Hersteller | Informationsfeld `manufacturer` |
|
||||
| Bestellnummer | `manufacturer_reference` |
|
||||
| Beschreibung (`DESCR1`) | `designation` |
|
||||
| Kommentar (`DESCR2`) | `comment` |
|
||||
| `<name lang="xx">`, eine je vom Teil gelieferter Sprache | ein lokalisierter Elementname, der in der jeweiligen QET-Oberflächensprache erscheint |
|
||||
|
||||
Genau diese vier Informationsfelder liest die Stückliste bereits — siehe
|
||||
**[Die Projektdatenbank](project_database-DE)** — ein importiertes Teil
|
||||
erscheint also ohne weitere Einrichtung korrekt in einer Stückliste.
|
||||
|
||||
Die Pins werden nach ihrem Funktionsblock gruppiert und sortiert, innerhalb
|
||||
dessen nach Bezeichnung: Leistungs-/Klemmenanschlüsse mit `terminalNr`
|
||||
werden danach gruppiert; andere fallen auf ihre `functiondefinition` zurück.
|
||||
|
||||
---
|
||||
|
||||
## 3. Das Symbol ist absichtlich generisch
|
||||
|
||||
Der Import zeichnet ein schlichtes Körperrechteck mit einer nach Westen
|
||||
ausgerichteten Klemme je Pin — **die Geometrie des EPLAN-Makros wird nicht
|
||||
reproduziert.** Das `.ema`-Makro ist tokenisiertes EPLAN-PXF, das auf
|
||||
EPLAN-eigene Symbolbibliotheken verweist; daran ist nichts Portables zu
|
||||
gewinnen.
|
||||
|
||||
Das generische Symbol genügt, um das Teil korrekt zu verdrahten und sofort in
|
||||
eine Stückliste aufzunehmen. Für ein ansehnlicheres Symbol öffnen Sie das
|
||||
importierte Element anschließend im **[Element-Editor](element_linking-DE)**
|
||||
und zeichnen die Grafik neu — Klemmen, Beschriftungen und Informationen
|
||||
stimmen bereits und müssen nicht angefasst werden.
|
||||
|
||||
---
|
||||
|
||||
## 4. Eine Anmerkung zur Herkunft der Daten
|
||||
|
||||
`.edz`-Dateien werden aus dem EPLAN Data Portal (`data.eplan.com`)
|
||||
heruntergeladen, betrieben von der EPLAN Software & Service GmbH & Co. KG.
|
||||
Die Nutzungsbedingungen des Data Portal beschränken die Verwendung
|
||||
heruntergeladener Daten auf EPLAN-Produkte.
|
||||
|
||||
**QET befürwortet oder ermutigt keinen Verstoß gegen diese Bedingungen.** Ob
|
||||
die Verwendung einer bestimmten `.edz` außerhalb von EPLAN-Produkten erlaubt
|
||||
ist, hängt von Ihrer Vereinbarung mit EPLAN und dem Hersteller des Teils ab —
|
||||
QET ist an keiner dieser Vereinbarungen beteiligt und kann das nicht für Sie
|
||||
beantworten. Im Zweifel wenden Sie sich direkt an EPLAN oder den Hersteller.
|
||||
|
||||
Was QETs eigener Leser tut: Er liest nur die sachlichen, portablen
|
||||
Teiledaten — Pinbezeichnungen, Bestellnummern, Herstellernamen — und
|
||||
reproduziert keine EPLAN-eigene Geometrie oder Symboldaten. Das ist eine
|
||||
Beschreibung dessen, was der Code tut, keine Rechtsberatung zu Ihrer
|
||||
konkreten Situation.
|
||||
|
||||
---
|
||||
|
||||
## 5. Wie es zusammenspielt
|
||||
|
||||
| Datei | Rolle |
|
||||
|---|---|
|
||||
| `edzarchive.*` | entpackt die `.edz` in ein temporäres Verzeichnis, findet `part.xml` |
|
||||
| `edzsevenzip.*` | 7-Zip-Entpackung über ein mitgeliefertes, nur entpackendes LZMA-SDK — keine externe 7-Zip-Installation nötig |
|
||||
| `edzpart.*` | liest `part.xml` in das portable Modell aus der obigen Tabelle |
|
||||
| `edzelementbuilder.*` | baut daraus das `.elmt` |
|
||||
| `edzimporter.*` | steuert das Vorstehende und schreibt in den gewählten Sammlungsordner |
|
||||
|
||||
Die Nicht-UI-Klassen sind bewusst vom Widget entkoppelt, sodass die gesamte
|
||||
Kette ohne Oberfläche testbar ist — `docker compose run --rm qet-edz-fuzz`
|
||||
fuzzt `EdzImporter::importToDirectory()` direkt gegen einen Korpus
|
||||
fehlerhafter `.edz`-Dateien unter AddressSanitizer/UBSan.
|
||||
|
||||
---
|
||||
|
||||
Siehe auch: **[Elemente verknüpfen](element_linking-DE)** ·
|
||||
**[Die Projektdatenbank](project_database-DE)**
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# Importer des pièces EPLAN (`.edz`)
|
||||
|
||||
QET peut importer une pièce depuis l'**EPLAN Data Portal** — le catalogue de
|
||||
composants de référence en CAO électrique (ifm, Phoenix Contact, Siemens,
|
||||
Rittal, Weidmüller, Schneider et d'autres) — directement dans une collection
|
||||
d'éléments. Les pièces du portail sont livrées en fichiers `.edz` ; cette
|
||||
fonction en lit les données factuelles et en génère un élément QET.
|
||||
|
||||
> **Ce n'est pas un import de symbole.** Le résultat est un élément
|
||||
> fonctionnel, correctement étiqueté, avec les bonnes bornes — pas une copie du
|
||||
> symbole EPLAN du fabricant. Voir §3.
|
||||
|
||||
Source : `sources/import/edz/` — le module porte son propre README de
|
||||
développeur, sur lequel cette page s'appuie.
|
||||
|
||||
---
|
||||
|
||||
## 1. L'utiliser
|
||||
|
||||
Clic droit sur un dossier de collection **modifiable** dans le panneau des
|
||||
éléments → **Importer une pièce EPLAN (.edz)…** → choisissez le fichier.
|
||||
L'élément généré est écrit dans ce dossier et le panneau se recharge.
|
||||
|
||||
Seuls les fichiers `.edz` au **format 7-Zip** sont pris en charge aujourd'hui.
|
||||
Certains exports EPLAN utilisent le format zip à la place (signature
|
||||
`PK\x03\x04` plutôt que celle de 7z) ; QET le détecte et le signale plutôt que
|
||||
d'échouer silencieusement, mais ne peut pas encore l'importer.
|
||||
|
||||
---
|
||||
|
||||
## 2. Ce qui est importé
|
||||
|
||||
Un `.edz` est une archive contenant une définition de pièce (`part.xml`), une
|
||||
macro EPLAN (`.ema`), une image produit et des métadonnées. QET ne lit que les
|
||||
données **portables** de la pièce — les faits, pas la géométrie de symbole
|
||||
propre à EPLAN :
|
||||
|
||||
| Du `.edz` | Devient |
|
||||
|---|---|
|
||||
| Chaque `<functiontemplate>` avec une connexion physique | une borne QET |
|
||||
| Désignation de broche (p. ex. `1`, `PE`) | l'étiquette de la borne |
|
||||
| Fabricant | champ d'information `manufacturer` |
|
||||
| Numéro de commande | `manufacturer_reference` |
|
||||
| Description (`DESCR1`) | `designation` |
|
||||
| Commentaire (`DESCR2`) | `comment` |
|
||||
| `<name lang="xx">`, un par langue fournie par la pièce | un nom d'élément localisé, qui s'affiche dans la langue de l'interface de QET |
|
||||
|
||||
Ces quatre champs d'information sont exactement ceux que lit déjà la
|
||||
nomenclature — voir **[La base de données du projet](project_database-FR)** —
|
||||
si bien qu'une pièce importée apparaît correctement dans une nomenclature sans
|
||||
réglage supplémentaire.
|
||||
|
||||
Les broches sont regroupées et triées par bloc fonctionnel, puis par
|
||||
désignation à l'intérieur de ce bloc : les connexions de puissance/bornier
|
||||
portant un `terminalNr` sont regroupées sur cette base ; les autres se
|
||||
rabattent sur leur `functiondefinition`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Le symbole est générique, volontairement
|
||||
|
||||
L'import dessine un simple rectangle de corps avec une borne orientée vers
|
||||
l'ouest par broche — **il ne reproduit pas la géométrie de la macro EPLAN.** La
|
||||
macro `.ema` est du PXF EPLAN tokenisé qui renvoie aux bibliothèques de
|
||||
symboles propres à EPLAN ; il n'y a rien de portable à en tirer.
|
||||
|
||||
Le symbole générique suffit à câbler correctement la pièce et à l'intégrer
|
||||
immédiatement à une nomenclature. Pour un symbole plus soigné, ouvrez
|
||||
l'élément importé dans l'**[éditeur d'élément](element_linking-FR)** ensuite et
|
||||
redessinez le graphisme — les bornes, étiquettes et informations sont déjà
|
||||
correctes et n'ont pas besoin d'être touchées.
|
||||
|
||||
---
|
||||
|
||||
## 4. Une remarque sur l'origine des données
|
||||
|
||||
Les fichiers `.edz` se téléchargent depuis l'EPLAN Data Portal
|
||||
(`data.eplan.com`), exploité par EPLAN Software & Service GmbH & Co. KG. Les
|
||||
conditions d'utilisation du Data Portal restreignent l'usage des données
|
||||
téléchargées aux produits EPLAN.
|
||||
|
||||
**QET n'encourage ni ne cautionne le non-respect de ces conditions.** Que
|
||||
l'usage d'un `.edz` donné en dehors des produits EPLAN soit permis dépend de
|
||||
l'accord que vous avez avec EPLAN et le fabricant de la pièce — QET n'est
|
||||
partie à aucun de ces accords et ne peut pas répondre à votre place. En cas de
|
||||
doute, adressez-vous directement à EPLAN ou au fabricant.
|
||||
|
||||
Ce que fait le lecteur de QET lui-même : il n'analyse que les données
|
||||
factuelles et portables de la pièce — désignations de broches, numéros de
|
||||
commande, noms de fabricants — et ne reproduit aucune géométrie ou donnée de
|
||||
symbole propriétaire EPLAN. C'est une description de ce que fait le code, pas
|
||||
un avis juridique sur votre situation particulière.
|
||||
|
||||
---
|
||||
|
||||
## 5. Comment ça s'articule
|
||||
|
||||
| Fichier | Rôle |
|
||||
|---|---|
|
||||
| `edzarchive.*` | extrait le `.edz` dans un dossier temporaire, localise `part.xml` |
|
||||
| `edzsevenzip.*` | extraction 7-Zip via un SDK LZMA embarqué, en lecture seule — aucune installation externe de 7-Zip requise |
|
||||
| `edzpart.*` | analyse `part.xml` selon le modèle portable du tableau ci-dessus |
|
||||
| `edzelementbuilder.*` | construit le `.elmt` à partir de ce modèle |
|
||||
| `edzimporter.*` | orchestre tout cela et écrit dans le dossier de collection choisi |
|
||||
|
||||
Les classes non-UI sont délibérément découplées du widget, si bien que toute
|
||||
la chaîne est testable sans interface — `docker compose run --rm
|
||||
qet-edz-fuzz` fuzz directement `EdzImporter::importToDirectory()` contre un
|
||||
corpus de fichiers `.edz` malformés sous AddressSanitizer/UBSan.
|
||||
|
||||
---
|
||||
|
||||
Voir aussi : **[Lier des éléments](element_linking-FR)** ·
|
||||
**[La base de données du projet](project_database-FR)**
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
# Importing EPLAN parts (`.edz`)
|
||||
|
||||
QET can import a part from the **EPLAN Data Portal** — the de-facto parts
|
||||
catalogue for electrical CAD (ifm, Phoenix Contact, Siemens, Rittal,
|
||||
Weidmüller, Schneider and others) — directly into an elements collection.
|
||||
Portal parts ship as `.edz` files; this feature reads the factual data out of
|
||||
one and generates a QET element from it.
|
||||
|
||||
> **This is not a symbol import.** The result is a working, correctly labelled
|
||||
> element with the right terminals — not a copy of the manufacturer's EPLAN
|
||||
> symbol. See §3.
|
||||
|
||||
Source: `sources/import/edz/` — the module carries its own developer README,
|
||||
which this page is based on.
|
||||
|
||||
---
|
||||
|
||||
## 1. Using it
|
||||
|
||||
Right-click a **writable** collection folder in the elements panel →
|
||||
**Import an EPLAN part (.edz)…** → choose the file. The generated element is
|
||||
written into that folder and the panel reloads.
|
||||
|
||||
Only **7-Zip-format** `.edz` files are supported today. Some EPLAN exports use
|
||||
zip format instead (`PK\x03\x04` rather than the 7z magic number); QET detects
|
||||
this and reports it rather than failing silently, but cannot import it yet.
|
||||
|
||||
---
|
||||
|
||||
## 2. What is imported
|
||||
|
||||
A `.edz` is an archive containing a part definition (`part.xml`), an EPLAN
|
||||
macro (`.ema`), a product image and metadata. QET reads only the **portable**
|
||||
part data — the facts, not EPLAN's own symbol geometry:
|
||||
|
||||
| From the `.edz` | Becomes |
|
||||
|---|---|
|
||||
| Each `<functiontemplate>` with a physical connection | a QET terminal |
|
||||
| Pin designation (e.g. `1`, `PE`) | the terminal's label |
|
||||
| Manufacturer | `manufacturer` element-information field |
|
||||
| Order number | `manufacturer_reference` |
|
||||
| Description (`DESCR1`) | `designation` |
|
||||
| Comment (`DESCR2`) | `comment` |
|
||||
| `<name lang="xx">`, one per language the part provides | a localized element name, so it appears in whatever language QET's UI is running in |
|
||||
|
||||
Those four information fields are exactly the ones the BOM/nomenclature
|
||||
already reads — see **[The project database](project_database)** — so an
|
||||
imported part appears correctly in a parts list with no further setup.
|
||||
|
||||
Pins are grouped and sorted by their functional block, then by designation
|
||||
within it: power/terminal connections carrying a `terminalNr` are grouped by
|
||||
that; others fall back to their `functiondefinition`.
|
||||
|
||||
---
|
||||
|
||||
## 3. The symbol is generic, on purpose
|
||||
|
||||
The importer draws a plain body rectangle with one west-facing terminal per
|
||||
pin — **it does not reproduce the EPLAN macro's geometry.** The `.ema` macro is
|
||||
tokenised EPLAN PXF that references EPLAN's own symbol libraries; there is
|
||||
nothing portable in it to draw from.
|
||||
|
||||
The generic symbol is enough to wire the part correctly and get it into a BOM
|
||||
immediately. If you want a nicer-looking symbol, open the imported element in
|
||||
the **[element editor](element_linking)** afterward and redraw the graphics —
|
||||
the terminals, labels and information are already correct and do not need to
|
||||
be touched.
|
||||
|
||||
---
|
||||
|
||||
## 4. A note on where the data comes from
|
||||
|
||||
`.edz` files are downloaded from the EPLAN Data Portal (`data.eplan.com`),
|
||||
operated by EPLAN Software & Service GmbH & Co. KG. The Data Portal's own
|
||||
Terms of Use restrict use of downloaded data to EPLAN products.
|
||||
|
||||
**QET does not endorse or encourage violating those terms.** Whether using a
|
||||
given `.edz` outside EPLAN products is permitted depends on your agreement
|
||||
with EPLAN and the part's manufacturer — QET has no part in that agreement and
|
||||
cannot answer it for you. If in doubt, ask EPLAN or the manufacturer directly.
|
||||
|
||||
What QET's reader itself does: it parses only the portable, factual part data
|
||||
— pin designations, order numbers, manufacturer names — and does not reproduce
|
||||
any EPLAN-proprietary geometry or symbol data. That is a description of what
|
||||
the code does, not legal advice about your specific situation.
|
||||
|
||||
---
|
||||
|
||||
## 5. How it fits together
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `edzarchive.*` | extracts the `.edz` to a temp directory, locates `part.xml` |
|
||||
| `edzsevenzip.*` | 7-Zip extraction via a bundled, decode-only LZMA SDK — no external 7-Zip install needed |
|
||||
| `edzpart.*` | parses `part.xml` into the portable model in the table above |
|
||||
| `edzelementbuilder.*` | builds the `.elmt` from that model |
|
||||
| `edzimporter.*` | orchestrates the above and writes into the chosen collection folder |
|
||||
|
||||
The non-UI classes are deliberately decoupled from the widget, so the whole
|
||||
pipeline is testable headless — `docker compose run --rm qet-edz-fuzz` fuzzes
|
||||
`EdzImporter::importToDirectory()` directly against a corpus of malformed
|
||||
`.edz` files under AddressSanitizer/UBSan.
|
||||
|
||||
---
|
||||
|
||||
See also: **[Linking elements](element_linking)** ·
|
||||
**[The project database](project_database)**
|
||||
+1
@@ -64,6 +64,7 @@ Beginnen Sie mit der deutschen Version dieses Wikis:
|
||||
| Auto-numbering | ✅ | ✅ | ✅ |
|
||||
| Title block templates | ✅ | ✅ | ✅ |
|
||||
| Linking wires across pages | ✅ | ✅ | ✅ |
|
||||
| Importing EPLAN parts (.edz) | ✅ | ✅ | ✅ |
|
||||
|
||||
**Legend:** ✅ Translated | 📋 Planned | ❌ Not yet started
|
||||
|
||||
|
||||
Reference in New Issue
Block a user