Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

The package version runs on its own semver; the schema it is generated from is `SCHEMA_DIST_TAG`.

## 0.130.1 (2026-11-16)

- **`layout_by_links_3d` no longer raises on a Map whose width or height is under 0.** A Map's `width` and `height` are any whole number in the standard. One under 0 raised a `PlateError` from inside the method when that Map held the most pinned elements, and with both under 0 the Map became a plate with every place mirrored. A width or height that is not over 0 is now no size: such a Map is no plate, no other Map is tried in its stead, and the world is laid out by its links alone; a Map over a place with such a size is no small plate. The method's shared fixture gains four cases for it (64), the same bytes as the npm SDK's copy.
- **Held points cost what they move.** The force steps worked out the push between every two fixed elements, 300 times, though neither can move and the push was never read. They no longer do; no number of any answer changes.
- The `held` list's comment says what False means: a pinned element stands at its Pin and is never answered as held, so what is new is every id that was not handed in.

## 0.130.0 (2026-11-16)

- **`layout_by_links_3d`: a 3D layout of a whole graph by its links (`by-links-3d`).** Given the graph as `world_graph` answers it and, optionally, the world's elements as served, it answers a point `[x, y, z]` for every node, in the order handed in (one flat `points` list), and how each was placed: a group's centre, with a centre, hanging off the body, on the shelf, or at its Pin. The body of the graph is cut into groups round its centres, the groups are packed apart in directions read from a table baked into the package, and 300 seeded force steps settle it; what hangs off the body is fanned out from it, and what is not joined to the main piece stands on a shelf under the picture. When a Map holds three or more of the graph's elements by a Pin, the Map that holds the most is a flat plate with each of its elements at its Pin, and a Map over a place on it a small plate above that place; a Pin's z is not read, and a layout map is never the plate. Maps and Pins are read through `map_space` and `layout_of`, nothing else. The same input gives the same points as the npm SDK's `layoutByLinks3d`: to the last bit for elements placed at a centre, with a centre or at a Pin, within a billionth of a rest (the unit `BY_LINKS_3D_REST`, 60) for the rest, which are placed with the runtime's cosine and sine. Two keyword options: `held`, points an earlier answer gave (element id to three finite numbers), so the picture keeps still as the world changes, and `held_unit`, the step those points were rounded to. A bad `held` or `held_unit` is refused before anything runs, each error with a `code` (`held-not-object`, `held-not-point`, `held-box`, `held-unit`). It is pure Python, so a world of several thousand elements takes minutes. The word `by-links-3d` is the tool's own until the method's page is published, and until then a release may move its points.
Expand Down
16 changes: 13 additions & 3 deletions src/onlyworlds/_layout3d/plate.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@

A row's key that is absent is read as UNDEF, which is not None. Map and element ids are held as keys by jkey(), so
True and 1 are two keys and 1 and 1.0 one (as the npm SDK's Map holds them). A width or height that is not a number,
or a negative area, raises PlateError. A division by a zero root is infinite (js_div()).
raises PlateError. A width or height that is not over 0 is no size: such a first map gives no plate, such a small
map is not taken, so a negative area is never reached. A division by a zero root is infinite (js_div()).
"""

from __future__ import annotations
Expand Down Expand Up @@ -85,6 +86,15 @@ def key(v: Any, what: str) -> tuple[Any, ...]:
return jkey(v, what)


def sized(v: Any) -> bool:
"""a size: truthy and, when a number, over 0 (a Map's width is any whole number; NaN is no size)"""
if not truthy(v):
return False
if is_num(v):
return bool(v > 0)
return True


def truthy(v: Any) -> bool:
"""the truth of a JSON value: UNDEF, None, False, 0, "", an empty list or object are false; NaN is true"""
if v is UNDEF or v is None or v is False:
Expand Down Expand Up @@ -214,7 +224,7 @@ def plate(rows: Sequence[Any], nodes: Sequence[Any], scale: Any = UNDEF) -> dict
mp = maps[mk]
W, H = get(mp, "width"), get(mp, "height")
count = len(at[mk][1])
if count < 3 or not truthy(W) or not truthy(H):
if count < 3 or not sized(W) or not sized(H):
return None

# 4. the scale and the first map's places
Expand Down Expand Up @@ -253,7 +263,7 @@ def plate(rows: Sequence[Any], nodes: Sequence[Any], scale: Any = UNDEF) -> dict
for ek, (el, xy) in mine.items():
if ek not in out:
fresh.append((ek, el, xy))
if key(loc, "a map's location") in out and truthy(cw) and truthy(ch) and len(mine) >= 3 and len(fresh):
if key(loc, "a map's location") in out and sized(cw) and sized(ch) and len(mine) >= 3 and len(fresh):
sc = js_div(TILE * REST, root(cw, ch, len(mine), f"the map {c}"))
lx, ly, lz = out[jkey(loc)][1]
rise = REST * (4 if len(mine) >= 20 else 2)
Expand Down
17 changes: 16 additions & 1 deletion src/onlyworlds/_layout3d/relax.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
3. the move: each element's push, plus its links' pull times its scale (1 over the larger of 1 and a quarter of its
links' summed weight), plus (anchor - point) * pull, moves it by at most the cap, cap0 * R * (1 - step / steps)
+ R / 20; a fixed element stands at its anchor.
The push between two fixed elements is never read and is not worked out, which moves no number.
Every sum runs in the order written and every expression keeps its grouping. A distance under 1e-6 is read as 1e-6 and
a move's length under 1e-9 as 1e-9; a NaN goes through as it is (no max() or min()).
"""
Expand Down Expand Up @@ -78,7 +79,13 @@ def relax(feed: dict[str, Any], cutoff: float = 3, cap0: float = 3) -> dict[str,
R3 = R / 3
OFFS = _offsets()

for step in range(STEPS):
# Two fixed elements push each other and neither moves, so that push is never read: it is not worked out (a
# cell pair with no free element is passed over whole, and so is a pair of two fixed elements). The pushes on a
# free element are still summed in the same order, so no number of the answer changes. With no free element at
# all one step does what every step would: each element at its anchor.
free = n - sum(fixed)
run = min(STEPS, 1) if free == 0 else STEPS
for step in range(run):
x0 = y0 = z0 = math.inf
x1 = y1 = z1 = -math.inf
for i in range(n):
Expand Down Expand Up @@ -115,6 +122,10 @@ def relax(feed: dict[str, Any], cutoff: float = 3, cap0: float = 3) -> dict[str,
c = cellOf[i]
order[fill[c]] = i
fill[c] += 1
freeIn = [0] * cells
for i in range(n):
if not fixed[i]:
freeIn[cellOf[i]] += 1

for i in range(n):
dx[i] = 0.0
Expand All @@ -140,13 +151,17 @@ def relax(feed: dict[str, Any], cutoff: float = 3, cap0: float = 3) -> dict[str,
t1 = startOf[q + 1]
if t0 == t1:
continue
if freeIn[c] == 0 and freeIn[q] == 0:
continue
for u in range(s0, s1):
i = order[u]
xi = px[i]
yi = py[i]
zi = pz[i]
for w in range(u + 1 if same else t0, t1):
j = order[w]
if fixed[i] and fixed[j]:
continue
ux = xi - px[j]
uy = yi - py[j]
uz = zi - pz[j]
Expand Down
2 changes: 1 addition & 1 deletion src/onlyworlds/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.130.0"
__version__ = "0.130.1"
11 changes: 7 additions & 4 deletions src/onlyworlds/layout_links_3d.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,9 @@ class LayoutByLinks3d(TypedDict):
part: list[Literal["map", "one-link", "no-link"] | None]
#: The centres' ids, in rank order.
centres: list[str]
#: True where the point answered is the element's held point; False everywhere when nothing is held.
#: True where the point answered is the element's held point; False everywhere when nothing is held. A pinned
#: element stands at its Pin and is never held, so False does not mean new: what is new is every id that was not
#: handed in.
held: list[bool]


Expand All @@ -65,9 +67,10 @@ def layout_by_links_3d(
body by one element is fanned out from it, and what is not joined to the main piece stands on a shelf under the
picture. When the world has a Map that holds three or more elements of the graph by a Pin, the Map that holds the
most (a tie to the greater id) is a flat plate, each of its pinned elements at its Pin, the groups whose centre is
pinned standing over it; a Map over a place on that plate is a small plate a little above it. A Pin's z is not
read: the plate is flat. A layout map (a Map whose ``x_layout`` names a method, the map-space profile's mark) is
never the plate: a saved layout never stands in for the world's own space.
pinned standing over it; a Map over a place on that plate is a small plate a little above it. A Map whose width
or height is not over 0 is no plate, and when it is the Map that holds the most, the world is laid out by its
links alone. A Pin's z is not read: the plate is flat. A layout map (a Map whose ``x_layout`` names a method,
the map-space profile's mark) is never the plate: a saved layout never stands in for the world's own space.

``graph`` is ``world_graph``'s answer, or any mapping of the same shape: ``nodes`` (each with ``id`` and
``type``) and ``edges`` (each with ``source`` and ``target``, and ``field`` and ``index`` where it has them), the
Expand Down
Loading
Loading