floorplan-scene 0.1.0__py3-none-any.whl

floorplan_scene/fpi.py

@@ -0,0 +1,1145 @@
+"""FPI/Legend adapters. Source attributes stay in a separate, bound supplement."""
+
+from __future__ import annotations
+
+import math
+import warnings
+from collections import defaultdict
+from copy import deepcopy
+from dataclasses import asdict, dataclass
+from typing import cast
+
+from .component_defaults import component_defaults
+from .fpi_geometry import (
+    building_geometry,
+    building_to_fpi,
+    line_geometry,
+    line_to_fpi,
+    optional_number,
+    point_dict,
+    polygon_geometry,
+    polygon_to_fpi,
+    source_points,
+    wall_geometry,
+    wall_to_fpi,
+)
+from .fpi_geometry import source_point as _xy
+from .furniture import (
+    LEGEND_SHAPES,
+    LEGEND_TYPES,
+    LEGEND_TYPES_SUPPORTED,
+    complete_legend_fields,
+    furniture_type,
+    legend_required_fields_missing,
+    legend_type_attributes,
+    require_stair_direction,
+)
+from .geometry import Issue, opening_host_issues, snap_openings_to_hosts
+from .model import (
+    OPENING_TYPES,
+    BayWindowParameters,
+    Building,
+    FloorplanScene,
+    Furniture,
+    FurniturePlacement,
+    JsonObject,
+    Opening,
+    OpeningKind,
+    OpeningSegment,
+    Point,
+    Room,
+    SceneEntity,
+    Separator,
+    Wall,
+    Zone,
+    _boolean,
+    _number,
+    _point,
+    opening_kind,
+    scene_from_dict,
+    scene_to_dict,
+)
+from .shape_geometry import (
+    arc_subsegment,
+    geometry_shape,
+    local_furniture_geometry,
+    placed_furniture_geometry,
+)
+from .shapes import (
+    GEOMETRY_TOLERANCE_MM,
+    ArcGeometry,
+    BayWindowGeometry,
+    CircleGeometry,
+    Geometry,
+    LineGeometry,
+    PolygonGeometry,
+)
+
+BUILDING_TYPES = {
+    "pillars": "pillar",
+    "circlePillars": "pillar",
+    "flues": "flue",
+    "beams": "beam",
+    "placeHolders": "placeholder",
+    "pipeWalls": "pipe_wall",
+    "bayWindowSills": "bay_window_sill",
+}
+BUILDING_COLLECTIONS = set(BUILDING_TYPES)
+FPI_COLLECTIONS = {
+    "walls",
+    "roomSeparators",
+    "rooms",
+    "holes",
+    "compositeHoles",
+    "niches",
+    "zones",
+    *BUILDING_COLLECTIONS,
+}
+BAY_WINDOW_FIELDS = {
+    "beamThickness",
+    "upperFloorThickness",
+    "lowerFloorThickness",
+    "wallThickness",
+    "offset",
+    "windowHeight",
+    "platformType",
+}
+GEOMETRY_FIELDS = {
+    "start",
+    "end",
+    "position",
+    "center",
+    "thickness",
+    "polygon",
+    "wallPolygon",
+    "shape",
+    "outlinePolygon",
+    "bbox",
+    "hostId",
+    "holeSegments",
+    "bulge",
+    "control",
+    "edges",
+    "height",
+    "z",
+    "sillHeight",
+    "groundClearance",
+    "depth",
+    "width",
+    "diameter",
+    "angle",
+    "direction",
+    "openSide",
+    "outside",
+    *BAY_WINDOW_FIELDS,
+}
+ROOM_IDS = {
+    "living": 1,
+    "dining": 3,
+    "living_dining": 22,
+    "bedroom": 15,
+    "kitchen": 7,
+    "bathroom": 8,
+    "balcony": 13,
+    "circulation": 14,
+    "other": 0,
+    "unknown": 31,
+    "study": 6,
+    "storage": 18,
+    "closet": 19,
+    "laundry": 27,
+    "office": 28,
+    "multipurpose": 9,
+}
+CUSTOM_ROOM_TYPE_ID = 17
+ROOM_TYPE_BY_ID = {
+    0: "other",
+    1: "living",
+    2: "circulation",
+    3: "living",
+    4: "bedroom",
+    5: "bedroom",
+    6: "other",
+    7: "kitchen",
+    8: "bathroom",
+    9: "living",
+    10: "bedroom",
+    11: "bedroom",
+    12: "bedroom",
+    13: "balcony",
+    14: "circulation",
+    15: "bedroom",
+    16: "circulation",
+    17: "other",
+    18: "other",
+    19: "other",
+    20: "other",
+    21: "living",
+    22: "living",
+    23: "balcony",
+    24: "living",
+    25: "other",
+    26: "circulation",
+    27: "other",
+    28: "other",
+    29: "other",
+    30: "other",
+    31: "other",
+    32: "other",
+    33: "bedroom",
+    34: "living",
+    35: "other",
+    36: "circulation",
+    37: "balcony",
+    38: "balcony",
+    39: "other",
+    40: "bathroom",
+    41: "bathroom",
+    42: "kitchen",
+    43: "kitchen",
+}
+ROOM_TYPE_NAME_TOKENS = (
+    ("卫生间", "bathroom"),
+    ("主卫", "bathroom"),
+    ("次卫", "bathroom"),
+    ("客卫", "bathroom"),
+    ("中厨", "kitchen"),
+    ("西厨", "kitchen"),
+    ("厨房", "kitchen"),
+    ("景观阳台", "balcony"),
+    ("生活阳台", "balcony"),
+    ("露台", "balcony"),
+    ("阳台", "balcony"),
+    ("儿童房", "bedroom"),
+    ("主卧", "bedroom"),
+    ("次卧", "bedroom"),
+    ("客房", "bedroom"),
+    ("客卧", "bedroom"),
+    ("老人房", "bedroom"),
+    ("保姆房", "bedroom"),
+    ("卧室", "bedroom"),
+    ("多功能室", "living"),
+    ("起居室", "living"),
+    ("影视间", "living"),
+    ("健身房", "living"),
+    ("客餐厅", "living_dining"),
+    ("客厅", "living"),
+    ("餐厅", "dining"),
+    ("走道", "circulation"),
+    ("过道", "circulation"),
+    ("玄关", "circulation"),
+    ("门厅", "circulation"),
+    ("楼梯间", "circulation"),
+)
+
+
+def _items(value: JsonObject, key: str) -> list[JsonObject]:
+    raw = value.get(key, [])
+    if raw is None:
+        return []
+    if not isinstance(raw, list) or any(not isinstance(item, dict) for item in raw):
+        raise ValueError(f"{key} must be an object array")
+    return raw
+
+
+def _extract_floorplan(fpi: JsonObject, level_index: int, floorplan_index: int) -> JsonObject:
+    if level_index < 0 or floorplan_index < 0:
+        raise ValueError("level_index and floorplan_index must be non-negative")
+    direct = fpi.get("floorPlan")
+    if isinstance(direct, dict):
+        return direct
+    if (
+        "floorPlan" not in fpi
+        and "levels" not in fpi
+        and (
+            not fpi
+            or FPI_COLLECTIONS.intersection(fpi)
+            or {"name", "communityName", "city", "province", "height"}.intersection(fpi)
+        )
+    ):
+        return fpi
+    try:
+        floorplan = fpi["levels"][level_index]["fpiFloorPlans"][floorplan_index]
+    except (KeyError, IndexError, TypeError) as exc:
+        raise ValueError("expected floorPlan or levels[*].fpiFloorPlans[*] in FPI JSON") from exc
+    if not isinstance(floorplan, dict):
+        raise TypeError("selected FPI floor plan must be an object")
+    return floorplan
+
+
+def _room_kind(room: JsonObject) -> str:
+    room_type_id = room.get("roomTypeId")
+    mapped = ROOM_TYPE_BY_ID.get(room_type_id) if isinstance(room_type_id, int) else None
+    if mapped is not None:
+        return mapped
+    name = str(room.get("name") or "").strip()
+    if name == "走廊":
+        return "circulation"
+    return next((kind for token, kind in ROOM_TYPE_NAME_TOKENS if token in name), "other")
+
+
+def _inverse_transform(fpi: JsonObject) -> list[list[float]]:
+    transforms = fpi.get("transforms") or []
+    try:
+        matrix = transforms[0]["inverseMatrix"]
+        if len(matrix) != 3 or any(len(row) != 3 for row in matrix):
+            raise ValueError
+        return [[_number(value) for value in row] for row in matrix]
+    except (IndexError, KeyError, TypeError, ValueError) as exc:
+        raise ValueError("FPI export must contain a 3x3 transforms[0].inverseMatrix") from exc
+
+
+def _transform_point(matrix: list[list[float]], point: Point) -> Point:
+    x, y = point
+    denominator = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2]
+    if abs(denominator) < 1e-12:
+        raise ValueError("invalid inverse transform denominator")
+    return (
+        _number((matrix[0][0] * x + matrix[0][1] * y + matrix[0][2]) / denominator),
+        _number((matrix[1][0] * x + matrix[1][1] * y + matrix[1][2]) / denominator),
+    )
+
+
+def _legend_placement(item: JsonObject) -> FurniturePlacement:
+    bbox = item["bbox"]
+    if not isinstance(bbox, dict):
+        raise TypeError("Legend bbox must be an object")
+    center = _xy(bbox["center"])
+    width, depth = _number(bbox["width"]), _number(bbox["height"])
+    rotation = _number(bbox.get("rotationAngle", 0))
+    if width <= 0 or depth <= 0:
+        raise ValueError("Legend bbox width and height must be finite and positive")
+    return FurniturePlacement(center, width, depth, rotation % 360)
+
+
+def _transform_placement(
+    matrix: list[list[float]],
+    placement: FurniturePlacement,
+) -> FurniturePlacement:
+    angle = math.radians(placement.rotation)
+    center = _transform_point(matrix, placement.center)
+    width_point = _transform_point(
+        matrix,
+        (placement.center[0] + math.cos(angle) * placement.width / 2,
+         placement.center[1] + math.sin(angle) * placement.width / 2),
+    )
+    depth_point = _transform_point(
+        matrix,
+        (placement.center[0] - math.sin(angle) * placement.depth / 2,
+         placement.center[1] + math.cos(angle) * placement.depth / 2),
+    )
+    rotation = math.degrees(math.atan2(width_point[1] - center[1], width_point[0] - center[0])) % 360
+    return FurniturePlacement(
+        center,
+        2 * math.dist(center, width_point),
+        2 * math.dist(center, depth_point),
+        rotation,
+    )
+
+
+def _item_polygon_points(
+    item: JsonObject,
+    placement: FurniturePlacement,
+) -> tuple[list[tuple[float, float]], str]:
+    outline = item.get("outlinePolygon") or []
+    if len(outline) >= 3:
+        return (
+            [
+                _xy(point) if isinstance(point, dict) else (float(point[0]), float(point[1]))
+                for point in outline
+            ],
+            "source_outline_polygon",
+        )
+    center = placement.center
+    width, depth = placement.width, placement.depth
+    angle = math.radians(placement.rotation)
+    cosine, sine = math.cos(angle), math.sin(angle)
+    points = [
+        (
+            center[0] + dx * cosine - dy * sine,
+            center[1] + dx * sine + dy * cosine,
+        )
+        for dx, dy in (
+            (-width / 2, -depth / 2),
+            (width / 2, -depth / 2),
+            (width / 2, depth / 2),
+            (-width / 2, depth / 2),
+        )
+    ]
+    return points, "rotated_bounding_box"
+
+
+@dataclass(frozen=True)
+class FpiSupplement:
+    sceneId: str
+    frameId: str
+    planAttributes: JsonObject
+    bindings: JsonObject
+    additionalRoomLabels: tuple[JsonObject, ...]
+    excludedLegend: tuple[JsonObject, ...]
+    furnitureCoverage: str
+    issues: tuple[Issue, ...]
+
+
+@dataclass(frozen=True)
+class FpiImport:
+    scene: FloorplanScene
+    supplement: FpiSupplement
+
+
+def _graph_ring(value: object, label: str) -> tuple[Point, ...]:
+    if not isinstance(value, list) or len(value) < 3:
+        raise ValueError(f"{label} must contain at least three points")
+    ring = tuple(_xy(point) for point in value)
+    return ring if ring[0] == ring[-1] else (*ring, ring[0])
+
+
+def _graph_room_data(graph: JsonObject | None, floorplan_index: int) -> dict[str, JsonObject]:
+    if graph is None:
+        return {}
+    frame = graph.get("geometryFrame")
+    if not isinstance(frame, dict) or frame.get("lengthUnit") != "mm" or frame.get("millimetersPerUnit") != 1:
+        raise ValueError("withGraph geometryFrame must use millimeters")
+    graph_index = graph.get("floorPlanIndex")
+    if graph_index is not None and graph_index != floorplan_index:
+        raise ValueError("withGraph floorPlanIndex does not match the selected FPI")
+    segments: dict[str, tuple[Point, ...]] = {}
+    for segment in _items(graph, "roomBoundarySegments"):
+        key = segment.get("key")
+        segment_points = segment.get("points")
+        if not isinstance(key, str) or not key or key in segments:
+            raise ValueError("withGraph room boundary segment keys must be unique strings")
+        if not isinstance(segment_points, list) or len(segment_points) < 2:
+            raise ValueError(f"withGraph segment {key} must contain at least two points")
+        segments[key] = tuple(_xy(point) for point in segment_points)
+    result: dict[str, JsonObject] = {}
+    for source in _items(graph, "roomOutlines"):
+        room_key = source.get("roomKey")
+        if not isinstance(room_key, str) or not room_key or room_key in result:
+            raise ValueError("withGraph roomKey values must be unique strings")
+        rings = [_graph_ring(source.get("outline"), f"withGraph outline {room_key}")]
+        contours = source.get("contours", [])
+        if not isinstance(contours, list) or any(not isinstance(item, dict) for item in contours):
+            raise ValueError(f"withGraph contours {room_key} must be an object array")
+        for contour in contours:
+            if contour.get("role") != "hole":
+                continue
+            keys = contour.get("boundarySegmentKeys")
+            if not isinstance(keys, list) or not keys or any(not isinstance(key, str) for key in keys):
+                raise ValueError(f"withGraph hole contour {room_key} has invalid segment keys")
+            hole_points: list[Point] = []
+            for key in keys:
+                if key not in segments:
+                    raise ValueError(f"withGraph hole contour {room_key} references missing segment {key}")
+                part = segments[key]
+                if hole_points and math.dist(hole_points[-1], part[0]) > GEOMETRY_TOLERANCE_MM:
+                    raise ValueError(f"withGraph hole contour {room_key} is not contiguous")
+                hole_points.extend(part if not hole_points else part[1:])
+            if len(hole_points) < 4 or math.dist(hole_points[0], hole_points[-1]) > GEOMETRY_TOLERANCE_MM:
+                raise ValueError(f"withGraph hole contour {room_key} is not closed")
+            hole_points[-1] = hole_points[0]
+            rings.append(tuple(hole_points))
+        area = source.get("area")
+        if area is not None:
+            area = _number(area)
+            if area <= 0:
+                raise ValueError(f"withGraph area {room_key} must be positive")
+        result[room_key] = {
+            "outline": tuple(rings),
+            "cellKey": source.get("cellKey"),
+            "faceId": source.get("faceId"),
+            "areaM2": area,
+            "confidence": source.get("confidence"),
+        }
+    return result
+
+
+def _room_type(source: JsonObject) -> str:
+    room_type = source.get("roomTypeId")
+    if room_type is not None and (isinstance(room_type, bool) or not isinstance(room_type, int)):
+        raise ValueError("roomTypeId must be an integer when supplied")
+    exact_type = next((kind for kind, type_id in ROOM_IDS.items() if type_id == room_type), None)
+    return exact_type if exact_type is not None else _room_kind(source)
+
+
+def _opening_kind(source: JsonObject) -> OpeningKind:
+    source_type = source.get("type")
+    if source_type is not None and (not isinstance(source_type, str) or source_type not in OPENING_TYPES - {"NICHE"}):
+        raise ValueError(f"unsupported FPI opening type: {source_type!r}")
+    return opening_kind(source_type)
+
+
+def import_fpi(
+    fpi: JsonObject,
+    legend: JsonObject | None = None,
+    *,
+    graph: JsonObject | None = None,
+    scene_id: str,
+    frame_id: str,
+    level_index: int = 0,
+    floorplan_index: int = 0,
+) -> FpiImport:
+    plan = _extract_floorplan(fpi, level_index, floorplan_index)
+    graph_rooms = _graph_room_data(graph, floorplan_index)
+    source_rooms = _items(plan, "rooms")
+    expected_room_keys = {f"room:{room.get('id')}" for room in source_rooms}
+    if graph is not None and set(graph_rooms) != expected_room_keys:
+        raise ValueError("withGraph room keys must exactly match the selected FPI rooms")
+    for key, value in plan.items():
+        if isinstance(value, list) and value and key not in FPI_COLLECTIONS:
+            raise ValueError(f"unsupported non-empty FPI collection: {key}")
+    bindings: JsonObject = {}
+    source_ids: dict[str, set[str]] = defaultdict(set)
+
+    def bind(entity_id: str, collection: str, source: JsonObject) -> None:
+        source_id = source.get("id")
+        if isinstance(source_id, bool) or not isinstance(source_id, (str, int)) or not str(source_id):
+            raise ValueError(f"{collection} requires a string or integer source id")
+        if str(source_id) in source_ids[collection]:
+            raise ValueError(f"duplicate {collection} id: {source_id}")
+        source_ids[collection].add(str(source_id))
+        bindings[entity_id] = {
+            "collection": collection,
+            "sourceId": source_id,
+            "attributes": deepcopy(
+                {k: v for k, v in source.items() if k not in GEOMETRY_FIELDS and k != "id"}
+            ),
+        }
+
+    walls: list[Wall] = []
+    separators: list[Separator] = []
+    wall_ids: dict[str, str] = {}
+    for collection, prefix in (("walls", "W"), ("roomSeparators", "V")):
+        for index, source in enumerate(_items(plan, collection), 1):
+            entity_id = f"{prefix}{index}"
+            bind(entity_id, collection, source)
+            thickness = optional_number(source, "thickness") if collection == "walls" else None
+            load_bearing = source.get("loadBearingWall") if collection == "walls" else None
+            if collection == "walls":
+                walls.append(
+                    Wall(
+                        entity_id,
+                        wall_geometry(source),
+                        thickness,
+                        False if load_bearing is None else _boolean(load_bearing),
+                        optional_number(source, "height"),
+                    )
+                )
+                wall_ids[str(source["id"])] = entity_id
+            else:
+                separators.append(Separator(entity_id, line_geometry(source)))
+    openings: list[Opening] = []
+
+    def host_id(source: JsonObject) -> str | None:
+        value = source.get("hostId")
+        if value is None:
+            return None
+        if str(value) not in wall_ids:
+            raise ValueError(f"unknown FPI hostId: {value}")
+        return wall_ids[str(value)]
+
+    walls_by_id = {wall.id: wall for wall in walls}
+
+    def opening_geometry(source: JsonObject) -> LineGeometry | ArcGeometry:
+        line = line_geometry(source)
+        wall = walls_by_id.get(host_id(source) or "")
+        if wall is not None and isinstance(wall.geometry, ArcGeometry) and wall.geometry.bulge != 0:
+            return arc_subsegment(wall.geometry, line.start, line.end)
+        return line
+
+    for collection in ("holes", "compositeHoles", "niches"):
+        for source in _items(plan, collection):
+            entity_id = f"O{len(openings) + 1}"
+            bind(entity_id, collection, source)
+            source_parts = _items(source, "holeSegments") if collection == "compositeHoles" else [source]
+            source_type = "NICHE" if collection == "niches" else source.get("type")
+            if collection == "holes" and source_type is None:
+                raise ValueError("ordinary FPI hole requires type")
+            if collection != "niches":
+                _opening_kind(source)
+            openings.append(
+                Opening(
+                    entity_id,
+                    source_type,
+                    tuple(
+                        OpeningSegment(
+                            opening_geometry(part),
+                            host_id(part),
+                            part.get("openSide"),
+                            optional_number(part, "outside"),
+                        )
+                        for part in source_parts
+                    ),
+                    optional_number(source, "height"),
+                    optional_number(source, "sillHeight")
+                    if source.get("sillHeight") is not None
+                    else optional_number(source, "groundClearance")
+                    if collection == "holes"
+                    else None,
+                    optional_number(source, "depth") if collection != "compositeHoles" else None,
+                )
+            )
+            if collection == "compositeHoles":
+                bindings[entity_id]["segmentAttributes"] = [
+                    {k: deepcopy(v) for k, v in segment.items() if k not in GEOMETRY_FIELDS}
+                    for segment in source_parts
+                ]
+    rooms: list[Room] = []
+    additional_room_labels: list[JsonObject] = []
+    issues: list[Issue] = []
+    for index, source in enumerate(source_rooms, 1):
+        entity_id = f"R{index}"
+        bind(entity_id, "rooms", source)
+        room_key = f"room:{source['id']}"
+        room_data = graph_rooms.get(room_key)
+        if room_data is None:
+            raise ValueError(f"withGraph did not return an outline for {room_key}")
+        rooms.append(
+            Room(
+                entity_id,
+                _room_type(source),
+                _xy(source["position"]),
+                PolygonGeometry((cast(tuple[tuple[Point, ...], ...], room_data["outline"]),)),
+                str(source.get("name") or "").strip() or None,
+                cast(float | None, room_data.get("areaM2")),
+                source.get("roomTypeId"),
+            )
+        )
+        bindings[entity_id]["geometryMethod"] = "withGraph"
+        bindings[entity_id]["geometryConfidence"] = room_data.get("confidence")
+    buildings: list[Building] = []
+    for collection in sorted(BUILDING_COLLECTIONS):
+        for source in _items(plan, collection):
+            entity_id = f"B{len(buildings) + 1}"
+            bind(entity_id, collection, source)
+            parameters = None
+            if collection == "bayWindowSills" and any(
+                source.get(key) is not None for key in BAY_WINDOW_FIELDS
+            ):
+                parameters = BayWindowParameters(
+                    beamThickness=optional_number(source, "beamThickness"),
+                    upperFloorThickness=optional_number(source, "upperFloorThickness"),
+                    lowerFloorThickness=optional_number(source, "lowerFloorThickness"),
+                    wallThickness=optional_number(source, "wallThickness"),
+                    offset=optional_number(source, "offset"),
+                    windowHeight=optional_number(source, "windowHeight"),
+                    platformType=source.get("platformType"),
+                )
+            buildings.append(
+                Building(
+                    entity_id,
+                    BUILDING_TYPES[collection],
+                    building_geometry(collection, source),
+                    height=optional_number(source, "height")
+                    if collection in {"beams", "pipeWalls", "placeHolders"}
+                    else None,
+                    bottomElevation=optional_number(source, "sillHeight")
+                    if collection == "placeHolders"
+                    else None,
+                    thickness=optional_number(source, "thickness") if collection == "beams" else None,
+                    direction=_xy(source["direction"])
+                    if collection == "placeHolders" and source.get("direction") is not None
+                    else None,
+                    name=source.get("name") if collection == "placeHolders" else None,
+                    bayWindow=parameters,
+                )
+            )
+    zones: list[Zone] = []
+    for index, source in enumerate(_items(plan, "zones"), 1):
+        entity_id = f"Z{index}"
+        bind(entity_id, "zones", source)
+        zones.append(
+            Zone(entity_id, source.get("name"), polygon_geometry(source_points(source.get("polygon"))))
+        )
+    if legend is not None and not isinstance(legend.get("items"), list):
+        raise ValueError("provided Legend must contain an items array; null is not an observed empty list")
+    items = _items(legend, "items") if legend is not None else []
+    matrix = None
+    if items and legend is not None and legend.get("coordinateSystem") not in {None, "fpi_mm"}:
+        raise ValueError("unsupported Legend coordinateSystem")
+    excluded: list[JsonObject] = []
+    furniture: list[Furniture] = []
+    furniture_count = 0
+    for source in items:
+        entity_id = f"F{furniture_count + 1}"
+        bind(entity_id, "legend", source)
+        kind = furniture_type(source)
+        if kind is None:
+            excluded.append(deepcopy(source))
+            del bindings[entity_id]
+            issues.append(Issue(
+                "filtered_furniture_type", None,
+                f"Legend {source['id']}: unrecognized furniture type.", "warning",
+            ))
+            continue
+        try:
+            outline = source.get("outlinePolygon")
+            if outline:
+                if not isinstance(outline, list) or len(outline) < 3:
+                    raise ValueError("Legend outlinePolygon must have at least three points")
+                for point in outline:
+                    _xy(point) if isinstance(point, dict) else _point(point)
+            placement = _legend_placement(source)
+            points, method = _item_polygon_points(source, placement)
+            if matrix is None and legend is not None and legend.get("coordinateSystem") != "fpi_mm":
+                matrix = _inverse_transform(fpi)
+            if matrix is not None:
+                points = [_transform_point(matrix, point) for point in points]
+                placement = _transform_placement(matrix, placement)
+            if method == "rotated_bounding_box" and matrix is None:
+                local_points = (
+                    (-placement.width / 2, -placement.depth / 2),
+                    (placement.width / 2, -placement.depth / 2),
+                    (placement.width / 2, placement.depth / 2),
+                    (-placement.width / 2, placement.depth / 2),
+                )
+                geometry = polygon_geometry(local_points)
+            else:
+                geometry = local_furniture_geometry(polygon_geometry(tuple(points)), placement)
+        except (KeyError, IndexError, TypeError, ValueError, OverflowError) as exc:
+            raise ValueError(f"Legend {source['id']}: invalid footprint") from exc
+        bindings[entity_id]["geometryMethod"] = method
+        bindings[entity_id]["geometryConfidence"] = (
+            "exact" if method == "source_outline_polygon" else "derived"
+        )
+        bindings[entity_id]["typeMethod"] = "legend_category"
+        bindings[entity_id]["typeConfidence"] = "derived"
+        path = source.get("path")
+        local_path = None
+        if path is not None:
+            world_path = [_xy(point) if isinstance(point, dict) else _point(point) for point in path]
+            if matrix is not None:
+                world_path = [_transform_point(matrix, point) for point in world_path]
+            local_path = local_furniture_geometry(
+                PolygonGeometry(((tuple(world_path),),)), placement,
+            ).polygons[0][0]
+        directions = deepcopy(source.get("upStairDirections"))
+        if directions is not None and matrix is not None:
+            original_placement = _legend_placement(source)
+            x, y = original_placement.center
+            denominator = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2]
+            determinant = sum(
+                matrix[0][i] * (matrix[1][(i + 1) % 3] * matrix[2][(i + 2) % 3]
+                                - matrix[1][(i + 2) % 3] * matrix[2][(i + 1) % 3])
+                for i in range(3)
+            )
+            mirrored = determinant / denominator ** 3 < 0
+            for direction in directions:
+                # Legend directions use the same world-angle convention as its bbox.
+                direction["rotationAngle"] = _transform_placement(
+                    matrix, FurniturePlacement(original_placement.center, 1, 1,
+                                               _number(direction["rotationAngle"])),
+                ).rotation
+                if mirrored and direction.get("ascendSide") in {"LEFT", "RIGHT"}:
+                    direction["ascendSide"] = {"LEFT": "RIGHT", "RIGHT": "LEFT"}[direction["ascendSide"]]
+        furniture.append(Furniture(entity_id, kind, placement, geometry,
+                                   shape=source.get("shape"), upStairDirections=directions, path=local_path))
+        furniture_count += 1
+    scene = scene_from_dict(
+        scene_to_dict(
+            FloorplanScene(
+                scene_id,
+                rooms=tuple(rooms),
+                walls=tuple(walls),
+                separators=tuple(separators),
+                openings=tuple(openings),
+                buildings=tuple(buildings),
+                furniture=tuple(furniture),
+                height=optional_number(plan, "height"),
+                zones=tuple(zones),
+            )
+        )
+    )
+    supplement = FpiSupplement(
+        scene.id,
+        frame_id,
+        deepcopy({k: v for k, v in plan.items() if k not in FPI_COLLECTIONS and k != "height"}),
+        bindings,
+        tuple(additional_room_labels),
+        tuple(excluded),
+        "filtered" if excluded else "provided" if legend is not None else "unavailable",
+        tuple(issues),
+    )
+    return FpiImport(scene, supplement)
+
+
+def export_fpi(
+    scene: FloorplanScene,
+    supplement: FpiSupplement | None = None,
+    *,
+    base_scene: FloorplanScene | None = None,
+    diagnostics: list[JsonObject] | None = None,
+    mm_per_pixel: float | None = None,
+) -> tuple[JsonObject, JsonObject]:
+    """Translate representable objects; room closure and spatial analysis are separate checks."""
+    scene_from_dict(scene_to_dict(scene))
+    if mm_per_pixel is not None and (not math.isfinite(mm_per_pixel) or mm_per_pixel <= 0):
+        raise ValueError("mm_per_pixel must be finite and positive")
+    if diagnostics is None:
+        diagnostics = []
+    scene = snap_openings_to_hosts(scene, max(1.0, mm_per_pixel or 1.0), diagnostics)
+    host_issues = [issue for issue in opening_host_issues(scene) if issue.code != "missing_host"]
+    if host_issues:
+        raise ValueError("invalid scene geometry: " + ", ".join(issue.code for issue in host_issues))
+    bindings: JsonObject = {}
+    plan: JsonObject = {}
+    if supplement is not None:
+        base = base_scene or scene
+        if supplement.sceneId != base.id:
+            raise ValueError("FPI supplement does not match the base scene")
+        bindings = supplement.bindings
+        plan = deepcopy(supplement.planAttributes)
+    for collection in sorted(FPI_COLLECTIONS):
+        plan[collection] = []
+    plan.pop("height", None)
+    if scene.height is not None:
+        plan["height"] = scene.height
+    reserved = {str(item["sourceId"]) for item in bindings.values()}
+    if supplement is not None:
+        reserved.update(str(item["source"]["id"]) for item in supplement.additionalRoomLabels)
+    next_id = 1
+    ids: dict[str, str | int] = {}
+    entities: tuple[SceneEntity, ...] = (
+        *scene.walls,
+        *scene.separators,
+        *scene.rooms,
+        *scene.openings,
+        *scene.buildings,
+        *scene.furniture,
+        *scene.zones,
+    )
+    for entity in entities:
+        if entity.id in bindings:
+            ids[entity.id] = bindings[entity.id]["sourceId"]
+        else:
+            while str(next_id) in reserved:
+                next_id += 1
+            ids[entity.id] = next_id
+            reserved.add(str(next_id))
+
+    def attrs(entity_id: str, collections: set[str]) -> JsonObject:
+        binding = bindings.get(entity_id)
+        if binding is not None and binding["collection"] not in collections:
+            raise ValueError(f"{entity_id} changed object family; use a new id")
+        attributes = binding["attributes"] if binding else {}
+        return {
+            **deepcopy({key: value for key, value in attributes.items() if key not in GEOMETRY_FIELDS}),
+            "id": ids[entity_id],
+        }
+
+    def optional_attrs(item: JsonObject, **values: object) -> None:
+        for key, value in values.items():
+            item.pop(key, None)
+            if value is not None:
+                item[key] = value
+
+    def unsupported(item: Building | Furniture, allowed: set[str]) -> None:
+        fields = {"height", "bottomElevation", "thickness", "name"} - allowed
+        if isinstance(item, Building):
+            fields |= {"direction", "bayWindow"} - allowed
+        extra = [field for field in sorted(fields) if getattr(item, field) is not None]
+        if extra:
+            raise ValueError(f"{item.id}: {item.type} has no ordinary FPI/Legend fields for {extra}")
+
+    for wall in scene.walls:
+        item = attrs(wall.id, {"walls"})
+        item.pop("type", None)
+        item.update(wall_to_fpi(wall.geometry), loadBearingWall=wall.loadBearing)
+        optional_attrs(item, thickness=wall.thickness, height=wall.height)
+        plan["walls"].append(item)
+    for separator in scene.separators:
+        item = attrs(separator.id, {"roomSeparators"})
+        item.pop("type", None)
+        geometry = separator.geometry
+        if isinstance(geometry, ArcGeometry):
+            warnings.warn(
+                f"separator_arc_to_chord: {separator.id}: FPI roomSeparators stores only endpoints; "
+                "exporting the arc as a straight chord, losing curvature",
+                UserWarning,
+                stacklevel=2,
+            )
+            geometry = LineGeometry(geometry.start, geometry.end)
+        item.update(line_to_fpi(geometry))
+        plan["roomSeparators"].append(item)
+    base_room_types = {room.id: room.type for room in (base_scene or scene).rooms}
+    additional_by_room = {
+        str(item["roomId"])
+        for item in (supplement.additionalRoomLabels if supplement is not None else ())
+    }
+    unchanged_rooms: set[str] = set()
+    for room in scene.rooms:
+        item = attrs(room.id, {"rooms"})
+        unchanged = room.type == base_room_types.get(room.id)
+        preserve_source_labels = unchanged and room.id in additional_by_room
+        room_type_id = ROOM_IDS.get(room.type, CUSTOM_ROOM_TYPE_ID)
+        if room.roomTypeId is not None:
+            item["roomTypeId"] = room.roomTypeId
+        elif room.id not in bindings or (
+            not preserve_source_labels and _room_type(item) != room.type
+        ):
+            item["roomTypeId"] = room_type_id
+        optional_attrs(item, name=room.name)
+        item.update(position=point_dict(room.labelPoint))
+        plan["rooms"].append(item)
+        if unchanged:
+            unchanged_rooms.add(room.id)
+    if supplement is not None:
+        plan["rooms"].extend(
+            deepcopy(item["source"])
+            for item in supplement.additionalRoomLabels
+            if str(item["roomId"]) in unchanged_rooms
+        )
+    for opening in scene.openings:
+        item = attrs(opening.id, {"holes", "compositeHoles", "niches"})
+        item.pop("type", None)
+        if opening.kind != "niche":
+            if opening.type is not None:
+                item["type"] = opening.type
+            elif opening.kind != "unknown":
+                item["type"] = {"door": "DOOR", "window": "WINDOW", "passage": "PASS"}[opening.kind]
+            if _opening_kind(item) != opening.kind:
+                raise ValueError(f"{opening.id}: opening kind disagrees with its FPI type")
+        optional_attrs(item, height=opening.height, sillHeight=opening.bottomElevation)
+        segment_attrs = bindings.get(opening.id, {}).get("segmentAttributes", [])
+        segments = []
+        for index, source_part in enumerate(opening.segments):
+            source_attributes = segment_attrs[index] if index < len(segment_attrs) else {}
+            part = deepcopy(
+                {key: value for key, value in source_attributes.items() if key not in GEOMETRY_FIELDS}
+            )
+            geometry = source_part.geometry
+            host = next((wall for wall in scene.walls if wall.id == source_part.wallId), None)
+            host_arc = host.geometry if host is not None and isinstance(host.geometry, ArcGeometry) else None
+            if isinstance(geometry, ArcGeometry) and geometry.bulge != 0 and (
+                host_arc is None or host_arc.bulge == 0
+            ):
+                raise ValueError(f"{opening.id}: FPI arc opening requires an arc host wall")
+            if host_arc is not None and host_arc.bulge != 0:
+                restored = arc_subsegment(host_arc, geometry.start, geometry.end)
+                if geometry_shape(restored).hausdorff_distance(geometry_shape(geometry)) > GEOMETRY_TOLERANCE_MM:
+                    raise ValueError(f"{opening.id}: FPI opening must follow its host arc; cannot preserve this curve")
+            part.update(start=point_dict(geometry.start), end=point_dict(geometry.end))
+            optional_attrs(
+                part,
+                hostId=ids[source_part.wallId] if source_part.wallId is not None else None,
+                openSide=source_part.openSide,
+                outside=source_part.outside,
+            )
+            segments.append(part)
+        if opening.kind == "niche":
+            if (
+                len(segments) != 1
+                or opening.segments[0].openSide is not None
+                or opening.segments[0].outside is not None
+            ):
+                raise ValueError(f"{opening.id}: niche requires one segment without openSide/outside")
+            item.update(segments[0])
+            optional_attrs(item, depth=opening.depth)
+            plan["niches"].append(item)
+            continue
+        composite = len(segments) > 1 or any(part.outside is not None for part in opening.segments)
+        if composite:
+            if not 2 <= len(segments) <= 3:
+                raise ValueError(f"{opening.id}: ordinary FPI compositeHole requires two or three segments")
+            if opening.depth is not None:
+                raise ValueError(f"{opening.id}: compositeHole has no depth field")
+            item["holeSegments"] = segments
+        else:
+            item.update(segments[0])
+            optional_attrs(item, depth=opening.depth)
+        plan["compositeHoles" if composite else "holes"].append(item)
+    for floor_opening in scene.floorOpenings:
+        warnings.warn(
+            f"floor_opening_omitted: {floor_opening.id}: floor opening is retained in Scene/SVG only; omitted from FPI",
+            UserWarning, stacklevel=2,
+        )
+    def component_geometry(geometry: Geometry, entity_id: str) -> Geometry:
+        if isinstance(geometry, PolygonGeometry) and any(len(rings) > 1 for rings in geometry.polygons):
+            diagnostics.append({"code": "component_holes_filled", "entityId": entity_id,
+                                "holeCount": sum(len(rings) - 1 for rings in geometry.polygons)})
+            return PolygonGeometry(tuple((rings[0],) for rings in geometry.polygons))
+        return geometry
+
+    for building in scene.buildings:
+        if building.type in {"roof", "inspection_hatch"}:
+            if building.type == "inspection_hatch" and diagnostics is not None:
+                diagnostics.append({
+                    "code": "inspection_hatch_omitted", "entityId": building.id,
+                    "sourceType": building.type, "targetType": None,
+                    "lostFields": ["geometry", "inspectionHatch"],
+                })
+            warnings.warn(f"{building.type}_omitted: {building.id}: {building.type} is retained in Scene/SVG only; omitted from FPI",
+                          UserWarning, stacklevel=2)
+            continue
+        building_collection: str | None
+        if building.type == "pillar":
+            # FPI splits one Scene semantic type into two geometry-specific collections.
+            building_collection = "circlePillars" if isinstance(building.geometry, CircleGeometry) else "pillars"
+        else:
+            building_collection = next(
+                (key for key, kind in BUILDING_TYPES.items() if kind == building.type), None
+            )
+        if building.type in {"pipe_shaft", "service_shaft", "building_element"}:
+            building_collection = "placeHolders"
+        fallback = building_collection is None
+        if building_collection is None:
+            building_collection = "placeHolders"
+            lost = ["type"] + [key for key in ("thickness", "bayWindow") if getattr(building, key) is not None]
+            diagnostics.append({"code": "building_type_fallback", "entityId": building.id,
+                                "sourceType": building.type, "targetType": "placeholder", "lostFields": lost,
+                                "reason": "FPI 无对应类型，保留名称与占地轮廓；原始 Scene/SVG 语义不变"})
+            warnings.warn(f"building_type_fallback: {building.id}: {building.type} -> placeholder",
+                          UserWarning, stacklevel=2)
+        item = attrs(building.id, BUILDING_COLLECTIONS)
+        binding = bindings.get(building.id)
+        if binding is not None and binding["collection"] != building_collection:
+            item = {"id": ids[building.id], "name": building.type}
+        if building_collection == "bayWindowSills" and not isinstance(building.geometry, BayWindowGeometry):
+            building_collection = "placeHolders"
+            diagnostics.append({"code": "bay_window_geometry_fallback", "entityId": building.id,
+                                "sourceType": building.type, "targetType": "placeholder",
+                                "reason": "缺少可靠的飘窗附墙路径或形状，保留占地"})
+        item.update(building_to_fpi(building_collection, component_geometry(building.geometry, building.id)))
+        allowed: set[str] = {"name"}
+        if building.type == "bay_window_sill" and building_collection == "placeHolders":
+            allowed.add("bayWindow")  # Original parameters stay in Scene; fallback carries only footprint.
+        if building.name is not None:
+            optional_attrs(item, name=building.name)
+        if building_collection in {"beams", "pipeWalls", "placeHolders"}:
+            allowed.add("height")
+            optional_attrs(item, height=building.height)
+        if building_collection == "beams":
+            allowed.add("thickness")
+            optional_attrs(item, thickness=building.thickness)
+            if building.height is None:
+                beam_defaults = component_defaults()
+                item["height"] = beam_defaults["beam"]["height"]
+                diagnostics.append({"code": "component_defaults_applied", "entityId": building.id,
+                                    "values": {"height": item["height"]}, "source": beam_defaults["beamSource"]})
+        if building_collection == "placeHolders":
+            allowed.update({"bottomElevation", "direction"})
+            optional_attrs(
+                item,
+                sillHeight=building.bottomElevation,
+                name=building.name if building.name is not None else (
+                    building.type if building.type != "placeholder" else None
+                ),
+                direction=point_dict(building.direction) if building.direction is not None else None,
+            )
+        if building_collection == "bayWindowSills":
+            allowed.add("bayWindow")
+            if building.bayWindow is not None:
+                optional_attrs(item, **asdict(building.bayWindow))
+            defaults = component_defaults()["bay_window_sill"]
+            applied = {key: value for key, value in defaults.items() if item.get(key) is None}
+            item.update(applied)
+            if applied:
+                diagnostics.append({"code": "component_defaults_applied", "entityId": building.id,
+                                    "values": applied, "source": component_defaults()["source"]})
+        if fallback:
+            allowed.update({"thickness", "bayWindow"})  # Omitted fields are recorded in the fallback diagnostic.
+        unsupported(building, allowed)
+        plan[building_collection].append(item)
+    legend_items = []
+
+    def furniture_warning(
+        item: Furniture, code: str, lost: list[str], target: str, missing: list[str] | None = None,
+    ) -> None:
+        diagnostic: JsonObject = {
+            "code": code, "entityId": item.id, "sourceType": item.type,
+            "targetType": target, "lostFields": lost,
+        }
+        if missing:
+            diagnostic["missingFields"] = missing
+        if diagnostics is not None:
+            diagnostics.append(diagnostic)
+        warnings.warn(f"{code}: {item.id} ({item.type} -> {target}); lostFields={lost}",
+                      UserWarning, stacklevel=2)
+
+    for furniture in scene.furniture:
+        item = attrs(furniture.id, {"legend"})
+        known = furniture.type in LEGEND_TYPES or furniture.type in {"sink", "tv_cabinet"}
+        if not known:
+            furniture_warning(furniture, "furniture_type_fallback", ["type"], "OtherAppliance")
+        if (not known or furniture_type(item) != furniture.type
+                or item.get("recommendedType") != legend_type_attributes(furniture.type)["recommendedType"]):
+            for key in (
+                "recommendedType",
+                "subCategory",
+                "typeCode",
+                "confidence",
+                "subCategoryConfidence",
+                "label",
+            ):
+                item.pop(key, None)
+            item.update(legend_type_attributes(furniture.type), name=furniture.type)
+        if furniture.name is not None:
+            item["name"] = furniture.name
+        target = str(item["recommendedType"])
+        lost = [field for field in ("height", "bottomElevation", "thickness")
+                if getattr(furniture, field) is not None]
+        if furniture.attributes:
+            lost.append("attributes")
+        for field, supported in (("shape", target in LEGEND_SHAPES),
+                                 ("upStairDirections", target == "Stair"), ("path", target == "Railing")):
+            item.pop(field, None)
+            value = getattr(furniture, field)
+            if value is not None:
+                if supported:
+                    item[field] = deepcopy(list(value) if field == "upStairDirections" else value)
+                else:
+                    lost.append(field)
+        if target == "Stair" and item.get("upStairDirections") is not None:
+            for direction in item["upStairDirections"]:
+                direction.setdefault("ascendSide", None)
+        if furniture.path is not None and target == "Railing":
+            path_geometry = PolygonGeometry(((furniture.path,),))
+            path_item = Furniture(furniture.id, furniture.type, furniture.placement, path_geometry)
+            item["path"] = [point_dict(point) for point in placed_furniture_geometry(path_item).polygons[0][0]]
+        world_geometry = placed_furniture_geometry(furniture)
+        item.update(
+            bbox={
+                "center": point_dict(furniture.placement.center),
+                "width": furniture.placement.width,
+                "height": furniture.placement.depth,
+                "rotationAngle": furniture.placement.rotation,
+            },
+            outlinePolygon=polygon_to_fpi(component_geometry(world_geometry, furniture.id)),
+        )
+        item, defaults = complete_legend_fields(item)
+        missing = legend_required_fields_missing(item)
+        require_stair_direction(item, missing)
+        if target not in LEGEND_TYPES_SUPPORTED or missing:
+            discarded = [field for field in ("shape", "upStairDirections", "path") if field in item]
+            for field in discarded:
+                item.pop(field)
+            item.update(recommendedType="OtherAppliance", subCategory="NA")
+            furniture_warning(furniture, "furniture_required_fields_fallback" if missing else "furniture_type_fallback",
+                              list(dict.fromkeys(["type", *discarded, *lost])), "OtherAppliance", missing)
+        elif lost:
+            furniture_warning(furniture, "furniture_fields_omitted", lost, target)
+        if item["recommendedType"] == target and defaults:
+            if diagnostics is not None:
+                diagnostics.extend({**entry, "entityId": furniture.id, "sourceType": furniture.type}
+                                   for entry in defaults)
+            warnings.warn(f"legend_fields_defaulted: {furniture.id}; "
+                          f"fields={[entry['field'] for entry in defaults]}", UserWarning, stacklevel=2)
+        legend_items.append(item)
+    for zone in scene.zones:
+        item = attrs(zone.id, {"zones"})
+        optional_attrs(item, name=zone.name)
+        item["polygon"] = polygon_to_fpi(zone.geometry)
+        plan["zones"].append(item)
+    return {"floorPlan": plan}, {"coordinateSystem": "fpi_mm", "items": legend_items}
+
+
+def supplement_from_dict(value: JsonObject) -> FpiSupplement:
+    data = deepcopy(value)
+    data["issues"] = tuple(Issue(**item) for item in data["issues"])
+    data["additionalRoomLabels"] = tuple(data["additionalRoomLabels"])
+    data["excludedLegend"] = tuple(data["excludedLegend"])
+    return FpiSupplement(**data)
+
+
+def supplement_to_dict(value: FpiSupplement) -> JsonObject:
+    return asdict(value)