floorplan-scene 0.1.0__py3-none-any.whl

floorplan_scene/fpi_geometry.py

@@ -0,0 +1,237 @@
+"""Exact ordinary FPI geometry translation; curve sampling stays in analysis/rendering."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Literal, cast
+
+from .model import JsonObject, _number
+from .shapes import (
+    ArcGeometry,
+    BayWindowGeometry,
+    CircleGeometry,
+    Curve,
+    CurvedFootprint,
+    Geometry,
+    LineGeometry,
+    PathGeometry,
+    PipeGeometry,
+    Point,
+    PolygonGeometry,
+    QuadraticGeometry,
+    Ring,
+)
+
+
+def required(source: JsonObject, key: str) -> Any:
+    if key not in source or source[key] is None:
+        raise ValueError(f"FPI geometry requires {key}")
+    return source[key]
+
+
+def source_point(value: JsonObject) -> Point:
+    if not isinstance(value, dict):
+        raise TypeError("FPI point must be an x/y object")
+    return _number(required(value, "x")), _number(required(value, "y"))
+
+
+def point_dict(point: Point) -> JsonObject:
+    return {"x": point[0], "y": point[1]}
+
+
+def optional_number(source: JsonObject, key: str) -> float | None:
+    value = source.get(key)
+    return None if value is None else _number(value)
+
+
+def source_points(value: object) -> tuple[Point, ...]:
+    if not isinstance(value, list) or any(not isinstance(point, dict) for point in value):
+        raise ValueError("FPI points must be an array of x/y objects")
+    return tuple(source_point(point) for point in value)
+
+
+def closed_ring(points: tuple[Point, ...]) -> Ring:
+    if len(points) < 3:
+        raise ValueError("FPI polygon needs at least three vertices")
+    return points if points[0] == points[-1] else (*points, points[0])
+
+
+def polygon_geometry(points: tuple[Point, ...]) -> PolygonGeometry:
+    return PolygonGeometry(((closed_ring(points),),))
+
+
+def line_geometry(source: JsonObject) -> LineGeometry:
+    return LineGeometry(source_point(required(source, "start")), source_point(required(source, "end")))
+
+
+def curve_geometry(source: JsonObject) -> Curve:
+    kind = source.get("type") or "LINE"
+    line = line_geometry(source)
+    if kind == "LINE":
+        return line
+    if kind == "ARC":
+        return ArcGeometry(line.start, line.end, _number(required(source, "bulge")))
+    if kind == "QUADRATIC_BEZIER_CURVE":
+        return QuadraticGeometry(line.start, source_point(required(source, "control")), line.end)
+    raise ValueError(f"unsupported FPI curve type: {kind}")
+
+
+def _reverse_curve(curve: Curve) -> Curve:
+    if isinstance(curve, ArcGeometry):
+        return ArcGeometry(curve.end, curve.start, -curve.bulge)
+    if isinstance(curve, QuadraticGeometry):
+        return QuadraticGeometry(curve.end, curve.control, curve.start)
+    return LineGeometry(curve.end, curve.start)
+
+
+def _closed_paths(edges: list[JsonObject]) -> CurvedFootprint:
+    curves = tuple(curve_geometry(edge) for edge in edges)
+    adjacency: dict[Point, list[int]] = {}
+    for index, curve in enumerate(curves):
+        adjacency.setdefault(curve.start, []).append(index)
+        adjacency.setdefault(curve.end, []).append(index)
+    remaining = set(range(len(curves)))
+    rings: list[tuple[Curve, ...]] = []
+    while remaining:
+        vertices = [curves[min(remaining)].start]
+        path: list[Curve] = []
+        while True:
+            vertex = vertices[-1]
+            candidate = next((item for item in adjacency[vertex] if item in remaining), None)
+            if candidate is None:
+                if path:
+                    raise ValueError("SHAPED edges must form closed connected rings")
+                break
+            remaining.remove(candidate)
+            curve = curves[candidate]
+            if curve.start != vertex:
+                curve = _reverse_curve(curve)
+            path.append(curve)
+            # Split a loop as soon as an exact endpoint repeats, including loops sharing a vertex.
+            if curve.end in vertices:
+                start = vertices.index(curve.end)
+                rings.append(tuple(path[start:]))
+                path = path[:start]
+                vertices = vertices[: start + 1]
+            else:
+                vertices.append(curve.end)
+    return tuple((ring,) for ring in rings)
+
+
+def wall_geometry(source: JsonObject) -> Geometry:
+    if source.get("type") != "SHAPED":
+        return curve_geometry(source)
+    edges = source.get("edges")
+    if edges:
+        if not isinstance(edges, list) or any(not isinstance(edge, dict) for edge in edges):
+            raise ValueError("SHAPED edges must be an object array")
+        return PathGeometry(_closed_paths(edges))
+    return polygon_geometry(source_points(source.get("polygon")))
+
+
+def building_geometry(collection: str, source: JsonObject) -> Geometry:
+    if collection == "circlePillars":
+        return CircleGeometry(
+            source_point(required(source, "position")), _number(required(source, "diameter")) / 2
+        )
+    if collection == "beams":
+        return line_geometry(source)
+    if collection == "pipeWalls":
+        thickness = source.get("wallThickness")
+        if not isinstance(thickness, list):
+            raise ValueError("pipeWall.wallThickness must be an array")
+        return PipeGeometry(
+            source_point(required(source, "center")),
+            _number(required(source, "width")),
+            _number(required(source, "depth")),
+            math.degrees(_number(required(source, "angle"))),
+            cast(Literal["L", "U", "RECT"], required(source, "shape")),
+            tuple(_number(value) for value in thickness),
+        )
+    if collection == "bayWindowSills":
+        return BayWindowGeometry(
+            closed_ring(source_points(source.get("polygon"))),
+            source_points(source.get("wallPolygon")),
+            required(source, "shape"),
+        )
+    return polygon_geometry(source_points(source.get("polygon")))
+
+
+def polygon_to_fpi(geometry: Geometry) -> list[JsonObject]:
+    if not isinstance(geometry, PolygonGeometry):
+        raise TypeError("FPI polygon objects require polygon geometry; no curve flattening was applied")
+    if len(geometry.polygons) != 1 or len(geometry.polygons[0]) != 1:
+        raise ValueError("ordinary FPI polygon cannot represent disconnected or holed geometry")
+    return [point_dict(point) for point in geometry.polygons[0][0][:-1]]
+
+
+def line_to_fpi(geometry: Geometry) -> JsonObject:
+    if not isinstance(geometry, LineGeometry):
+        raise TypeError("ordinary FPI object requires a straight segment")
+    return {"start": point_dict(geometry.start), "end": point_dict(geometry.end)}
+
+
+def curve_to_fpi(geometry: Curve) -> JsonObject:
+    result: JsonObject = {"start": point_dict(geometry.start), "end": point_dict(geometry.end)}
+    if isinstance(geometry, ArcGeometry):
+        result.update(type="ARC", bulge=geometry.bulge)
+    elif isinstance(geometry, QuadraticGeometry):
+        result.update(type="QUADRATIC_BEZIER_CURVE", control=point_dict(geometry.control))
+    else:
+        result["type"] = "LINE"
+    return result
+
+
+def wall_to_fpi(geometry: Geometry) -> JsonObject:
+    if isinstance(geometry, (LineGeometry, ArcGeometry, QuadraticGeometry)):
+        return curve_to_fpi(geometry)
+    if isinstance(geometry, PolygonGeometry):
+        if len(geometry.polygons) == 1:
+            return {"type": "SHAPED", "polygon": polygon_to_fpi(geometry)}
+        if any(len(polygon) != 1 for polygon in geometry.polygons):
+            raise ValueError("ordinary FPI SHAPED wall cannot represent holed geometry")
+        return {
+            "type": "SHAPED",
+            "edges": [
+                curve_to_fpi(LineGeometry(start, end))
+                for polygon in geometry.polygons
+                for start, end in zip(polygon[0][:-1], polygon[0][1:], strict=True)
+            ],
+        }
+    if isinstance(geometry, PathGeometry):
+        if any(len(polygon) != 1 for polygon in geometry.polygons):
+            raise ValueError("ordinary FPI SHAPED wall cannot represent holed geometry")
+        return {
+            "type": "SHAPED",
+            "edges": [curve_to_fpi(curve) for polygon in geometry.polygons for curve in polygon[0]],
+        }
+    raise ValueError(f"ordinary FPI wall cannot represent {geometry.type} geometry")
+
+
+def building_to_fpi(collection: str, geometry: Geometry) -> JsonObject:
+    if collection == "circlePillars":
+        if not isinstance(geometry, CircleGeometry):
+            raise ValueError("circlePillar requires circle geometry")
+        return {"position": point_dict(geometry.center), "diameter": geometry.radius * 2}
+    if collection == "beams":
+        return line_to_fpi(geometry)
+    if collection == "pipeWalls":
+        if not isinstance(geometry, PipeGeometry):
+            raise ValueError("pipeWall requires pipe geometry")
+        return {
+            "center": point_dict(geometry.center),
+            "width": geometry.width,
+            "depth": geometry.depth,
+            "angle": math.radians(geometry.angle),
+            "shape": geometry.profile,
+            "wallThickness": list(geometry.wallThickness),
+        }
+    if collection == "bayWindowSills":
+        if not isinstance(geometry, BayWindowGeometry):
+            raise ValueError("bayWindowSill requires bay_window geometry")
+        return {
+            "shape": geometry.profile,
+            "polygon": [point_dict(point) for point in geometry.outline[:-1]],
+            "wallPolygon": [point_dict(point) for point in geometry.wallPath],
+        }
+    return {"polygon": polygon_to_fpi(geometry)}

floorplan_scene/furniture.py

@@ -0,0 +1,317 @@
+"""Known Legend furniture types shared with the image skill vocabulary."""
+
+from __future__ import annotations
+
+import math
+import re
+from itertools import pairwise
+
+from .model import JsonObject
+
+# Stable target vocabulary; unknown Scene types use the existing OtherAppliance fallback.
+LEGEND_TYPES: dict[str, tuple[str, str | None]] = {
+    "bed": ("Bed", None),
+    "single_bed": ("Bed", "SINGLE_BED"),
+    "double_bed": ("Bed", "DOUBLE_BED"),
+    "sofa": ("Sofa", None),
+    "single_sofa": ("Sofa", "SINGLE_SOFA"),
+    "double_sofa": ("Sofa", "DOUBLE_SOFA"),
+    "multi_seat_sofa": ("Sofa", "MULTI_SEAT_SOFA"),
+    "chaise_sofa": ("Sofa", "CHAISE_SOFA"),
+    "bedside_table": ("BedsideTable", "BEDSIDE_TABLE"),
+    "coffee_table": ("CoffeeTableGroup", "COFFEE_TABLE"),
+    "side_table": ("CoffeeTableGroup", "SIDE_TABLE"),
+    # These observed table functions have no dedicated legend_doc subtype.
+    # Keep the family and let the existing audited subtype default apply.
+    "conference_table": ("TableGroup", None),
+    "meeting_table": ("TableGroup", None),
+    "mahjong_table": ("TableGroup", None),
+    "table": ("TableGroup", None),
+    "dining_table": ("TableGroup", "DINING_TABLE"),
+    "desk": ("TableGroup", "DESK"),
+    "dressing_table": ("TableGroup", "DRESSING_TABLE"),
+    "cabinet": ("CabinetShelf", None),
+    "wardrobe": ("CabinetShelf", "WARDROBE"),
+    "bookcase": ("CabinetShelf", "BOOKCASE"),
+    "shelf": ("CabinetShelf", "SHELF"),
+    "entry_cabinet": ("CabinetShelf", "ENTRY_CABINET"),
+    "shoe_storage": ("CabinetShelf", "SHOE_STORAGE"),
+    "storage_cabinet": ("CabinetShelf", "STORAGE_CABINET"),
+    "balcony_cabinet": ("CabinetShelf", "BALCONY_CABINET"),
+    "drawer_cabinet": ("CabinetShelf", "DRAWER_CABINET"),
+    "sideboard": ("CabinetShelf", "SIDEBOARD"),
+    "tv_stand_set": ("CabinetShelf", "TV_STAND_SET"),
+    "bunk_bed": ("Bed", "BUNK_BED"),
+    "baby_cot": ("Bed", "BABY_COT"),
+    "tatami": ("Bed", "TATAMI"),
+    "bar": ("Bar", "BAR"),
+    "countertop": ("Countertop", "COUNTERTOP"),
+    "kitchen_cabinet": ("KitchenCabinet", None),
+    "kitchen_base_cabinet": ("KitchenBaseCabinet", None),
+    "kitchen_tall_cabinet": ("KitchenTallCabinet", "KITCHEN_TALL_CABINET"),
+    "kitchen_wall_cabinet": ("KitchenWallCabinet", "KITCHEN_WALL_CABINET"),
+    "kitchen_island": ("KitchenIsland", "KITCHEN_ISLAND"),
+    "bathroom_cabinet": ("BathroomCabinet", "BATHROOM_CABINET"),
+    "wash_basin": ("WashBasin", None),
+    "basin": ("Basin", "BASIN"),
+    "chair": ("ChairStool", "CHAIR"),
+    "stool": ("ChairStool", "STOOL"),
+    "counter_chair": ("ChairStool", "COUNTER_CHAIR"),
+    "dining_chair_bench": ("ChairStool", "DINING_CHAIR_BENCH"),
+    "toilet": ("Toilet", "TOILET"),
+    "bathtub": ("Bathtub", "BATHTUB"),
+    "shower": ("Shower", "SHOWER"),
+    "shower_room": ("ShowerRoom", "SHOWER_ROOM"),
+    "shower_partition": ("ShowerPartition", "SHOWER_PARTITION"),
+    "kitchen_sink": ("KitchenSink", "KITCHEN_SINK"),
+    "stove": ("Stove", "STOVE"),
+    "range_hood": ("RangeHood", "RANGE_HOOD"),
+    "mirror_cabinet": ("MirrorCabinet", "MIRROR_CABINET"),
+    "refrigerator": ("Refrigerator", "REFRIGERATOR"),
+    "washing_machine": ("WashingMachine", "WASHING_MACHINE"),
+    "tv": ("Tv", "TV"),
+    "stair": ("Stair", "STAIR"),
+    "steps": ("Stair", "STEPS"),
+    "ramp": ("Stair", "RAMP"),
+    "railing": ("Railing", "RAILING"),
+    "fireplace": ("Fireplace", "FIREPLACE"),
+    "squat_toilet": ("Toilet", "SQUAT_TOILET"),
+    "urinal": ("Toilet", "URINAL"),
+    "floor_lamp": ("FloorLamp", "FLOOR_LAMP"),
+    "wall_ac": ("AirConditioner", "WALL_AC"),
+    "floor_ac": ("AirConditioner", "FLOOR_AC"),
+    "carpet": ("Carpet", "CARPET"),
+    "curtain": ("Curtain", "CURTAIN"),
+    "plant": ("Plant", "PLANT"),
+    "piano": ("Piano", "PIANO"),
+    "car": ("Car", "CAR"),
+    "other_appliance": ("OtherAppliance", "NA"),
+}
+TYPE_BY_LEGEND = {value: key for key, value in LEGEND_TYPES.items()}
+# Keep reading historical parent-only Legend items without inventing a subtype.
+for _kind, (_category, _subcategory) in LEGEND_TYPES.items():
+    TYPE_BY_LEGEND.setdefault((_category, None), _kind)
+TYPE_BY_LEGEND[("ChairStool", None)] = "chair"
+TYPE_BY_LEGEND[("Basin", None)] = "basin"
+
+
+def furniture_type(source: JsonObject) -> str | None:
+    category, subcategory = source.get("recommendedType"), source.get("subCategory")
+    if not isinstance(category, str) or (subcategory is not None and not isinstance(subcategory, str)):
+        return None
+    if category == "Sofa" and not subcategory:
+        description = " ".join(str(source.get(key) or "").upper() for key in ("subCategory", "name", "label"))
+        if any(
+            marker in description
+            for marker in ("SINGLE", "ARMCHAIR", "EASY_CHAIR", "LOUNGE_CHAIR", "单人沙发", "单人位沙发")
+        ):
+            return "single_sofa"
+    known = TYPE_BY_LEGEND.get((category, subcategory))
+    if known is not None:
+        return known
+    label = subcategory or category
+    # Preserve explicit subtypes and new families instead of falling back to a parent.
+    label = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", label.strip())
+    label = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", label)
+    return re.sub(r"[\s-]+", "_", label).lower() or None
+
+
+def legend_type_attributes(kind: str) -> JsonObject:
+    kind = {"sink": "kitchen_sink", "tv_cabinet": "tv_stand_set"}.get(kind, kind)
+    category, subcategory = LEGEND_TYPES.get(kind, LEGEND_TYPES["other_appliance"])
+    attributes: JsonObject = {"recommendedType": category}
+    if subcategory is not None:
+        attributes["subCategory"] = subcategory
+    return attributes
+
+
+# Capabilities of the pinned legend_doc contract; not restrictions on Scene/model output.
+LEGEND_OUTLINE_TYPES = {"CabinetShelf", "KitchenWallCabinet", "KitchenTallCabinet", "Countertop", "Stair", "Railing"}
+# Ordered exactly as legend_doc/Classification.puml at the pinned commit.
+LEGEND_CLASSIFICATION_SOURCE = "legend_doc@8813f642680f36a5864dd8420ce3e2050f8c59fe/Classification.puml"
+LEGEND_SUBCATEGORIES: dict[str, tuple[str, ...]] = {
+    "Sofa": ("SINGLE_SOFA", "DOUBLE_SOFA", "MULTI_SEAT_SOFA", "CHAISE_SOFA"),
+    "CoffeeTableGroup": ("COFFEE_TABLE", "SIDE_TABLE"),
+    "CabinetShelf": (
+        "STORAGE_CABINET", "DRAWER_CABINET", "SHELF", "BOOKCASE", "TV_STAND_SET", "SIDEBOARD",
+        "ENTRY_CABINET", "SHOE_STORAGE", "BALCONY_CABINET", "WARDROBE",
+    ),
+    "BedsideTable": ("BEDSIDE_TABLE",),
+    "TableGroup": ("DESK", "DINING_TABLE", "DRESSING_TABLE"),
+    "ChairStool": ("CHAIR", "STOOL", "COUNTER_CHAIR", "DINING_CHAIR_BENCH"),
+    "Bed": ("SINGLE_BED", "DOUBLE_BED", "BUNK_BED", "BABY_COT", "TATAMI"),
+    "Bar": ("BAR",),
+    "KitchenIsland": ("KITCHEN_ISLAND",),
+    "KitchenWallCabinet": ("KITCHEN_WALL_CABINET",),
+    "KitchenTallCabinet": ("KITCHEN_TALL_CABINET",),
+    "Countertop": ("COUNTERTOP",),
+    "KitchenSink": ("KITCHEN_SINK",),
+    "Stove": ("STOVE",),
+    "RangeHood": ("RANGE_HOOD",),
+    "BathroomCabinet": ("BATHROOM_CABINET",),
+    "MirrorCabinet": ("MIRROR_CABINET",),
+    "Basin": ("BASIN",),
+    "Shower": ("SHOWER",),
+    "Bathtub": ("BATHTUB",),
+    "ShowerRoom": ("SHOWER_ROOM",),
+    "ShowerPartition": ("SHOWER_PARTITION",),
+    "Stair": ("STAIR", "STEPS", "RAMP"),
+    "Railing": ("RAILING",),
+    "Fireplace": ("FIREPLACE",),
+    "Toilet": ("TOILET", "SQUAT_TOILET", "URINAL"),
+    "FloorLamp": ("FLOOR_LAMP",),
+    "Tv": ("TV",),
+    "Refrigerator": ("REFRIGERATOR",),
+    "WashingMachine": ("WASHING_MACHINE",),
+    "AirConditioner": ("WALL_AC", "FLOOR_AC"),
+    "Carpet": ("CARPET",),
+    "Curtain": ("CURTAIN",),
+    "Plant": ("PLANT",),
+    "Piano": ("PIANO",),
+    "Car": ("CAR",),
+    "OtherAppliance": ("NA",),
+}
+
+_EXTENDED_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "CIRCLE", "ELLIPSE", "SEMICIRCLE", "IRREGULAR", "ARC", "L_SHAPE",
+    "L_SHAPE_LEFT", "L_SHAPE_RIGHT", "U_SHAPE", "U_SHAPE_LEFT", "U_SHAPE_RIGHT",
+)
+_BASIC_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "CIRCLE", "ELLIPSE", "SEMICIRCLE", "IRREGULAR", "LONG_STRIP", "TRIANGLE",
+)
+_LAYOUT_SHAPES: tuple[str, ...] = (
+    "LINEAR", "L_SHAPE", "L_SHAPE_LEFT", "L_SHAPE_RIGHT", "U_SHAPE", "U_SHAPE_LEFT", "U_SHAPE_RIGHT",
+)
+_COUNTERTOP_SHAPES: tuple[str, ...] = (
+    "LINEAR", "L_SHAPE", "L_SHAPE_LEFT", "L_SHAPE_RIGHT", "U_SHAPE", "U_SHAPE_LEFT", "U_SHAPE_RIGHT", "IRREGULAR",
+)
+_BATH_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "CIRCLE", "ELLIPSE", "IRREGULAR", "FAN_LEFT", "FAN_RIGHT",
+)
+_SHOWER_ROOM_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "FAN_LEFT", "FAN_RIGHT", "DIAMOND_LEFT", "DIAMOND_RIGHT",
+)
+_PARTITION_SHAPES: tuple[str, ...] = (
+    "LINEAR",
+)
+_STAIR_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "L_SHAPE", "U_SHAPE", "CIRCLE", "ARC", "IRREGULAR",
+)
+_RAILING_SHAPES: tuple[str, ...] = (
+    "RECTANGLE", "ARC", "IRREGULAR",
+)
+_IRREGULAR_SHAPES: tuple[str, ...] = (
+    "IRREGULAR",
+)
+LEGEND_SHAPES: dict[str, tuple[str, ...]] = {
+    "Sofa": _EXTENDED_SHAPES,
+    "CoffeeTableGroup": _BASIC_SHAPES,
+    "CabinetShelf": _LAYOUT_SHAPES,
+    "BedsideTable": _BASIC_SHAPES,
+    "TableGroup": _EXTENDED_SHAPES,
+    "ChairStool": _BASIC_SHAPES,
+    "Bed": _BASIC_SHAPES,
+    "Bar": _BASIC_SHAPES,
+    "KitchenIsland": _BASIC_SHAPES,
+    "KitchenWallCabinet": _EXTENDED_SHAPES,
+    "KitchenTallCabinet": _EXTENDED_SHAPES,
+    "Countertop": _COUNTERTOP_SHAPES,
+    "KitchenSink": _BASIC_SHAPES,
+    "Stove": _BASIC_SHAPES,
+    "BathroomCabinet": _BASIC_SHAPES,
+    "MirrorCabinet": _BASIC_SHAPES,
+    "Basin": _BASIC_SHAPES,
+    "Bathtub": _BATH_SHAPES,
+    "ShowerRoom": _SHOWER_ROOM_SHAPES,
+    "ShowerPartition": _PARTITION_SHAPES,
+    "Stair": _STAIR_SHAPES,
+    "Railing": _RAILING_SHAPES,
+    "AirConditioner": _BASIC_SHAPES,
+    "Carpet": _BASIC_SHAPES,
+    "Curtain": _LAYOUT_SHAPES,
+    "Plant": _IRREGULAR_SHAPES,
+    "Piano": _BASIC_SHAPES,
+}
+LEGEND_TYPES_SUPPORTED = set(LEGEND_SUBCATEGORIES)
+
+
+def complete_legend_fields(item: JsonObject) -> tuple[JsonObject, list[JsonObject]]:
+    """Complete derived classification fields; keep the observation and geometry intact."""
+    result = item.copy()
+    category = result.get("recommendedType")
+    diagnostics: list[JsonObject] = []
+    if not isinstance(category, str):
+        return result, diagnostics
+    for field, choices in (("subCategory", LEGEND_SUBCATEGORIES.get(category, ())),
+                           ("shape", LEGEND_SHAPES.get(category, ()))):
+        # Steps and ramps inherit Stair's category but only support these two shapes.
+        if field == "shape" and category == "Stair" and result.get("subCategory") in {"STEPS", "RAMP"}:
+            choices = ("RECTANGLE", "IRREGULAR")
+        value = result.get(field)
+        if not choices or value in choices:
+            continue
+        result[field] = choices[0]
+        diagnostics.append({
+            "code": "legend_fields_defaulted", "entityId": str(item.get("id", "")),
+            "sourceType": category, "targetType": category, "field": field,
+            "sourceValue": value, "value": choices[0],
+            "reason": "missing" if value is None or value == "" else "unsupported",
+            "confidence": "derived", "provenance": LEGEND_CLASSIFICATION_SOURCE,
+        })
+    return result, diagnostics
+
+def legend_required_fields_missing(item: JsonObject) -> list[str]:
+    """Only enforce target-required fields here; Scene retains incomplete observations."""
+    kind = item.get("recommendedType")
+    if kind not in {"Stair", "Railing"}:
+        return []
+    missing = []
+    shape = item.get("shape")
+    if shape not in LEGEND_SHAPES[kind]:
+        missing.append("shape")
+    outline = item.get("outlinePolygon")
+    if (kind == "Railing" or shape != "RECTANGLE" or outline) and (
+        not outline or len(outline) < 3 or abs(sum(
+            a["x"] * b["y"] - b["x"] * a["y"]
+            for a, b in zip(outline, outline[1:] + outline[:1])
+        )) <= 1e-9
+    ):
+        missing.append("outlinePolygon")
+    if kind == "Stair":
+        if item.get("subCategory") not in {"STAIR", "STEPS", "RAMP"}:
+            missing.append("subCategory")
+        if item.get("subCategory") in {"STEPS", "RAMP"} and shape not in {"RECTANGLE", "IRREGULAR"}:
+            missing.append("shape")
+        directions = item.get("upStairDirections")
+        if not isinstance(directions, list) or not directions or any(
+            not isinstance(direction, dict)
+            or isinstance(direction.get("rotationAngle"), bool)
+            or not isinstance(direction.get("rotationAngle"), (int, float))
+            or not math.isfinite(direction["rotationAngle"])
+            or not 0 <= direction["rotationAngle"] < 360
+            or direction.get("ascendSide") not in {None, "LEFT", "RIGHT"}
+            for direction in directions
+        ):
+            missing.append("upStairDirections")
+    else:
+        path = item.get("path")
+        if item.get("subCategory") != "RAILING":
+            missing.append("subCategory")
+        if not isinstance(path, list) or len(path) < 2 or path[0] == path[-1] or any(
+            a == b for a, b in pairwise(path)
+        ) or shape == "ARC" and (len(path) < 3 or all(
+            abs((p["x"] - path[0]["x"]) * (path[1]["y"] - path[0]["y"])
+                - (p["y"] - path[0]["y"]) * (path[1]["x"] - path[0]["x"])) <= 1e-9
+            for p in path[2:]
+        )):
+            missing.append("path")
+    return missing
+
+
+def require_stair_direction(item: JsonObject, missing: list[str]) -> None:
+    """Prevent both Legend exporters from disguising an incomplete stair as generic furniture."""
+    if item.get("recommendedType") == "Stair" and "upStairDirections" in missing:
+        raise ValueError(
+            f"stair_direction_required: {item.get('id')} 缺少或无效的 upStairDirections；"
+            "请依据原图补充上行方向后重新转换，楼梯不能降级为普通家具。"
+        )

floorplan_scene/geometry.py

@@ -0,0 +1,119 @@
+"""Derived geometry checks and explicit export-only host snapping."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, replace
+from typing import Any, Literal
+
+from shapely.geometry import Point, Polygon  # type: ignore[import-untyped]
+from shapely.ops import nearest_points  # type: ignore[import-untyped]
+
+from .model import FloorplanScene, scene_from_dict, scene_to_dict
+from .shape_geometry import arc_circle, arc_subsegment, geometry_shape
+from .shape_geometry import wall_shape as wall_geometry
+from .shapes import GEOMETRY_TOLERANCE_MM, ArcGeometry, Geometry, QuadraticGeometry
+
+
+@dataclass(frozen=True)
+class Issue:
+    code: str
+    entityId: str | None
+    message: str
+    severity: Literal["error", "warning"] = "error"
+
+
+
+
+def polygon_parts(geometry: Any) -> list[Any]:
+    if isinstance(geometry, Polygon):
+        return [geometry]
+    return [polygon for part in getattr(geometry, "geoms", ()) for polygon in polygon_parts(part)]
+
+
+
+
+
+
+
+
+def opening_host_issues(scene: FloorplanScene) -> list[Issue]:
+    """A curved wall opening is represented by its chord, not a segment of the wall axis."""
+    issues: list[Issue] = []
+    walls = {wall.id: wall for wall in scene.walls}
+    for opening in scene.openings:
+        for index, part in enumerate(opening.segments):
+            wall = walls.get(part.wallId or "")
+            if wall is None:
+                issues.append(Issue("missing_host", opening.id, f"Segment {index} has no host wall."))
+                continue
+            host = geometry_shape(wall.geometry)
+            if opening.kind == "niche":
+                on_host = (isinstance(wall.geometry, (ArcGeometry, QuadraticGeometry)) or
+                           wall.geometry.type == "line") and wall.thickness is None
+                if not on_host:
+                    on_host = wall_geometry(wall).buffer(GEOMETRY_TOLERANCE_MM).covers(
+                        geometry_shape(part.geometry, opening.depth))
+            elif isinstance(part.geometry, ArcGeometry):
+                on_host = host.buffer(GEOMETRY_TOLERANCE_MM).covers(geometry_shape(part.geometry))
+            elif isinstance(wall.geometry, (ArcGeometry, QuadraticGeometry)):
+                on_host = all(host.distance(Point(p)) <= GEOMETRY_TOLERANCE_MM for p in (part.geometry.start, part.geometry.end))
+            else:
+                # Allow up to 1 mm of source-coordinate deviation without moving either geometry.
+                on_host = host.buffer(GEOMETRY_TOLERANCE_MM).covers(geometry_shape(part.geometry))
+            if not on_host:
+                issues.append(Issue("opening_off_host", opening.id, f"Segment {index} is outside its host geometry."))
+    return issues
+
+
+
+
+def snap_openings_to_hosts(
+    scene: FloorplanScene, tolerance_mm: float, diagnostics: list[dict[str, Any]],
+) -> FloorplanScene:
+    """Create an export-only repair; never change host IDs or the source scene."""
+    walls = {wall.id: wall for wall in scene.walls}
+    openings = []
+    for opening in scene.openings:
+        parts = []
+        for index, part in enumerate(opening.segments):
+            wall = walls.get(part.wallId or "")
+            if opening.kind == "niche" or wall is None or (isinstance(part.geometry, ArcGeometry) and not isinstance(wall.geometry, ArcGeometry)):
+                parts.append(part)
+                continue
+            before = (part.geometry.start, part.geometry.end)
+            after = tuple(_nearest_host_point(point, wall.geometry) for point in before)
+            distances = [Point(a).distance(Point(b)) for a, b in zip(before, after, strict=True)]
+            if max(distances) > tolerance_mm:
+                raise ValueError(f"invalid scene geometry: opening_off_host: {opening.id} exceeds {tolerance_mm:g} mm")
+            if Point(after[0]).distance(Point(after[1])) < 1e-6:
+                raise ValueError(f"opening_snap_degenerate: {opening.id}")
+            repaired = replace(part.geometry, start=after[0], end=after[1])
+            if (isinstance(part.geometry, ArcGeometry) and isinstance(wall.geometry, ArcGeometry)
+                    and abs(wall.geometry.bulge) > 1e-12):
+                repaired = arc_subsegment(wall.geometry, after[0], after[1])
+                if geometry_shape(part.geometry).hausdorff_distance(geometry_shape(repaired)) > tolerance_mm:
+                    raise ValueError(f"invalid scene geometry: opening_off_host: {opening.id} arc exceeds {tolerance_mm:g} mm")
+            if max(distances) > 1e-9 or repaired != part.geometry:
+                diagnostics.append({"code": "opening_snapped", "entityId": opening.id,
+                                    "segmentIndex": index, "hostId": part.wallId,
+                                    "before": before, "after": after,
+                                    "displacementsMm": distances, "toleranceMm": tolerance_mm})
+                part = replace(part, geometry=repaired)
+            parts.append(part)
+        openings.append(replace(opening, segments=tuple(parts)))
+    return scene_from_dict(scene_to_dict(replace(scene, openings=tuple(openings))))
+
+
+def _nearest_host_point(point: tuple[float, float], geometry: Geometry) -> tuple[float, float]:
+    if isinstance(geometry, ArcGeometry) and abs(geometry.bulge) > 1e-12:
+        center, radius = arc_circle(geometry)
+        angle = math.atan2(point[1] - center[1], point[0] - center[0])
+        start_angle = math.atan2(geometry.start[1] - center[1], geometry.start[0] - center[0])
+        along = ((1 if geometry.bulge > 0 else -1) * (angle - start_angle)) % math.tau
+        candidates = [geometry.start, geometry.end]
+        if along <= abs(4 * math.atan(geometry.bulge)):
+            candidates.append((center[0] + radius * math.cos(angle), center[1] + radius * math.sin(angle)))
+        return min(candidates, key=lambda candidate: math.dist(point, candidate))
+    result = nearest_points(Point(point), geometry_shape(geometry))[1]
+    return float(result.x), float(result.y)