python-cad-tools 0.1.17__tar.gz → 0.1.19__tar.gz

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/.github/workflows/ci.yml

@@ -17,6 +17,12 @@
 # creates the tag and triggers this run. Keeping publish logic in one
 # gated place (instead of duplicating it in release.yml) avoids two
 # workflows racing to publish the same version.
+#
+# Test tiers (workspace test-cost-reduction, 2026-10-12): pushes and pull
+# requests run the checks a code change can break on Linux, plus one macOS
+# platform job. Version tags and manual dispatch (the release path, before
+# PyPI) also run Windows, the per-extra toolchain matrix on macOS and Linux,
+# and the platform locks. macOS minutes bill 10x on this private repository.
 name: CI
 
 on:
@@ -227,15 +233,15 @@ jobs:
           done
           echo "All tree shape checks passed."
 
-  # Confirms init/build works on Linux, macOS, and Windows. Windows
-  # skips ruff/mypy since static checks aren't part of the
-  # cross-platform contract, just the CLI behavior.
+  # Confirms init/build works on Linux, macOS, and Windows (Windows only
+  # on the release tier). Windows skips ruff/mypy since static checks
+  # aren't part of the cross-platform contract, just the CLI behavior.
   supported-platforms:
     name: Supported platforms (${{ matrix.os }})
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["ubuntu-latest","macos-latest","windows-latest"]' || '["ubuntu-latest","macos-latest"]') }}
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -263,9 +269,10 @@ jobs:
 
   # Generates a per-OS `pip freeze` lockfile as a downloadable
   # artifact for reference. Informational only — not enforced or
-  # committed anywhere automatically.
+  # committed anywhere automatically. Release tier only.
   platform-locks:
     name: Platform lock generation (${{ matrix.os }})
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
     strategy:
       fail-fast: false
       matrix:
@@ -297,40 +304,27 @@ jobs:
           path: ${{ matrix.lock }}
 
   # Confirms every optional dependency group (cad, bim, mesh, ...)
-  # installs cleanly and imports across OS/Python combinations. PRs
-  # only run a fast subset (core+all on ubuntu/py3.13) via the gate
-  # step below; main and tag pushes run the full matrix.
+  # installs cleanly and imports across OS/Python combinations. Pushes
+  # and PRs run core and all on Linux for both Pythons; the release tier
+  # runs every group on Linux and macOS. The matrix itself is narrowed,
+  # so no runner starts for a cell that would be skipped.
   toolchain-matrix:
     name: Toolchain matrix (${{ matrix.os }}, py${{ matrix.python }}, ${{ matrix.group }})
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["ubuntu-latest","macos-latest"]' || '["ubuntu-latest"]') }}
         python: ["3.12", "3.13"]
-        group: [core, cad, bim, mesh, drawings, engineering, visualization, all]
+        group: ${{ fromJSON((startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch') && '["core","cad","bim","mesh","drawings","engineering","visualization","all"]' || '["core","all"]') }}
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      # Full matrix on main/tags/release-candidates; a fast core+all subset on pull requests.
-      - name: Determine whether this matrix cell runs
-        id: gate
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ] && \
-             ! { [ "${{ matrix.os }}" = "ubuntu-latest" ] && [ "${{ matrix.python }}" = "3.13" ] && \
-                 { [ "${{ matrix.group }}" = "core" ] || [ "${{ matrix.group }}" = "all" ]; }; }; then
-            echo "run=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          fi
       - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
-        if: steps.gate.outputs.run == 'true'
         with:
           python-version: ${{ matrix.python }}
           cache: pip
       - run: python -m pip install --upgrade pip
-        if: steps.gate.outputs.run == 'true'
       - name: Install capability group
-        if: steps.gate.outputs.run == 'true'
         run: |
           if [ "${{ matrix.group }}" = "core" ]; then
             pip install -e .
@@ -338,9 +332,7 @@ jobs:
             pip install -e ".[${{ matrix.group }}]"
           fi
       - run: pip check
-        if: steps.gate.outputs.run == 'true'
       - name: Import declared libraries for this group
-        if: steps.gate.outputs.run == 'true'
         run: |
           python - <<'PY'
           import importlib
@@ -384,7 +376,7 @@ jobs:
           print(json.dumps(report, indent=2, sort_keys=True))
           PY
       - name: Tier-2 interop smoke and no-GUI assertion
-        if: steps.gate.outputs.run == 'true' && matrix.group == 'all'
+        if: matrix.group == 'all'
         run: |
           python - <<'PY'
           import sys
@@ -413,7 +405,6 @@ jobs:
           print("Tier-2 interop smoke and no-GUI assertion passed.")
           PY
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
-        if: steps.gate.outputs.run == 'true'
         with:
           name: toolchain-compatibility-${{ matrix.os }}-py${{ matrix.python }}-${{ matrix.group }}
           path: toolchain-compatibility.json

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/CHANGELOG.md

@@ -7,6 +7,48 @@ stable release is published.
 
 ## [Unreleased]
 
+## [0.1.19] - 2026-10-19
+
+### Changed
+
+- Every public function and class in the authoring modules (`artifacts`,
+  `build`, `context`, `drawings`, `elements`, `geometry`, `units`,
+  `validation`) has a one-line docstring stating its units and, for
+  geometry, its placement:
+  - `box` puts its minimum corner at the origin;
+  - `prism_between` starts at a bottom corner, with its width to the left
+    of the run;
+  - `Placement` is recorded only and never moves geometry.
+
+  Tools that list the public API with signatures and first docstring
+  lines now describe each helper. Behavior is unchanged.
+- Routine CI runs a smaller platform and extras matrix. Version tags and
+  manual dispatch still run the full release matrix.
+
+## [0.1.18] - 2026-10-08
+
+### Fixed
+
+- Curved B-rep solids (spheres, `cylinder_between` cylinders and other curved
+  shapes) no longer fail `build` and `verify` with `artifact_integrity:
+  IFC/design bounds mismatch`. The design manifest records each element's
+  `body_bounds_mm` (the bounds of the body IFC actually writes: the mesh of a
+  tessellated solid, the exact shape for recipes), and the IFC check compares
+  against it at the same `1e-6` tolerance. Manifests without the field fall
+  back to `bounds_mm`. `body_bounds_mm` describes the export, not the design,
+  so it is left out of `semantic_hash`: design hashes are unchanged, and
+  `validate` does not tessellate.
+- `validate` reports a build123d `Part` (or compound) that holds one solid as
+  `solid-wrapped` with the fix (`.solid()`), instead of a bare
+  `solid-invalid`.
+
+### Changed
+
+- A build tessellates each element once and shares the mesh between the
+  design manifest, IFC and GLB (`geometry.shared_tessellation`), instead of
+  IFC and GLB each meshing it. `benge-property-cad`'s full build went from
+  106 s to 67 s on the owner's Mac.
+
 ## [0.1.16] - 2026-09-22
 
 ### Fixed

{python_cad_tools-0.1.17/src/python_cad_tools.egg-info → python_cad_tools-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cad-tools
-Version: 0.1.17
+Version: 0.1.19
 Summary: Typed, headless Python tooling for CAD/BIM models and artifacts
 Author: Brandon Benge
 License: AGPL-3.0-only

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/docs/public-api.md

@@ -16,13 +16,15 @@ of optional runtime imports.
   `cubic_yards`, `metres`, and `square_metres`.
 - `python_cad_tools.geometry`: `box`, `reference_line`, `cylinder_between`,
   `prism_between`, `sloped_pool`, `bounds`, `combined_bounds`, `tessellate`,
-  `is_valid_solid`, and `diagonal`. **Curved geometry that must pass the
-  build pipeline's `artifact_integrity` IFC/design-bounds check should not
-  use `cylinder_between`** -- its tessellated B-rep output cannot exactly
-  match analytic design-side bounds. Use `python_cad_tools.recipes`'
-  `CircleProfile` + `ExtrudedProfile` instead; see
-  [`cylinder_between`'s docstring](../src/python_cad_tools/geometry.py) and
-  `docs/spikes/curved-geometry-ifc-bounds.md` for the confirmed mechanism.
+  `is_valid_solid`, and `diagonal`. Curved B-rep solids (`cylinder_between`,
+  build123d spheres and other curved shapes) build and verify: IFC writes
+  them as triangle meshes, and the IFC bounds check compares that mesh with
+  the same tessellation recorded in the design manifest as `body_bounds_mm`
+  (0.1.18). Use `python_cad_tools.recipes`' `CircleProfile` +
+  `ExtrudedProfile` where an analytic IFC body is wanted instead of a mesh.
+  Pass a `Solid`: build123d algebra-mode shapes such as `Sphere(...)` are a
+  `Part` wrapping one solid, which `validate` reports as `solid-wrapped`
+  (use `.solid()`).
 - `python_cad_tools.drawings`: `Point2`, `Direction`, `DrawingStyleToken`,
   `DrawingSheet`, `Line`, `Polyline`, `Text`, `Dimension`, `SectionCallout`,
   `ElevationMarker`, `TableRow`, `Table`, `SheetAnnotations`, and

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/docs/spikes/curved-geometry-ifc-bounds.md

@@ -1,4 +1,21 @@
-# Curved geometry vs. the IFC/design bounds integrity check (mechanism confirmed empirically)
+# Curved geometry vs. the IFC/design bounds integrity check
+
+**Resolved in 0.1.18 (2026-10-08).** The mechanism is confirmed in source:
+elements without a recipe are written to IFC as an `IfcTriangulatedFaceSet`
+from `tessellate(geometry, 0.5, 0.25)`, the IFC report's bounds are read back
+from those mesh coordinates, and the manifest recorded only the exact B-rep
+bounds; `_reconcile_formats` compared the two at `1e-6`. The fix is candidate
+direction 1 below ("compare like with like"): the design manifest now records
+`body_bounds_mm`, the bounds of the same tessellation
+(`geometry.IFC_TESSELLATION`, shared with the exporter), and the IFC check
+compares against it, still exactly. A live hosted run on 2026-10-08 ("change
+the cube to a sphere", `Sphere(152.4).solid()`) failed with x/y short by
+0.58 mm before the fix; `tests/integration/test_curved_geometry.py` covers a
+sphere, a `cylinder_between` cylinder, a box, and a tampered IFC report.
+Approval: `specrepo/approved/2026-10-08-curved-geometry-ifc-bounds/` (workspace).
+
+The history below is kept as it was written.
+
 
 Status: **mechanism confirmed, fix known — not yet verified against this
 repo's own source.** A later sandbox-agent attempt on the same project (see

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/docs/toolchain.md

@@ -90,7 +90,9 @@ See `docs/two-tier-contract.md` for what "Tier 1" and "Tier 2" mean.
 ## Compatibility verification
 
 The `toolchain-matrix` CI job (`.github/workflows/ci.yml`) installs every
-capability group across `{ubuntu-latest, macos-latest} × {3.12, 3.13}`, runs
+capability group across `{ubuntu-latest, macos-latest} × {3.12, 3.13}` on
+version tags and manual runs (the release path; pushes and pull requests
+run `core` and `all` on Linux for both Pythons), runs
 `pip check`, imports every library the group declares, and — for `all` — runs
 a Tier-2 interop smoke (a shape crosses build123d → `geometry.tessellate` →
 trimesh → ifcopenshell read-back → ezdxf) plus the no-GUI assertion. It

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/artifacts.py

@@ -14,7 +14,7 @@ from xml.etree import ElementTree
 
 from .determinism import semantic_hash, sha256_file
 from .exceptions import ArtifactIntegrityError, BuildExportError
-from .manifests import load_json_document, validate_json_document
+from .manifests import design_semantic_projection, load_json_document, validate_json_document
 from .validation import ValidationIssue
 
 BUILD_MANIFEST_RELATIVE = "manifests/build-manifest.json"
@@ -25,6 +25,7 @@ _EXPECTED_REPRESENTATION_TYPE = {None: "Tessellation", "extruded_profile": "Swep
 
 @dataclass(frozen=True, slots=True)
 class ArtifactRecord:
+    """One generated file: its path, size, SHA-256, media type and producer."""
     path: str
     size: int
     sha256: str
@@ -37,6 +38,7 @@ class ArtifactRecord:
 
 @dataclass(frozen=True, slots=True)
 class VerificationResult:
+    """The outcome of ``verify_build_output``: whether the output matches its manifest, and any issues."""
     ok: bool
     output_root: Path
     issues: tuple[ValidationIssue, ...]
@@ -48,6 +50,7 @@ class VerificationResult:
 
 @dataclass(frozen=True, slots=True)
 class PackageBuildInfo:
+    """The installed python-cad-tools distribution's version and build provenance."""
     schema_id: Literal["urn:python-cad-tools:schema:package-build-info:1"]
     schema_version: Literal[1]
     distribution: Literal["python-cad-tools"]
@@ -58,6 +61,7 @@ class PackageBuildInfo:
 
 
 def load_build_manifest(path: Path) -> dict[str, Any]:
+    """Read and schema-check a build manifest JSON file."""
     value = validate_json_document(path)
     if value["schema_id"] != "urn:python-cad-tools:schema:build-manifest:1":
         raise ArtifactIntegrityError(f"Not a build manifest: {path}")
@@ -65,6 +69,7 @@ def load_build_manifest(path: Path) -> dict[str, Any]:
 
 
 def load_design_manifest(path: Path) -> dict[str, Any]:
+    """Read and schema-check a design manifest JSON file."""
     value = validate_json_document(path)
     if value["schema_id"] != "urn:python-cad-tools:schema:design-manifest:1":
         raise ArtifactIntegrityError(f"Not a design manifest: {path}")
@@ -153,9 +158,8 @@ def verify_output_root(output_root: Path, project_root: Path | None = None) -> V
         _verify_sources(project_root, document)
     selected = _selected_formats(document)
     design = load_design_manifest(output_root / "manifests/design-manifest.json")
-    design_without_hash = dict(design)
-    recorded_design_hash = design_without_hash.pop("semantic_hash", None)
-    if recorded_design_hash != semantic_hash(design_without_hash):
+    recorded_design_hash = design.get("semantic_hash")
+    if recorded_design_hash != semantic_hash(design_semantic_projection(design)):
         raise ArtifactIntegrityError("Design manifest semantic_hash does not reproduce")
     if document["design_semantic_hash"] != design["semantic_hash"]:
         raise ArtifactIntegrityError("Build and design manifest semantic hashes disagree")
@@ -172,6 +176,7 @@ def verify_output_root(output_root: Path, project_root: Path | None = None) -> V
 
 
 def verify_build_output(project_root: Path) -> VerificationResult:
+    """Check that a project's generated output still matches its build manifest."""
     from ._locking import project_lock
     from ._transaction import recover_promotion
     from .project_config import load_project_config, output_path, resolve_project_root
@@ -185,6 +190,7 @@ def verify_build_output(project_root: Path) -> VerificationResult:
 
 
 def get_package_build_info() -> PackageBuildInfo:
+    """Return the installed distribution's build information."""
     try:
         document = json.loads(resources.files("python_cad_tools").joinpath("build-info.json").read_text(encoding="utf-8"))
     except (FileNotFoundError, json.JSONDecodeError) as error:
@@ -386,7 +392,11 @@ def _reconcile_formats(root: Path, formats: tuple[str, ...]) -> None:
             for item in elements
             if item["physical"] and "ifc" in item["export_formats"] and item["ifc_class"] is not None
         ]
-        _require_matching_bounds("IFC", report["bounds_mm"], _combined_manifest_bounds(expected_elements))
+        # Tessellated IFC bodies are meshes; compare them with the same mesh, recorded in the
+        # manifest as body_bounds_mm (0.1.18). Older manifests fall back to the exact bounds.
+        _require_matching_bounds(
+            "IFC", report["bounds_mm"], _combined_manifest_bounds(expected_elements, key="body_bounds_mm")
+        )
         _reconcile_ifc_extensions(root, formats, report, expected_elements)
     if "glb" in formats:
         from .exporters.glb import glb_json
@@ -536,14 +546,15 @@ def _normalized_text(value: str) -> str:
     return " ".join(value.split())
 
 
-def _combined_manifest_bounds(elements: list[dict[str, Any]]) -> list[float]:
+def _combined_manifest_bounds(elements: list[dict[str, Any]], key: str = "bounds_mm") -> list[float]:
     if not elements:
         return [0.0] * 6
+    values = [item.get(key) or item["bounds_mm"] for item in elements]
     return [
-        round(min(float(item["bounds_mm"][index]) for item in elements), 6)
+        round(min(float(value[index]) for value in values), 6)
         for index in range(3)
     ] + [
-        round(max(float(item["bounds_mm"][index]) for item in elements), 6)
+        round(max(float(value[index]) for value in values), 6)
         for index in range(3, 6)
     ]
 

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/build.py

@@ -22,6 +22,7 @@ from .determinism import semantic_hash, sha256_file, write_json
 from .exceptions import BuildExportError, ModelValidationError, ProjectConfigError, UnsafePathError
 from .exporters import GlbExporter, IfcExporter, QuantityExporter, StepExporter
 from .exporters.drawings import DrawingExporter
+from .geometry import shared_tessellation
 from .manifests import build_manifest_document, design_manifest, write_preinventory_manifests
 from .project_config import FORMAT_ORDER, load_project_config, output_path, resolve_project_root
 from .validation import ValidationIssue, fatal_issues
@@ -31,18 +32,21 @@ type FormatName = Literal["step", "ifc", "glb", "drawings", "quantities"]
 
 @dataclass(frozen=True, slots=True)
 class BuildOptions:
+    """Options for ``build_project``: the project root and the formats to build (default: the project's own)."""
     project_root: Path
     formats: tuple[FormatName, ...] | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class ValidationOptions:
+    """Options for ``validate_project``: the project root and the formats to check (default: the project's own)."""
     project_root: Path
     formats: tuple[FormatName, ...] | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class BuildResult:
+    """What ``build_project`` produced: its output folder, artifacts, build manifest and hashes."""
     project_root: Path
     output_root: Path
     formats: tuple[FormatName, ...]
@@ -56,6 +60,7 @@ class BuildResult:
 
 @dataclass(frozen=True, slots=True)
 class ValidationReport:
+    """The issues ``validate_project`` found; ``ok`` is true when none is fatal."""
     project_root: Path
     formats: tuple[FormatName, ...]
     issues: tuple[ValidationIssue, ...]
@@ -78,11 +83,12 @@ EXPORTERS: dict[str, type[Any]] = {
 
 
 def build_project(options: BuildOptions) -> BuildResult:
+    """Build the project's requested formats into its output folder and return the result."""
     if not isinstance(options, BuildOptions):
         raise TypeError("build_project expects BuildOptions")
     requested = _validate_requested_formats(options.formats)
     root = resolve_project_root(options.project_root)
-    with project_execution():
+    with project_execution(), shared_tessellation():
         with project_lock(root):
             config = load_project_config(root)
             formats = config.default_formats if requested is None else requested
@@ -158,6 +164,7 @@ def build_project(options: BuildOptions) -> BuildResult:
 
 
 def validate_project(options: ValidationOptions) -> ValidationReport:
+    """Load the project's model and check it without writing any artifacts."""
     if not isinstance(options, ValidationOptions):
         raise TypeError("validate_project expects ValidationOptions")
     requested = _validate_requested_formats(options.formats)
@@ -173,7 +180,7 @@ def validate_project(options: ValidationOptions) -> ValidationReport:
                 formats=formats,
                 issues=loaded.issues,
                 source_set_hash=source_set_hash,
-                design_semantic_hash=design_manifest(loaded.model)["semantic_hash"],
+                design_semantic_hash=design_manifest(loaded.model, include_body_bounds=False)["semantic_hash"],
                 annotation_provider_id=(
                     None if loaded.annotations is None else loaded.annotations.provider_id
                 ),
@@ -181,6 +188,7 @@ def validate_project(options: ValidationOptions) -> ValidationReport:
 
 
 def clean_project(project_root: Path) -> None:
+    """Remove the project's generated output folder."""
     reject_nested_project_execution()
     root = resolve_project_root(project_root)
     config = load_project_config(root)

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/context.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
 
 @dataclass(frozen=True, slots=True)
 class BuildContext:
+    """What ``build_model`` receives: the project root, its loaded ``config`` and source revision, with recorded read-only access to declared sources."""
     project_root: Path
     config: Any
     source_revision: str | None
@@ -57,6 +58,7 @@ class BuildContext:
 
 @dataclass(frozen=True, slots=True)
 class DrawingContext:
+    """What a drawing annotation provider receives: the built model and its sheets, in millimetres."""
     project_root: Path
     config: Any
     model: DesignModel

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/drawings/__init__.py

@@ -19,6 +19,8 @@ type DrawingStyleToken = Literal[
 
 @dataclass(frozen=True, slots=True)
 class DrawingSheet:
+    """One drawing view: its id, view kind, projection origin and axes, and projected bounds in millimetres."""
+
     sheet_id: str
     view_id: Literal["plan", "front", "side", "section"]
     origin_mm: tuple[float, float, float]
@@ -29,6 +31,8 @@ class DrawingSheet:
 
 @dataclass(frozen=True, slots=True)
 class Line:
+    """A straight annotation line on a sheet, in projected millimetres."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -38,6 +42,8 @@ class Line:
 
 @dataclass(frozen=True, slots=True)
 class Polyline:
+    """An open or closed annotation polyline on a sheet, in projected millimetres."""
+
     id: str
     sheet_id: str
     points: tuple[Point2, ...]
@@ -47,6 +53,8 @@ class Polyline:
 
 @dataclass(frozen=True, slots=True)
 class Text:
+    """Annotation text placed on a sheet, with its height in millimetres and rotation in degrees."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -58,6 +66,8 @@ class Text:
 
 @dataclass(frozen=True, slots=True)
 class Dimension:
+    """A labelled dimension between two sheet points, offset in millimetres."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -69,6 +79,8 @@ class Dimension:
 
 @dataclass(frozen=True, slots=True)
 class SectionCallout:
+    """A section cut line on a sheet that refers to the sheet showing that section."""
+
     id: str
     sheet_id: str
     start: Point2
@@ -80,6 +92,8 @@ class SectionCallout:
 
 @dataclass(frozen=True, slots=True)
 class ElevationMarker:
+    """A marker on a sheet that refers to the sheet showing that elevation."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -90,12 +104,16 @@ class ElevationMarker:
 
 @dataclass(frozen=True, slots=True)
 class TableRow:
+    """One row of an annotation ``Table``."""
+
     id: str
     cells: tuple[str, ...]
 
 
 @dataclass(frozen=True, slots=True)
 class Table:
+    """A titled annotation table placed on a sheet."""
+
     id: str
     sheet_id: str
     position: Point2
@@ -109,12 +127,16 @@ type AnnotationPrimitive = Line | Polyline | Text | Dimension | SectionCallout |
 
 @dataclass(frozen=True, slots=True)
 class SheetAnnotations:
+    """All annotations for one sheet."""
+
     sheet_id: str
     annotations: tuple[AnnotationPrimitive, ...]
 
 
 @dataclass(frozen=True, slots=True)
 class DrawingAnnotationSet:
+    """What a drawing annotation provider returns: annotations per sheet."""
+
     provider_id: str
     sheets: tuple[SheetAnnotations, ...]
 

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/elements.py

@@ -15,6 +15,8 @@ GeometryKind = Literal["solid", "shell", "wire", "edge", "reference"]
 
 @dataclass(frozen=True, slots=True)
 class MaterialSpec:
+    """A material: id, display name, category, RGB colour in 0-1 and optional density in kg/m3."""
+
     id: str
     name: str
     category: str
@@ -25,12 +27,16 @@ class MaterialSpec:
 
 @dataclass(frozen=True, slots=True)
 class Placement:
+    """An element's recorded position (millimetres) and XYZ rotation (degrees); it does not move the geometry, which must already be in place."""
+
     translation_mm: tuple[float, float, float] = (0.0, 0.0, 0.0)
     rotation_deg_xyz: tuple[float, float, float] = (0.0, 0.0, 0.0)
 
 
 @dataclass(frozen=True, slots=True)
 class Dimensions:
+    """An element's declared size in millimetres; every value given must be finite and positive."""
+
     length_mm: float | None = None
     width_mm: float | None = None
     height_mm: float | None = None
@@ -46,6 +52,8 @@ class Dimensions:
 
 @dataclass(frozen=True, slots=True)
 class IfcMapping:
+    """The IFC class and predefined type an element exports as, or why it is excluded from IFC."""
+
     ifc_class: str | None
     predefined_type: str | None = None
     exclude_reason: str | None = None
@@ -68,6 +76,8 @@ class Opening:
 
 @dataclass(slots=True)
 class DesignElement:
+    """One model element with a stable id; physical elements need solid geometry and a material, and colours use RGB in 0-1."""
+
     id: str
     name: str
     category: str
@@ -98,6 +108,8 @@ class DesignElement:
 
 @dataclass(slots=True)
 class DesignModel:
+    """The whole model a project's ``build_model`` returns: its elements in millimetres, X right, Y away, Z up."""
+
     id: str
     name: str
     artifact_stem: str

{python_cad_tools-0.1.17 → python_cad_tools-0.1.19}/src/python_cad_tools/exporters/ifc.py

@@ -17,7 +17,7 @@ from ifcopenshell import ifcopenshell_wrapper
 from ..determinism import normalized_build_epoch, write_json
 from ..elements import DesignElement, Opening
 from ..exceptions import BuildExportError, ModelValidationError
-from ..geometry import bounds, tessellate
+from ..geometry import IFC_TESSELLATION, bounds, tessellate
 from ..recipes import (
     CircleProfile,
     DifferenceRecipe,
@@ -326,7 +326,7 @@ def _build_representation(file, context, element: DesignElement) -> tuple[Any, s
     BREP instead.
     """
     if element.recipe is None:
-        vertices, triangles = tessellate(element.geometry, 0.5, 0.25)
+        vertices, triangles = tessellate(element.geometry, *IFC_TESSELLATION)
         points = file.createIfcCartesianPointList3D(vertices)
         face_set = file.createIfcTriangulatedFaceSet(
             points,
@@ -482,7 +482,7 @@ def _add_opening(file, context, host_product, storey, element, opening: Opening)
     The host element's ``geometry`` stays authoritative for every other
     format; the framework does not boolean-subtract the opening.
     """
-    vertices, triangles = tessellate(opening.geometry, 0.5, 0.25)
+    vertices, triangles = tessellate(opening.geometry, *IFC_TESSELLATION)
     points = file.createIfcCartesianPointList3D(vertices)
     face_set = file.createIfcTriangulatedFaceSet(
         points, None, True, [[index + 1 for index in triangle] for triangle in triangles], None