MLStructFP 0.3.4

Machine learning structural floor plan dataset

Multi-unit floor plan dataset.

Description

This repo contains the base library to load and parse floor plans from MLSTRUCT-FP dataset, which contains over 954 large-scale floor plans images, alongside annotations for their walls in JSON format. The database loader just loads in memory the Floor, Walls, and Slabs objects, and also offers methods to create custom images from floor plans by applying a crop, a rotation, and custom scaling.

The images can be generated from the real rasterized plan, or by using the polygons stored in the JSON file. Both image and wall polygons are consistent in their placement.

See more information in our published article.

First steps

In order to install the library, use the following python-pip commands:

python -m pip install MLStructFP

To download the dataset (compressed in .zip), request for a public download link by completing a simple form.

Dataset details

The dataset (uncompressed) has the following structure:

dataset/
    0a0...736.png
    0a7...b41.png
    ...
    ff4...ff4.png
    ffd...faf.png
    fp.json

Each image is stored in PNG format, with transparent background. Image size ranges between 6500 and 9500 px. Each file represents a distinct floor, whose labels (wall polygons, slabs) and metadata are stored within fp.json.

The format of the fp.json file is characterized as follows:

{
    "rect": {
        "1000393": {
            "angle": 0.0,
            "floorID": 8970646,
            "length": 2.6,
            "line": [
                0.0,
                -15.039,
                0.0
            ],
            "thickness": 0.2,
            "wallID": 5969311,
            "x": [
                13.39,
                15.99,
                15.99,
                13.39
            ],
            "y": [
                -14.939,
                -14.939,
                -15.139,
                -15.139
            ]
        },
        ...
    },
    "slab": {
        "1002588": {
            "floorID": 5980221,
            "x": [
                -1.153,
                4.897,
                4.897,
                ...
            ],
            "y": [
                -22.622,
                -22.622,
                -19.117,
                ...
            ],
        },
        ...
    },
    "floor": {
        "1014539": {
            "image": "83d4b2b46052b81347c2c369076ce9e792da8b7c.png",
            "scale": 193.412
        },
        ...
    }
}

Note the dataset comprises a list of “rect” representing the rectangles (wall segments), “slab” and “floor”. Each item has a distinct ID for quering and grouping elements. In the example, the rect ID 1000393 is within floor ID 8970646, with an angle of 0 degrees, a length of 2.6 m, and within the wall ID 5969311. Likewise, the slab 1002588 is within floor ID 5980221, whose its first point (x, y) is (-1.153, -22.622) m. Finally, the floor ID 1014539 is associated with the image 83d...8b7c.png and a scale 193.412 px/m. In total, there are 70873 rects, 954 slabs and 954 floors.

Object API

The basic usage of the API is illustrated on the jupyter notebook. The most basic object is DbLoader, which receives the path of the fp.json file.

class DbLoader(db: str)

# Example
db = DbLoader('test/data/fp.json')
db.tabulate()

DbLoader creates a dict of Floor object, which each contains a dict of Rect and Slab objects. Each item is associated using their respective ids. Floor object also have many methods to retrieve their elements, plot, and apply transformations (aka mutations) such as scaling or rotation using mutate() method:

class Floor:
    ...

    def mutate(self, angle: NumberType = 0, sx: NumberType = 1, sy: NumberType = 1,
            scale_first: bool = True) -> 'Floor':
        ...

# Example
plot_floor = db.floor[302]
plot_floor.mutate(30, 1, 1)  # 30 degrees, scale 1 in x-axis, 1 in y-axis
plot_floor.plot_complex()

Finally, the most important classes are RectBinaryImage and RectFloorPhoto, whose main responsabilities are creating plan crops for machine learning model training. These classes perform crops and downsampling on any image size and scale factor. For both objects, the main methods are:

def make_rect(self, rect: 'Rect', crop_length: NumberType = 5) -> Tuple[int, 'np.ndarray']:

def make_region(self, xmin: NumberType, xmax: NumberType, ymin: NumberType, ymax: NumberType,
                floor: 'Floor', rect: Optional['Rect'] = None) -> Tuple[int, 'np.ndarray']:

The first one creates a crop around the provided rect (using its position as the center, adding crop_length m for each axis). The second one creates a region on any arbitrary (xmin, ymin, xmax, ymax) region. Consider each position in meters.

From the provided notebook example, the following image shows two crops generated using a mutated floor plan with 30 degrees angle rotation. Crops are 256x256 px size, and displays a 10x10 m region, for a selected rectangle as origin.

Citing

@article{Pizarro2023,
    title = {Large-scale multi-unit floor plan dataset for architectural plan analysis and recognition},
    journal = {Automation in Construction},
    volume = {156},
    pages = {105132},
    year = {2023},
    issn = {0926-5805},
    doi = {https://doi.org/10.1016/j.autcon.2023.105132},
    url = {https://www.sciencedirect.com/science/article/pii/S0926580523003928},
    author = {Pablo N. Pizarro and Nancy Hitschfeld and Ivan Sipiran}
}

Author

Pablo Pizarro R. | 2023