From ce9a93e015fdbbc1622508a44446160dcaacfa05 Mon Sep 17 00:00:00 2001 From: ispyisail Date: Wed, 30 Sep 2026 08:52:04 +1300 Subject: [PATCH] Document conductor segments and the non-finite value check (PR #1161) --- conductors.md | 12 +++++++++ .../project_diagram_child_conductors.md | 26 ++++++++++++++++++- 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/conductors.md b/conductors.md index 06adf19..2248d67 100644 --- a/conductors.md +++ b/conductors.md @@ -199,6 +199,18 @@ matches where its terminals are — because something moved without the path being updated — QElectroTech quietly discards it on load and re-routes automatically. The drawing looks fine; the hand-routing is lost. +> **Status: pending.** The next paragraph describes +> [PR #1161](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1161), +> not yet merged. Until it lands, one unreadable length (`nan`) in a damaged +> file turns the whole stored route into `nan` on the first save, and the +> next save drops it. This notice will come out once it merges. + +The same happens when a stored segment length is not a usable number — a +project file damaged by an outside tool or a disk error, with `nan` or `inf` +where a length should be. The conductor is routed automatically on load and +the file saves normally from then on. The storage format is described in +**[conductors (XML)](project_diagram_child_conductors)**. + --- ## 7. Colouring quickly diff --git a/data_files/project_diagram_child_conductors.md b/data_files/project_diagram_child_conductors.md index ecc323b..cf498ca 100644 --- a/data_files/project_diagram_child_conductors.md +++ b/data_files/project_diagram_child_conductors.md @@ -14,9 +14,33 @@ attribute : none * terminal1, terminal2 -- the terminals joined * terminalname1, terminalname2 -- their names * element1_name, element2_name, element1_label, element2_label -- cached labels - * x, y, userx, usery, rotation -- geometry of the conductor text + * x, y -- the conductor's own position + * userx, usery -- the label's position, written only when the label has + been moved by hand + * rotation -- the label's rotation, written only when it has been rotated + by hand * freezeLabel -- `true` / `false` + A conductor whose route was shaped by hand also has one `` child + per segment, in order from the first terminal: + * orientation -- `horizontal` or `vertical` + * length -- signed length in pixels; negative goes left or up + + On load the lengths must add up to the distance between the two terminals + (within one pixel), or the stored route is discarded and the conductor is + routed automatically. A conductor with no `` children is routed + automatically. + +> **Status: pending.** The next paragraph describes +> [PR #1161](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1161), +> not yet merged. This notice will come out once it merges. + +Every number above must be finite. `nan`, `inf` and `-inf` parse as numbers, +so QElectroTech checks for them: a non-finite segment length is ignored (so +the route no longer adds up and is routed automatically), a non-finite `x` or +`y` is read as 0, and a non-finite `userx`, `usery` or `rotation` is ignored +as if the label had never been moved or rotated. + Conductors are written in a stable sorted order derived from both endpoints, so that saving twice produces byte-identical files.