Add IfcClash to docs

2026-09-23 08:03:01 +00:00 · 2023-01-10 06:35:21 +11:00
parent 8aa4934d92
commit 9d39760f6f
4 changed files with 114 additions and 212 deletions
@@ -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()
 ```
@@ -1,16 +1,119 @@
 IfcClash
 ========
-This documentation is free software! You are free to contribute and help write
+IfcClash is both a CLI utility and library that lets you perform clash detection
-this document.
+on one or more IFC models. Clashes are defined in terms of clash sets with
 filters using the IFC query syntax.
-.. toctree::
+Source installation
-   :maxdepth: 1
+-------------------
   :caption: Contents:
-Indices and tables
+1. :doc:`Install IfcOpenShell <ifcopenshell-python/installation>`
------------------
+2. `Install hppfcl <https://github.com/humanoid-path-planner/hpp-fcl>`_
 3. Optionally `install bcf <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.7.0/src/bcf>`_ (needed for BCF reports of results)
 4. `Clone the source code <https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.7.0/src/ifcclash>`_.
 5. ``cd /path/to/src/ifcclash``
-* :ref:`genindex`
+Here is a minimal example of how to use IfcPatch as a Python module or CLI
-* :ref:`modindex`
+utility:
-* :ref:`search`
+
 ::
    $ 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
@@ -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
@@ -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"],
 })
 ```