Shared-Wall Normalisation

Shared wall-face detection and normalisation.

Architectural room polygons commonly follow opposite faces of the same physical wall. This module identifies compatible parallel overlaps and moves accepted pairs to one common midline. Rejected candidates are retained as diagnostic metadata so uncertain geometry can be reviewed without silently changing room boundaries.

SharedWallCandidate dataclass

A candidate pair of wall faces that may represent one physical wall.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class SharedWallCandidate:
    """A candidate pair of wall faces that may represent one physical wall."""

    first: WallSegment
    second: WallSegment
    gap: float
    overlap_length: float
    overlap_ratio: float
    overlap: tuple[float, float]
    first_interval: tuple[float, float]
    second_interval: tuple[float, float]
    strip: Polygon

SharedWallConfig dataclass

Configuration for optional shared-wall normalisation.

Attributes:

Name	Type	Description
enabled	bool	Whether shared-wall normalisation should run.
min_gap	float	Minimum distance between paired wall faces.
max_gap	float	Maximum distance between paired wall faces.
angle_tolerance_degrees	float	Maximum angle difference for wall faces to be considered parallel.
min_overlap_ratio	float	Minimum projected overlap ratio required for pairing.
min_overlap_length	float	Minimum projected overlap length required for pairing.
canonical_line	str	Strategy for choosing the replacement shared wall line.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class SharedWallConfig:
    """
    Configuration for optional shared-wall normalisation.

    Attributes
    ----------
    enabled : bool
        Whether shared-wall normalisation should run.
    min_gap : float
        Minimum distance between paired wall faces.
    max_gap : float
        Maximum distance between paired wall faces.
    angle_tolerance_degrees : float
        Maximum angle difference for wall faces to be considered parallel.
    min_overlap_ratio : float
        Minimum projected overlap ratio required for pairing.
    min_overlap_length : float
        Minimum projected overlap length required for pairing.
    canonical_line : str
        Strategy for choosing the replacement shared wall line.

    """

    enabled: bool = False
    min_gap: float = 50.0
    max_gap: float = 130.0
    angle_tolerance_degrees: float = 2.0
    min_overlap_ratio: float = 0.75
    min_overlap_length: float = 250.0
    canonical_line: str = "midline"

SharedWallDetectionResult dataclass

Accepted and rejected shared-wall records for downstream diagnostics.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class SharedWallDetectionResult:
    """Accepted and rejected shared-wall records for downstream diagnostics."""

    candidates: list[SharedWallCandidate]
    rejections: list[SharedWallRejection]

SharedWallPairMetrics dataclass

Geometric measurements for a paired wall-face comparison.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class SharedWallPairMetrics:
    """Geometric measurements for a paired wall-face comparison."""

    gap: float
    overlap: tuple[float, float]
    overlap_length: float
    overlap_ratio: float

SharedWallRejection dataclass

A rejected wall-face pair with diagnostic context.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class SharedWallRejection:
    """A rejected wall-face pair with diagnostic context."""

    first: WallSegment
    second: WallSegment
    reason: str
    gap: float | None = None
    overlap_length: float | None = None
    overlap_ratio: float | None = None
    blocking_room_id: Hashable | None = None

WallSegment dataclass

A straight exterior segment from one room polygon.

Source code in src/floorplan_extractor/shared_walls.py

@dataclass(frozen=True)
class WallSegment:
    """A straight exterior segment from one room polygon."""

    room_id: Hashable
    segment_index: int
    line: LineString
    start: XY
    end: XY
    length: float
    angle_radians: float

    @property
    def key(self) -> tuple[Hashable, int]:
        """Return a stable key for matching and ambiguity checks."""
        return (self.room_id, self.segment_index)

key property

Return a stable key for matching and ambiguity checks.

candidate_midline(candidate)

Return the canonical midline for an accepted shared-wall candidate.

Parameters:

Name	Type	Description	Default
candidate	SharedWallCandidate	Candidate whose paired wall-face overlap should be represented.	required

Returns:

Type	Description
LineString	Line segment halfway between the paired overlapping wall faces.

Source code in src/floorplan_extractor/shared_walls.py

def candidate_midline(candidate: SharedWallCandidate) -> LineString:
    """
    Return the canonical midline for an accepted shared-wall candidate.

    Parameters
    ----------
    candidate : SharedWallCandidate
        Candidate whose paired wall-face overlap should be represented.

    Returns
    -------
    shapely.geometry.LineString
        Line segment halfway between the paired overlapping wall faces.

    """
    first_start, first_end, second_start, second_end = _candidate_overlap_points(
        candidate
    )

    return LineString(
        [
            _midpoint(first_start, second_start),
            _midpoint(first_end, second_end),
        ]
    )

detect_shared_wall_candidates(rooms, config)

Detect possible shared wall-face pairs without mutating room geometry.

Parameters:

Name	Type	Description	Default
rooms	GeoDataFrame	Room polygons to inspect. The GeoDataFrame index is used as the room identifier in returned records.	required
config	SharedWallConfig	Geometric thresholds controlling candidate detection.	required

Returns:

Type	Description
SharedWallDetectionResult	Accepted candidates and rejected pair records.

Source code in src/floorplan_extractor/shared_walls.py

def detect_shared_wall_candidates(
    rooms: gpd.GeoDataFrame,
    config: SharedWallConfig,
) -> SharedWallDetectionResult:
    """
    Detect possible shared wall-face pairs without mutating room geometry.

    Parameters
    ----------
    rooms : geopandas.GeoDataFrame
        Room polygons to inspect. The GeoDataFrame index is used as the room
        identifier in returned records.
    config : SharedWallConfig
        Geometric thresholds controlling candidate detection.

    Returns
    -------
    SharedWallDetectionResult
        Accepted candidates and rejected pair records.

    """
    segments = _extract_wall_segments(rooms)
    pairs = _indexed_segment_pairs(segments, config.max_gap)
    room_index = _build_room_spatial_index(rooms)
    return _detect_shared_wall_candidates_from_pairs(
        config,
        pairs,
        room_index,
    )

normalise_shared_walls(rooms, config, detection=None)

Move accepted shared wall-face overlaps to a common midline.

Parameters:

Name	Type	Description	Default
rooms	GeoDataFrame	Labelled room polygons to normalise.	required
config	SharedWallConfig	Shared-wall configuration. If disabled, geometries are not changed.	required
detection	SharedWallDetectionResult or None	Candidate detection output. If omitted and config is enabled, detection is run using rooms and config.	None

Returns:

Type	Description
GeoDataFrame	A copy of rooms with updated geometries and the columns shared_wall_count, shared_wall_rejections, and shared_wall_review. The complete detection result is also stored in result.attrs["shared_wall_detection"].

Source code in src/floorplan_extractor/shared_walls.py

def normalise_shared_walls(
    rooms: gpd.GeoDataFrame,
    config: SharedWallConfig,
    detection: SharedWallDetectionResult | None = None,
) -> gpd.GeoDataFrame:
    """
    Move accepted shared wall-face overlaps to a common midline.

    Parameters
    ----------
    rooms : geopandas.GeoDataFrame
        Labelled room polygons to normalise.
    config : SharedWallConfig
        Shared-wall configuration. If disabled, geometries are not changed.
    detection : SharedWallDetectionResult or None
        Candidate detection output. If omitted and config is enabled, detection
        is run using ``rooms`` and ``config``.

    Returns
    -------
    geopandas.GeoDataFrame
        A copy of ``rooms`` with updated geometries and the columns
        ``shared_wall_count``, ``shared_wall_rejections``, and
        ``shared_wall_review``. The complete detection result is also stored in
        ``result.attrs["shared_wall_detection"]``.

    """
    result = rooms.copy()

    if detection is None:
        detection = (
            detect_shared_wall_candidates(rooms, config)
            if config.enabled
            else SharedWallDetectionResult(candidates=[], rejections=[])
        )

    if config.enabled and detection.candidates:
        result.geometry, applied_candidates, application_rejections = (
            _normalised_geometry(result, detection.candidates)
        )
        detection = SharedWallDetectionResult(
            candidates=applied_candidates,
            rejections=[*detection.rejections, *application_rejections],
        )

    return _attach_review_metadata(result, detection)

rejection_overlap_lines(rejection)

Return source-wall lines clipped to a rejected pair's projected overlap.

Parameters:

Name	Type	Description	Default
rejection	SharedWallRejection	Rejected wall-face pair to represent.	required

Returns:

Type	Description
tuple[LineString, LineString]	Corresponding overlap portions on the first and second wall faces.

Source code in src/floorplan_extractor/shared_walls.py

def rejection_overlap_lines(
    rejection: SharedWallRejection,
) -> tuple[LineString, LineString]:
    """
    Return source-wall lines clipped to a rejected pair's projected overlap.

    Parameters
    ----------
    rejection : SharedWallRejection
        Rejected wall-face pair to represent.

    Returns
    -------
    tuple[shapely.geometry.LineString, shapely.geometry.LineString]
        Corresponding overlap portions on the first and second wall faces.

    """
    overlap = _projected_overlap(rejection.first, rejection.second)
    axis = _unit_axis(rejection.first)

    return (
        LineString(
            [
                _point_at_axis_projection(rejection.first, axis, overlap[0]),
                _point_at_axis_projection(rejection.first, axis, overlap[1]),
            ]
        ),
        LineString(
            [
                _point_at_axis_projection(rejection.second, axis, overlap[0]),
                _point_at_axis_projection(rejection.second, axis, overlap[1]),
            ]
        ),
    )