Skip to content

Commit e0cd74d

Browse files
MoultMoult
committed
Fix #1338. Add documentation for how to use IfcClash.
1 parent 4fe4275 commit e0cd74d

5 files changed

Lines changed: 153 additions & 23 deletions

File tree

‎src/ifcclash/README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# ifcclash
2+
3+
`ifcclash` is both a CLI utility and library that lets you perform clash
4+
detections on and between IFC files.
5+
6+
## Installation
7+
8+
`ifcclash` depends on
9+
[`hppfcl`](https://github.com/humanoid-path-planner/hpp-fcl) and optionally
10+
[`bcf`](https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.6.0/src/bcf). Once
11+
you have the dependencies, the `ifcclash` directory may be added to your Python
12+
site packages like any other Python module. You can run it as a CLI like:
13+
14+
```
15+
$ python -m ifcclash
16+
```
17+
18+
If you want something more Unix-like ...
19+
20+
```
21+
$ alias ifcclash='python -m ifcclash'
22+
```
23+
24+
## Usage
25+
26+
Instructions on what clashes to perform are structured in terms of clash sets.
27+
Each clash set contains instructions of collisions that we want to perform, and
28+
can be named so it is easy to distinguish. A typical name would be "Structure
29+
and Pipes", to describe that we are are detecting collisions between structural
30+
elements and pipes.
31+
32+
Each clash set may include two groups of objects, named `A` and `B`. This tells
33+
IfcClash to attempt to find collisions between any object in group `A` with any
34+
object in group `B`. Group `A` is mandatory, but group `B` is optional. If group
35+
`B` is not provided, IfcClash will detect all clashes within objects of group
36+
`A`.
37+
38+
Within group `A` or `B`, you may be define one or more data sources of objects.
39+
A data source must include a path to the IFC file which the objects come from.
40+
You may also optionally provide a filter to only include or exclude certain
41+
objects. If no filter is provided, then all objects will be used to detect
42+
collisions.
43+
44+
Here's a sample JSON description of a single clash set, with both groups
45+
defined with data sources.
46+
47+
```json
48+
[
49+
{
50+
"name": "Clash Set A",
51+
"a": [
52+
{
53+
"file": "/path/to/one.ifc"
54+
}
55+
],
56+
"b": [
57+
{
58+
"file": "/path/to/two.ifc"
59+
"selector": ".IfcWall",
60+
"mode": "i"
61+
}
62+
]
63+
},
64+
...
65+
]
66+
```
67+
68+
Once your have your JSON description of your clashes, usage is like any other
69+
CLI app.
70+
71+
```
72+
$ ifcclash -h
73+
74+
usage: __main__.py [-h] [-o OUTPUT] input
75+
76+
Clashes geometry between two IFC files
77+
78+
positional arguments:
79+
input A JSON dataset describing a series of clashsets
80+
81+
optional arguments:
82+
-h, --help show this help message and exit
83+
-o OUTPUT, --output OUTPUT
84+
The JSON diff file to output. Defaults to output.json
85+
```
86+
87+
In it simplest form, just present your JSON file.
88+
89+
```
90+
$ ifcclash clash_sets.json
91+
$ cat output.json
92+
```
93+
94+
You can also use it as a library.
95+
96+
```python
97+
import sys
98+
import json
99+
import logging
100+
import ifcclash
101+
102+
103+
settings = ClashSettings()
104+
settings.output = "output.json"
105+
settings.logger = logging.getLogger("Clash")
106+
settings.logger.setLevel(logging.DEBUG)
107+
handler = logging.StreamHandler(sys.stdout)
108+
handler.setLevel(logging.DEBUG)
109+
settings.logger.addHandler(handler)
110+
ifc_clasher = Clasher(settings)
111+
with open(args.input, "r") as clash_sets_file:
112+
ifc_clasher.clash_sets = json.loads(clash_sets_file.read())
113+
ifc_clasher.clash()
114+
ifc_clasher.export()
115+
```

‎src/ifcclash/ifcclash/__init__.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import sys
2+
import json
3+
import logging
4+
import argparse
5+
from .ifcclash import Clasher, ClashSettings
6+
7+
8+
def main():
9+
parser = argparse.ArgumentParser(description="Clashes geometry between two IFC files")
10+
parser.add_argument("input", type=str, help="A JSON dataset describing a series of clashsets")
11+
parser.add_argument(
12+
"-o", "--output", type=str, help="The JSON diff file to output. Defaults to output.json", default="output.json"
13+
)
14+
args = parser.parse_args()
15+
16+
settings = ClashSettings()
17+
settings.output = args.output
18+
settings.logger = logging.getLogger("Clash")
19+
settings.logger.setLevel(logging.DEBUG)
20+
handler = logging.StreamHandler(sys.stdout)
21+
handler.setLevel(logging.DEBUG)
22+
settings.logger.addHandler(handler)
23+
ifc_clasher = Clasher(settings)
24+
with open(args.input, "r") as clash_sets_file:
25+
ifc_clasher.clash_sets = json.loads(clash_sets_file.read())
26+
ifc_clasher.clash()
27+
ifc_clasher.export()
28+
29+
30+
if __name__ == "__main__":
31+
main()

‎src/ifcclash/ifcclash/__main__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/usr/bin/env python3
2+
import ifcclash
3+
4+
ifcclash.main()

‎src/ifcclash/ifcclash/ifcclash.py‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -265,25 +265,3 @@ class ClashSettings:
265265
def __init__(self):
266266
self.logger = None
267267
self.output = "clashes.json"
268-
269-
270-
if __name__ == "__main__":
271-
parser = argparse.ArgumentParser(description="Clashes geometry between two IFC files")
272-
parser.add_argument("input", type=str, help="A JSON dataset describing a series of clashsets")
273-
parser.add_argument(
274-
"-o", "--output", type=str, help="The JSON diff file to output. Defaults to output.json", default="output.json"
275-
)
276-
args = parser.parse_args()
277-
278-
settings = ClashSettings()
279-
settings.output = args.output
280-
settings.logger = logging.getLogger("Clash")
281-
settings.logger.setLevel(logging.DEBUG)
282-
handler = logging.StreamHandler(sys.stdout)
283-
handler.setLevel(logging.DEBUG)
284-
settings.logger.addHandler(handler)
285-
ifc_clasher = Clasher(settings)
286-
with open(args.input, "r") as clash_sets_file:
287-
ifc_clasher.clash_sets = json.loads(clash_sets_file.read())
288-
ifc_clasher.clash()
289-
ifc_clasher.export()

‎src/ifcpatch/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,10 @@ $ ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a ".IfcWall"
5959

6060
You can also use it as a library.
6161

62-
```
62+
```python
6363
import ifcpatch
64+
65+
6466
ifcpatch.execute({
6567
"input": "input.ifc",
6668
"output": "output.ifc",

0 commit comments

Comments
 (0)