Geometry

Built-in 3D geometry primitives for surface area calculations, zone volume estimation, and coordinate transforms -- no external geometry dependencies required.

Geometry utilities for IDF models.

Provides coordinate handling and transformations without geomeppy dependency.

Polygon2D = list[tuple[float, float]] module-attribute

VERTEX_SURFACE_TYPES = ['BuildingSurface:Detailed', 'FenestrationSurface:Detailed', 'Shading:Site:Detailed', 'Shading:Building:Detailed', 'Shading:Zone:Detailed'] module-attribute

logger = logging.getLogger(__name__) module-attribute

Polygon3D dataclass

3D polygon defined by vertices.

Computes geometric properties (area, normal, tilt, azimuth) and supports transformations (translate, rotate).

Examples:

A 5 m x 4 m ground-floor slab:

>>> floor = Polygon3D([
...     Vector3D(0, 0, 0), Vector3D(5, 0, 0),
...     Vector3D(5, 4, 0), Vector3D(0, 4, 0),
... ])
>>> floor.area
20.0
>>> floor.is_horizontal
True

A 10 m wide, 3 m high south-facing exterior wall:

>>> south_wall = Polygon3D([
...     Vector3D(0, 0, 0), Vector3D(10, 0, 0),
...     Vector3D(10, 0, 3), Vector3D(0, 0, 3),
... ])
>>> south_wall.area
30.0
>>> south_wall.tilt
90.0
>>> south_wall.azimuth
180.0

Source code in idfkit/geometry.py

@dataclass
class Polygon3D:
    """
    3D polygon defined by vertices.

    Computes geometric properties (area, normal, tilt, azimuth) and supports
    transformations (translate, rotate).

    Examples:
        A 5 m x 4 m ground-floor slab:

        >>> floor = Polygon3D([
        ...     Vector3D(0, 0, 0), Vector3D(5, 0, 0),
        ...     Vector3D(5, 4, 0), Vector3D(0, 4, 0),
        ... ])
        >>> floor.area
        20.0
        >>> floor.is_horizontal
        True

        A 10 m wide, 3 m high south-facing exterior wall:

        >>> south_wall = Polygon3D([
        ...     Vector3D(0, 0, 0), Vector3D(10, 0, 0),
        ...     Vector3D(10, 0, 3), Vector3D(0, 0, 3),
        ... ])
        >>> south_wall.area
        30.0
        >>> south_wall.tilt
        90.0
        >>> south_wall.azimuth
        180.0
    """

    vertices: list[Vector3D]

    @property
    def num_vertices(self) -> int:
        """Number of vertices.

        Examples:
            >>> Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)]).num_vertices
            3
        """
        return len(self.vertices)

    @property
    def normal(self) -> Vector3D:
        """Surface normal vector.

        Examples:
            >>> floor = Polygon3D([
            ...     Vector3D(0, 0, 0), Vector3D(1, 0, 0),
            ...     Vector3D(1, 1, 0), Vector3D(0, 1, 0),
            ... ])
            >>> floor.normal
            Vector3D(x=0.0, y=0.0, z=1.0)
        """
        if self.num_vertices < 3:
            return Vector3D(0, 0, 1)

        # Use Newell's method for robustness
        n = Vector3D(0, 0, 0)
        for i in range(self.num_vertices):
            v1 = self.vertices[i]
            v2 = self.vertices[(i + 1) % self.num_vertices]
            n = Vector3D(
                n.x + (v1.y - v2.y) * (v1.z + v2.z),
                n.y + (v1.z - v2.z) * (v1.x + v2.x),
                n.z + (v1.x - v2.x) * (v1.y + v2.y),
            )
        return n.normalize()

    @property
    def area(self) -> float:
        """Surface area using cross product method.

        Examples:
            A 5 m x 5 m floor slab:

            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(5,0,0),
            ...     Vector3D(5,5,0), Vector3D(0,5,0),
            ... ]).area
            25.0
        """
        if self.num_vertices < 3:
            return 0.0

        # Triangulate and sum areas
        total = Vector3D(0, 0, 0)
        v0 = self.vertices[0]

        for i in range(1, self.num_vertices - 1):
            v1 = self.vertices[i]
            v2 = self.vertices[i + 1]
            edge1 = v1 - v0
            edge2 = v2 - v0
            cross = edge1.cross(edge2)
            total = total + cross

        return total.length() / 2.0

    @property
    def centroid(self) -> Vector3D:
        """Geometric center.

        Examples:
            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(4,0,0),
            ...     Vector3D(4,4,0), Vector3D(0,4,0),
            ... ]).centroid
            Vector3D(x=2.0, y=2.0, z=0.0)
        """
        if not self.vertices:
            return Vector3D.origin()

        x = sum(v.x for v in self.vertices) / self.num_vertices
        y = sum(v.y for v in self.vertices) / self.num_vertices
        z = sum(v.z for v in self.vertices) / self.num_vertices
        return Vector3D(x, y, z)

    @property
    def tilt(self) -> float:
        """Surface tilt angle in degrees.

        0 = facing up (horizontal roof/ceiling), 90 = vertical wall,
        180 = facing down (horizontal floor).  Computed from the surface
        normal using the same convention as EnergyPlus / eppy.

        Examples:
            Flat roof (tilt 0 = facing up):

            >>> Polygon3D([
            ...     Vector3D(0,0,3), Vector3D(5,0,3),
            ...     Vector3D(5,5,3), Vector3D(0,5,3),
            ... ]).tilt
            0.0

            Exterior wall (tilt 90 = vertical):

            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(10,0,0),
            ...     Vector3D(10,0,3), Vector3D(0,0,3),
            ... ]).tilt
            90.0
        """
        n = self.normal
        # Clamp to avoid floating-point issues with acos
        clamped = max(-1.0, min(1.0, n.z))
        return math.degrees(math.acos(clamped))

    @property
    def azimuth(self) -> float:
        """Surface azimuth in degrees (0=north, 90=east, 180=south, 270=west).

        Uses the same convention as EnergyPlus / eppy: the angle of the
        outward normal projected onto the horizontal plane, measured
        clockwise from north (+Y axis).

        Returns 0.0 for perfectly horizontal surfaces (tilt 0 or 180).

        Examples:
            South-facing wall (normal points toward -Y):

            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(10,0,0),
            ...     Vector3D(10,0,3), Vector3D(0,0,3),
            ... ]).azimuth
            180.0

            Horizontal surface has azimuth 0:

            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(1,0,0),
            ...     Vector3D(1,1,0), Vector3D(0,1,0),
            ... ]).azimuth
            0.0
        """
        n = self.normal
        # For horizontal surfaces the azimuth is undefined
        if abs(n.x) < 1e-10 and abs(n.y) < 1e-10:
            return 0.0
        # atan2(x, y) gives the angle from +Y axis toward +X axis,
        # which is clockwise from north -- exactly the convention we need.
        angle = math.degrees(math.atan2(n.x, n.y))
        if angle < 0:
            angle += 360.0
        return angle

    @property
    def is_horizontal(self) -> bool:
        """Check if polygon is horizontal (floor/ceiling).

        Examples:
            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(1,0,0),
            ...     Vector3D(1,1,0), Vector3D(0,1,0),
            ... ]).is_horizontal
            True
            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(1,0,0),
            ...     Vector3D(1,0,1), Vector3D(0,0,1),
            ... ]).is_horizontal
            False
        """
        n = self.normal
        return abs(n.z) > 0.99

    @property
    def is_vertical(self) -> bool:
        """Check if polygon is vertical (wall).

        Examples:
            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(1,0,0),
            ...     Vector3D(1,0,1), Vector3D(0,0,1),
            ... ]).is_vertical
            True
            >>> Polygon3D([
            ...     Vector3D(0,0,0), Vector3D(1,0,0),
            ...     Vector3D(1,1,0), Vector3D(0,1,0),
            ... ]).is_vertical
            False
        """
        n = self.normal
        return abs(n.z) < 0.01

    def translate(self, offset: Vector3D) -> Polygon3D:
        """Return translated polygon.

        Examples:
            >>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
            >>> moved = tri.translate(Vector3D(10, 20, 0))
            >>> moved.centroid
            Vector3D(x=10.333333333333334, y=20.333333333333332, z=0.0)
        """
        return Polygon3D([v + offset for v in self.vertices])

    def rotate_z(self, angle_deg: float, anchor: Vector3D | None = None) -> Polygon3D:
        """Rotate around Z axis."""
        if anchor is None:
            anchor = self.centroid

        rotated: list[Vector3D] = []
        for v in self.vertices:
            # Translate to anchor, rotate, translate back
            relative = v - anchor
            rotated_rel = relative.rotate_z(angle_deg)
            rotated.append(rotated_rel + anchor)

        return Polygon3D(rotated)

    def as_tuple_list(self) -> list[tuple[float, float, float]]:
        """Return vertices as list of tuples.

        Examples:
            >>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
            >>> tri.as_tuple_list()
            [(0, 0, 0), (1, 0, 0), (0, 1, 0)]
        """
        return [v.as_tuple() for v in self.vertices]

    @classmethod
    def from_tuples(cls, coords: Sequence[Sequence[float]]) -> Polygon3D:
        """Create from sequence of coordinate tuples.

        Examples:
            >>> poly = Polygon3D.from_tuples([(0,0,0), (5,0,0), (5,5,0), (0,5,0)])
            >>> poly.area
            25.0
            >>> poly.num_vertices
            4
        """
        return cls([Vector3D.from_tuple(c) for c in coords])

area property

Surface area using cross product method.

Examples:

A 5 m x 5 m floor slab:

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(5,0,0),
...     Vector3D(5,5,0), Vector3D(0,5,0),
... ]).area
25.0

azimuth property

Surface azimuth in degrees (0=north, 90=east, 180=south, 270=west).

Uses the same convention as EnergyPlus / eppy: the angle of the outward normal projected onto the horizontal plane, measured clockwise from north (+Y axis).

Returns 0.0 for perfectly horizontal surfaces (tilt 0 or 180).

Examples:

South-facing wall (normal points toward -Y):

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(10,0,0),
...     Vector3D(10,0,3), Vector3D(0,0,3),
... ]).azimuth
180.0

Horizontal surface has azimuth 0:

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(1,0,0),
...     Vector3D(1,1,0), Vector3D(0,1,0),
... ]).azimuth
0.0

centroid property

Geometric center.

Examples:

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(4,0,0),
...     Vector3D(4,4,0), Vector3D(0,4,0),
... ]).centroid
Vector3D(x=2.0, y=2.0, z=0.0)

is_horizontal property

Check if polygon is horizontal (floor/ceiling).

Examples:

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(1,0,0),
...     Vector3D(1,1,0), Vector3D(0,1,0),
... ]).is_horizontal
True
>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(1,0,0),
...     Vector3D(1,0,1), Vector3D(0,0,1),
... ]).is_horizontal
False

is_vertical property

Check if polygon is vertical (wall).

Examples:

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(1,0,0),
...     Vector3D(1,0,1), Vector3D(0,0,1),
... ]).is_vertical
True
>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(1,0,0),
...     Vector3D(1,1,0), Vector3D(0,1,0),
... ]).is_vertical
False

normal property

Surface normal vector.

Examples:

>>> floor = Polygon3D([
...     Vector3D(0, 0, 0), Vector3D(1, 0, 0),
...     Vector3D(1, 1, 0), Vector3D(0, 1, 0),
... ])
>>> floor.normal
Vector3D(x=0.0, y=0.0, z=1.0)

num_vertices property

Number of vertices.

Examples:

>>> Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)]).num_vertices
3

tilt property

Surface tilt angle in degrees.

0 = facing up (horizontal roof/ceiling), 90 = vertical wall, 180 = facing down (horizontal floor). Computed from the surface normal using the same convention as EnergyPlus / eppy.

Examples:

Flat roof (tilt 0 = facing up):

>>> Polygon3D([
...     Vector3D(0,0,3), Vector3D(5,0,3),
...     Vector3D(5,5,3), Vector3D(0,5,3),
... ]).tilt
0.0

Exterior wall (tilt 90 = vertical):

>>> Polygon3D([
...     Vector3D(0,0,0), Vector3D(10,0,0),
...     Vector3D(10,0,3), Vector3D(0,0,3),
... ]).tilt
90.0

vertices instance-attribute

as_tuple_list()

Return vertices as list of tuples.

Examples:

>>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
>>> tri.as_tuple_list()
[(0, 0, 0), (1, 0, 0), (0, 1, 0)]

Source code in idfkit/geometry.py

def as_tuple_list(self) -> list[tuple[float, float, float]]:
    """Return vertices as list of tuples.

    Examples:
        >>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
        >>> tri.as_tuple_list()
        [(0, 0, 0), (1, 0, 0), (0, 1, 0)]
    """
    return [v.as_tuple() for v in self.vertices]

from_tuples(coords) classmethod

Create from sequence of coordinate tuples.

Examples:

>>> poly = Polygon3D.from_tuples([(0,0,0), (5,0,0), (5,5,0), (0,5,0)])
>>> poly.area
25.0
>>> poly.num_vertices
4

Source code in idfkit/geometry.py

@classmethod
def from_tuples(cls, coords: Sequence[Sequence[float]]) -> Polygon3D:
    """Create from sequence of coordinate tuples.

    Examples:
        >>> poly = Polygon3D.from_tuples([(0,0,0), (5,0,0), (5,5,0), (0,5,0)])
        >>> poly.area
        25.0
        >>> poly.num_vertices
        4
    """
    return cls([Vector3D.from_tuple(c) for c in coords])

rotate_z(angle_deg, anchor=None)

Rotate around Z axis.

Source code in idfkit/geometry.py

def rotate_z(self, angle_deg: float, anchor: Vector3D | None = None) -> Polygon3D:
    """Rotate around Z axis."""
    if anchor is None:
        anchor = self.centroid

    rotated: list[Vector3D] = []
    for v in self.vertices:
        # Translate to anchor, rotate, translate back
        relative = v - anchor
        rotated_rel = relative.rotate_z(angle_deg)
        rotated.append(rotated_rel + anchor)

    return Polygon3D(rotated)

translate(offset)

Return translated polygon.

Examples:

>>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
>>> moved = tri.translate(Vector3D(10, 20, 0))
>>> moved.centroid
Vector3D(x=10.333333333333334, y=20.333333333333332, z=0.0)

Source code in idfkit/geometry.py

def translate(self, offset: Vector3D) -> Polygon3D:
    """Return translated polygon.

    Examples:
        >>> tri = Polygon3D([Vector3D(0,0,0), Vector3D(1,0,0), Vector3D(0,1,0)])
        >>> moved = tri.translate(Vector3D(10, 20, 0))
        >>> moved.centroid
        Vector3D(x=10.333333333333334, y=20.333333333333332, z=0.0)
    """
    return Polygon3D([v + offset for v in self.vertices])

Vector3D dataclass

Immutable 3D vector.

Supports arithmetic operations (+, -, *, /, unary -) and common vector operations (dot product, cross product, normalization).

Examples:

>>> v = Vector3D(1.0, 2.0, 3.0)
>>> v.x, v.y, v.z
(1.0, 2.0, 3.0)

Vectors support arithmetic:

>>> Vector3D(1, 2, 3) + Vector3D(4, 5, 6)
Vector3D(x=5, y=7, z=9)
>>> Vector3D(3, 0, 0) * 2
Vector3D(x=6, y=0, z=0)
>>> -Vector3D(1, 0, 0)
Vector3D(x=-1, y=0, z=0)

Source code in idfkit/geometry.py

@dataclass(frozen=True, slots=True)
class Vector3D:
    """
    Immutable 3D vector.

    Supports arithmetic operations (``+``, ``-``, ``*``, ``/``, unary ``-``)
    and common vector operations (dot product, cross product, normalization).

    Examples:
        >>> v = Vector3D(1.0, 2.0, 3.0)
        >>> v.x, v.y, v.z
        (1.0, 2.0, 3.0)

        Vectors support arithmetic:

        >>> Vector3D(1, 2, 3) + Vector3D(4, 5, 6)
        Vector3D(x=5, y=7, z=9)
        >>> Vector3D(3, 0, 0) * 2
        Vector3D(x=6, y=0, z=0)
        >>> -Vector3D(1, 0, 0)
        Vector3D(x=-1, y=0, z=0)
    """

    x: float
    y: float
    z: float

    def __add__(self, other: Vector3D) -> Vector3D:
        return Vector3D(self.x + other.x, self.y + other.y, self.z + other.z)

    def __sub__(self, other: Vector3D) -> Vector3D:
        return Vector3D(self.x - other.x, self.y - other.y, self.z - other.z)

    def __mul__(self, scalar: float) -> Vector3D:
        return Vector3D(self.x * scalar, self.y * scalar, self.z * scalar)

    def __rmul__(self, scalar: float) -> Vector3D:
        return self * scalar

    def __truediv__(self, scalar: float) -> Vector3D:
        return Vector3D(self.x / scalar, self.y / scalar, self.z / scalar)

    def __neg__(self) -> Vector3D:
        return Vector3D(-self.x, -self.y, -self.z)

    def dot(self, other: Vector3D) -> float:
        """Dot product.

        Examples:
            >>> Vector3D(1, 0, 0).dot(Vector3D(0, 1, 0))
            0
            >>> Vector3D(3.0, 0.0, 0.0).dot(Vector3D(4.0, 0.0, 0.0))
            12.0
        """
        return self.x * other.x + self.y * other.y + self.z * other.z

    def cross(self, other: Vector3D) -> Vector3D:
        """Cross product.

        Examples:
            >>> Vector3D(1, 0, 0).cross(Vector3D(0, 1, 0))
            Vector3D(x=0, y=0, z=1)
            >>> Vector3D(3, 0, 0).cross(Vector3D(0, 4, 0))
            Vector3D(x=0, y=0, z=12)
        """
        return Vector3D(
            self.y * other.z - self.z * other.y,
            self.z * other.x - self.x * other.z,
            self.x * other.y - self.y * other.x,
        )

    def length(self) -> float:
        """Vector magnitude.

        Examples:
            >>> Vector3D(3, 4, 0).length()
            5.0
            >>> Vector3D(1, 0, 0).length()
            1.0
        """
        return math.hypot(self.x, self.y, self.z)

    def normalize(self) -> Vector3D:
        """Return unit vector.

        Examples:
            >>> Vector3D(3, 0, 0).normalize()
            Vector3D(x=1.0, y=0.0, z=0.0)
            >>> Vector3D(0, 0, 5).normalize()
            Vector3D(x=0.0, y=0.0, z=1.0)
        """
        mag = self.length()
        if mag == 0:
            return Vector3D(0, 0, 0)
        return self / mag

    def rotate_z(self, angle_deg: float) -> Vector3D:
        """Rotate around Z axis by angle in degrees.

        Examples:
            >>> v = Vector3D(1, 0, 0).rotate_z(90)
            >>> round(v.x, 10), round(v.y, 10)
            (0.0, 1.0)
            >>> Vector3D(1, 0, 5).rotate_z(180)  # doctest: +SKIP
            Vector3D(x=-1.0, y=0.0, z=5.0)
        """
        angle_rad = math.radians(angle_deg)
        cos_a = math.cos(angle_rad)
        sin_a = math.sin(angle_rad)
        return Vector3D(
            self.x * cos_a - self.y * sin_a,
            self.x * sin_a + self.y * cos_a,
            self.z,
        )

    def as_tuple(self) -> tuple[float, float, float]:
        """Return as tuple.

        Examples:
            >>> Vector3D(1.0, 2.0, 3.0).as_tuple()
            (1.0, 2.0, 3.0)
            >>> Vector3D.origin().as_tuple()
            (0.0, 0.0, 0.0)
        """
        return (self.x, self.y, self.z)

    @classmethod
    def from_tuple(cls, t: Sequence[float]) -> Vector3D:
        """Create from tuple or list.

        Examples:
            >>> Vector3D.from_tuple((1.0, 2.0, 3.0))
            Vector3D(x=1.0, y=2.0, z=3.0)
            >>> Vector3D.from_tuple([0, 0, 0])
            Vector3D(x=0.0, y=0.0, z=0.0)
        """
        return cls(float(t[0]), float(t[1]), float(t[2]))

    @classmethod
    def origin(cls) -> Vector3D:
        """Return origin vector.

        Examples:
            >>> Vector3D.origin()
            Vector3D(x=0.0, y=0.0, z=0.0)
        """
        return cls(0.0, 0.0, 0.0)

x instance-attribute

y instance-attribute

z instance-attribute

as_tuple()

Return as tuple.

Examples:

>>> Vector3D(1.0, 2.0, 3.0).as_tuple()
(1.0, 2.0, 3.0)
>>> Vector3D.origin().as_tuple()
(0.0, 0.0, 0.0)

Source code in idfkit/geometry.py

def as_tuple(self) -> tuple[float, float, float]:
    """Return as tuple.

    Examples:
        >>> Vector3D(1.0, 2.0, 3.0).as_tuple()
        (1.0, 2.0, 3.0)
        >>> Vector3D.origin().as_tuple()
        (0.0, 0.0, 0.0)
    """
    return (self.x, self.y, self.z)

cross(other)

Cross product.

Examples:

>>> Vector3D(1, 0, 0).cross(Vector3D(0, 1, 0))
Vector3D(x=0, y=0, z=1)
>>> Vector3D(3, 0, 0).cross(Vector3D(0, 4, 0))
Vector3D(x=0, y=0, z=12)

Source code in idfkit/geometry.py

def cross(self, other: Vector3D) -> Vector3D:
    """Cross product.

    Examples:
        >>> Vector3D(1, 0, 0).cross(Vector3D(0, 1, 0))
        Vector3D(x=0, y=0, z=1)
        >>> Vector3D(3, 0, 0).cross(Vector3D(0, 4, 0))
        Vector3D(x=0, y=0, z=12)
    """
    return Vector3D(
        self.y * other.z - self.z * other.y,
        self.z * other.x - self.x * other.z,
        self.x * other.y - self.y * other.x,
    )

dot(other)

Dot product.

Examples:

>>> Vector3D(1, 0, 0).dot(Vector3D(0, 1, 0))
0
>>> Vector3D(3.0, 0.0, 0.0).dot(Vector3D(4.0, 0.0, 0.0))
12.0

Source code in idfkit/geometry.py

def dot(self, other: Vector3D) -> float:
    """Dot product.

    Examples:
        >>> Vector3D(1, 0, 0).dot(Vector3D(0, 1, 0))
        0
        >>> Vector3D(3.0, 0.0, 0.0).dot(Vector3D(4.0, 0.0, 0.0))
        12.0
    """
    return self.x * other.x + self.y * other.y + self.z * other.z

from_tuple(t) classmethod

Create from tuple or list.

Examples:

>>> Vector3D.from_tuple((1.0, 2.0, 3.0))
Vector3D(x=1.0, y=2.0, z=3.0)
>>> Vector3D.from_tuple([0, 0, 0])
Vector3D(x=0.0, y=0.0, z=0.0)

Source code in idfkit/geometry.py

@classmethod
def from_tuple(cls, t: Sequence[float]) -> Vector3D:
    """Create from tuple or list.

    Examples:
        >>> Vector3D.from_tuple((1.0, 2.0, 3.0))
        Vector3D(x=1.0, y=2.0, z=3.0)
        >>> Vector3D.from_tuple([0, 0, 0])
        Vector3D(x=0.0, y=0.0, z=0.0)
    """
    return cls(float(t[0]), float(t[1]), float(t[2]))

length()

Vector magnitude.

Examples:

>>> Vector3D(3, 4, 0).length()
5.0
>>> Vector3D(1, 0, 0).length()
1.0

Source code in idfkit/geometry.py

def length(self) -> float:
    """Vector magnitude.

    Examples:
        >>> Vector3D(3, 4, 0).length()
        5.0
        >>> Vector3D(1, 0, 0).length()
        1.0
    """
    return math.hypot(self.x, self.y, self.z)

normalize()

Return unit vector.

Examples:

>>> Vector3D(3, 0, 0).normalize()
Vector3D(x=1.0, y=0.0, z=0.0)
>>> Vector3D(0, 0, 5).normalize()
Vector3D(x=0.0, y=0.0, z=1.0)

Source code in idfkit/geometry.py

def normalize(self) -> Vector3D:
    """Return unit vector.

    Examples:
        >>> Vector3D(3, 0, 0).normalize()
        Vector3D(x=1.0, y=0.0, z=0.0)
        >>> Vector3D(0, 0, 5).normalize()
        Vector3D(x=0.0, y=0.0, z=1.0)
    """
    mag = self.length()
    if mag == 0:
        return Vector3D(0, 0, 0)
    return self / mag

origin() classmethod

Return origin vector.

Examples:

>>> Vector3D.origin()
Vector3D(x=0.0, y=0.0, z=0.0)

Source code in idfkit/geometry.py

@classmethod
def origin(cls) -> Vector3D:
    """Return origin vector.

    Examples:
        >>> Vector3D.origin()
        Vector3D(x=0.0, y=0.0, z=0.0)
    """
    return cls(0.0, 0.0, 0.0)

rotate_z(angle_deg)

Rotate around Z axis by angle in degrees.

Examples:

>>> v = Vector3D(1, 0, 0).rotate_z(90)
>>> round(v.x, 10), round(v.y, 10)
(0.0, 1.0)
>>> Vector3D(1, 0, 5).rotate_z(180)
Vector3D(x=-1.0, y=0.0, z=5.0)

Source code in idfkit/geometry.py

def rotate_z(self, angle_deg: float) -> Vector3D:
    """Rotate around Z axis by angle in degrees.

    Examples:
        >>> v = Vector3D(1, 0, 0).rotate_z(90)
        >>> round(v.x, 10), round(v.y, 10)
        (0.0, 1.0)
        >>> Vector3D(1, 0, 5).rotate_z(180)  # doctest: +SKIP
        Vector3D(x=-1.0, y=0.0, z=5.0)
    """
    angle_rad = math.radians(angle_deg)
    cos_a = math.cos(angle_rad)
    sin_a = math.sin(angle_rad)
    return Vector3D(
        self.x * cos_a - self.y * sin_a,
        self.x * sin_a + self.y * cos_a,
        self.z,
    )

calculate_surface_area(surface)

Calculate the area of a surface in m².

Examples:

Area of a 10 m wide, 3 m high exterior wall:

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> calculate_surface_area(wall)
30.0

Source code in idfkit/geometry.py

def calculate_surface_area(surface: IDFObject) -> float:
    """Calculate the area of a surface in m².

    Examples:
        Area of a 10 m wide, 3 m high exterior wall:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> calculate_surface_area(wall)
        30.0
    """
    coords = get_surface_coords(surface)
    return coords.area if coords else 0.0

calculate_surface_azimuth(surface)

Calculate the azimuth of a surface in degrees (eppy compatibility).

0 = north, 90 = east, 180 = south, 270 = west. Useful for identifying solar exposure for glazing and shading studies.

Examples:

Confirm a wall faces south (azimuth 180):

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "SouthWall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> calculate_surface_azimuth(wall)
180.0

Source code in idfkit/geometry.py

def calculate_surface_azimuth(surface: IDFObject) -> float:
    """Calculate the azimuth of a surface in degrees (eppy compatibility).

    0 = north, 90 = east, 180 = south, 270 = west.  Useful for
    identifying solar exposure for glazing and shading studies.

    Examples:
        Confirm a wall faces south (azimuth 180):

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "SouthWall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> calculate_surface_azimuth(wall)
        180.0
    """
    coords = get_surface_coords(surface)
    return coords.azimuth if coords else 0.0

calculate_surface_tilt(surface)

Calculate the tilt of a surface in degrees (eppy compatibility).

0 = facing up (roof), 90 = vertical (wall), 180 = facing down (floor).

Examples:

Verify that an exterior wall is vertical:

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> calculate_surface_tilt(wall)
90.0

Source code in idfkit/geometry.py

def calculate_surface_tilt(surface: IDFObject) -> float:
    """Calculate the tilt of a surface in degrees (eppy compatibility).

    0 = facing up (roof), 90 = vertical (wall), 180 = facing down (floor).

    Examples:
        Verify that an exterior wall is vertical:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> calculate_surface_tilt(wall)
        90.0
    """
    coords = get_surface_coords(surface)
    return coords.tilt if coords else 0.0

calculate_zone_ceiling_area(doc, zone_name)

Calculate the total ceiling/roof area of a zone (eppy compatibility).

Sums the area of all surfaces whose surface_type is "Ceiling" or "Roof" in the given zone.

Examples:

Calculate the ceiling area of a 5 m x 4 m office at z=3 m:

>>> from idfkit import new_document
>>> model = new_document()
>>> model.add("Zone", "Office")
Zone('Office')
>>> model.add("BuildingSurface:Detailed", "Office_Ceiling",
...     surface_type="Ceiling", construction_name="", zone_name="Office",
...     outside_boundary_condition="Outdoors",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 4, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 4, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
BuildingSurface:Detailed('Office_Ceiling')
>>> calculate_zone_ceiling_area(model, "Office")
20.0

Source code in idfkit/geometry.py

def calculate_zone_ceiling_area(doc: IDFDocument, zone_name: str) -> float:
    """Calculate the total ceiling/roof area of a zone (eppy compatibility).

    Sums the area of all surfaces whose ``surface_type`` is ``"Ceiling"``
    or ``"Roof"`` in the given zone.

    Examples:
        Calculate the ceiling area of a 5 m x 4 m office at z=3 m:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> model.add("Zone", "Office")  # doctest: +ELLIPSIS
        Zone('Office')
        >>> model.add("BuildingSurface:Detailed", "Office_Ceiling",
        ...     surface_type="Ceiling", construction_name="", zone_name="Office",
        ...     outside_boundary_condition="Outdoors",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 4, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 4, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)  # doctest: +ELLIPSIS
        BuildingSurface:Detailed('Office_Ceiling')
        >>> calculate_zone_ceiling_area(model, "Office")
        20.0
    """
    total_area = 0.0

    for surface in doc["BuildingSurface:Detailed"]:
        if (getattr(surface, "zone_name", None) or "").upper() != zone_name.upper():
            continue

        surface_type = getattr(surface, "surface_type", None) or ""
        if surface_type and surface_type.lower() in ("ceiling", "roof"):
            total_area += calculate_surface_area(surface)

    return total_area

calculate_zone_floor_area(doc, zone_name)

Calculate the total floor area of a zone.

Sums the area of all BuildingSurface:Detailed objects whose surface_type is "Floor" and whose zone_name matches.

Examples:

Calculate the floor area of a 5 m x 4 m office:

>>> from idfkit import new_document
>>> model = new_document()
>>> model.add("Zone", "Office")
Zone('Office')
>>> model.add("BuildingSurface:Detailed", "Office_Floor",
...     surface_type="Floor", construction_name="", zone_name="Office",
...     outside_boundary_condition="Ground",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 4, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 4, "vertex_z_coordinate": 0},
...     ],
...     validate=False)
BuildingSurface:Detailed('Office_Floor')
>>> calculate_zone_floor_area(model, "Office")
20.0

Source code in idfkit/geometry.py

def calculate_zone_floor_area(doc: IDFDocument, zone_name: str) -> float:
    """Calculate the total floor area of a zone.

    Sums the area of all ``BuildingSurface:Detailed`` objects whose
    ``surface_type`` is ``"Floor"`` and whose ``zone_name`` matches.

    Examples:
        Calculate the floor area of a 5 m x 4 m office:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> model.add("Zone", "Office")  # doctest: +ELLIPSIS
        Zone('Office')
        >>> model.add("BuildingSurface:Detailed", "Office_Floor",
        ...     surface_type="Floor", construction_name="", zone_name="Office",
        ...     outside_boundary_condition="Ground",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 4, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 4, "vertex_z_coordinate": 0},
        ...     ],
        ...     validate=False)  # doctest: +ELLIPSIS
        BuildingSurface:Detailed('Office_Floor')
        >>> calculate_zone_floor_area(model, "Office")
        20.0
    """
    total_area = 0.0

    for surface in doc["BuildingSurface:Detailed"]:
        if (getattr(surface, "zone_name", None) or "").upper() != zone_name.upper():
            continue

        surface_type = getattr(surface, "surface_type", None) or ""
        if surface_type and surface_type.lower() == "floor":
            total_area += calculate_surface_area(surface)

    return total_area

calculate_zone_height(doc, zone_name)

Calculate the height of a zone from its surfaces.

Returns the difference between the maximum and minimum Z coordinates across all surfaces belonging to the zone.

Examples:

Determine the floor-to-ceiling height of a 3 m tall office:

>>> from idfkit import new_document
>>> model = new_document()
>>> model.add("Zone", "Office")
Zone('Office')
>>> model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="Office",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
BuildingSurface:Detailed('South_Wall')
>>> calculate_zone_height(model, "Office")
3.0

Source code in idfkit/geometry.py

def calculate_zone_height(doc: IDFDocument, zone_name: str) -> float:
    """Calculate the height of a zone from its surfaces.

    Returns the difference between the maximum and minimum Z coordinates
    across all surfaces belonging to the zone.

    Examples:
        Determine the floor-to-ceiling height of a 3 m tall office:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> model.add("Zone", "Office")  # doctest: +ELLIPSIS
        Zone('Office')
        >>> model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="Office",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)  # doctest: +ELLIPSIS
        BuildingSurface:Detailed('South_Wall')
        >>> calculate_zone_height(model, "Office")
        3.0
    """
    z_min = float("inf")
    z_max = float("-inf")

    for surface in doc["BuildingSurface:Detailed"]:
        if (getattr(surface, "zone_name", None) or "").upper() != zone_name.upper():
            continue

        coords = get_surface_coords(surface)
        if coords is None:
            continue

        for v in coords.vertices:
            z_min = min(z_min, v.z)
            z_max = max(z_max, v.z)

    if z_min == float("inf"):
        return 0.0
    return z_max - z_min

calculate_zone_volume(doc, zone_name)

Calculate the volume of a zone from its surfaces.

Uses the divergence theorem to compute volume from surface polygons. Returns 0.0 if the zone has no surfaces.

Source code in idfkit/geometry.py

def calculate_zone_volume(doc: IDFDocument, zone_name: str) -> float:
    """
    Calculate the volume of a zone from its surfaces.

    Uses the divergence theorem to compute volume from surface polygons.
    Returns 0.0 if the zone has no surfaces.
    """
    volume = 0.0

    for surface in doc["BuildingSurface:Detailed"]:
        if (getattr(surface, "zone_name", None) or "").upper() != zone_name.upper():
            continue

        coords = get_surface_coords(surface)
        if coords is None or coords.num_vertices < 3:
            continue

        # Contribution to volume using signed volume of tetrahedra
        centroid = coords.centroid
        for i in range(coords.num_vertices):
            v1 = coords.vertices[i]
            v2 = coords.vertices[(i + 1) % coords.num_vertices]

            # Volume of tetrahedron with origin
            volume += v1.dot(v2.cross(centroid)) / 6.0

    return abs(volume)

get_surface_coords(surface)

Extract coordinates from a surface object.

Reads from the canonical wrapper array (surface.data["vertices"]) for extensible types like BuildingSurface:Detailed, and falls back to fixed flat vertex_N_x_coordinate fields for surface types whose vertex count is fixed in the schema (e.g. FenestrationSurface:Detailed).

Examples:

Extract geometry from a 10 m x 3 m south-facing exterior wall:

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> poly = get_surface_coords(wall)
>>> poly.area
30.0
>>> poly.azimuth
180.0

Source code in idfkit/geometry.py

def get_surface_coords(surface: IDFObject) -> Polygon3D | None:
    """
    Extract coordinates from a surface object.

    Reads from the canonical wrapper array (``surface.data["vertices"]``)
    for extensible types like ``BuildingSurface:Detailed``, and falls back
    to fixed flat ``vertex_N_x_coordinate`` fields for surface types whose
    vertex count is fixed in the schema (e.g. ``FenestrationSurface:Detailed``).

    Examples:
        Extract geometry from a 10 m x 3 m south-facing exterior wall:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> poly = get_surface_coords(wall)
        >>> poly.area
        30.0
        >>> poly.azimuth
        180.0
    """
    vertices = _get_vertices(surface)
    if len(vertices) < 3:
        return None
    return Polygon3D(vertices)

get_zone_origin(zone)

Get the origin point of a zone.

Examples:

A second-floor zone offset 3.5 m above ground:

>>> from idfkit import new_document
>>> model = new_document()
>>> zone = model.add("Zone", "Floor2_Office",
...     x_origin=10.0, y_origin=20.0, z_origin=3.5)
>>> get_zone_origin(zone)
Vector3D(x=10.0, y=20.0, z=3.5)

Source code in idfkit/geometry.py

def get_zone_origin(zone: IDFObject) -> Vector3D:
    """Get the origin point of a zone.

    Examples:
        A second-floor zone offset 3.5 m above ground:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> zone = model.add("Zone", "Floor2_Office",
        ...     x_origin=10.0, y_origin=20.0, z_origin=3.5)
        >>> get_zone_origin(zone)
        Vector3D(x=10.0, y=20.0, z=3.5)
    """
    x = getattr(zone, "x_origin", 0) or 0
    y = getattr(zone, "y_origin", 0) or 0
    z = getattr(zone, "z_origin", 0) or 0
    return Vector3D(float(x), float(y), float(z))

get_zone_rotation(zone)

Get the rotation angle of a zone in degrees.

Examples:

A zone rotated 45 degrees from true north (common for buildings aligned to a street grid):

>>> from idfkit import new_document
>>> model = new_document()
>>> zone = model.add("Zone", "Corner_Office",
...     direction_of_relative_north=45.0)
>>> get_zone_rotation(zone)
45.0

Source code in idfkit/geometry.py

def get_zone_rotation(zone: IDFObject) -> float:
    """Get the rotation angle of a zone in degrees.

    Examples:
        A zone rotated 45 degrees from true north (common for
        buildings aligned to a street grid):

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> zone = model.add("Zone", "Corner_Office",
        ...     direction_of_relative_north=45.0)
        >>> get_zone_rotation(zone)
        45.0
    """
    angle = getattr(zone, "direction_of_relative_north", 0)
    return float(angle) if angle else 0.0

intersect_match(doc)

Intersect and match adjacent interzone surfaces, splitting as needed.

Coplanar, oppositely-facing surfaces that overlap are split into congruent matched fragments (interior Surface boundary conditions) plus exterior remainders. A single surface abutting several smaller neighbours is split into one matched fragment per neighbour — the long-wall-shared-with-many-zones case. The document is modified in place.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The document to modify in-place.	required

Note

This is a thin wrapper over intersect_and_match, which returns a MatchReport and accepts a MatchOptions for tuning tolerances and scope. Call it directly when you need either.

Source code in idfkit/geometry.py

def intersect_match(doc: IDFDocument) -> None:
    """Intersect and match adjacent interzone surfaces, splitting as needed.

    Coplanar, oppositely-facing surfaces that overlap are split into
    congruent matched fragments (interior ``Surface`` boundary conditions)
    plus exterior remainders.  A single surface abutting several smaller
    neighbours is split into one matched fragment per neighbour — the
    long-wall-shared-with-many-zones case.  The document is modified in place.

    Args:
        doc: The document to modify in-place.

    !!! note
        This is a thin wrapper over
        [`intersect_and_match`][idfkit.surface_matching.intersect_and_match],
        which returns a
        [`MatchReport`][idfkit.surface_matching.MatchReport] and accepts a
        [`MatchOptions`][idfkit.surface_matching.MatchOptions] for tuning
        tolerances and scope.  Call it directly when you need either.
    """
    from .surface_matching import intersect_and_match

    intersect_and_match(doc)

is_convex_2d(poly, *, eps=1e-12)

Return True if the 2-D polygon is convex.

Source code in idfkit/geometry.py

def is_convex_2d(poly: Sequence[tuple[float, float]], *, eps: float = 1e-12) -> bool:
    """Return ``True`` if the 2-D polygon is convex."""
    n = len(poly)
    if n < 3:
        return False
    sign: float | None = None
    for i in range(n):
        x1, y1 = poly[i]
        x2, y2 = poly[(i + 1) % n]
        x3, y3 = poly[(i + 2) % n]
        cross = (x2 - x1) * (y3 - y2) - (y2 - y1) * (x3 - x2)
        if abs(cross) < eps:
            continue
        if sign is None:
            sign = cross
        elif cross * sign < 0:
            return False
    return True

line_intersect_2d(a1, a2, b1, b2, *, eps=1e-12)

Intersection of two infinite lines through (a1, a2) and (b1, b2).

Source code in idfkit/geometry.py

def line_intersect_2d(
    a1: tuple[float, float],
    a2: tuple[float, float],
    b1: tuple[float, float],
    b2: tuple[float, float],
    *,
    eps: float = 1e-12,
) -> tuple[float, float] | None:
    """Intersection of two infinite lines through (a1, a2) and (b1, b2)."""
    d1x = a2[0] - a1[0]
    d1y = a2[1] - a1[1]
    d2x = b2[0] - b1[0]
    d2y = b2[1] - b1[1]
    denom = d1x * d2y - d1y * d2x
    if abs(denom) < eps:
        return None
    t = ((b1[0] - a1[0]) * d2y - (b1[1] - a1[1]) * d2x) / denom
    return (a1[0] + t * d1x, a1[1] + t * d1y)

polygon_area_2d(poly)

Signed area of a 2-D polygon (positive = CCW).

Source code in idfkit/geometry.py

def polygon_area_2d(poly: Sequence[tuple[float, float]]) -> float:
    """Signed area of a 2-D polygon (positive = CCW)."""
    n = len(poly)
    area = 0.0
    for i in range(n):
        j = (i + 1) % n
        area += poly[i][0] * poly[j][1]
        area -= poly[j][0] * poly[i][1]
    return area / 2.0

polygon_contains_2d(outer, inner)

Return True if all vertices of inner are inside outer.

Source code in idfkit/geometry.py

def polygon_contains_2d(
    outer: Sequence[tuple[float, float]],
    inner: Sequence[tuple[float, float]],
) -> bool:
    """Return ``True`` if all vertices of *inner* are inside *outer*."""
    return all(_point_in_polygon_2d(p, outer) for p in inner)

polygon_difference_2d(outer, inner)

Subtract inner from outer using a bridge/slit polygon.

The inner polygon must be fully contained within outer. Both must be counter-clockwise. Returns a single simple (non-convex) polygon representing the frame region, or None if the inner polygon covers the entire outer polygon.

The approach is the same slit technique used by :func:~idfkit.zoning.footprint_courtyard.

Source code in idfkit/geometry.py

def polygon_difference_2d(
    outer: Sequence[tuple[float, float]],
    inner: Sequence[tuple[float, float]],
) -> Polygon2D | None:
    """Subtract *inner* from *outer* using a bridge/slit polygon.

    The *inner* polygon must be fully contained within *outer*.  Both
    must be counter-clockwise.  Returns a single simple (non-convex)
    polygon representing the frame region, or ``None`` if the inner
    polygon covers the entire outer polygon.

    The approach is the same slit technique used by
    :func:`~idfkit.zoning.footprint_courtyard`.
    """
    outer_list = list(outer)
    inner_list = list(inner)

    outer_area = abs(polygon_area_2d(outer_list))
    inner_area = abs(polygon_area_2d(inner_list))
    if abs(outer_area - inner_area) < 1e-6:
        return None

    # Find closest vertex pair for the slit
    best_dist = float("inf")
    best_oi = 0
    best_ii = 0
    for oi, op in enumerate(outer_list):
        for ii, ip in enumerate(inner_list):
            d = math.hypot(op[0] - ip[0], op[1] - ip[1])
            if d < best_dist:
                best_dist = d
                best_oi = oi
                best_ii = ii

    n_outer = len(outer_list)
    n_inner = len(inner_list)

    # Build bridge polygon:
    # Walk outer CCW from best_oi+1 back to best_oi,
    # slit to inner at best_ii,
    # walk inner CW (reversed) from best_ii back to best_ii+1,
    # slit back to outer.
    result: Polygon2D = []
    for k in range(n_outer):
        result.append(outer_list[(best_oi + 1 + k) % n_outer])
    # Slit entry: last point is outer[best_oi], now add inner[best_ii]
    for k in range(n_inner):
        result.append(inner_list[(best_ii - k) % n_inner])
    # Slit exit: last point is inner[best_ii+1 in CW = best_ii-n_inner+1]
    # Close back to outer[best_oi+1] via the implicit polygon close

    return result

polygon_intersection_2d(poly_a, poly_b)

Compute the intersection of two 2-D polygons.

Uses the Sutherland-Hodgman algorithm. At least one polygon must be convex (the convex one is used as the clip polygon). If both are concave the function returns None.

Returns:

Type	Description
Polygon2D | None	The intersection polygon vertices, or None if disjoint or
Polygon2D | None	both polygons are concave.

Source code in idfkit/geometry.py

def polygon_intersection_2d(
    poly_a: Sequence[tuple[float, float]],
    poly_b: Sequence[tuple[float, float]],
) -> Polygon2D | None:
    """Compute the intersection of two 2-D polygons.

    Uses the Sutherland-Hodgman algorithm.  At least one polygon must be
    convex (the convex one is used as the clip polygon).  If both are
    concave the function returns ``None``.

    Returns:
        The intersection polygon vertices, or ``None`` if disjoint or
        both polygons are concave.
    """
    a_convex = is_convex_2d(poly_a)
    b_convex = is_convex_2d(poly_b)

    if (a_convex and b_convex) or b_convex:
        result = _sutherland_hodgman(poly_a, poly_b)
    elif a_convex:
        result = _sutherland_hodgman(poly_b, poly_a)
    else:
        logger.warning("polygon_intersection_2d: both polygons are concave — not supported")
        return None

    if len(result) < 3:
        return None
    if abs(polygon_area_2d(result)) < 1e-6:
        return None
    return result

rotate_building(doc, angle_deg, anchor=None)

Rotate all building surfaces around the Z axis.

Only vertex coordinates are modified; Building.north_axis and Zone rotation fields are not updated.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The document to modify in-place.	required
angle_deg	float	Rotation angle in degrees (positive = counter-clockwise when viewed from above).	required
anchor	Vector3D | None	Point to rotate around. If None, the origin (0, 0, 0) is used.	None

Source code in idfkit/geometry.py

def rotate_building(doc: IDFDocument, angle_deg: float, anchor: Vector3D | None = None) -> None:
    """Rotate all building surfaces around the Z axis.

    Only vertex coordinates are modified; ``Building.north_axis`` and
    ``Zone`` rotation fields are **not** updated.

    Args:
        doc: The document to modify in-place.
        angle_deg: Rotation angle in degrees (positive = counter-clockwise when
            viewed from above).
        anchor: Point to rotate around.  If ``None``, the origin ``(0, 0, 0)``
            is used.
    """
    if anchor is None:
        anchor = Vector3D.origin()

    for stype in VERTEX_SURFACE_TYPES:
        for surface in doc.get_collection(stype):
            coords = get_surface_coords(surface)
            if coords is not None:
                set_surface_coords(surface, coords.rotate_z(angle_deg, anchor=anchor))

set_surface_coords(surface, polygon)

Set coordinates on a surface object.

Updates vertex fields and number_of_vertices.

Examples:

Shorten a wall from 10 m to 5 m by replacing its vertices:

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> shorter = Polygon3D.from_tuples([(0,0,0),(5,0,0),(5,0,3),(0,0,3)])
>>> set_surface_coords(wall, shorter)
>>> get_surface_coords(wall).area
15.0

Source code in idfkit/geometry.py

def set_surface_coords(surface: IDFObject, polygon: Polygon3D) -> None:
    """
    Set coordinates on a surface object.

    Updates vertex fields and number_of_vertices.

    Examples:
        Shorten a wall from 10 m to 5 m by replacing its vertices:

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> shorter = Polygon3D.from_tuples([(0,0,0),(5,0,0),(5,0,3),(0,0,3)])
        >>> set_surface_coords(wall, shorter)
        >>> get_surface_coords(wall).area
        15.0
    """
    # Set number of vertices
    surface.number_of_vertices = len(polygon.vertices)

    # Extensible surface types (BuildingSurface:Detailed etc.) use the
    # canonical wrapper. Fixed-vertex types (FenestrationSurface:Detailed)
    # use flat ``vertex_N_x_coordinate`` fields per the schema's fixed
    # legacy_idd ordering.
    doc = surface._document  # pyright: ignore[reportPrivateUsage]
    pc = doc.schema.get_parsing_cache(surface.obj_type) if doc and doc.schema else None
    if pc and pc.ext_wrapper_key == "vertices":
        surface.data["vertices"] = [
            {
                "vertex_x_coordinate": vertex.x,
                "vertex_y_coordinate": vertex.y,
                "vertex_z_coordinate": vertex.z,
            }
            for vertex in polygon.vertices
        ]
    else:
        # Fixed flat-field surface — write vertex_N_x/y/z_coordinate.
        # Clear any stale vertex flat keys so removed vertices vanish.
        for key in [k for k in surface.data if k.startswith("vertex_") and k != "vertices"]:
            del surface.data[key]
        for i, v in enumerate(polygon.vertices, 1):
            surface.data[f"vertex_{i}_x_coordinate"] = v.x
            surface.data[f"vertex_{i}_y_coordinate"] = v.y
            surface.data[f"vertex_{i}_z_coordinate"] = v.z
    surface._bump_version()  # pyright: ignore[reportPrivateUsage]

set_wwr(doc, wwr, *, construction=None, surface_type='Wall', orientation=None, tolerance=10.0)

Add or replace windows to achieve a target window-wall ratio.

For each exterior wall matching the filter criteria, a single rectangular sub-surface (FenestrationSurface:Detailed) is created whose area equals wwr * wall_area. Any existing FenestrationSurface:Detailed sub-surfaces on matching walls are removed first.

This is the idfkit equivalent of geomeppy's idf.set_wwr().

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The document to modify in-place.	required
wwr	float	Target window-wall ratio in the range (0, 1).	required
construction	str | None	Name of the window Construction to assign. If None and existing fenestration is present, the construction from the existing window is preserved. If None and no existing fenestration exists, the field is left empty.	None
surface_type	str	Only walls whose surface_type matches (case- insensitive) are considered. Defaults to "Wall".	'Wall'
orientation	str | None	Optional cardinal direction filter — one of "north", "south", "east", "west". Only walls within tolerance degrees of that azimuth are modified.	None
tolerance	float	Azimuth tolerance in degrees when orientation is given. Defaults to 10°.	10.0

Returns:

Type	Description
list[IDFObject]	List of newly created FenestrationSurface:Detailed objects.

Raises:

Type	Description
ValueError	If wwr is not in (0, 1).

Source code in idfkit/geometry.py

def set_wwr(  # noqa: C901
    doc: IDFDocument,
    wwr: float,
    *,
    construction: str | None = None,
    surface_type: str = "Wall",
    orientation: str | None = None,
    tolerance: float = 10.0,
) -> list[IDFObject]:
    """Add or replace windows to achieve a target window-wall ratio.

    For each exterior wall matching the filter criteria, a single
    rectangular sub-surface (``FenestrationSurface:Detailed``) is
    created whose area equals ``wwr * wall_area``.  Any existing
    ``FenestrationSurface:Detailed`` sub-surfaces on matching walls are
    removed first.

    This is the idfkit equivalent of geomeppy's ``idf.set_wwr()``.

    Args:
        doc: The document to modify in-place.
        wwr: Target window-wall ratio in the range ``(0, 1)``.
        construction: Name of the window ``Construction`` to assign.
            If ``None`` and existing fenestration is present, the
            construction from the existing window is preserved.
            If ``None`` and no existing fenestration exists, the field
            is left empty.
        surface_type: Only walls whose ``surface_type`` matches (case-
            insensitive) are considered.  Defaults to ``"Wall"``.
        orientation: Optional cardinal direction filter — one of
            ``"north"``, ``"south"``, ``"east"``, ``"west"``.  Only
            walls within *tolerance* degrees of that azimuth are modified.
        tolerance: Azimuth tolerance in degrees when *orientation* is
            given.  Defaults to 10°.

    Returns:
        List of newly created ``FenestrationSurface:Detailed`` objects.

    Raises:
        ValueError: If *wwr* is not in ``(0, 1)``.
    """
    if not 0 < wwr < 1:
        msg = f"wwr must be between 0 and 1 (exclusive), got {wwr}"
        raise ValueError(msg)

    azimuth_target = _orientation_to_azimuth(orientation) if orientation else None

    # Remove existing fenestration on matching walls
    existing_fen: list[IDFObject] = []
    wall_names: set[str] = set()
    for wall in doc["BuildingSurface:Detailed"]:
        if not _wall_matches(wall, surface_type, azimuth_target, tolerance):
            continue
        wall_names.add(wall.name.upper())

    # Capture construction names and cross-references before removal
    wall_constructions: dict[str, str] = {}
    fen_referrers: dict[str, tuple[str, set[tuple[IDFObject, str]]]] = {}
    for fen in list(doc["FenestrationSurface:Detailed"]):
        bsn = getattr(fen, "building_surface_name", None) or ""
        bsn_upper = bsn.upper()
        if bsn_upper not in wall_names:
            continue
        existing_fen.append(fen)
        # Preserve construction from the first fenestration per wall
        fen_construction = getattr(fen, "construction_name", None) or ""
        if fen_construction and bsn_upper not in wall_constructions:
            wall_constructions[bsn_upper] = fen_construction
        # Snapshot objects that reference this fenestration
        referrers = doc.references.get_referencing_with_fields(fen.name)
        if referrers:
            fen_referrers[fen.name.upper()] = (bsn_upper, referrers)
    for fen in existing_fen:
        doc.removeidfobject(fen)

    # Create new windows
    new_windows: list[IDFObject] = []
    for wall in doc["BuildingSurface:Detailed"]:
        if not _wall_matches(wall, surface_type, azimuth_target, tolerance):
            continue
        obc = getattr(wall, "outside_boundary_condition", None) or ""
        if obc.upper() != "OUTDOORS":
            continue

        coords = get_surface_coords(wall)
        if coords is None or coords.area < 1e-6:
            continue

        window_poly = _inset_polygon(coords, wwr)
        if window_poly is None:
            continue

        wall_upper = wall.name.upper()
        win_name = f"{wall.name}_Window"
        win_data: dict[str, Any] = {
            "surface_type": "Window",
            "building_surface_name": wall.name,
            "number_of_vertices": window_poly.num_vertices,
        }
        if construction is not None:
            win_data["construction_name"] = construction
        elif wall_upper in wall_constructions:
            win_data["construction_name"] = wall_constructions[wall_upper]
        # FenestrationSurface:Detailed uses fixed flat vertex_N_x_coordinate
        # fields (verified against real EnergyPlus epJSON output) — not the
        # canonical wrapper. Write the flat shape directly.
        for i, v in enumerate(window_poly.vertices, 1):
            win_data[f"vertex_{i}_x_coordinate"] = round(v.x, 6)
            win_data[f"vertex_{i}_y_coordinate"] = round(v.y, 6)
            win_data[f"vertex_{i}_z_coordinate"] = round(v.z, 6)

        win_obj = doc.add("FenestrationSurface:Detailed", win_name, win_data, validate=False)
        new_windows.append(win_obj)

    # Re-point cross-references from old fenestration names to new windows
    if fen_referrers:
        wall_to_new_win: dict[str, str] = {}
        for win in new_windows:
            win_bsn = getattr(win, "building_surface_name", None) or ""
            wall_to_new_win[win_bsn.upper()] = win.name
        for _old_upper, (wall_upper, referrers) in fen_referrers.items():
            new_win_name = wall_to_new_win.get(wall_upper)
            if new_win_name is None:
                continue
            for ref_obj, field_name in referrers:
                setattr(ref_obj, field_name, new_win_name)

    logger.debug("set_wwr: created %d windows at target ratio %.2f", len(new_windows), wwr)
    return new_windows

translate_building(doc, offset)

Translate all building surfaces by the given offset vector.

Modifies the document in-place, shifting every surface's vertices by offset.

Note

Only vertex coordinates are modified. Zone origin fields and the Building object are not updated. Use translate_to_world if you need to collapse zone-relative coordinates into world coordinates.

Examples:

Reposition a building on its site (e.g., from local to geo-referenced coordinates):

>>> from idfkit import new_document
>>> model = new_document()
>>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
...     surface_type="Wall", construction_name="", zone_name="",
...     outside_boundary_condition="Outdoors",
...     sun_exposure="SunExposed", wind_exposure="WindExposed",
...     number_of_vertices=4,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...     ],
...     validate=False)
>>> translate_building(model, Vector3D(100, 200, 0))
>>> wall.vertices[0].vertex_x_coordinate
100.0

Source code in idfkit/geometry.py

def translate_building(doc: IDFDocument, offset: Vector3D) -> None:
    """Translate all building surfaces by the given offset vector.

    Modifies the document in-place, shifting every surface's vertices
    by *offset*.

    !!! note
        Only vertex coordinates are modified.  ``Zone`` origin fields
        and the ``Building`` object are **not** updated.  Use
        [translate_to_world][idfkit.geometry.translate_to_world] if you need to collapse zone-relative
        coordinates into world coordinates.

    Examples:
        Reposition a building on its site (e.g., from local to
        geo-referenced coordinates):

        >>> from idfkit import new_document
        >>> model = new_document()
        >>> wall = model.add("BuildingSurface:Detailed", "South_Wall",
        ...     surface_type="Wall", construction_name="", zone_name="",
        ...     outside_boundary_condition="Outdoors",
        ...     sun_exposure="SunExposed", wind_exposure="WindExposed",
        ...     number_of_vertices=4,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 10, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...     ],
        ...     validate=False)
        >>> translate_building(model, Vector3D(100, 200, 0))
        >>> wall.vertices[0].vertex_x_coordinate
        100.0
    """
    for stype in VERTEX_SURFACE_TYPES:
        for surface in doc.get_collection(stype):
            coords = get_surface_coords(surface)
            if coords is not None:
                set_surface_coords(surface, coords.translate(offset))

translate_to_world(doc)

Rewrite every detailed surface's vertices into the frame the engine computes, in place.

This is the mutating counterpart of get_scene, and it is that function that does the work: the polygons written back here are the ones the scene resolved, so the two cannot drift apart. The document, and not a copy, is what changes, which is what this function is for.

BEHAVIOUR CHANGE, WITH THE MEASUREMENT THAT PROMPTED IT

Until idfkit 1.0.0-rc.6 this function resolved coordinates by a rule that disagreed with EnergyPlus. Against the engine's own Output:Surfaces:List vertex report over seventeen of the shipped example models and five hundred and thirty-two surfaces, the old rule agreed with the engine on five of the seventeen models, worst case 201.98 m of displacement. The rule it now applies agrees on seventeen of seventeen, worst case 0.0045 m, against a report that prints two decimals. Three defects account for the difference:

1. It rotated each surface by Building.north_axis inside its own zone frame, about the polygon's centroid. The engine turns the resolved building as one body about the world origin, and in the opposite sense: the north axis is measured clockwise from true north. Each surface therefore came out correctly oriented with its zone in the wrong place, a drawing that passes an eyeball test at up to 201.98 m of error.
2. It translated by the zone origin without rotating that origin by the building axis first, so the two clauses composed in the wrong order.
3. It collected a zone's surfaces with get_referencing(zone_name), which fenestration never matches: a window names its parent wall and not the zone, so no window was ever moved.

The same defects measured on the corpus's own fixture set, which is what checks/geometry-vertices in idfkit-conformance now runs this function against: the old rule failed 60 of the 234 surfaces over four of the seven fixtures, worst case 40.00 m, and left a fifth unreadable by declaring the world system while leaving clockwise entry in place. The corrected rule fails none of them.

Two further differences follow from the corrected rule rather than from a defect. A model declaring World is no longer returned from untouched: the building north axis applies to such a model too, and only the zone origin and the zone's relative north are conditional on the relative system. And a model declaring clockwise vertex entry has its rings reversed, the first vertex held in place, with GlobalGeometryRules restated as counter-clockwise, so that the right-hand rule gives the outward normal in the result.

WHAT IT DOES NOT TOUCH, WHICH MATTERS FOR A MIXED MODEL

Only the five detailed vertex types are read: BuildingSurface:Detailed, FenestrationSurface:Detailed and the three detailed shading forms. The simplified surface family (Wall:Exterior, Window, Roof and their siblings) and Daylighting:ReferencePoint state their geometry against the zone origin under their own coordinate-system fields, which this function does not read and cannot transform. Zeroing Building.north_axis at the end therefore leaves such objects unrotated in a document that no longer declares the rotation. A model holding both families is outside what this function can make consistent; get_scene reports the types it did not attempt instead of editing the document, and is the better tool there.

An object the scene could not place is not rewritten either, for the same reason and with the same consequence: its vertices stay as the author wrote them while the declarations they were written against are restated underneath it. Each one is logged at warning level, and get_scene names them with a reason in Scene.unresolved.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	the document to rewrite. Every surface the scene resolved has its vertices replaced, and the declarations those vertices were resolved against are restated so that reading the result back applies nothing a second time.	required

Examples:

A zone at (10, 20, 0) with one wall authored at the zone's own origin:

>>> from idfkit import new_document
>>> model = new_document(version=(24, 1, 0))
>>> rules = model["GlobalGeometryRules"].first()
>>> rules.coordinate_system = "Relative"
>>> zone = model.add("Zone", "Office", x_origin=10.0, y_origin=20.0, z_origin=0.0)
>>> wall = model.add("BuildingSurface:Detailed", "OfficeWall",
...     surface_type="Wall", zone_name="Office",
...     outside_boundary_condition="Outdoors", number_of_vertices=3,
...     vertices=[
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
...     ],
...     validate=False)
>>> translate_to_world(model)
>>> get_surface_coords(wall).vertices[0]
Vector3D(x=10.0, y=20.0, z=3.0)
>>> rules.coordinate_system
'World'

Source code in idfkit/geometry.py

def translate_to_world(doc: IDFDocument) -> None:
    """Rewrite every detailed surface's vertices into the frame the engine computes, in place.

    This is the mutating counterpart of [get_scene][idfkit.scene.get_scene], and it is that function
    that does the work: the polygons written back here are the ones the scene resolved, so the two
    cannot drift apart. The document, and not a copy, is what changes, which is what this function
    is for.

    BEHAVIOUR CHANGE, WITH THE MEASUREMENT THAT PROMPTED IT

    Until idfkit 1.0.0-rc.6 this function resolved coordinates by a rule that disagreed with
    EnergyPlus. Against the engine's own ``Output:Surfaces:List`` vertex report over seventeen of the
    shipped example models and five hundred and thirty-two surfaces, the old rule agreed with the
    engine on **five of the seventeen models**, worst case **201.98 m** of displacement. The rule it
    now applies agrees on **seventeen of seventeen**, worst case **0.0045 m**, against a report that
    prints two decimals. Three defects account for the difference:

    1. It rotated each surface by ``Building.north_axis`` inside its own zone frame, about the
       polygon's centroid. The engine turns the resolved building as one body about the world
       origin, and in the opposite sense: the north axis is measured clockwise from true north. Each
       surface therefore came out correctly oriented with its zone in the wrong place, a drawing that
       passes an eyeball test at up to 201.98 m of error.
    2. It translated by the zone origin without rotating that origin by the building axis first, so
       the two clauses composed in the wrong order.
    3. It collected a zone's surfaces with ``get_referencing(zone_name)``, which fenestration never
       matches: a window names its parent wall and not the zone, so no window was ever moved.

    The same defects measured on the corpus's own fixture set, which is what
    ``checks/geometry-vertices`` in ``idfkit-conformance`` now runs this function against: the old
    rule failed **60 of the 234 surfaces** over four of the seven fixtures, worst case **40.00 m**,
    and left a fifth unreadable by declaring the world system while leaving clockwise entry in
    place. The corrected rule fails none of them.

    Two further differences follow from the corrected rule rather than from a defect. A model
    declaring ``World`` is no longer returned from untouched: the building north axis applies to such
    a model too, and only the zone origin and the zone's relative north are conditional on the
    relative system. And a model declaring clockwise vertex entry has its rings reversed, the first
    vertex held in place, with ``GlobalGeometryRules`` restated as counter-clockwise, so that the
    right-hand rule gives the outward normal in the result.

    WHAT IT DOES NOT TOUCH, WHICH MATTERS FOR A MIXED MODEL

    Only the five detailed vertex types are read: ``BuildingSurface:Detailed``,
    ``FenestrationSurface:Detailed`` and the three detailed shading forms. The simplified surface
    family (``Wall:Exterior``, ``Window``, ``Roof`` and their siblings) and
    ``Daylighting:ReferencePoint`` state their geometry against the zone origin under their own
    coordinate-system fields, which this function does not read and cannot transform. Zeroing
    ``Building.north_axis`` at the end therefore leaves such objects unrotated in a document that no
    longer declares the rotation. A model holding both families is outside what this function can
    make consistent; [get_scene][idfkit.scene.get_scene] reports the types it did not attempt
    instead of editing the document, and is the better tool there.

    An object the scene could not place is not rewritten either, for the same reason and with the
    same consequence: its vertices stay as the author wrote them while the declarations they were
    written against are restated underneath it. Each one is logged at warning level, and
    [get_scene][idfkit.scene.get_scene] names them with a reason in ``Scene.unresolved``.

    Args:
        doc: the document to rewrite. Every surface the scene resolved has its vertices replaced,
            and the declarations those vertices were resolved against are restated so that reading
            the result back applies nothing a second time.

    Examples:
        A zone at (10, 20, 0) with one wall authored at the zone's own origin:

        >>> from idfkit import new_document
        >>> model = new_document(version=(24, 1, 0))
        >>> rules = model["GlobalGeometryRules"].first()
        >>> rules.coordinate_system = "Relative"
        >>> zone = model.add("Zone", "Office", x_origin=10.0, y_origin=20.0, z_origin=0.0)
        >>> wall = model.add("BuildingSurface:Detailed", "OfficeWall",
        ...     surface_type="Wall", zone_name="Office",
        ...     outside_boundary_condition="Outdoors", number_of_vertices=3,
        ...     vertices=[
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 3},
        ...         {"vertex_x_coordinate": 0, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...         {"vertex_x_coordinate": 5, "vertex_y_coordinate": 0, "vertex_z_coordinate": 0},
        ...     ],
        ...     validate=False)
        >>> translate_to_world(model)
        >>> get_surface_coords(wall).vertices[0]
        Vector3D(x=10.0, y=20.0, z=3.0)
        >>> rules.coordinate_system
        'World'
    """
    from .scene import get_scene

    scene = get_scene(doc)

    # Address a surface by its type and name together. A name is unique within a type and not
    # across them, and the scene reports both, so this is the pairing that finds the object the
    # scene resolved rather than one that happens to share its name.
    objects: dict[tuple[str, str], IDFObject] = {}
    for object_type in VERTEX_SURFACE_TYPES:
        if object_type not in doc:
            continue
        for obj in cast("IDFCollection[IDFObject]", doc[object_type]):
            objects[(object_type, obj.name.upper())] = obj

    for resolved in scene.surfaces:
        obj = objects.get((resolved.object_type, resolved.name.upper()))
        if obj is not None:
            set_surface_coords(obj, resolved.polygon)

    # An object the scene could not place keeps the vertices the author wrote, while the
    # declarations those vertices were written against are restated underneath it. It is therefore
    # read afterwards in a frame it was never stated in. This function cannot resolve what the scene
    # could not, but the rewritten document records nothing about the omission, so the omission is
    # reported here. ``get_scene`` reports the same objects with a reason and edits nothing.
    if scene.unresolved:
        logger.warning(
            "translate_to_world left %d object(s) in the frame they were authored in, because the "
            "scene could not place them: %s",
            len(scene.unresolved),
            ", ".join(f"{item.object_type} {item.name} ({item.reason})" for item in scene.unresolved),
        )

    _restate_resolved_declarations(
        doc, was_relative=scene.applied.is_relative, was_clockwise=scene.applied.is_clockwise
    )