Skip to content

Building#

cheersafe.inventory.Building represents one building archetype. It stores the 28 geometry and configuration values from a building-geometry input column and, when automatic execution is enabled, derives roof sheathing panel coordinates and roof-to-wall connection coordinates.

Purpose And When To Use#

Use Building when you need to inspect or calculate geometry for one archetype, or when you are constructing an inventory manually. Most workflows receive Building instances from BuildingInventory instead of creating them one at a time.

Inputs#

Building takes 28 positional arguments. BuildingInventory passes each column of BuildingGeometry_Old.json or BuildingGeometry.json in this order.

Position Attribute Unit or code
1 BldgType 1-based building type ID.
2 Story Number of stories.
3 Material Material code.
4 WallFloorCon_FrontBack Count.
5 WallFloorCon_Side Count.
6 BldgLength ft.
7 BldgWidth ft.
8 MeanRoofHeight ft.
9 WallHeight ft.
10 OpeningFront Count.
11 OpeningBack Count.
12 OpeningSideR Count.
13 OpeningSideH Count.
14 OpeningLength ft.
15 OpeningWidth ft.
16 DoorFront Count.
17 DoorGarage Count.
18 DoorBack Count.
19 RoofShape 1 hip roof, 2 gable roof.
20 RoofPitchDegree degrees.
21 RoofPitch_r rise/run ratio.
22 RoofHeight ft.
23 RoofWidth ft.
24 HipRidgeLength ft.
25 HipRidgeAngle degrees.
26 TrussSpacing ft.
27 SheathingLength ft.
28 SheathingWidth ft.

The bundled geometry files have shape [28, 8]: rows are attributes, columns are building archetypes. The type annotations in Building coerce each constructor value to the expected Python type during __post_init__.

Outputs And Returns#

When Config.AUTO_EXECUTE_METHODS is True, these attributes are assigned during initialization:

Attribute Shape or type Meaning
PanelCoordinate Hip: [6, n]; gable: [4, n] Roof sheathing panel coordinates. Hip rows are left base x, right base x, left top x, right top x, base y, top y. Gable rows are left x, right x, base y, top y. Coordinates are in ft.
NumPanel Hip: [4]; gable: [2] Panel counts by roof face. Hip order is front, back, side, side. Gable order is front, back.
ConnectionCoordinate [n] Roof-to-wall connection coordinates in ft along the relevant roof edges.
NumConnection Hip: length 4; gable: length 2 RWC counts by roof face, matching the roof-face order above.

fn_panel_coordinate() returns (panel_coordinate, num_panel). fn_connection_coordinate() returns (connection_coordinate, num_connection).

AUTO_LOAD_DATASETS Behavior#

Building does not load files directly. This flag has no direct effect on a standalone Building. It matters when a BuildingInventory creates buildings from a JSON input file.

AUTO_EXECUTE_METHODS Behavior#

With AUTO_EXECUTE_METHODS = True, Building(...) computes and assigns PanelCoordinate, NumPanel, ConnectionCoordinate, and NumConnection.

With AUTO_EXECUTE_METHODS = False, those attributes are not present after initialization. Call fn_panel_coordinate() and fn_connection_coordinate() manually and use their returned values.

Minimal Automatic Example#

PYTHONPATH=src python3 - <<'PY'
from cheersafe.config import Config
from cheersafe.inventory import Building
from cheersafe.tools import Utils

Config.reset_flags()
geometry = Utils.from_json("Inputs/BuildingGeometry_Old.json")

building = Building(*geometry[:, 0])
print(building.BldgType)
print(building.PanelCoordinate.shape)
print(building.NumPanel.tolist())

Config.reset_flags()
PY

Minimal Manual-Control Example#

PYTHONPATH=src python3 - <<'PY'
from cheersafe.config import Config
from cheersafe.inventory import Building
from cheersafe.tools import Utils

Config.reset_flags()
Config.AUTO_EXECUTE_METHODS = False

geometry = Utils.from_json("Inputs/BuildingGeometry_Old.json")
building = Building(*geometry[:, 0])

panel_coordinate, num_panel = building.fn_panel_coordinate()
connection_coordinate, num_connection = building.fn_connection_coordinate()

print(panel_coordinate.shape, num_panel.tolist())
print(connection_coordinate.shape, num_connection)

Config.reset_flags()
PY