From 47c6c2ce9aad493c700a4f45cf9d804d0ed07ff9 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Wed, 7 Jun 2023 16:00:12 +1000 Subject: [PATCH] See #3266. Write documentation on how to use IfcCSV. --- src/ifcopenshell-python/docs/ifcclash.rst | 3 +- src/ifcopenshell-python/docs/ifcconvert.rst | 4 +- src/ifcopenshell-python/docs/ifccsv.rst | 150 +++++++++++++++++++- src/ifcopenshell-python/docs/ifcdiff.rst | 2 +- 4 files changed, 152 insertions(+), 7 deletions(-) diff --git a/src/ifcopenshell-python/docs/ifcclash.rst b/src/ifcopenshell-python/docs/ifcclash.rst index 44ce3074dd..5448bdde91 100644 --- a/src/ifcopenshell-python/docs/ifcclash.rst +++ b/src/ifcopenshell-python/docs/ifcclash.rst @@ -12,7 +12,7 @@ Source installation 2. `Install hppfcl `_ 3. Optionally `install bcf `_ (needed for BCF reports of results) 4. `Clone the source code `_. -5. ``cd /path/to/src/ifcclash`` +5. ``cd /path/to/IfcOpenShell/src/ifcclash`` Here is a minimal example of how to use IfcPatch as a Python module or CLI utility: @@ -91,7 +91,6 @@ Here is a minimal example of how to use IfcClash as a library: import logging import ifcclash - settings = ClashSettings() settings.output = "output.json" settings.logger = logging.getLogger("Clash") diff --git a/src/ifcopenshell-python/docs/ifcconvert.rst b/src/ifcopenshell-python/docs/ifcconvert.rst index 19c59c7b0f..78d9ae808e 100644 --- a/src/ifcopenshell-python/docs/ifcconvert.rst +++ b/src/ifcopenshell-python/docs/ifcconvert.rst @@ -4,8 +4,8 @@ IfcConvert IfcConvert is a command-line application for converting IFC geometry into file formats such as OBJ, DAE, GLB, STP, IGS, XML, SVG, H5, and IFC itself. -For other conversions, other software is available as other utilities within -IfcOpenShell. +For other formats, you may use other IfcOpenShell utilities as shown in the +table below. +-------------------------+-------------------------+----------------------+ | From Format | To Format | Tool | diff --git a/src/ifcopenshell-python/docs/ifccsv.rst b/src/ifcopenshell-python/docs/ifccsv.rst index 3734dbfbf5..da2ecc8298 100644 --- a/src/ifcopenshell-python/docs/ifccsv.rst +++ b/src/ifcopenshell-python/docs/ifccsv.rst @@ -1,5 +1,151 @@ IfcCSV ====== -IfcCSV exports and imports data from spreadsheet or tabular datasets. This lets -you view and edit IFC data using CSV, ODS, XLSX, and more. +IfcCSV lets you view and edit IFC data using spreadsheets or tabular datasets, +such as CSV, ODS, XLSX, Pandas DataFrames, and regular Python lists. + +IfcCSV lets you select rooted elements using the IFC selection queries. These +elements may be physical elements (walls, doors, windows, etc), construction +types (wall types, door types, window types, etc), or even non-geometric +(tasks, resources, cost items, etc). + +Once you have selected a list of elements, you may specify attributes, +properties, quantities, or relationships to extract and use as columns in your +table. + +For example, you might use a selection query of ``.IfcDoor``, for all doors in +your project. You may then specify a ``class`` attribute, a ``Name`` attribute, +a ``type.Name`` relationship, and a ``type.Description`` relationship. This +will produce a table as shown: + ++------------------------+---------+------+-----------+------------------------------------+ +| GlobalId | class | Name | type.Name | type.Description | ++========================+=========+======+===========+====================================+ +| 3AjGVS9EjBeBrDA5_tAcwQ | IfcDoor | 01 | DT-A | Single swing steel frame door | ++------------------------+---------+------+-----------+------------------------------------+ +| 07BewvHLn2$x6HsHH06rAA | IfcDoor | 02 | DT-A | Single swing steel frame door | ++------------------------+---------+------+-----------+------------------------------------+ +| 3b3Mk8uIb3Qu_eSPKxsI8x | IfcDoor | 01 | DT-B | Double swing steel frame fire door | ++------------------------+---------+------+-----------+------------------------------------+ +| ... | ... | ... | ... | ... | ++------------------------+---------+------+-----------+------------------------------------+ + +.. note:: + + IfcCSV automatically inserts the GlobalId column at the beginning, in order + to uniquely identify the element. + +This tabular data may then be exported in your desired format. + +You may then edit the data, and reimport the data back into IFC. The changes +you make in the spreadsheet or table will also be made in the IFC. + +There are different methods of installation, depending on your situation. + +1. **Source installation** is recommended for users wanting to use the latest + code as a library or a CLI utility. +2. **Using the BlenderBIM Add-on** is recommended for non-developers wanting a + graphical interface. + +Source installation +------------------- + +1. :doc:`Install IfcOpenShell ` +2. `Clone the source code `_. +3. ``cd /path/to/IfcOpenShell/src/ifccsv`` + +Depending on which formats you want to edit, you will need to install more dependencies: + +- ``pip install odfpy`` for ODS support +- ``pip install xlsxwriter`` for XLSX support +- ``pip install pandas`` for Pandas DataFrame support + +Here is a minimal example of how to use IfcDiff as a Python module or CLI +utility: + +:: + + $ python -m ifccsv -h + usage: ifccsv.py [-h] -i IFC [-s SPREADSHEET] [-f FORMAT] [-q QUERY] [-a ARGUMENTS [ARGUMENTS ...]] [--export] [--import] + + Exports IFC data to and from CSV + + options: + -h, --help show this help message and exit + -i IFC, --ifc IFC The IFC file + -s SPREADSHEET, --spreadsheet SPREADSHEET + The spreadsheet file + -f FORMAT, --format FORMAT + The format, chosen from csv, ods, or xlsx + -q QUERY, --query QUERY + Specify a IFC query selector, such as ".IfcWall" + -a ARGUMENTS [ARGUMENTS ...], --arguments ARGUMENTS [ARGUMENTS ...] + Specify attributes that are part of the extract, using the IfcQuery syntax such as 'type', 'Name' or 'Pset_Foo.Bar' + --export Export from IFC to CSV + --import Import from CSV to IFC + $ python -m ifccsv -i model.ifc -s out.csv -f csv -q .IfcProduct -a "Name" "Description" --export + $ cat out.csv + +Here is a minimal example of how to use IfcCSV as a library: + +.. code-block:: python + + import ifcopenshell + from ifccsv import IfcCsv + + model = ifcopenshell.open("/path/to/model.ifc") + # Using the selector is optional. You may specify elements as a list manually if you prefer. + # e.g. elements = model.by_type("IfcElement") + elements = ifcopenshell.util.selector.Selector.parse(model, ".IfcElement") + attributes = ["Name", "Description"] + + # Export our model's elements and their attributes to a CSV. + ifc_csv = IfcCsv() + ifc_csv.export(model, elements, attributes, output="out.csv", format="csv", delimiter=",") + + # Optionally, you can explicitly export to different formats. + # ifc_csv = IfcCsv() + # ifc_csv.export(model, elements, attributes) + ifc_csv.export_csv("out.csv", delimiter=";") + ifc_csv.export_ods("out.ods") + ifc_csv.export_xlsx("out.xlsx") + + # Optionally, you can create a Pandas DataFrame. + df = ifc_csv.export_pd() + print(df) + + # Optionally, you can directly fetch the headers and rows as Python lists. + print(ifc_csv.headers) + print(ifc_csv.results) + + # You can also import changes from a CSV + ifc_csv.Import(model, "input.csv") + model.write("/path/to/updated_model.ifc") + +Using the BlenderBIM Add-on +--------------------------- + +The BlenderBIM Add-on is a Blender based graphical interface to IfcOpenShell. +Other than providing a graphical IFC authoring platform, it also comes with +IfcOpenShell, its utilities, and a Python shell built-in. This means you don't +need to install Python first, and you also can compare your IfcOpenShell +scripting to what you see with a visual model viewer, or use a graphical +interface to access the IfcOpenShell utilities. + +1. Install the BlenderBIM Add-on by following the `BlenderBIM Add-on + installation documentation + `_. + +2. Launch Blender. Change to the **Scene Properties** tab in the **Properties + Panel**. Scroll down to the **IFC Collaboration > IFC CSV Import / Export** + panel. + +3. Browse to your IFC file. + +4. Type in a filter query, such as ``.IfcDoor``. + +5. Optionally add attributes you'd like to export. + +6. Press **Export IFC to CSV** + +TODO: add pictures and make this clearer for non-developers. diff --git a/src/ifcopenshell-python/docs/ifcdiff.rst b/src/ifcopenshell-python/docs/ifcdiff.rst index b73530cae4..b8b5332566 100644 --- a/src/ifcopenshell-python/docs/ifcdiff.rst +++ b/src/ifcopenshell-python/docs/ifcdiff.rst @@ -28,7 +28,7 @@ Source installation 1. :doc:`Install IfcOpenShell ` 2. `Clone the source code `_. -3. ``cd /path/to/src/ifcdiff`` +3. ``cd /path/to/IfcOpenShell/src/ifcdiff`` 4. ``pip install -r requirements.txt`` Here is a minimal example of how to use IfcDiff as a Python module or CLI