From 9d39760f6fadecf7d67feaf3626400ad55adc5f9 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Tue, 10 Jan 2023 06:35:21 +1100 Subject: [PATCH] Add IfcClash to docs --- src/ifcclash/README.md | 121 --------------------- src/ifcopenshell-python/docs/ifcclash.rst | 123 ++++++++++++++++++++-- src/ifcopenshell-python/docs/ifcpatch.rst | 2 +- src/ifcpatch/README.md | 80 -------------- 4 files changed, 114 insertions(+), 212 deletions(-) delete mode 100644 src/ifcclash/README.md delete mode 100644 src/ifcpatch/README.md diff --git a/src/ifcclash/README.md b/src/ifcclash/README.md deleted file mode 100644 index 406131efb4..0000000000 --- a/src/ifcclash/README.md +++ /dev/null @@ -1,121 +0,0 @@ -# ifcclash - -`ifcclash` is both a CLI utility and library that lets you perform clash -detections on and between IFC files. - -## Installation - -`ifcclash` depends on -[`hppfcl`](https://github.com/humanoid-path-planner/hpp-fcl) and optionally -[`bcf`](https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.6.0/src/bcf). Once -you have the dependencies, the `ifcclash` directory may be added to your Python -site packages like any other Python module. You can run it as a CLI like: - -``` -$ python -m ifcclash -``` - -If you want something more Unix-like ... - -``` -$ alias ifcclash='python -m ifcclash' -``` - -Alternatively, you can package it as a distributable. - -``` -$ python make.py -$ ./dist/ifcclash -``` - -## Usage - -Instructions on what clashes to perform are structured in terms of clash sets. -Each clash set contains instructions of collisions that we want to perform, and -can be named so it is easy to distinguish. A typical name would be "Structure -and Pipes", to describe that we are are detecting collisions between structural -elements and pipes. - -Each clash set may include two groups of objects, named `A` and `B`. This tells -IfcClash to attempt to find collisions between any object in group `A` with any -object in group `B`. Group `A` is mandatory, but group `B` is optional. If group -`B` is not provided, IfcClash will detect all clashes within objects of group -`A`. - -Within group `A` or `B`, you may be define one or more data sources of objects. -A data source must include a path to the IFC file which the objects come from. -You may also optionally provide a filter to only include or exclude certain -objects. If no filter is provided, then all objects will be used to detect -collisions. - -Here's a sample JSON description of a single clash set, with both groups -defined with data sources. - -```json -[ - { - "name": "Clash Set A", - "a": [ - { - "file": "/path/to/one.ifc" - } - ], - "b": [ - { - "file": "/path/to/two.ifc", - "selector": ".IfcWall", - "mode": "i" - } - ] - } -] -``` - -Once your have your JSON description of your clashes, usage is like any other -CLI app. - -``` -$ ifcclash -h - -usage: __main__.py [-h] [-o OUTPUT] input - -Clashes geometry between two IFC files - -positional arguments: - input A JSON dataset describing a series of clashsets - -optional arguments: - -h, --help show this help message and exit - -o OUTPUT, --output OUTPUT - The JSON diff file to output. Defaults to output.json -``` - -In it simplest form, just present your JSON file. - -``` -$ ifcclash clash_sets.json -$ cat output.json -``` - -You can also use it as a library. - -```python -import sys -import json -import logging -import ifcclash - - -settings = ClashSettings() -settings.output = "output.json" -settings.logger = logging.getLogger("Clash") -settings.logger.setLevel(logging.DEBUG) -handler = logging.StreamHandler(sys.stdout) -handler.setLevel(logging.DEBUG) -settings.logger.addHandler(handler) -ifc_clasher = Clasher(settings) -with open(args.input, "r") as clash_sets_file: - ifc_clasher.clash_sets = json.loads(clash_sets_file.read()) -ifc_clasher.clash() -ifc_clasher.export() -``` diff --git a/src/ifcopenshell-python/docs/ifcclash.rst b/src/ifcopenshell-python/docs/ifcclash.rst index f112df4f52..44ce3074dd 100644 --- a/src/ifcopenshell-python/docs/ifcclash.rst +++ b/src/ifcopenshell-python/docs/ifcclash.rst @@ -1,16 +1,119 @@ IfcClash ======== -This documentation is free software! You are free to contribute and help write -this document. +IfcClash is both a CLI utility and library that lets you perform clash detection +on one or more IFC models. Clashes are defined in terms of clash sets with +filters using the IFC query syntax. -.. toctree:: - :maxdepth: 1 - :caption: Contents: +Source installation +------------------- -Indices and tables ------------------- +1. :doc:`Install IfcOpenShell ` +2. `Install hppfcl `_ +3. Optionally `install bcf `_ (needed for BCF reports of results) +4. `Clone the source code `_. +5. ``cd /path/to/src/ifcclash`` -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Here is a minimal example of how to use IfcPatch as a Python module or CLI +utility: + +:: + + $ python -m ifcclash -h + + usage: __main__.py [-h] [-o OUTPUT] input + + Clashes geometry between two IFC files + + positional arguments: + input A JSON dataset describing a series of clashsets + + options: + -h, --help show this help message and exit + -o OUTPUT, --output OUTPUT + The JSON diff file to output. Defaults to output.json + +Instructions on what clashes to perform are structured in terms of clash sets. +Each clash set contains instructions of collisions that we want to perform, and +can be named so it is easy to distinguish. A typical name would be "Structure +and Pipes", to describe that we are are detecting collisions between structural +elements and pipes. + +Each clash set may include two groups of objects, named ``A`` and ``B``. This +tells IfcClash to attempt to find collisions between any object in group ``A`` +with any object in group ``B``. Group ``A`` is mandatory, but group ``B`` is +optional. If group ``B`` is not provided, IfcClash will detect all clashes +within objects of group ``A``. + +Within group ``A`` or ``B``, you may define one or more data sources of objects. +A data source must include a path to the IFC file which the objects come from. +You may also optionally provide a filter to only include or exclude certain +objects. If no filter is provided, then all objects will be used to detect +collisions. + +Here's a sample JSON description of a single clash set, with both groups +defined with data sources. + +.. code-block:: json + + [ + { + "name": "Clash Set A", + "a": [ + { + "file": "/path/to/one.ifc" + } + ], + "b": [ + { + "file": "/path/to/two.ifc", + "selector": ".IfcWall", + "mode": "i" + } + ] + } + ] + +Once your have your JSON description of your clashes, usage is like any other +CLI app. + +:: + + $ ifcclash clash_sets.json + $ cat output.json + +Here is a minimal example of how to use IfcClash as a library: + +.. code-block:: python + + import sys + import json + import logging + import ifcclash + + + settings = ClashSettings() + settings.output = "output.json" + settings.logger = logging.getLogger("Clash") + settings.logger.setLevel(logging.DEBUG) + handler = logging.StreamHandler(sys.stdout) + handler.setLevel(logging.DEBUG) + settings.logger.addHandler(handler) + ifc_clasher = Clasher(settings) + with open(args.input, "r") as clash_sets_file: + ifc_clasher.clash_sets = json.loads(clash_sets_file.read()) + ifc_clasher.clash() + ifc_clasher.export() + +You can also alias it to a command: + +:: + + $ alias ifcclash='python -m ifcclash' + +Alternatively, you can package it as an executable. + +:: + + $ python make.py + $ ./dist/ifcclash diff --git a/src/ifcopenshell-python/docs/ifcpatch.rst b/src/ifcopenshell-python/docs/ifcpatch.rst index a1efe2b46d..bbf9043311 100644 --- a/src/ifcopenshell-python/docs/ifcpatch.rst +++ b/src/ifcopenshell-python/docs/ifcpatch.rst @@ -50,7 +50,7 @@ In this example, we'll extract out all `IfcWall` elements. $ ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a ".IfcWall" $ cat output.ifc -Here is a minimal example of how to use IfcDiff as a library: +Here is a minimal example of how to use IfcPatch as a library: .. code-block:: python diff --git a/src/ifcpatch/README.md b/src/ifcpatch/README.md deleted file mode 100644 index ac77c270b6..0000000000 --- a/src/ifcpatch/README.md +++ /dev/null @@ -1,80 +0,0 @@ -# ifcpatch - -`ifcpatch` is a little CLI utility and library that lets you run a predetermined -modification on an IFC file, known as a patch recipe. This is great for -distributing little scripts that need to modify an IFC to users who don't know -how to code or aren't interested in knowing the details. - -## Installation - -`ifcpatch` is a simple Python module. No compilation or packaging is necessary. -Just download the `ifcpatch` directory and add it to your Python site packages. -Then, you can run it as a CLI like: - -``` -$ python -m ifcpatch -``` - -If you want something more Unix-like ... - -``` -$ alias ifcpatch='python -m ifcpatch' -``` - -Alternatively, you can package it as a distributable. - -``` -$ python make.py -$ ./dist/ifcpatch -``` - -## Usage - -Usage is like any other CLI app. - -``` -$ ifcpatch -h - -usage: __main__.py [-h] -i INPUT [-o OUTPUT] -r RECIPE [-l LOG] - [-a ARGUMENTS [ARGUMENTS ...]] - -Patches IFC files to fix badly formatted data - -optional arguments: - -h, --help show this help message and exit - -i INPUT, --input INPUT - The IFC file to patch - -o OUTPUT, --output OUTPUT - The output file to save the patched IFC - -r RECIPE, --recipe RECIPE - Name of the recipe to use when patching - -l LOG, --log LOG Specify a log file - -a ARGUMENTS [ARGUMENTS ...], --arguments ARGUMENTS [ARGUMENTS ...] - Specify custom arguments to the patch recipe -``` - -Exactly how it is run depends on the recipe. A recipe may require zero or more -arguments which are specific to the recipe. Here's an example which runs the -`ExtractElements` recipe, which, as the same suggests, extracts out elements. -This recipe expects one argument, which uses the [IFC Query -syntax](https://wiki.osarch.org/index.php?title=IfcOpenShell_code_examples#IFC_Query_Syntax). -In this example, we'll extract out all `IfcWall` elements. - -``` -$ ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a ".IfcWall" -``` - -You can also use it as a library. - -```python -import ifcpatch - - -ifcpatch.execute({ - "input": "input.ifc", - "output": "output.ifc", - "recipe": "ExtractElements", - "log": "ifcpatch.log", - "arguments": [".IfcWall"], -}) -```