floorplan-scene 0.1.0__py3-none-any.whl

floorplan_scene/model.py

@@ -0,0 +1,1072 @@
+"""Plan geometry and physical dimensions, plus optional SVG presentation data."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from copy import deepcopy
+from dataclasses import dataclass, replace
+from typing import Any, Literal, cast
+from urllib.parse import urlsplit
+
+from .presentation import FurniturePresentation, ScenePresentation, SvgDecoration
+from .shapes import (
+    GEOMETRY_TOLERANCE_MM,
+    ArcGeometry,
+    BayWindowGeometry,
+    CircleGeometry,
+    Curve,
+    Footprint,
+    Geometry,
+    Line,
+    LineGeometry,
+    PathGeometry,
+    PipeGeometry,
+    Point,
+    PolygonGeometry,
+    QuadraticGeometry,
+    Ring,
+)
+
+__all__ = ["ORIGIN_IMAGE_SCALE_REL_TOLERANCE", "SCHEMA", "SPACE_TYPES", "SPACE_TYPE_PATTERN",
+           "BayWindowParameters", "Building",
+           "DimensionAnnotation",
+           "FloorOpening", "FloorplanScene", "Footprint",
+           "Furniture", "FurniturePlacement", "InferenceMetadata", "InspectionHatchParameters", "JsonObject", "LevelMetadata", "Line", "Opening", "OpeningKind",
+           "OpeningSegment", "OriginImage", "Point", "Ring", "Room", "SceneEntity", "SceneMetadata",
+           "Separator", "Wall", "Zone",
+           "geometry_from_dict", "read_json", "scene_from_dict", "scene_to_dict"]
+
+OpeningKind = Literal["door", "window", "passage", "niche", "unknown"]
+JsonObject = dict[str, Any]
+DEFAULT_MM_DECIMALS = 3
+ORIGIN_IMAGE_SCALE_REL_TOLERANCE = 1e-3
+SCHEMA = "floorplan-scene"
+SPACE_TYPE_PATTERN = r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*"
+SPACE_TYPES = {
+    "living",
+    "dining",
+    "living_dining",
+    "bedroom",
+    "kitchen",
+    "bathroom",
+    "balcony",
+    "circulation",
+    "study",
+    "storage",
+    "closet",
+    "laundry",
+    "office",
+    "multipurpose",
+    "other",
+    "unknown",
+}
+DOOR_OPENING_TYPES = {
+    "DOOR", "DOUBLE_DOOR", "SLIDE_DOOR", "UNEQUAL_DOUBLE_DOOR", "SHUTTER_DOOR", "ARCHED_DOOR",
+}
+PASSAGE_OPENING_TYPES = {"PASS", "WALL_HOLE"}
+WINDOW_OPENING_TYPES = {
+    "WINDOW", "BAY_WINDOW", "ONE_SIDE_BAY_WINDOW", "TWO_SIDE_BAY_WINDOW", "FRENCH_WINDOW",
+    "HANDRAIL_WINDOW", "SLIDE_WINDOW", "SHUTTER_WINDOW", "TOP_HUNG_WINDOW", "ARCHED_WINDOW",
+    "ARC_WINDOW", "ROUND_WINDOW", "WINDOW_HOLE", "ALUMINUM_WINDOW",
+}
+OPENING_TYPES = DOOR_OPENING_TYPES | PASSAGE_OPENING_TYPES | WINDOW_OPENING_TYPES | {"NICHE"}
+OPEN_SIDES = {"LEFT", "RIGHT", "LEFT_INVERSE", "RIGHT_INVERSE"}
+
+
+def opening_kind(opening_type: str | None) -> OpeningKind:
+    if opening_type in DOOR_OPENING_TYPES:
+        return "door"
+    if opening_type in WINDOW_OPENING_TYPES:
+        return "window"
+    if opening_type in PASSAGE_OPENING_TYPES:
+        return "passage"
+    if opening_type == "NICHE":
+        return "niche"
+    return "unknown"
+
+
+@dataclass(frozen=True)
+class Room:
+    id: str
+    type: str
+    labelPoint: Point
+    geometry: PolygonGeometry | PathGeometry
+    name: str | None = None
+    area: float | None = None
+    roomTypeId: int | None = None
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+
+@dataclass(frozen=True)
+class Wall:
+    id: str
+    geometry: Geometry
+    thickness: float | None = None
+    loadBearing: bool = False
+    height: float | None = None
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+
+@dataclass(frozen=True)
+class Separator:
+    id: str
+    geometry: LineGeometry | ArcGeometry
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+
+@dataclass(frozen=True)
+class OpeningSegment:
+    geometry: LineGeometry | ArcGeometry
+    wallId: str | None
+    openSide: str | None = None
+    outside: float | None = None
+
+
+@dataclass(frozen=True)
+class Opening:
+    id: str
+    type: str | None
+    segments: tuple[OpeningSegment, ...]
+    height: float | None = None
+    bottomElevation: float | None = None
+    depth: float | None = None
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+    @property
+    def kind(self) -> OpeningKind:
+        return opening_kind(self.type)
+
+
+@dataclass(frozen=True)
+class FloorOpening:
+    """A through opening in the floor beneath this Scene's level."""
+
+    id: str
+    geometry: PolygonGeometry | PathGeometry | CircleGeometry
+    name: str | None = None
+    bottomElevation: float | None = None
+    thickness: float | None = None
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+    def __post_init__(self) -> None:
+        from .shape_geometry import geometry_shape
+
+        _text(self.id)
+        _label(self.name)
+        _dimension({"bottomElevation": self.bottomElevation}, "bottomElevation", signed=True)
+        _dimension({"thickness": self.thickness}, "thickness", positive=True)
+        if not isinstance(self.geometry, (PolygonGeometry, PathGeometry, CircleGeometry)):
+            raise TypeError("floor opening requires a polygon, closed path or circle")
+        if isinstance(self.geometry, CircleGeometry):
+            _point(list(self.geometry.center))
+            if _number(self.geometry.radius) <= 0:
+                raise ValueError("floor opening radius must be positive")
+        elif len(self.geometry.polygons) != 1 or not self.geometry.polygons[0]:
+            raise ValueError("floor opening requires one connected footprint")
+        shape = geometry_shape(self.geometry)
+        if shape.is_empty or not shape.is_valid or not math.isfinite(shape.area) or shape.area <= 0:
+            raise ValueError("floor opening requires a valid non-degenerate footprint")
+
+
+@dataclass(frozen=True)
+class BayWindowParameters:
+    beamThickness: float | None = None
+    upperFloorThickness: float | None = None
+    lowerFloorThickness: float | None = None
+    wallThickness: float | None = None
+    offset: float | None = None
+    windowHeight: float | None = None
+    platformType: str | None = None
+
+
+@dataclass(frozen=True)
+class InspectionHatchParameters:
+    """检修盖板的安装面与储物标注；不表示永久开洞或独立收纳家具。"""
+
+    # 未知安装面明确为 unknown；不能由平面投影猜测标高或楼板贯穿关系。
+    surface: str = "unknown"
+    # 仅在原图明确说明时填写；false 表示“収納庫なし”，None 表示未说明。
+    hasStorage: bool | None = None
+
+    def __post_init__(self) -> None:
+        _choice(self.surface, {"floor", "ceiling", "wall", "unknown"})
+        if self.hasStorage is not None and not isinstance(self.hasStorage, bool):
+            raise TypeError("inspection hatch hasStorage must be boolean or null")
+
+
+@dataclass(frozen=True)
+class Building:
+    """A physical building object; pillar shape belongs to geometry, not type."""
+
+    id: str
+    type: str
+    geometry: Geometry
+    height: float | None = None
+    bottomElevation: float | None = None
+    thickness: float | None = None
+    direction: Point | None = None
+    name: str | None = None
+    bayWindow: BayWindowParameters | None = None
+    ridgeLines: tuple[LineGeometry, ...] = ()
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+    # 仅 inspection_hatch 使用。Scene/SVG 保留，FPI/Legend 不支持时显式省略并告警。
+    inspectionHatch: InspectionHatchParameters | None = None
+
+    def __post_init__(self) -> None:
+        if self.type == "inspection_hatch":
+            if not isinstance(self.geometry, (PolygonGeometry, PathGeometry, CircleGeometry)):
+                raise TypeError("inspection hatch requires a closed panel projection")
+            if self.inspectionHatch is None:
+                object.__setattr__(self, "inspectionHatch", InspectionHatchParameters())
+        elif self.inspectionHatch is not None:
+            raise ValueError("inspectionHatch parameters belong only to inspection_hatch")
+        if self.type == "roof":
+            if not isinstance(self.geometry, PolygonGeometry) or len(self.geometry.polygons) != 1 or len(self.geometry.polygons[0]) != 1:
+                raise ValueError("roof requires one polygon projection without holes")
+            if self.direction is not None or self.bayWindow is not None:
+                raise ValueError("roof has no direction or bayWindow parameters")
+        elif self.ridgeLines:
+            raise ValueError("ridgeLines belong only to roof")
+        for ridge in self.ridgeLines:
+            if not isinstance(ridge, LineGeometry):
+                raise TypeError("roof ridgeLines require straight line segments")
+            _line([*ridge.start, *ridge.end])
+        # Normalize the previously emitted type at the shared Python/JSON/SVG entry point.
+        if self.type == "circle_pillar":
+            object.__setattr__(self, "type", "pillar")
+
+
+@dataclass(frozen=True)
+class FurniturePlacement:
+    center: Point
+    width: float
+    depth: float
+    rotation: float
+
+
+@dataclass(frozen=True)
+class Furniture:
+    id: str
+    type: str
+    placement: FurniturePlacement
+    geometry: PolygonGeometry
+    height: float | None = None
+    bottomElevation: float | None = None
+    thickness: float | None = None
+    name: str | None = None
+    shape: str | None = None
+    upStairDirections: tuple[JsonObject, ...] | None = None
+    path: tuple[Point, ...] | None = None
+    attributes: JsonObject | None = None
+    # SVG 专用局部外观；缺省不生成，FPI/Legend 导出忽略，不能代替 geometry。
+    presentation: FurniturePresentation | None = None
+
+
+@dataclass(frozen=True)
+class Zone:
+    id: str
+    name: str | None
+    geometry: PolygonGeometry
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+
+@dataclass(frozen=True)
+class DimensionAnnotation:
+    id: str
+    value: int
+    geometry: LineGeometry
+    refId: str | None = None
+    kind: Literal["linear"] = "linear"
+    # 模型额外观察与依据；非权威几何，保留于 Scene/SVG，不进入 FPI。
+    attributes: JsonObject | None = None
+
+
+@dataclass(frozen=True)
+class OriginImage:
+    url: str
+    pixelWidth: int
+    pixelHeight: int
+    sceneBounds: tuple[float, float, float, float]
+
+
+@dataclass(frozen=True)
+class InferenceMetadata:
+    model: str
+    reasoningEffort: str
+    sessionId: str
+    skillVersion: str
+    sourceAsset: str
+
+
+@dataclass(frozen=True)
+class LevelMetadata:
+    name: str
+    index: int | None = None
+
+
+@dataclass(frozen=True)
+class SceneMetadata:
+    originImage: OriginImage | None = None
+    inference: InferenceMetadata | None = None
+    level: LevelMetadata | None = None
+
+
+@dataclass(frozen=True)
+class FloorplanScene:
+    id: str
+    rooms: tuple[Room, ...] = ()
+    walls: tuple[Wall, ...] = ()
+    separators: tuple[Separator, ...] = ()
+    openings: tuple[Opening, ...] = ()
+    buildings: tuple[Building, ...] = ()
+    furniture: tuple[Furniture, ...] = ()
+    unit: str = "mm"
+    height: float | None = None
+    zones: tuple[Zone, ...] = ()
+    dimensionAnnotations: tuple[DimensionAnnotation, ...] = ()
+    metadata: SceneMetadata | None = None
+    floorOpenings: tuple[FloorOpening, ...] = ()
+    # SVG 文档画布；不等于原图定位或交互相机，参见 ScenePresentation。
+    presentation: ScenePresentation | None = None
+
+
+SceneEntity = Room | Wall | Separator | Opening | FloorOpening | Building | Furniture | Zone | DimensionAnnotation
+
+
+def _object(value: Any, required: str, optional: str = "") -> JsonObject:
+    if not isinstance(value, dict):
+        raise TypeError("expected an object")
+    missing = set(required.split()) - value.keys()
+    extra = value.keys() - set((required + " " + optional).split())
+    if missing or extra:
+        raise ValueError(f"missing fields {sorted(missing)}; unexpected fields {sorted(extra)}")
+    return value
+
+
+def _json_attributes(value: Any) -> JsonObject | None:
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise TypeError("entity attributes must be an object")
+    # JSON only: preserve extra model semantics without admitting non-finite values.
+    json.dumps(value, allow_nan=False)
+    return deepcopy(value)
+
+
+def _stair_directions(value: Any) -> tuple[JsonObject, ...] | None:
+    if value is None:
+        return None
+    directions = []
+    for entry in _array(value):
+        row = _object(entry, "rotationAngle", "ascendSide")
+        directions.append({"rotationAngle": _number(row["rotationAngle"]),
+                           **({"ascendSide": _label(row["ascendSide"])} if "ascendSide" in row else {})})
+    return tuple(directions)
+
+
+def _array(value: Any) -> list[Any]:
+    if not isinstance(value, list):
+        raise TypeError("expected an array")
+    return value
+
+
+def _text(value: Any) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("expected a non-empty string")
+    return value
+
+
+def _label(value: Any) -> str | None:
+    if value is not None and not isinstance(value, str):
+        raise TypeError("label must be a string or null")
+    return value
+
+
+def _choice(value: Any, options: set[str]) -> str:
+    text = _text(value)
+    if text not in options:
+        raise ValueError(f"expected one of {sorted(options)}, got {text!r}")
+    return text
+
+
+def _space_type(value: Any) -> str:
+    text = _text(value)
+    if re.fullmatch(SPACE_TYPE_PATTERN, text) is None:
+        raise ValueError("room type must use lowercase snake case")
+    return text
+
+
+def _number(value: Any) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise ValueError("expected a finite number")
+    return float(value)
+
+
+def _integer(value: Any) -> int:
+    number = _number(value)
+    if not number.is_integer():
+        raise ValueError("expected an integer")
+    return int(number)
+
+
+def _boolean(value: Any) -> bool:
+    if not isinstance(value, bool):
+        raise TypeError("expected a boolean")
+    return value
+
+
+def _origin_url(value: Any) -> str:
+    text = _text(value)
+    url = urlsplit(text)
+    if url.scheme not in {"http", "https"} or not url.netloc or url.username or url.password:
+        raise ValueError("origin image URL must use HTTP(S) without embedded credentials")
+    return text
+
+
+def _point(value: Any) -> Point:
+    points = _array(value)
+    if len(points) != 2:
+        raise ValueError("point must have exactly two coordinates")
+    return _number(points[0]), _number(points[1])
+
+
+def _line(value: Any) -> Line:
+    values = _array(value)
+    if len(values) != 4:
+        raise ValueError("line must contain x1, y1, x2 and y2")
+    start, end = (_number(values[0]), _number(values[1])), (_number(values[2]), _number(values[3]))
+    if start == end:
+        raise ValueError("zero-length segment")
+    return start, end
+
+
+def _ring(value: Any) -> Ring:
+    points = tuple(_point(point) for point in _array(value))
+    if len(points) < 3 or points[0] == points[-1]:
+        raise ValueError("polygon rings use at least three points and close implicitly")
+    return (*points, points[0])
+
+
+def _footprint(value: Any) -> Footprint:
+    polygons = tuple(tuple(_ring(ring) for ring in _array(polygon)) for polygon in _array(value))
+    if not polygons or any(not poly for poly in polygons):
+        raise ValueError("footprint must contain polygons with exterior rings")
+    return polygons
+
+
+def _dimension(row: JsonObject, key: str, *, positive: bool = False, signed: bool = False) -> float | None:
+    if row.get(key) is None:
+        return None
+    value = _number(row[key])
+    if (value < 0 and not signed) or (positive and value == 0):
+        raise ValueError(f"{key} must be {'positive' if positive else 'non-negative'}")
+    return value
+
+
+def geometry_from_dict(value: Any) -> Geometry:
+    if not isinstance(value, dict):
+        raise TypeError("shape must be an object")
+    if len(value) != 1:
+        raise ValueError("shape must contain exactly one geometry key")
+    kind, raw = next(iter(value.items()))
+    if kind == "line":
+        start, end = _line(raw)
+        return LineGeometry(start, end)
+    if kind in {"arc", "quadratic"}:
+        extra = "bulge" if kind == "arc" else "control"
+        row = _object(raw, f"start end {extra}")
+        start, end = _point(row["start"]), _point(row["end"])
+        if start == end:
+            raise ValueError("zero-length segment")
+        if kind == "arc":
+            return ArcGeometry(start, end, _number(row["bulge"]))
+        return QuadraticGeometry(start, _point(row["control"]), end)
+    if kind == "polygon":
+        return PolygonGeometry(((_ring(raw),),))
+    if kind == "polygons":
+        return PolygonGeometry(_footprint(raw))
+    if kind == "path":
+        polygons = []
+        for raw_polygon in _array(raw):
+            rings = []
+            for raw_ring in _array(raw_polygon):
+                edges = [geometry_from_dict(edge) for edge in _array(raw_ring)]
+                if not edges or any(not isinstance(edge, (LineGeometry, ArcGeometry, QuadraticGeometry))
+                                    for edge in edges):
+                    raise ValueError("path rings must contain line, arc or quadratic edges")
+                curves = cast(list[Curve], edges)
+                if any(math.dist(edge.end, curves[(i + 1) % len(curves)].start) > GEOMETRY_TOLERANCE_MM
+                       for i, edge in enumerate(curves)):
+                    raise ValueError("path edges must form connected closed rings")
+                rings.append(tuple(curves))
+            if not rings:
+                raise ValueError("path polygon must contain an exterior ring")
+            polygons.append(tuple(rings))
+        if not polygons:
+            raise ValueError("path must contain polygons")
+        return PathGeometry(tuple(polygons))
+    if kind == "circle":
+        row = _object(raw, "center radius")
+        radius = _dimension(row, "radius", positive=True)
+        if radius is None:
+            raise ValueError("circle radius is required")
+        return CircleGeometry(_point(row["center"]), radius)
+    if kind == "pipe":
+        row = _object(raw, "center width depth angle profile wallThickness")
+        profile = cast(Literal["L", "U", "RECT"], _choice(row["profile"], {"L", "U", "RECT"}))
+        widths = tuple(_number(v) for v in _array(row["wallThickness"]))
+        if len(widths) != {"L": 2, "U": 3, "RECT": 4}[profile] or any(v <= 0 for v in widths):
+            raise ValueError("pipe wallThickness must contain positive widths for its profile")
+        width, depth = _dimension(row, "width", positive=True), _dimension(row, "depth", positive=True)
+        if width is None or depth is None:
+            raise ValueError("pipe width and depth are required")
+        return PipeGeometry(_point(row["center"]), width, depth, _number(row["angle"]), profile, widths)
+    if kind == "bayWindow":
+        row = _object(raw, "outline wallPath profile")
+        outline = _ring(row["outline"])
+        wall_path = tuple(_point(p) for p in _array(row["wallPath"]))
+        if len(wall_path) < 2:
+            raise ValueError("bay window wallPath requires at least two points")
+        bay_profile = _choice(row["profile"], {"SHAPE_I", "SHAPE_L", "SHAPE_U", "SHAPE_AUTO"})
+        return BayWindowGeometry(outline, wall_path, bay_profile)
+    raise ValueError(f"unsupported geometry type: {kind!r}")
+
+
+def _furniture_presentation(value: Any) -> FurniturePresentation | None:
+    if value is None:
+        return None
+    row = _object(value, "", "decorations footprintStyle footprintIndex")
+    decorations = []
+    for item in _array(row.get("decorations", [])):
+        primitive = _object(item, "tag attributes")
+        decorations.append(SvgDecoration(primitive["tag"], deepcopy(primitive["attributes"])))
+    return FurniturePresentation(tuple(decorations), deepcopy(row.get("footprintStyle", {})),
+                                 row.get("footprintIndex", 0))
+
+
+def scene_from_dict(payload: Any) -> FloorplanScene:
+    """Reject malformed output, unknown fields and dangling references; do not repair it."""
+    data = _object(
+        payload,
+        "id units rooms",
+        "height walls separators openings floorOpenings buildings furniture zones dimensionAnnotations metadata presentation",
+    )
+    units = _object(data["units"], "length area angle")
+    if units != {"length": "mm", "area": "m2", "angle": "deg"}:
+        raise ValueError("units must use millimetres, square metres and degrees")
+    scene_height = _dimension(data, "height")
+    metadata = None
+    if data.get("metadata") is not None:
+        metadata_row = _object(data["metadata"], "", "originImage inference level")
+        origin = None
+        if "originImage" in metadata_row:
+            origin_row = _object(metadata_row["originImage"], "url pixelWidth pixelHeight sceneBounds")
+            pixel_width, pixel_height = _integer(origin_row["pixelWidth"]), _integer(origin_row["pixelHeight"])
+            bounds_values = _array(origin_row["sceneBounds"])
+            if pixel_width <= 0 or pixel_height <= 0:
+                raise ValueError("origin image pixel dimensions must be positive")
+            if len(bounds_values) != 4:
+                raise ValueError("origin image sceneBounds must contain x, y, width and height")
+            bounds = tuple(_number(value) for value in bounds_values)
+            if bounds[2] <= 0 or bounds[3] <= 0:
+                raise ValueError("origin image Scene width and height must be positive")
+            if not math.isclose(
+                bounds[2] / pixel_width,
+                bounds[3] / pixel_height,
+                rel_tol=ORIGIN_IMAGE_SCALE_REL_TOLERANCE,
+            ):
+                raise ValueError("origin image must use one pixel-to-millimetre scale")
+            origin = OriginImage(_origin_url(origin_row["url"]), pixel_width, pixel_height,
+                                 cast(tuple[float, float, float, float], bounds))
+        inference = None
+        if "inference" in metadata_row:
+            inference_row = _object(metadata_row["inference"],
+                                    "model reasoningEffort sessionId skillVersion sourceAsset")
+            inference = InferenceMetadata(*(_text(inference_row[key]) for key in
+                                           ("model", "reasoningEffort", "sessionId", "skillVersion", "sourceAsset")))
+        level = None
+        if "level" in metadata_row:
+            level_row = _object(metadata_row["level"], "name", "index")
+            level = LevelMetadata(_text(level_row["name"]),
+                                  _integer(level_row["index"]) if "index" in level_row else None)
+        metadata = SceneMetadata(origin, inference, level)
+    entity_attributes = {}
+    data = deepcopy(data)
+    for collection in ("rooms", "walls", "separators", "openings", "floorOpenings", "buildings",
+                       "furniture", "zones", "dimensionAnnotations"):
+        for entity in _array(data.get(collection, [])):
+            if isinstance(entity, dict) and "attributes" in entity:
+                entity_attributes[entity.get("id")] = _json_attributes(entity.pop("attributes"))
+    rooms = []
+    for value in _array(data["rooms"]):
+        row = _object(value, "id type labelPoint geometry", "name area roomTypeId")
+        geometry = geometry_from_dict(row["geometry"])
+        if not isinstance(geometry, (PolygonGeometry, PathGeometry)) or len(geometry.polygons) != 1:
+            raise TypeError("room geometry must contain one polygon or curved footprint")
+        rooms.append(
+            Room(
+                _text(row["id"]),
+                _space_type(row["type"]),
+                _point(row["labelPoint"]),
+                geometry,
+                _label(row.get("name")),
+                _dimension(row, "area", positive=True),
+                _integer(row["roomTypeId"]) if "roomTypeId" in row else None,
+            )
+        )
+    walls = []
+    for value in _array(data.get("walls", [])):
+        row = _object(value, "id geometry", "thickness loadBearing height")
+        shape = geometry_from_dict(row["geometry"])
+        if isinstance(shape, (PipeGeometry, BayWindowGeometry)):
+            raise TypeError("pipe and bay window shapes belong to building obstacles")
+        walls.append(
+            Wall(
+                _text(row["id"]),
+                shape,
+                _dimension(row, "thickness", positive=True),
+                _boolean(row.get("loadBearing", False)),
+                _dimension(row, "height") if "height" in row else scene_height,
+            )
+        )
+    separators = []
+    for value in _array(data.get("separators", [])):
+        row = _object(value, "id geometry")
+        geometry = geometry_from_dict(row["geometry"])
+        if not isinstance(geometry, (LineGeometry, ArcGeometry)):
+            raise TypeError("separator geometry must be a line or circular arc")
+        separators.append(Separator(_text(row["id"]), geometry))
+    openings = []
+    for value in _array(data.get("openings", [])):
+        row = _object(value, "id type segments", "height bottomElevation depth")
+        source_type = row["type"]
+        if source_type is not None:
+            source_type = _choice(source_type, OPENING_TYPES)
+        segments = []
+        for value in _array(row["segments"]):
+            segment = _object(value, "geometry wallId", "openSide outside")
+            geometry = geometry_from_dict(segment["geometry"])
+            if not isinstance(geometry, (LineGeometry, ArcGeometry)):
+                raise TypeError("opening segment geometry must be a line or circular arc")
+            host = segment["wallId"]
+            open_side = segment.get("openSide")
+            segments.append(
+                OpeningSegment(
+                    geometry,
+                    None if host is None else _text(host),
+                    _choice(open_side, OPEN_SIDES) if open_side is not None else None,
+                    _number(segment["outside"]) if segment.get("outside") is not None else None,
+                )
+            )
+        if not 1 <= len(segments) <= 3:
+            raise ValueError("opening requires one to three segments")
+        if source_type == "NICHE":
+            if (
+                len(segments) != 1
+                or segments[0].openSide is not None
+                or segments[0].outside is not None
+            ):
+                raise ValueError("niche requires one segment without openSide/outside")
+        elif len(segments) == 1:
+            if source_type is None:
+                raise ValueError("ordinary opening requires type")
+            if segments[0].outside is not None:
+                raise ValueError("ordinary single-segment opening has no outside field")
+        elif row.get("depth") is not None:
+            raise ValueError("composite opening has no depth field")
+        openings.append(
+            Opening(
+                _text(row["id"]),
+                source_type,
+                tuple(segments),
+                _dimension(row, "height"),
+                _dimension(row, "bottomElevation", signed=True),
+                _dimension(row, "depth"),
+            )
+        )
+    floor_openings = []
+    for value in _array(data.get("floorOpenings", [])):
+        row = _object(value, "id geometry", "name bottomElevation thickness")
+        geometry = geometry_from_dict(row["geometry"])
+        if not isinstance(geometry, (PolygonGeometry, PathGeometry, CircleGeometry)):
+            raise TypeError("floor opening requires a polygon, closed path or circle")
+        floor_openings.append(FloorOpening(
+            _text(row["id"]), geometry, _label(row.get("name")),
+            _dimension(row, "bottomElevation", signed=True), _dimension(row, "thickness", positive=True),
+        ))
+    buildings = []
+    for value in _array(data.get("buildings", [])):
+        row = _object(
+            value,
+            "id type geometry",
+            "height bottomElevation thickness direction name bayWindow ridgeLines inspectionHatch",
+        )
+        hatch = None
+        if row.get("inspectionHatch") is not None:
+            hatch = InspectionHatchParameters(**_object(row["inspectionHatch"], "", "surface hasStorage"))
+        bay = None
+        if row.get("bayWindow") is not None:
+            params = _object(row["bayWindow"], "", "beamThickness upperFloorThickness lowerFloorThickness "
+                             "wallThickness offset windowHeight platformType")
+            platform = params.get("platformType")
+            bay = BayWindowParameters(
+                _dimension(params, "beamThickness"), _dimension(params, "upperFloorThickness"),
+                _dimension(params, "lowerFloorThickness"), _dimension(params, "wallThickness"),
+                _dimension(params, "offset", signed=True), _dimension(params, "windowHeight"),
+                None if platform is None else _choice(platform, {"BOTTOM_ONLY", "TOP_ONLY", "ALL"}),
+            )
+        buildings.append(
+            Building(
+                _text(row["id"]),
+                _text(row["type"]),
+                geometry_from_dict(row["geometry"]),
+                _dimension(row, "height"),
+                _dimension(row, "bottomElevation", signed=True),
+                _dimension(row, "thickness", positive=True),
+                _point(row["direction"]) if row.get("direction") is not None else None,
+                _label(row.get("name")),
+                bay,
+                tuple(LineGeometry(*_line(line)) for line in _array(row.get("ridgeLines", []))),
+                inspectionHatch=hatch,
+            )
+        )
+    furniture = []
+    for value in _array(data.get("furniture", [])):
+        row = _object(
+            value,
+            "id type placement geometry",
+            "height bottomElevation thickness name shape upStairDirections path attributes presentation",
+        )
+        placement_row = _object(row["placement"], "center width depth rotation")
+        width = _dimension(placement_row, "width", positive=True)
+        depth = _dimension(placement_row, "depth", positive=True)
+        rotation = _number(placement_row["rotation"])
+        if width is None or depth is None:
+            raise ValueError("furniture placement width and depth are required")
+        if not 0 <= rotation < 360:
+            raise ValueError("furniture placement rotation must be in [0, 360) degrees")
+        geometry = geometry_from_dict(row["geometry"])
+        if not isinstance(geometry, PolygonGeometry):
+            raise TypeError("furniture geometry must be a polygon in placement-local coordinates")
+        furniture.append(
+            Furniture(
+                _text(row["id"]),
+                _text(row["type"]),
+                FurniturePlacement(_point(placement_row["center"]), width, depth, rotation),
+                geometry,
+                _dimension(row, "height"),
+                _dimension(row, "bottomElevation", signed=True),
+                _dimension(row, "thickness", positive=True),
+                _label(row.get("name")),
+                _label(row.get("shape")),
+                _stair_directions(row.get("upStairDirections")),
+                tuple(_point(point) for point in _array(row["path"])) if row.get("path") is not None else None,
+                _json_attributes(row.get("attributes")),
+                _furniture_presentation(row.get("presentation")),
+            )
+        )
+    zones = []
+    for value in _array(data.get("zones", [])):
+        row = _object(value, "id geometry", "name")
+        shape = geometry_from_dict(row["geometry"])
+        if not isinstance(shape, PolygonGeometry):
+            raise TypeError("zone geometry must be a polygon")
+        zones.append(Zone(_text(row["id"]), _label(row.get("name")), shape))
+    dimension_annotations = []
+    for value in _array(data.get("dimensionAnnotations", [])):
+        row = _object(value, "id kind value geometry", "refId")
+        geometry = geometry_from_dict(row["geometry"])
+        if not isinstance(geometry, LineGeometry):
+            raise TypeError("dimension annotation geometry must be a line")
+        annotation_value = _integer(row["value"])
+        if annotation_value <= 0:
+            raise ValueError("dimension annotation value must be a positive integer")
+        dimension_annotations.append(DimensionAnnotation(
+            _text(row["id"]), annotation_value, geometry,
+            _text(row["refId"]) if row.get("refId") is not None else None,
+            cast(Literal["linear"], _choice(row["kind"], {"linear"})),
+        ))
+    referenced_entities: list[SceneEntity] = [
+        *rooms, *walls, *separators, *openings, *floor_openings, *buildings, *furniture, *zones,
+    ]
+    entities: list[SceneEntity] = [*referenced_entities, *dimension_annotations]
+    ids = [item.id for item in entities]
+    if len(ids) != len(set(ids)):
+        raise ValueError("duplicate entity ids")
+    wall_ids = {wall.id for wall in walls}
+    if any(
+        segment.wallId is not None and segment.wallId not in wall_ids
+        for opening in openings
+        for segment in opening.segments
+    ):
+        raise ValueError("opening references an unknown host wall")
+    entity_ids = {item.id for item in referenced_entities}
+    if any(item.refId is not None and item.refId not in entity_ids for item in dimension_annotations):
+        raise ValueError("dimension annotation references an unknown entity")
+    return FloorplanScene(
+        _text(data["id"]),
+        rooms=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in rooms),
+        walls=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in walls),
+        separators=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in separators),
+        openings=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in openings),
+        floorOpenings=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in floor_openings),
+        buildings=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in buildings),
+        furniture=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in furniture),
+        height=scene_height,
+        zones=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in zones),
+        dimensionAnnotations=tuple(replace(item, attributes=entity_attributes.get(item.id)) for item in dimension_annotations),
+        metadata=metadata,
+        presentation=(ScenePresentation(tuple(_array(_object(data["presentation"], "viewBox")["viewBox"])))
+                      if data.get("presentation") is not None else None),
+    )
+
+
+def quantize_mm(value: float) -> float:
+    """Normalize millimeter values to the default 1e-3 mm grid."""
+    result = round(value, DEFAULT_MM_DECIMALS)
+    return 0.0 if result == 0 else result
+
+
+def scene_to_dict(scene: FloorplanScene) -> JsonObject:
+    def point(value: Point) -> list[float]:
+        return [value[0], value[1]]
+
+    def line(value: LineGeometry) -> list[float]:
+        return [*value.start, *value.end]
+
+    def ring(value: Ring) -> list[list[float]]:
+        return [point(item) for item in value[:-1]]
+
+    def footprint(value: Footprint) -> list[list[list[list[float]]]]:
+        return [[ring(item) for item in polygon] for polygon in value]
+
+    def shape(value: Geometry) -> JsonObject:
+        if isinstance(value, LineGeometry):
+            return {"line": line(value)}
+        if isinstance(value, ArcGeometry):
+            return {"arc": {"start": point(value.start), "end": point(value.end), "bulge": value.bulge}}
+        if isinstance(value, QuadraticGeometry):
+            return {"quadratic": {"start": point(value.start), "control": point(value.control),
+                                   "end": point(value.end)}}
+        if isinstance(value, PolygonGeometry):
+            if len(value.polygons) == 1 and len(value.polygons[0]) == 1:
+                return {"polygon": ring(value.polygons[0][0])}
+            return {"polygons": footprint(value.polygons)}
+        if isinstance(value, PathGeometry):
+            return {"path": [[[shape(edge) for edge in curve_ring] for curve_ring in polygon]
+                             for polygon in value.polygons]}
+        if isinstance(value, CircleGeometry):
+            return {"circle": {"center": point(value.center), "radius": value.radius}}
+        if isinstance(value, PipeGeometry):
+            return {"pipe": {"center": point(value.center), "width": value.width, "depth": value.depth,
+                             "angle": value.angle, "profile": value.profile,
+                             "wallThickness": list(value.wallThickness)}}
+        return {"bayWindow": {"outline": ring(value.outline), "wallPath": [point(p) for p in value.wallPath],
+                              "profile": value.profile}}
+
+    def optional(row: JsonObject, obj: Any, names: tuple[str, ...]) -> None:
+        for name in names:
+            value = getattr(obj, name)
+            if value is not None:
+                row[name] = value
+
+    data: JsonObject = {"id": scene.id, "units": {"length": scene.unit, "area": "m2", "angle": "deg"}}
+    if scene.height is not None:
+        data["height"] = scene.height
+    if scene.presentation is not None:
+        data["presentation"] = {"viewBox": list(scene.presentation.viewBox)}
+    if scene.metadata is not None:
+        origin, inference, level = scene.metadata.originImage, scene.metadata.inference, scene.metadata.level
+        metadata_row: JsonObject = {}
+        if origin is not None:
+            metadata_row["originImage"] = {"url": origin.url, "pixelWidth": origin.pixelWidth,
+                                           "pixelHeight": origin.pixelHeight, "sceneBounds": list(origin.sceneBounds)}
+        if inference is not None:
+            metadata_row["inference"] = {"model": inference.model, "reasoningEffort": inference.reasoningEffort,
+                                         "sessionId": inference.sessionId, "skillVersion": inference.skillVersion,
+                                         "sourceAsset": inference.sourceAsset}
+        if level is not None:
+            metadata_row["level"] = {"name": level.name}
+            if level.index is not None:
+                metadata_row["level"]["index"] = level.index
+        data["metadata"] = metadata_row
+    data["rooms"] = []
+    for room in scene.rooms:
+        room_row: JsonObject = {
+            "id": room.id,
+            "type": room.type,
+            "labelPoint": point(room.labelPoint),
+            "geometry": shape(room.geometry),
+        }
+        optional(room_row, room, ("name", "area", "roomTypeId"))
+        data["rooms"].append(room_row)
+    walls: list[JsonObject] = []
+    for wall in scene.walls:
+        wall_row: JsonObject = {"id": wall.id, "geometry": shape(wall.geometry)}
+        optional(wall_row, wall, ("thickness",))
+        if wall.loadBearing:
+            wall_row["loadBearing"] = True
+        if wall.height != scene.height:
+            wall_row["height"] = wall.height
+        walls.append(wall_row)
+    if walls:
+        data["walls"] = walls
+    if scene.separators:
+        data["separators"] = [
+            {"id": separator.id, "geometry": shape(separator.geometry)}
+            for separator in scene.separators
+        ]
+    if scene.openings:
+        data["openings"] = []
+        for opening in scene.openings:
+            opening_row: JsonObject = {"id": opening.id, "type": opening.type}
+            optional(opening_row, opening, ("height", "depth"))
+            if opening.bottomElevation is not None:
+                opening_row["bottomElevation"] = opening.bottomElevation
+            segments: list[JsonObject] = []
+            for source_segment in opening.segments:
+                segment: JsonObject = {"geometry": shape(source_segment.geometry), "wallId": source_segment.wallId}
+                optional(segment, source_segment, ("openSide", "outside"))
+                segments.append(segment)
+            opening_row["segments"] = segments
+            data["openings"].append(opening_row)
+    if scene.floorOpenings:
+        data["floorOpenings"] = []
+        for floor_opening in scene.floorOpenings:
+            floor_row: JsonObject = {"id": floor_opening.id, "geometry": shape(floor_opening.geometry)}
+            optional(floor_row, floor_opening, ("name", "bottomElevation", "thickness"))
+            data["floorOpenings"].append(floor_row)
+    buildings: list[JsonObject] = []
+    for building in scene.buildings:
+        building_row: JsonObject = {
+            "id": building.id,
+            "type": building.type,
+            "geometry": shape(building.geometry),
+        }
+        optional(building_row, building, ("height", "thickness", "name"))
+        if building.bottomElevation is not None:
+            building_row["bottomElevation"] = building.bottomElevation
+        if building.type == "roof":
+            building_row.update(height=building.height, bottomElevation=building.bottomElevation,
+                                thickness=building.thickness,
+                                ridgeLines=[[*point(line.start), *point(line.end)] for line in building.ridgeLines])
+        if building.direction is not None:
+            building_row["direction"] = point(building.direction)
+        if building.bayWindow is not None:
+            params: JsonObject = {}
+            optional(params, building.bayWindow, ("beamThickness", "upperFloorThickness", "lowerFloorThickness",
+                                                  "wallThickness", "offset", "windowHeight", "platformType"))
+            building_row["bayWindow"] = params
+        if building.inspectionHatch is not None:
+            hatch_params: JsonObject = {"surface": building.inspectionHatch.surface}
+            optional(hatch_params, building.inspectionHatch, ("hasStorage",))
+            building_row["inspectionHatch"] = hatch_params
+        buildings.append(building_row)
+    if buildings:
+        data["buildings"] = buildings
+    if scene.furniture:
+        data["furniture"] = []
+        for item in scene.furniture:
+            row: JsonObject = {
+                "id": item.id,
+                "type": item.type,
+                "placement": {
+                    "center": point(item.placement.center),
+                    "width": item.placement.width,
+                    "depth": item.placement.depth,
+                    "rotation": item.placement.rotation,
+                },
+                "geometry": shape(item.geometry),
+            }
+            optional(row, item, ("height", "thickness", "name"))
+            if item.bottomElevation is not None:
+                row["bottomElevation"] = item.bottomElevation
+            if item.shape is not None:
+                row["shape"] = item.shape
+            if item.upStairDirections is not None:
+                row["upStairDirections"] = deepcopy(list(item.upStairDirections))
+            if item.path is not None:
+                row["path"] = [point(value) for value in item.path]
+            if item.attributes is not None:
+                row["attributes"] = deepcopy(item.attributes)
+            if item.presentation is not None:
+                row["presentation"] = {
+                    "decorations": [{"tag": value.tag, "attributes": deepcopy(value.attributes)}
+                                    for value in item.presentation.decorations],
+                    "footprintStyle": deepcopy(item.presentation.footprintStyle),
+                    "footprintIndex": item.presentation.footprintIndex,
+                }
+            data["furniture"].append(row)
+    if scene.zones:
+        data["zones"] = []
+        for zone in scene.zones:
+            row = {"id": zone.id, "geometry": shape(zone.geometry)}
+            if zone.name is not None:
+                row["name"] = zone.name
+            data["zones"].append(row)
+    if scene.dimensionAnnotations:
+        data["dimensionAnnotations"] = []
+        for dimension in scene.dimensionAnnotations:
+            row = {
+                "id": dimension.id,
+                "kind": dimension.kind,
+                "value": dimension.value,
+                "geometry": shape(dimension.geometry),
+            }
+            if dimension.refId is not None:
+                row["refId"] = dimension.refId
+            data["dimensionAnnotations"].append(row)
+
+    for collection in ("rooms", "walls", "separators", "openings", "floorOpenings", "buildings",
+                       "furniture", "zones", "dimensionAnnotations"):
+        for entity, row in zip(getattr(scene, collection), data.get(collection, [])):
+            if entity.attributes is not None:
+                row["attributes"] = _json_attributes(entity.attributes)
+
+    def compact_numbers(value: Any, unit: str = "length") -> Any:
+        if isinstance(value, dict):
+            return {
+                key: deepcopy(item) if key == "attributes" else compact_numbers(
+                    item,
+                    "area" if key == "area" else "native" if key in {"angle", "bulge", "direction", "rotation"} else unit,
+                )
+                for key, item in value.items()
+            }
+        if isinstance(value, list):
+            return [compact_numbers(item, unit) for item in value]
+        if isinstance(value, float):
+            if unit == "area":
+                value = round(value, 2)
+            elif unit == "length":
+                value = quantize_mm(value)
+            return int(value) if value.is_integer() else value
+        return value
+
+    return cast(JsonObject, compact_numbers(data))
+
+
+def read_json(text: str) -> JsonObject:
+    def reject_constant(value: str) -> None:
+        raise ValueError(f"non-finite JSON number: {value}")
+
+    def unique(pairs: list[tuple[str, Any]]) -> JsonObject:
+        result: JsonObject = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError(f"duplicate JSON key: {key}")
+            result[key] = value
+        return result
+
+    value = json.loads(text, object_pairs_hook=unique, parse_constant=reject_constant)
+    if not isinstance(value, dict):
+        raise TypeError("expected a JSON object")
+    return value