Feature idea: auto-derive IEC 81346-2 classification letter per element category (placeholder before numbering is configured)

[ispyisail]

Checked: is this already done?

No. #613/#648 and #649/#650/#652 built the structure half of an IEC 81346 reference designation — the =plant+location-prefix part. This is about the other half: the classification letter itself (the K in -K3, the Q in -Q1) — and making it visible the moment an element is placed, before any numbering is even configured.

The ask

Right now, getting -K1 on a relay means typing -K%sequ_1 into that relay's numbering-context formula yourself (Project Properties → Numérotation auto → Éléments). QET has no idea a relay is a relay — the letter only ever appears because a person typed it.

Two pieces:

1. Placed, unconfigured: drop any element on a diagram with no numbering set up, and it shows its classification letter with a placeholder — K?, Q?, S? — so you can see at a glance what it will become, before you've set anything up.
2. Numbering configured: same element shows K1, K2 — letter and number together, combining this with the existing auto-numbering system (%sequ_1 etc.) rather than replacing it.

Why this is genuinely hard — and I don't want to undersell it

QET has no concept of device classification anywhere today. Checked before writing this up, not assumed:

• kindInformations() — the closest thing that sounds relevant — exists on very few elements, and where present it describes contact state (type=simple, state=NO), not device category.
• ElementData::typeToString() returns simple/master/slave/terminal/etc. — the element's link role, orthogonal to what kind of device it physically is.
• Nothing in the .elmt format or the qet_directory per-folder metadata carries anything like a designation letter.

So this needs new classification data from scratch, and the collection is 1156 category folders, 8757 elements (counted directly). That's the real scope problem, and it's the same shape as translations: 1 person cannot classify all of it accurately in one PR, and a rushed, wrong classification is worse than an honest gap, especially for something claiming IEC compliance.

One more thing that needs a real answer before this goes far: IEC 81346-2's classification table is a paid, copyrighted ISO/IEC document. I don't know how much of "K = relay" is a protectable expression versus an uncopyrightable fact/correspondence, and I'm not the right one to decide that. Worth someone actually checking before this is built, not after.

Proposed scope — phased, not all-or-nothing

Phase 1 — mechanism + a handful of seed examples.

• New optional field on the per-category qet_directory file (same file that already carries translated category names — see the PR Never leave a collection folder without a name (replaces #622) #633 work on FileElementCollectionItem) — something like a designation-letter attribute. Absent by default; nothing changes for a category that hasn't been classified.
• Element::actualLabel()/setUpFormula() (sources/qetgraphicsitem/element.cpp) gain a third state alongside "static label" and "formula-computed label": no formula configured, but the element's category has a letter → show LETTER?.
• Seed a small number of genuinely uncontroversial, publicly well-documented categories (relays, contactors, circuit breakers — the ones nobody would argue about) as a working proof of concept. Not an attempt to classify everything in one go.

Phase 2 — progressive, crowdsourced classification.
Same shape as translation coverage: track how many of the 1156 categories have a letter assigned, let it grow over time, don't gate the feature on 100% completion. A category folder is a much more tractable unit to hand out to volunteer contributors than 8757 individual elements would be.

Phase 3 — only if actually needed.
Per-element override, for the categories that turn out to mix classifications a single folder-level letter can't capture correctly.

Open questions I'm deliberately not answering here

• The licensing question above — needs a real answer, not a guess.
• Folder-level granularity will sometimes be wrong when one folder mixes device kinds that IEC 81346-2 splits apart. Worth deciding up front whether that's an acceptable v1 limitation or a blocker.
• IEC 81346-2 also has multi-letter combination codes for finer classification — single-letter-only feels like the right v1 scope, but flagging it as a deliberate simplification rather than an oversight.
• Should a K? placeholder be styled differently from a finished label, so nobody mistakes it for something ready to manufacture from? UI question for whoever picks this up.

Relationship to #617

Not the same problem. #617 is about grouping several elements into one assembly with shared external terminals — connectivity. This is purely about what letter+number gets displayed on a single element's label. Same distinction #649 already drew for the same reason.

[ispyisail]

Phase 1 mechanism (the first of the two states described above — placed, unconfigured, placeholder) is built and up for review: #668.

What it does:

• New ElementsLocation::designationLetter() walks up from an element's category to the collection root looking for a designation-letter attribute on the category's qet_directory, deferring to the nearest ancestor that has one set (a leaf folder named after nothing more than a manufacturer's model code inherits from its parent category).
• Element::actualLabel() gains the third fallback described above: formula → manual label → this placeholder (K?) → empty. Never written back into element data, so it costs nothing to recompute and never fights with whatever gets configured later.
• Every element ever dropped on a diagram gets copied into the project's own embedded collection — that copy path wasn't carrying category metadata across at all, so it needed a small fix too (QETXML::fileSystemDirToXmlCollectionDir()), otherwise the placeholder could only ever have worked for elements still sitting in the source collection, never for anything actually placed on a diagram.

What it deliberately does not do:

• No designation-letter values are seeded into any real category yet — this is the mechanism only, per the phased scope above. A category shows nothing until someone (or a future seeding pass) sets the attribute on its qet_directory.
• State 2 (formula-combined K1, K2) isn't built — a numbering formula still takes priority over the placeholder exactly as before, unchanged.
• The licensing question above is still open — not resolved, not assumed.

Separately, some classification tooling exists in the Docker harness repo (qelectrotech-docker, tools/iec81346/) — an IEC 81346-2 letter table sourced from the standard's own definitions (not the popular K=relay folklore) plus a script that name/folder-matches existing element categories against it, currently at ~66% coverage of the ~6900 elements in 10_electric. That tooling isn't wired into this PR and nothing from it has been seeded anywhere — it exists as a starting point for whoever picks up Phase 2 (or as something to fork/adapt), not as a claim that classification is solved.

[ispyisail]

First real data for #668's mechanism to read: qelectrotech/qelectrotech-elements#69 seeds designation-letter on 291 category folders (of ~810 total under 10_electric) that cleared a fairly strict evidence bar — at least 3 independently-classified elements per category, at least 80% agreement. Everything else is deliberately left unseeded rather than guessed.

Full methodology, thresholds, and one specific edge case worth a second pair of eyes are in that PR's description rather than repeated here.

[scorpio810]

@ispyisail : see https://github.com/qelectrotech/qelectrotech-elements/blob/main/10_electric/qet_labels.xml and search on forum, sorry for my delay I don't have the time or the health for it at the moment.