===========
MLSTRUCT-FP
===========
.. image:: https://img.shields.io/github/actions/workflow/status/MLSTRUCT/MLSTRUCT-FP/ci.yml?branch=master
:target: https://github.com/MLSTRUCT/MLSTRUCT-FP/actions/workflows/ci.yml
:alt: Build status
.. image:: https://img.shields.io/github/issues/MLSTRUCT/MLSTRUCT-FP
:target: https://github.com/MLSTRUCT/MLSTRUCT-FP/issues
:alt: Open issues
.. image:: https://badge.fury.io/py/MLStructFP.svg
:target: https://pypi.org/project/MLStructFP
:alt: PyPi package
.. image:: https://codecov.io/gh/MLSTRUCT/MLSTRUCT-FP/branch/master/graph/badge.svg?token=EJ8S2AAGUO
:target: https://codecov.io/gh/MLSTRUCT/MLSTRUCT-FP
:alt: Codecov
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
:target: https://opensource.org/licenses/MIT
:alt: License MIT
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 Slab' 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 <https://doi.org/10.1016/j.autcon.2023.105132>`_.
First steps
-----------
In order to install the library, use the following python-pip commands:
.. code-block:: bash
python -m pip install MLStructFP
To download the dataset (compressed in .zip), request for a public download link by completing a
`simple form <https://forms.gle/HigdGxngnTEvnNC37>`_.
Dataset details
---------------
The dataset (uncompressed) has the following structure:
.. code-block:: bash
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:
.. code-block:: JSON
{
"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 <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/example.ipynb>`_. The most basic
object is `DbLoader <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_db_loader.py>`_,
which receives the path of the ``fp.json`` file.
.. code-block:: python
class DbLoader(db: str)
# Example
db = DbLoader('test/data/fp.json')
db.tabulate()
.. image:: docs/example-tabulate.png
:width: 640
:alt: Example tabulate
DbLoader creates a dict of `Floor <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_floor.py>`_ object,
which each contains a dict of `Rect <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_c_rect.py>`_ and
`Slab <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_c_slab.py>`_ 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:
.. code-block:: python
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()
.. image:: docs/example-plot.png
:width: 640
:alt: Example plot
Finally, the most important classes are
`RectBinaryImage <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/image/_rect_binary.py>`_ and
`RectFloorPhoto <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/image/_rect_photo.py>`_, 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:
.. code-block:: python
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.
.. image:: docs/example-rects.png
:width: 640
:alt: Example plot
Citing
------
.. code-block:: tex
@article{Pizarro2023,
title = {Large-scale multi-unit floor plan datasetfor 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. <https://ppizarror.com>`_ | 2023 - 2024
Raw data
{
"_id": null,
"home_page": "https://github.com/MLSTRUCT/MLSTRUCT-FP",
"name": "MLStructFP",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ml, ai, dataset, calc, matrix analysis, cnn, structural analysis, structural design",
"author": "Pablo Pizarro R.",
"author_email": "pablo@ppizarror.com",
"download_url": "https://files.pythonhosted.org/packages/8f/2a/782744d77198403ac59391143a7a739c079c725b930594e2e5a14b3afbd3/MLStructFP-0.5.7.tar.gz",
"platform": "any",
"description": "\r\n===========\r\nMLSTRUCT-FP\r\n===========\r\n\r\n.. image:: https://img.shields.io/github/actions/workflow/status/MLSTRUCT/MLSTRUCT-FP/ci.yml?branch=master\r\n :target: https://github.com/MLSTRUCT/MLSTRUCT-FP/actions/workflows/ci.yml\r\n :alt: Build status\r\n\r\n.. image:: https://img.shields.io/github/issues/MLSTRUCT/MLSTRUCT-FP\r\n :target: https://github.com/MLSTRUCT/MLSTRUCT-FP/issues\r\n :alt: Open issues\r\n\r\n.. image:: https://badge.fury.io/py/MLStructFP.svg\r\n :target: https://pypi.org/project/MLStructFP\r\n :alt: PyPi package\r\n\r\n.. image:: https://codecov.io/gh/MLSTRUCT/MLSTRUCT-FP/branch/master/graph/badge.svg?token=EJ8S2AAGUO\r\n :target: https://codecov.io/gh/MLSTRUCT/MLSTRUCT-FP\r\n :alt: Codecov\r\n\r\n.. image:: https://img.shields.io/badge/license-MIT-blue.svg\r\n :target: https://opensource.org/licenses/MIT\r\n :alt: License MIT\r\n\r\nMulti-unit floor plan dataset.\r\n\r\n\r\nDescription\r\n-----------\r\n\r\nThis repo contains the base library to load and parse floor plans from MLSTRUCT-FP dataset, which\r\ncontains over 954 large-scale floor plans images, alongside annotations for their walls in JSON\r\nformat. The database loader just loads in memory the Floor, Walls, and Slab' objects, and also\r\noffers methods to create custom images from floor plans by applying a crop, a rotation, and custom\r\nscaling.\r\n\r\nThe images can be generated from the real rasterized plan, or by using the polygons stored in the\r\nJSON file. Both image and wall polygons are consistent in their placement.\r\n\r\nSee more information in our `published article <https://doi.org/10.1016/j.autcon.2023.105132>`_.\r\n\r\n\r\nFirst steps\r\n-----------\r\n\r\nIn order to install the library, use the following python-pip commands:\r\n\r\n.. code-block:: bash\r\n\r\n python -m pip install MLStructFP\r\n\r\nTo download the dataset (compressed in .zip), request for a public download link by completing a \r\n`simple form <https://forms.gle/HigdGxngnTEvnNC37>`_.\r\n\r\n\r\nDataset details\r\n---------------\r\n\r\nThe dataset (uncompressed) has the following structure:\r\n\r\n.. code-block:: bash\r\n \r\n dataset/\r\n 0a0...736.png\r\n 0a7...b41.png\r\n ...\r\n ff4...ff4.png\r\n ffd...faf.png\r\n fp.json\r\n\r\nEach image is stored in PNG format, with transparent background. Image\r\nsize ranges between 6500 and 9500 px. Each file represents a distinct floor,\r\nwhose labels (wall polygons, slabs) and metadata are stored within fp.json.\r\n\r\nThe format of the fp.json file is characterized as follows:\r\n\r\n.. code-block:: JSON\r\n \r\n {\r\n \"rect\": {\r\n \"1000393\": {\r\n \"angle\": 0.0,\r\n \"floorID\": 8970646,\r\n \"length\": 2.6,\r\n \"line\": [\r\n 0.0,\r\n -15.039,\r\n 0.0\r\n ],\r\n \"thickness\": 0.2,\r\n \"wallID\": 5969311,\r\n \"x\": [\r\n 13.39,\r\n 15.99,\r\n 15.99,\r\n 13.39\r\n ],\r\n \"y\": [\r\n -14.939,\r\n -14.939,\r\n -15.139,\r\n -15.139\r\n ]\r\n },\r\n ...\r\n },\r\n \"slab\": {\r\n \"1002588\": {\r\n \"floorID\": 5980221,\r\n \"x\": [\r\n -1.153,\r\n 4.897,\r\n 4.897,\r\n ...\r\n ],\r\n \"y\": [\r\n -22.622,\r\n -22.622,\r\n -19.117,\r\n ...\r\n ],\r\n },\r\n ...\r\n },\r\n \"floor\": {\r\n \"1014539\": {\r\n \"image\": \"83d4b2b46052b81347c2c369076ce9e792da8b7c.png\",\r\n \"scale\": 193.412\r\n },\r\n ...\r\n }\r\n }\r\n\r\nNote the dataset comprises a list of \"rect\" representing the rectangles (wall segments),\r\n\"slab\" and \"floor\". Each item has a distinct ID for quering and grouping elements. In the example,\r\nthe rect ID ``1000393`` is within floor ID ``8970646``, with an angle of ``0`` degrees, a length\r\nof ``2.6 m``, and within the wall ID ``5969311``. Likewise, the slab ``1002588`` is within floor\r\nID ``5980221``, whose its first point (x, y) is ``(-1.153, -22.622) m``. Finally, the floor ID\r\n``1014539`` is associated with the image ``83d...8b7c.png`` and a scale ``193.412 px/m``. In total,\r\nthere are ``70873`` rects, ``954`` slabs and ``954`` floors.\r\n\r\n\r\nObject API\r\n----------\r\n\r\nThe basic usage of the API is illustrated on the\r\n`jupyter notebook <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/example.ipynb>`_. The most basic\r\nobject is `DbLoader <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_db_loader.py>`_,\r\nwhich receives the path of the ``fp.json`` file.\r\n\r\n.. code-block:: python\r\n \r\n class DbLoader(db: str)\r\n \r\n # Example\r\n db = DbLoader('test/data/fp.json')\r\n db.tabulate()\r\n\r\n.. image:: docs/example-tabulate.png\r\n :width: 640\r\n :alt: Example tabulate\r\n\r\nDbLoader creates a dict of `Floor <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_floor.py>`_ object,\r\nwhich each contains a dict of `Rect <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_c_rect.py>`_ and\r\n`Slab <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/_c_slab.py>`_ objects. Each item is associated\r\nusing their respective ids. Floor object also have many methods to retrieve their elements, plot, and apply\r\ntransformations (aka mutations) such as scaling or rotation using ``mutate()`` method:\r\n\r\n.. code-block:: python\r\n \r\n class Floor:\r\n ...\r\n \r\n def mutate(self, angle: NumberType = 0, sx: NumberType = 1, sy: NumberType = 1,\r\n scale_first: bool = True) -> 'Floor':\r\n ...\r\n \r\n # Example\r\n plot_floor = db.floor[302]\r\n plot_floor.mutate(30, 1, 1) # 30 degrees, scale 1 in x-axis, 1 in y-axis\r\n plot_floor.plot_complex()\r\n\r\n.. image:: docs/example-plot.png\r\n :width: 640\r\n :alt: Example plot\r\n\r\nFinally, the most important classes are\r\n`RectBinaryImage <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/image/_rect_binary.py>`_ and\r\n`RectFloorPhoto <https://github.com/MLSTRUCT/MLSTRUCT-FP/blob/master/MLStructFP/db/image/_rect_photo.py>`_, whose\r\nmain responsabilities are creating plan crops for machine learning model training. These classes perform crops\r\nand downsampling on any image size and scale factor. For both objects, the main methods are:\r\n\r\n.. code-block:: python\r\n \r\n def make_rect(self, rect: 'Rect', crop_length: NumberType = 5) -> Tuple[int, 'np.ndarray']:\r\n \r\n def make_region(self, xmin: NumberType, xmax: NumberType, ymin: NumberType, ymax: NumberType,\r\n floor: 'Floor', rect: Optional['Rect'] = None) -> Tuple[int, 'np.ndarray']:\r\n\r\nThe first one creates a crop around the provided rect (using its position as the center, adding ``crop_length`` m\r\nfor each axis). The second one creates a region on any arbitrary ``(xmin, ymin, xmax, ymax)`` region. Consider\r\neach position in meters.\r\n\r\nFrom the provided notebook example, the following image shows two crops generated using a mutated floor plan\r\nwith 30 degrees angle rotation. Crops are ``256x256 px`` size, and displays a ``10x10 m`` region, for a selected\r\nrectangle as origin.\r\n\r\n.. image:: docs/example-rects.png\r\n :width: 640\r\n :alt: Example plot\r\n\r\n\r\nCiting\r\n------\r\n\r\n.. code-block:: tex\r\n \r\n @article{Pizarro2023,\r\n title = {Large-scale multi-unit floor plan datasetfor architectural plan analysis and\r\n recognition},\r\n journal = {Automation in Construction},\r\n volume = {156},\r\n pages = {105132},\r\n year = {2023},\r\n issn = {0926-5805},\r\n doi = {https://doi.org/10.1016/j.autcon.2023.105132},\r\n url = {https://www.sciencedirect.com/science/article/pii/S0926580523003928},\r\n author = {Pablo N. Pizarro and Nancy Hitschfeld and Ivan Sipiran}\r\n }\r\n\r\n\r\nAuthor\r\n------\r\n\r\n`Pablo Pizarro R. <https://ppizarror.com>`_ | 2023 - 2024\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Machine learning structural floor plan dataset",
"version": "0.5.7",
"project_urls": {
"Bug Tracker": "https://github.com/MLSTRUCT/MLSTRUCT-FP/issues",
"Documentation": "https://github.com/MLSTRUCT/MLSTRUCT-FP",
"Homepage": "https://github.com/MLSTRUCT/MLSTRUCT-FP",
"Source Code": "https://github.com/MLSTRUCT/MLSTRUCT-FP"
},
"split_keywords": [
"ml",
" ai",
" dataset",
" calc",
" matrix analysis",
" cnn",
" structural analysis",
" structural design"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f01a775669a1d026af8061e1640495eb12330b1f7d826168ed580188b3e2d7aa",
"md5": "22c3a0bd9be9687d043c6d0230e085cf",
"sha256": "8344b6cb9b663afa0ec21c94becfb542bf407a952c2d7b5f35c9ff930ccb26bb"
},
"downloads": -1,
"filename": "MLStructFP-0.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22c3a0bd9be9687d043c6d0230e085cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30708,
"upload_time": "2024-04-01T00:34:21",
"upload_time_iso_8601": "2024-04-01T00:34:21.393680Z",
"url": "https://files.pythonhosted.org/packages/f0/1a/775669a1d026af8061e1640495eb12330b1f7d826168ed580188b3e2d7aa/MLStructFP-0.5.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f2a782744d77198403ac59391143a7a739c079c725b930594e2e5a14b3afbd3",
"md5": "08b8abdea6e43639dc0d8292ce0784ad",
"sha256": "cebf36b6203c0a129109daba16dceec351714c38974ac30d39b6c3a2565b1e45"
},
"downloads": -1,
"filename": "MLStructFP-0.5.7.tar.gz",
"has_sig": false,
"md5_digest": "08b8abdea6e43639dc0d8292ce0784ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24704,
"upload_time": "2024-04-01T00:34:22",
"upload_time_iso_8601": "2024-04-01T00:34:22.939303Z",
"url": "https://files.pythonhosted.org/packages/8f/2a/782744d77198403ac59391143a7a739c079c725b930594e2e5a14b3afbd3/MLStructFP-0.5.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-01 00:34:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MLSTRUCT",
"github_project": "MLSTRUCT-FP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mlstructfp"
}
JSON
