Repository navigation
Document reading a model's geometry, and two defects the page was asserting away - #24
Merged
Merged
Conversation
samuelduchesne
commented
Sep 25, 2026
samuelduchesne
commented
Contributor
- Document reading a model's geometry, once, for both languages
- Record two measured defects the page was asserting away, and add the TypeScript reference
`docs/geometry/reading.md`, filed as a how-to guide under "Reading and editing
models". One page with language-neutral prose and one set of instructions: what
a coordinate resolves to is a property of the EnergyPlus input format rather
than of either library, so only the fenced code varies.
The page states the three declarations that move a surface's vertices before a
reader sees them, and the one measured exception to the second:
`Shading:Site:Detailed` is fixed in space and does not turn with the building's
north axis, where `Shading:Building:Detailed` does. It records the accounting
guarantee, the four unresolved reasons and the unattempted types, and it ends
with the Python-only `translate_to_world`, marked as such.
Availability is rendered by `{{ parity("geometry-extraction") }}` rather than
stated in prose, so the page cannot disagree with the ledger. At the pinned
`governance-2026.20` that renders the JavaScript gap and its tracking issue;
once the pin advances to the level carrying the scene concepts, the same token
renders the stated difference instead. No hand-written mark has to be removed.
Six Python examples under `docs/snippets/geometry/reading/`, type-checked by
pyright like every other snippet on this site. The TypeScript half is authored
in idfkit-js and vendored.
TWO GATES ARE RED HERE UNTIL THE PINS ADVANCE, AND BOTH ARE THE SAME TASK.
pyright the installed library is 1.0.0-rc.4, which has no `get_scene`.
The examples type-check clean against the library they document.
check-vendored `docs/snippets/js/geometry/` does not exist at `docs-2026.5`.
The page's TypeScript tabs include files no published artifact
carries yet.
Both clear when `[tool.idfkit.library]` and `[tool.idfkit.docs]` advance to the
releases that carry this capability. This page must not merge before them: the
parity notice would tell a reader the capability is absent in JavaScript while
the tabs beside it show JavaScript.
TypeScript reference The page said nothing raises for a model it cannot fully read, which is the contract. Measured against both libraries on a model whose vertex field holds `autosize`, neither meets it: Python raises `ValueError`, and TypeScript reports the surface as resolved with `NaN` coordinates. Because resolution mixes axes, one bad coordinate leaves `scene.bounds` `NaN` in two axes for the whole model, so a consumer framing a view gets nothing and is told nothing. The documented answer is an entry in `unresolved`, and none of the four reasons covers it. Adding a fifth is a registered concept in both languages, so the page records the gap rather than implying it is closed. `translate_to_world` gained the mixed-model hazard its own library docstring names. It rewrites five detailed vertex types and then zeroes `Building.north_axis`; the simplified surface family and `Daylighting:ReferencePoint` are neither read nor rewritten and carry their own coordinate-system fields, so in a model holding both they keep their authored coordinates while the declaration they were written against is removed. `docs/reference/typescript/geometry.md` gives the TypeScript tab somewhere to look up `getScene`, which the page's "See also" previously offered only for Python. NOTE THAT THE REFERENCE PAGE DEEPENS THE PINNED-LEVEL BREAKAGE RATHER THAN EASING IT. The pinned `docs-2026.5` TypeDoc artifact enumerates core, language, schemas and weather, and no geometry. At that level the page fails to render with `Could not collect '@idfkit/geometry'`, which is a second hard build error beside the missing snippets. Both clear together when `[tool.idfkit.docs]` advances; neither can be verified except under the sibling override.
…ut rendering The library pin moved to 1.0.0-rc.6 on main. The other three had not moved since before geometry extraction landed, so the site was rendering a reference without the new package, and two governance pages that disagreed with the tags the libraries are gated on. conformance-2026.12 -> conformance-2026.15 governance-2026.20 -> governance-2026.22 docs-2026.5 -> docs-2026.6 docs-2026.6 was published from idfkit-js for this: docs-2026.5 predates @idfkit/geometry, and check-vendored reported it as "only in the vendored copy: geometry" because the five TypeScript examples this page includes existed locally and in no release. The vendored tree is now synced from the release rather than from a local build, which is the discipline that keeps the reference and the examples describing one commit. The parity page changes twice, and the second one matters most. Reading geometry moves from "absent (not yet)" to "partial" in JavaScript, which is the extraction half landing. Rendering a three-dimensional scene moves from "complete" to "absent (never)", which corrects a claim the published site has been making all along: @idfkit/viewer does not exist, is not in idfkit-js/packages, and is not reachable through the shared install name. A reader meeting that row concluded a renderer was an npm install away. Feature 009 corrected the ledger; this is the change that reaches the reader. The naming map and the consumer page re-render against governance-2026.22 with no surprises: 275 entries and 9 consumers.
samuelduchesne
force-pushed
the
geometry-reading-page
branch
from
September 25, 2026 03:16
e392740 to
a059bbd
Compare
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.