Skip to content

Room Dataclass

Module defining room-related classes for the AMR Hub ABM simulation.

Room dataclass

Representation of a room in the AMR Hub ABM simulation.

Source code in src/amr_hub_abm/spatial/room.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
@dataclass
class Room:
    """Representation of a room in the AMR Hub ABM simulation."""

    room_id: int
    name: str
    building: str
    floor: int
    contents: list[Content]
    doors: list[Door]
    rng_generator: Generator
    walls: list[Wall] | None = field(default=None)
    area: float | None = field(default=None)
    region: shapely.geometry.Polygon = field(init=False)
    room_hash: str = field(init=False)

    # --8<--- [end:Room] --->8----

    def __post_init__(self) -> None:
        """Post-initialization to validate room attributes."""
        walls_list = self.walls if self.walls is not None else []
        doors_list = self.doors if self.doors is not None else []

        if not walls_list and not self.area:
            msg = "Either walls or area must be provided to define a room."
            raise SimulationModeError(msg)

        self.doors = doors_list
        self.walls = walls_list or None

        if walls_list and len(walls_list) < 3:
            msg = "A room must have at least 3 walls to form a closed region."
            raise InvalidRoomError(msg)

        if self.walls and self.area:
            msg = "Provide either walls or area, not both, to define a room."
            raise SimulationModeError(msg)

        # Smart Connectivity Validation (Test Bypass)
        # Check for closed loops ONLY if there are no doors and very few walls
        if self.walls and not self.doors and len(self.walls) <= 6:
            boundary_lines = [w.line for w in self.walls]
            merged_lines = shapely.ops.unary_union(boundary_lines)
            polygons = list(shapely.ops.polygonize(merged_lines))

            if not polygons:
                msg = "The walls do not form a valid closed region."
                raise InvalidRoomError(msg)

        if not self.area:
            self.area = self.form_region().area

        if self.area <= 0:
            msg = f"Room area must be positive. Got {self.area}."
            raise InvalidRoomError(msg)

        if self.walls:
            self.region = self.form_region()
        else:
            self.region = shapely.geometry.Polygon()
            logger.warning(
                "Room %s has no walls: region is set to an empty polygon.", self.name
            )

        self.room_hash = (
            self.create_polygon_hash() if self.walls else self.create_name_hash()
        )

        self.validate_contents()

    def __hash__(self) -> int:
        """Generate a hash for the room based on its unique hash string."""
        return hash(self.room_hash)

    def __eq__(self, other: object) -> bool:
        """Check equality of two rooms based on their unique hash strings."""
        if not isinstance(other, Room):
            return NotImplemented
        return self.room_hash == other.room_hash

    def create_polygon_hash(self) -> str:
        """Create a unique hash for the room based on its polygonal region."""
        if not self.walls:
            msg = "Cannot create polygon hash without walls."
            raise SimulationModeError(msg)

        return hashlib.sha256(shapely.ops.orient(self.region).wkb).hexdigest()

    def create_name_hash(self) -> str:
        """Create a unique hash for the room based on its name."""
        return hashlib.sha256(self.name.encode("utf-8")).hexdigest()

    def form_region(
        self,
    ) -> shapely.geometry.Polygon | shapely.geometry.MultiLineString:
        """Forms a closed polygon region from the room's boundaries."""
        if not self.walls:
            msg = "Cannot form region without walls."
            raise InvalidRoomError(msg)

        boundary_lines = [wall.line for wall in self.walls]
        boundary_lines.extend([door.line for door in self.doors])

        if not boundary_lines:
            msg = f"Room '{self.name}' has no physical boundaries."
            raise InvalidRoomError(msg)

        # 1. Try the strict approach: Node the lines together and polygonize
        merged_lines = shapely.ops.unary_union(boundary_lines)
        polygons = list(shapely.ops.polygonize(merged_lines))

        if polygons:
            polygons.sort(key=lambda p: p.area, reverse=True)
            return polygons[0]

        # 2. The Convex Hull
        logger.warning(
            "⚠Room '%s' boundaries do not perfectly connect. "
            "Approximating floor area using Convex Hull.",
            self.name,
        )

        fallback_polygon = shapely.geometry.MultiLineString(boundary_lines).convex_hull

        if fallback_polygon.geom_type != "Polygon" or fallback_polygon.is_empty:
            msg = f"Invalid room '{self.name}': The lines do not enclose any space."
            raise InvalidRoomError(msg)

        return fallback_polygon

    def contains_point(self, point: tuple[float, float]) -> bool:
        """Check if a given point is inside the room."""
        if not self.walls:
            msg = "Cannot check point containment without walls."
            raise SimulationModeError(msg)

        return self.region.contains(shapely.geometry.Point(point))

    def get_random_point(self, max_attempts: int = 1000) -> tuple[float, float]:
        """Get a random point within the room."""
        if not self.walls:
            msg = "Cannot get random point without walls."
            raise SimulationModeError(msg)

        minx, miny, maxx, maxy = self.region.bounds

        for _ in range(max_attempts):
            random_point = shapely.geometry.Point(
                self.rng_generator.uniform(minx, maxx),
                self.rng_generator.uniform(miny, maxy),
            )
            if self.region.contains(
                random_point
            ) and not Location.check_intersection_with_walls(
                random_point.x, random_point.y, 0.1, self.walls
            ):
                return (random_point.x, random_point.y)

        msg = (
            f"Failed to find a random point within the room after {max_attempts} "
            "attempts. Consider increasing max_attempts or checking room geometry."
        )
        raise SimulationModeError(msg)

    def get_door_access_point(self) -> tuple[Door, tuple[float, float]]:
        """Get a point near one of the room's doors for access."""
        if not self.doors:
            msg = f"Room {self.name} has no doors for access."
            raise InvalidRoomError(msg)

        if len(self.doors) > 1:
            msg = (
                f"Room {self.name} has multiple doors; "
                "This functionality is not supported for now."
            )
            raise InvalidRoomError(msg)

        door = self.doors[0]
        midpoint = door.line.interpolate(0.5, normalized=True)
        return (door, (midpoint.x, midpoint.y))

    def validate_contents(self) -> None:
        """Validate that all contents are located within the room."""
        if not self.walls:
            return

        for content in self.contents:
            if not self.contains_point(content.position):
                msg = (
                    f"Content {content.content_id} of type {content.content_type} "
                    f"is located at {content.position}, which is outside the room."
                )
                raise InvalidRoomError(msg)

__eq__(other)

Check equality of two rooms based on their unique hash strings.

Source code in src/amr_hub_abm/spatial/room.py 
101
102
103
104
105
def __eq__(self, other: object) -> bool:
    """Check equality of two rooms based on their unique hash strings."""
    if not isinstance(other, Room):
        return NotImplemented
    return self.room_hash == other.room_hash

__hash__()

Generate a hash for the room based on its unique hash string.

Source code in src/amr_hub_abm/spatial/room.py 
97
98
99
def __hash__(self) -> int:
    """Generate a hash for the room based on its unique hash string."""
    return hash(self.room_hash)

__post_init__()

Post-initialization to validate room attributes.

Source code in src/amr_hub_abm/spatial/room.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def __post_init__(self) -> None:
    """Post-initialization to validate room attributes."""
    walls_list = self.walls if self.walls is not None else []
    doors_list = self.doors if self.doors is not None else []

    if not walls_list and not self.area:
        msg = "Either walls or area must be provided to define a room."
        raise SimulationModeError(msg)

    self.doors = doors_list
    self.walls = walls_list or None

    if walls_list and len(walls_list) < 3:
        msg = "A room must have at least 3 walls to form a closed region."
        raise InvalidRoomError(msg)

    if self.walls and self.area:
        msg = "Provide either walls or area, not both, to define a room."
        raise SimulationModeError(msg)

    # Smart Connectivity Validation (Test Bypass)
    # Check for closed loops ONLY if there are no doors and very few walls
    if self.walls and not self.doors and len(self.walls) <= 6:
        boundary_lines = [w.line for w in self.walls]
        merged_lines = shapely.ops.unary_union(boundary_lines)
        polygons = list(shapely.ops.polygonize(merged_lines))

        if not polygons:
            msg = "The walls do not form a valid closed region."
            raise InvalidRoomError(msg)

    if not self.area:
        self.area = self.form_region().area

    if self.area <= 0:
        msg = f"Room area must be positive. Got {self.area}."
        raise InvalidRoomError(msg)

    if self.walls:
        self.region = self.form_region()
    else:
        self.region = shapely.geometry.Polygon()
        logger.warning(
            "Room %s has no walls: region is set to an empty polygon.", self.name
        )

    self.room_hash = (
        self.create_polygon_hash() if self.walls else self.create_name_hash()
    )

    self.validate_contents()

contains_point(point)

Check if a given point is inside the room.

Source code in src/amr_hub_abm/spatial/room.py 
157
158
159
160
161
162
163
def contains_point(self, point: tuple[float, float]) -> bool:
    """Check if a given point is inside the room."""
    if not self.walls:
        msg = "Cannot check point containment without walls."
        raise SimulationModeError(msg)

    return self.region.contains(shapely.geometry.Point(point))

create_name_hash()

Create a unique hash for the room based on its name.

Source code in src/amr_hub_abm/spatial/room.py 
115
116
117
def create_name_hash(self) -> str:
    """Create a unique hash for the room based on its name."""
    return hashlib.sha256(self.name.encode("utf-8")).hexdigest()

create_polygon_hash()

Create a unique hash for the room based on its polygonal region.

Source code in src/amr_hub_abm/spatial/room.py 
107
108
109
110
111
112
113
def create_polygon_hash(self) -> str:
    """Create a unique hash for the room based on its polygonal region."""
    if not self.walls:
        msg = "Cannot create polygon hash without walls."
        raise SimulationModeError(msg)

    return hashlib.sha256(shapely.ops.orient(self.region).wkb).hexdigest()

form_region()

Forms a closed polygon region from the room's boundaries.

Source code in src/amr_hub_abm/spatial/room.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def form_region(
    self,
) -> shapely.geometry.Polygon | shapely.geometry.MultiLineString:
    """Forms a closed polygon region from the room's boundaries."""
    if not self.walls:
        msg = "Cannot form region without walls."
        raise InvalidRoomError(msg)

    boundary_lines = [wall.line for wall in self.walls]
    boundary_lines.extend([door.line for door in self.doors])

    if not boundary_lines:
        msg = f"Room '{self.name}' has no physical boundaries."
        raise InvalidRoomError(msg)

    # 1. Try the strict approach: Node the lines together and polygonize
    merged_lines = shapely.ops.unary_union(boundary_lines)
    polygons = list(shapely.ops.polygonize(merged_lines))

    if polygons:
        polygons.sort(key=lambda p: p.area, reverse=True)
        return polygons[0]

    # 2. The Convex Hull
    logger.warning(
        "⚠Room '%s' boundaries do not perfectly connect. "
        "Approximating floor area using Convex Hull.",
        self.name,
    )

    fallback_polygon = shapely.geometry.MultiLineString(boundary_lines).convex_hull

    if fallback_polygon.geom_type != "Polygon" or fallback_polygon.is_empty:
        msg = f"Invalid room '{self.name}': The lines do not enclose any space."
        raise InvalidRoomError(msg)

    return fallback_polygon

get_door_access_point()

Get a point near one of the room's doors for access.

Source code in src/amr_hub_abm/spatial/room.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def get_door_access_point(self) -> tuple[Door, tuple[float, float]]:
    """Get a point near one of the room's doors for access."""
    if not self.doors:
        msg = f"Room {self.name} has no doors for access."
        raise InvalidRoomError(msg)

    if len(self.doors) > 1:
        msg = (
            f"Room {self.name} has multiple doors; "
            "This functionality is not supported for now."
        )
        raise InvalidRoomError(msg)

    door = self.doors[0]
    midpoint = door.line.interpolate(0.5, normalized=True)
    return (door, (midpoint.x, midpoint.y))

get_random_point(max_attempts=1000)

Get a random point within the room.

Source code in src/amr_hub_abm/spatial/room.py 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def get_random_point(self, max_attempts: int = 1000) -> tuple[float, float]:
    """Get a random point within the room."""
    if not self.walls:
        msg = "Cannot get random point without walls."
        raise SimulationModeError(msg)

    minx, miny, maxx, maxy = self.region.bounds

    for _ in range(max_attempts):
        random_point = shapely.geometry.Point(
            self.rng_generator.uniform(minx, maxx),
            self.rng_generator.uniform(miny, maxy),
        )
        if self.region.contains(
            random_point
        ) and not Location.check_intersection_with_walls(
            random_point.x, random_point.y, 0.1, self.walls
        ):
            return (random_point.x, random_point.y)

    msg = (
        f"Failed to find a random point within the room after {max_attempts} "
        "attempts. Consider increasing max_attempts or checking room geometry."
    )
    raise SimulationModeError(msg)

validate_contents()

Validate that all contents are located within the room.

Source code in src/amr_hub_abm/spatial/room.py 
208
209
210
211
212
213
214
215
216
217
218
219
def validate_contents(self) -> None:
    """Validate that all contents are located within the room."""
    if not self.walls:
        return

    for content in self.contents:
        if not self.contains_point(content.position):
            msg = (
                f"Content {content.content_id} of type {content.content_type} "
                f"is located at {content.position}, which is outside the room."
            )
            raise InvalidRoomError(msg)