python-cad-tools 0.1.0rc1__py3-none-any.whl

python_cad_tools/templates/project/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+generated/*
+!generated/.gitkeep

python_cad_tools/templates/project/README.md

@@ -0,0 +1,38 @@
+# Python CAD Project
+
+This project uses `model.py`, `config.py`, and `drawing_annotations.py` as its authoritative design source. One headless build generates exact STEP, IFC4, GLB, conceptual SVG/DXF/PDF drawings, quantities, validation reports, and manifests.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install python-cad-tools
+python-cad build
+```
+
+On Windows, use the executables under `.venv\Scripts`.
+
+Edit project dimensions and materials in `config.py` and build shared elements in `model.py`. Preserve stable semantic IDs. Do not edit files under `generated/`.
+
+Useful commands:
+
+```bash
+python-cad build
+python-cad build --format step
+python-cad build --format ifc --format quantities
+python-cad validate
+python-cad verify
+python-cad clean
+```
+
+`generated/` is ignored by Git except for `.gitkeep`. CI should upload generated artifacts instead of committing them.
+
+## Review in the browser
+
+```bash
+python-cad serve
+```
+
+This builds the latest CAD artifacts and serves a static, read-only viewer site on the loopback address. See `python-cad serve --help` for host, port, and base-path options.
+
+Conceptual drawings are not for construction or permitting. This project does not provide engineering, code, permit, survey, or licensed-trade approval.

python_cad_tools/templates/project/config.py

@@ -0,0 +1,36 @@
+"""Project-owned typed dimensions, materials, colors, and export settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from python_cad_tools.units import FOOT, INCH, MM, Length
+
+PROJECT_NAME = "ProjectModel"
+BASE_LENGTH = 10 * FOOT
+BASE_WIDTH = 6 * FOOT
+BASE_THICKNESS = 6 * INCH
+BLOCK_LENGTH = 4 * FOOT
+BLOCK_WIDTH = 3 * FOOT
+BLOCK_HEIGHT = 2 * FOOT
+BASE_COLOR = (0.65, 0.65, 0.62)
+PRIMARY_COLOR = (0.25, 0.42, 0.58)
+ACCENT_COLOR = (0.12, 0.12, 0.12)
+
+
+@dataclass(frozen=True, slots=True)
+class ExportSettings:
+    step_schema_preference: str = "AP242"
+    glb_linear_deflection_mm: float = 0.5
+    glb_angular_deflection_rad: float = 0.25
+    include_reference_geometry_in_glb: bool = False
+    drawing_dimension_denominator: int = 16
+
+
+EXPORTS = ExportSettings()
+
+__all__ = [
+    "ACCENT_COLOR", "BASE_COLOR", "BASE_LENGTH", "BASE_THICKNESS", "BASE_WIDTH",
+    "BLOCK_HEIGHT", "BLOCK_LENGTH", "BLOCK_WIDTH", "EXPORTS", "FOOT", "INCH",
+    "Length", "MM", "PRIMARY_COLOR", "PROJECT_NAME",
+]

python_cad_tools/templates/project/drawing_annotations.py

@@ -0,0 +1,117 @@
+"""Project-owned drawing annotation intent derived from the shared model."""
+
+from __future__ import annotations
+
+from python_cad_tools.context import DrawingContext
+from python_cad_tools.drawings import (
+    DrawingAnnotationSet,
+    ElevationMarker,
+    Line,
+    Polyline,
+    SectionCallout,
+    SheetAnnotations,
+    Table,
+    TableRow,
+    Text,
+)
+
+
+def build_annotations(context: DrawingContext) -> DrawingAnnotationSet:
+    """Return renderer-independent annotations derived from the shared model."""
+    plan = next(sheet for sheet in context.sheets if sheet.sheet_id == "A-101")
+    min_x, min_y, max_x, max_y = plan.projected_bounds_mm
+    center_x = (min_x + max_x) / 2
+    center_y = (min_y + max_y) / 2
+    physical = [element for element in context.model.walk() if element.physical]
+    rows = tuple(
+        TableRow(
+            id=f"item-{index}",
+            cells=(
+                element.id,
+                _dimension(element.dimensions.length_mm),
+                _dimension(element.dimensions.width_mm),
+                _dimension(element.dimensions.height_mm),
+            ),
+        )
+        for index, element in enumerate(physical, start=1)
+    )
+    return DrawingAnnotationSet(
+        provider_id="generic.annotations.v1",
+        sheets=(
+            SheetAnnotations(
+                sheet_id="A-101",
+                annotations=(
+                    SectionCallout(
+                        id="generic.section.main",
+                        sheet_id="A-101",
+                        start=(center_x, min_y),
+                        end=(center_x, max_y),
+                        reference_sheet_id="A-301",
+                        label="Section A",
+                        view_direction="right",
+                    ),
+                    ElevationMarker(
+                        id="generic.elevation.front",
+                        sheet_id="A-101",
+                        position=(min_x + (max_x - min_x) * 0.2, center_y),
+                        reference_sheet_id="A-201",
+                        label="Front Elevation",
+                        direction="down",
+                    ),
+                    Table(
+                        id="generic.schedule.elements",
+                        sheet_id="A-101",
+                        position=(max_x + 120.0, center_y),
+                        title="Element Schedule",
+                        columns=("Stable ID", "Length mm", "Width mm", "Height mm"),
+                        rows=rows,
+                    ),
+                ),
+            ),
+            SheetAnnotations(
+                sheet_id="A-201",
+                annotations=(
+                    Line(
+                        id="generic.datum.front",
+                        sheet_id="A-201",
+                        start=(min_x, 0.0),
+                        end=(max_x, 0.0),
+                        style="annotation-line",
+                    ),
+                ),
+            ),
+            SheetAnnotations(
+                sheet_id="A-202",
+                annotations=(
+                    Polyline(
+                        id="generic.boundary.side",
+                        sheet_id="A-202",
+                        points=((min_y, 0.0), (max_y, 0.0), (max_y, 80.0)),
+                        closed=False,
+                        style="annotation-line",
+                    ),
+                ),
+            ),
+            SheetAnnotations(
+                sheet_id="A-301",
+                annotations=(
+                    Text(
+                        id="generic.note.section",
+                        sheet_id="A-301",
+                        position=(min_x, 100.0),
+                        value=f"Model: {context.model.name}",
+                        height_mm=12.0,
+                        rotation_degrees=0.0,
+                        style="annotation-text",
+                    ),
+                ),
+            ),
+        ),
+    )
+
+
+__all__ = ["build_annotations"]
+
+
+def _dimension(value: float | None) -> str:
+    return "not specified" if value is None else f"{value:g}"

python_cad_tools/templates/project/model.py

@@ -0,0 +1,87 @@
+"""Project-owned starter design source; this builds the shared model exactly once."""
+
+from __future__ import annotations
+
+import config as cfg
+
+from python_cad_tools.context import BuildContext
+from python_cad_tools.elements import (
+    DesignElement,
+    DesignModel,
+    Dimensions,
+    IfcMapping,
+    MaterialSpec,
+    Placement,
+)
+from python_cad_tools.geometry import bounds, box, reference_line
+from python_cad_tools.units import INCH, to_mm
+from python_cad_tools.validation import ValidationIssue
+
+
+def build_model(context: BuildContext) -> DesignModel:
+    base_material = MaterialSpec("material.starter.base", "Starter Base Material", "example", cfg.BASE_COLOR)
+    primary_material = MaterialSpec("material.starter.primary", "Starter Primary Material", "example", cfg.PRIMARY_COLOR)
+    block_x = (cfg.BASE_LENGTH - cfg.BLOCK_LENGTH) / 2
+    block_y = (cfg.BASE_WIDTH - cfg.BLOCK_WIDTH) / 2
+    block_z = cfg.BASE_THICKNESS
+    axis_x_z = cfg.BASE_THICKNESS + cfg.BLOCK_HEIGHT + 6 * INCH
+    axis_y_z = cfg.BASE_THICKNESS + cfg.BLOCK_HEIGHT + 10 * INCH
+    zero = 0 * cfg.MM
+    elements = [
+        DesignElement(
+            id="starter.base_plate", name="Base Plate", category="physical-example",
+            geometry=box(cfg.BASE_LENGTH, cfg.BASE_WIDTH, cfg.BASE_THICKNESS, origin=(zero, zero, zero)),
+            geometry_kind="solid", dimensions=Dimensions(to_mm(cfg.BASE_LENGTH), to_mm(cfg.BASE_WIDTH), to_mm(cfg.BASE_THICKNESS)),
+            material=base_material, color_rgb=cfg.BASE_COLOR,
+            ifc_mapping=IfcMapping("IfcBuildingElementProxy", "NOTDEFINED"), storey="Default Storey",
+            tags={"starter", "physical"}, properties={"quantity_provenance": "exact_geometry"},
+        ),
+        DesignElement(
+            id="starter.primary_block", name="Primary Block", category="physical-example",
+            geometry=box(cfg.BLOCK_LENGTH, cfg.BLOCK_WIDTH, cfg.BLOCK_HEIGHT, origin=(block_x, block_y, block_z)),
+            geometry_kind="solid", placement=Placement((to_mm(block_x), to_mm(block_y), to_mm(block_z))),
+            dimensions=Dimensions(to_mm(cfg.BLOCK_LENGTH), to_mm(cfg.BLOCK_WIDTH), to_mm(cfg.BLOCK_HEIGHT)),
+            material=primary_material, color_rgb=cfg.PRIMARY_COLOR,
+            ifc_mapping=IfcMapping("IfcBuildingElementProxy", "NOTDEFINED"), storey="Default Storey",
+            tags={"starter", "physical"}, properties={"quantity_provenance": "exact_geometry"},
+        ),
+        DesignElement(
+            id="reference.axis_x", name="X Reference Axis", category="reference-axis",
+            geometry=reference_line((zero, cfg.BASE_WIDTH / 2, axis_x_z), (cfg.BASE_LENGTH, cfg.BASE_WIDTH / 2, axis_x_z)),
+            geometry_kind="reference", placement=Placement((0.0, to_mm(cfg.BASE_WIDTH / 2), to_mm(axis_x_z))),
+            dimensions=Dimensions(length_mm=to_mm(cfg.BASE_LENGTH), radius_mm=to_mm(0.75 * INCH)),
+            color_rgb=cfg.ACCENT_COLOR, ifc_mapping=IfcMapping(None, exclude_reason="non-physical reference geometry"),
+            tags={"starter", "reference", "axis-x"}, export_formats={"drawings"}, physical=False,
+        ),
+        DesignElement(
+            id="reference.axis_y", name="Y Reference Axis", category="reference-axis",
+            geometry=reference_line((cfg.BASE_LENGTH / 2, zero, axis_y_z), (cfg.BASE_LENGTH / 2, cfg.BASE_WIDTH, axis_y_z)),
+            geometry_kind="reference", placement=Placement((to_mm(cfg.BASE_LENGTH / 2), 0.0, to_mm(axis_y_z))),
+            dimensions=Dimensions(length_mm=to_mm(cfg.BASE_WIDTH), radius_mm=to_mm(0.75 * INCH)),
+            color_rgb=cfg.ACCENT_COLOR, ifc_mapping=IfcMapping(None, exclude_reason="non-physical reference geometry"),
+            tags={"starter", "reference", "axis-y"}, export_formats={"drawings"}, physical=False,
+        ),
+    ]
+    return DesignModel(
+        id="starter.project_model", name=cfg.PROJECT_NAME, artifact_stem="starter_project", elements=elements,
+        metadata={"fixture": "generic starter scaffold", "authoritative_source": "model.py"}, validators=[_validate_starter],
+    )
+
+
+def _validate_starter(model: DesignModel) -> list[ValidationIssue]:
+    base = model.get("starter.base_plate")
+    block = model.get("starter.primary_block")
+    base_bounds = bounds(base.geometry)
+    block_bounds = bounds(block.geometry)
+    checks = {
+        "block-centered-x": abs(block_bounds[0] - (to_mm(cfg.BASE_LENGTH) - to_mm(cfg.BLOCK_LENGTH)) / 2) <= 1e-6,
+        "block-centered-y": abs(block_bounds[1] - (to_mm(cfg.BASE_WIDTH) - to_mm(cfg.BLOCK_WIDTH)) / 2) <= 1e-6,
+        "block-rests-on-base": abs(block_bounds[2] - base_bounds[5]) <= 1e-6,
+        "base-color": base.color_rgb == cfg.BASE_COLOR,
+        "block-color": block.color_rgb == cfg.PRIMARY_COLOR,
+        "reference-not-physical": all(not model.get(stable_id).physical for stable_id in ("reference.axis_x", "reference.axis_y")),
+    }
+    return [
+        ValidationIssue(f"starter-{code}", "error", f"Starter invariant failed: {code}")
+        for code, passed in checks.items() if not passed
+    ]

python_cad_tools/templates/project/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-cad-design"
+version = "0.1.0"
+requires-python = ">=3.12,<3.14"
+dependencies = [
+  "python-cad-tools==0.1.0rc1",
+]
+
+[tool.python-cad]
+schema-version = 1
+config = "config"
+model = "model:build_model"
+drawing-annotations = "drawing_annotations:build_annotations"
+source-inputs = ["pyproject.toml", "config.py", "model.py", "drawing_annotations.py"]
+output-directory = "generated"
+default-formats = ["step", "ifc", "glb", "drawings", "quantities"]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["model.py", "config.py"]
+ignore_missing_imports = true
+check_untyped_defs = true
+warn_unused_ignores = true

python_cad_tools/units.py

@@ -0,0 +1,207 @@
+"""Dimension-safe unit types; the geometry kernel boundary is millimetres."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import overload
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Length:
+    mm: float
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.mm, (int, float)) or not isfinite(self.mm):
+            raise ValueError("Length requires a finite numeric millimetre value")
+
+    @overload
+    def __mul__(self, other: float) -> Length: ...
+
+    @overload
+    def __mul__(self, other: Length) -> Area: ...
+
+    def __mul__(self, other: float | Length) -> Length | Area:
+        if isinstance(other, Length):
+            return Area(self.mm * other.mm)
+        if isinstance(other, (int, float)):
+            return Length(self.mm * other)
+        return NotImplemented
+
+    def __rmul__(self, other: float) -> Length:
+        return Length(self.mm * other)
+
+    @overload
+    def __truediv__(self, other: float) -> Length: ...
+
+    @overload
+    def __truediv__(self, other: Length) -> float: ...
+
+    def __truediv__(self, other: float | Length) -> Length | float:
+        if isinstance(other, Length):
+            return self.mm / other.mm
+        if isinstance(other, (int, float)):
+            return Length(self.mm / other)
+        return NotImplemented
+
+    def __add__(self, other: Length) -> Length:
+        if not isinstance(other, Length):
+            return NotImplemented
+        return Length(self.mm + other.mm)
+
+    def __sub__(self, other: Length) -> Length:
+        if not isinstance(other, Length):
+            return NotImplemented
+        return Length(self.mm - other.mm)
+
+    def __neg__(self) -> Length:
+        return Length(-self.mm)
+
+    def __abs__(self) -> Length:
+        return Length(abs(self.mm))
+
+    def __float__(self) -> float:
+        raise TypeError("Use to_mm(length) for an explicit kernel conversion")
+
+
+@dataclass(frozen=True, slots=True)
+class Area:
+    mm2: float
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.mm2, (int, float)) or not isfinite(self.mm2):
+            raise ValueError("Area requires a finite numeric square-millimetre value")
+
+    @overload
+    def __mul__(self, other: float) -> Area: ...
+
+    @overload
+    def __mul__(self, other: Length) -> Volume: ...
+
+    def __mul__(self, other: float | Length) -> Area | Volume:
+        if isinstance(other, Length):
+            return Volume(self.mm2 * other.mm)
+        if isinstance(other, (int, float)):
+            return Area(self.mm2 * other)
+        return NotImplemented
+
+    def __rmul__(self, other: float) -> Area:
+        return Area(self.mm2 * other)
+
+
+@dataclass(frozen=True, slots=True)
+class Volume:
+    mm3: float
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.mm3, (int, float)) or not isfinite(self.mm3):
+            raise ValueError("Volume requires a finite numeric cubic-millimetre value")
+
+    def __mul__(self, other: float) -> Volume:
+        if not isinstance(other, (int, float)):
+            return NotImplemented
+        return Volume(self.mm3 * other)
+
+    __rmul__ = __mul__
+
+
+MM = Length(1.0)
+INCH = Length(25.4)
+FOOT = 12 * INCH
+
+
+def to_mm(value: Length) -> float:
+    if not isinstance(value, Length):
+        raise TypeError(f"Expected Length, got {type(value).__name__}")
+    return float(value.mm)
+
+
+def mm(value: float) -> Length:
+    return value * MM
+
+
+def inches(value: float) -> Length:
+    return value * INCH
+
+
+def feet(value: float) -> Length:
+    return value * FOOT
+
+
+def feet_inches(feet_value: float, inches_value: float = 0) -> Length:
+    return feet_value * FOOT + inches_value * INCH
+
+
+def square_feet(value: Area) -> float:
+    if not isinstance(value, Area):
+        raise TypeError("square_feet expects Area")
+    return value.mm2 / (304.8**2)
+
+
+def cubic_feet(value: Volume) -> float:
+    if not isinstance(value, Volume):
+        raise TypeError("cubic_feet expects Volume")
+    return value.mm3 / (304.8**3)
+
+
+def cubic_yards(value: Volume) -> float:
+    if not isinstance(value, Volume):
+        raise TypeError("cubic_yards expects Volume")
+    return value.mm3 / (914.4**3)
+
+
+def metres(value: Length) -> float:
+    return to_mm(value) / 1000.0
+
+
+def square_metres(value: Area) -> float:
+    if not isinstance(value, Area):
+        raise TypeError("square_metres expects Area")
+    return value.mm2 / 1_000_000.0
+
+
+def cubic_metres(value: Volume) -> float:
+    if not isinstance(value, Volume):
+        raise TypeError("cubic_metres expects Volume")
+    return value.mm3 / 1_000_000_000.0
+
+
+def format_feet_inches(length_mm: float, denominator: int = 16) -> str:
+    total_inches = length_mm / 25.4
+    feet_part = int(total_inches // 12)
+    inches_part = total_inches - feet_part * 12
+    rounded = round(inches_part * denominator) / denominator
+    if rounded >= 12:
+        feet_part += 1
+        rounded = 0
+    whole = int(rounded)
+    fraction = rounded - whole
+    if fraction:
+        numerator = round(fraction * denominator)
+        from math import gcd
+
+        divisor = gcd(numerator, denominator)
+        inch_text = f"{whole} {numerator // divisor}/{denominator // divisor}"
+    else:
+        inch_text = str(whole)
+    return f"{feet_part}'-{inch_text}\""
+
+
+__all__ = [
+    "Area",
+    "FOOT",
+    "INCH",
+    "Length",
+    "MM",
+    "Volume",
+    "cubic_feet",
+    "cubic_yards",
+    "feet",
+    "feet_inches",
+    "inches",
+    "metres",
+    "mm",
+    "square_feet",
+    "square_metres",
+    "to_mm",
+]

python_cad_tools/validation.py

@@ -0,0 +1,153 @@
+"""Public validation issue type and shared-model contract validation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from math import isfinite
+from typing import Literal
+
+from .elements import DesignElement, DesignModel, MaterialSpec
+from .geometry import is_valid_solid
+
+_ARTIFACT_STEM = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z", re.ASCII)
+_RESERVED_STEMS = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{number}" for number in range(1, 10)),
+    *(f"LPT{number}" for number in range(1, 10)),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationIssue:
+    code: str
+    severity: Literal["warning", "error"]
+    message: str
+    source_path: str | None = None
+    element_id: str | None = None
+
+
+def validate_model(model: DesignModel) -> list[ValidationIssue]:
+    issues: list[ValidationIssue] = []
+    if not model.id:
+        issues.append(ValidationIssue("model-id", "error", "Model ID must be nonempty"))
+    if not model.name:
+        issues.append(ValidationIssue("model-name", "error", "Model display name must be nonempty"))
+    if not valid_artifact_stem(model.artifact_stem):
+        issues.append(ValidationIssue("artifact-stem", "error", "Model artifact_stem is not a safe portable filename stem"))
+
+    walked = list(model.walk())
+    known = {element.id for element in walked}
+    seen_ids: set[str] = set()
+    seen_instances: set[int] = set()
+    for element in walked:
+        issues.extend(_validate_element(element, seen_ids, seen_instances, known))
+    for validator in model.validators:
+        issues.extend(validator(model))
+    return sorted(issues, key=lambda issue: (issue.severity, issue.code, issue.source_path or "", issue.element_id or ""))
+
+
+def valid_artifact_stem(value: str) -> bool:
+    if not isinstance(value, str) or value in {".", ".."} or _ARTIFACT_STEM.fullmatch(value) is None:
+        return False
+    device = value.split(".", 1)[0].upper()
+    return device not in _RESERVED_STEMS
+
+
+def _validate_element(
+    element: DesignElement,
+    seen_ids: set[str],
+    seen_instances: set[int],
+    known: set[str],
+) -> list[ValidationIssue]:
+    issues: list[ValidationIssue] = []
+    instance_id = id(element)
+    if instance_id in seen_instances:
+        issues.append(ValidationIssue("shared-element", "error", "Element instances must not be shared", element_id=element.id))
+    seen_instances.add(instance_id)
+    if not element.id or element.id in seen_ids:
+        issues.append(ValidationIssue("stable-id", "error", "Stable IDs must be nonempty and unique", element_id=element.id or None))
+    seen_ids.add(element.id)
+    if not element.name:
+        issues.append(ValidationIssue("element-name", "error", "Element display names must be nonempty", element_id=element.id))
+    values = (*element.placement.translation_mm, *element.placement.rotation_deg_xyz)
+    if not all(isfinite(value) for value in values):
+        issues.append(ValidationIssue("placement", "error", "Placement values must be finite", element_id=element.id))
+    if element.geometry is None:
+        issues.append(ValidationIssue("geometry-missing", "error", "Geometry must be present", element_id=element.id))
+    if element.physical and element.geometry_kind != "solid":
+        issues.append(ValidationIssue("physical-kind", "error", "Physical elements must be solids", element_id=element.id))
+    if element.physical and element.geometry is not None and not is_valid_solid(element.geometry):
+        issues.append(
+            ValidationIssue("solid-invalid", "error", "Physical geometry must be a valid positive-volume solid", element_id=element.id)
+        )
+    if not element.physical and element.geometry_kind == "solid":
+        issues.append(
+            ValidationIssue(
+                "reference-solid",
+                "warning",
+                "Non-physical reference geometry is represented as a solid",
+                element_id=element.id,
+            )
+        )
+    if any(value <= 0 or not isfinite(value) for value in element.dimensions.values()):
+        issues.append(
+            ValidationIssue("dimensions", "error", "Declared dimensions must be finite and positive", element_id=element.id)
+        )
+    if element.physical and element.material is None:
+        issues.append(ValidationIssue("material", "error", "Physical elements require a material", element_id=element.id))
+    if element.material is not None:
+        issues.extend(_validate_material(element.material, element.id))
+    color = element.color_rgb
+    if color is not None and not _valid_color(color):
+        issues.append(ValidationIssue("color", "error", "Colors must contain three finite values in [0, 1]", element_id=element.id))
+    mapping = element.ifc_mapping
+    mapped = isinstance(mapping.ifc_class, str) and bool(mapping.ifc_class.strip())
+    excluded = isinstance(mapping.exclude_reason, str) and bool(mapping.exclude_reason.strip())
+    if mapped == excluded:
+        issues.append(
+            ValidationIssue(
+                "ifc-intent",
+                "error",
+                "IFC intent must contain exactly one mapping class or exclusion reason",
+                element_id=element.id,
+            )
+        )
+    if element.parent_id is not None and element.parent_id not in known:
+        issues.append(ValidationIssue("parent", "error", f"Unknown parent ID: {element.parent_id}", element_id=element.id))
+    return issues
+
+
+def _validate_material(material: MaterialSpec, element_id: str) -> list[ValidationIssue]:
+    issues: list[ValidationIssue] = []
+    if not material.id or not material.name or not material.category:
+        issues.append(
+            ValidationIssue("material-fields", "error", "Material ID, name, and category must be nonempty", element_id=element_id)
+        )
+    if not _valid_color(material.color_rgb):
+        issues.append(
+            ValidationIssue("material-color", "error", "Material color must contain three finite values in [0, 1]", element_id=element_id)
+        )
+    if material.density_kg_m3 is not None and (not isfinite(material.density_kg_m3) or material.density_kg_m3 <= 0):
+        issues.append(
+            ValidationIssue("material-density", "error", "Material density must be finite and positive", element_id=element_id)
+        )
+    return issues
+
+
+def _valid_color(color: object) -> bool:
+    return (
+        isinstance(color, tuple)
+        and len(color) == 3
+        and all(isinstance(value, (int, float)) and isfinite(value) and 0 <= value <= 1 for value in color)
+    )
+
+
+def fatal_issues(issues: list[ValidationIssue] | tuple[ValidationIssue, ...]) -> list[ValidationIssue]:
+    return [issue for issue in issues if issue.severity == "error"]
+
+
+__all__ = ["ValidationIssue"]