mirror of
https://github.com/IfcOpenShell/IfcOpenShell.git
synced 2026-08-05 23:41:44 +00:00
ifcquery, ifcedit, ifcmcp: add documentation
Add ifcquery, ifcedit and ifcmcp to the README contents table, the Sphinx docs toctree and introduction utilities table. Add new .rst pages for each package documenting subcommands, installation, usage, and parameter types. Fix plot and render CLI examples in ifcquery README to use -o/--out-format flags. Update ifcmcp README to use the installed ifcmcp command rather than python3 -m ifcmcp. Generated with the assistance of an AI coding tool.
This commit is contained in:
Bruno Postle
committed by
Thomas Krijnen
Thomas Krijnen
parent
c057e79f17
commit
9ea302cdf1
@@ -50,10 +50,13 @@ Contents
|
||||
| [ifcconvert](https://docs.ifcopenshell.org/ifcconvert.html) | CLI app to convert IFC to many other formats | LGPL-3.0-or-later\* | [](https://docs.ifcopenshell.org/ifcconvert/installation.html) [](https://github.com/IfcOpenShell/IfcOpenShell/releases?q=ifcconvert&expanded=true)
|
||||
| [ifccsv](https://docs.ifcopenshell.org/ifccsv.html) | Library and CLI app to export and import schedules from IFC | LGPL-3.0-or-later | [](https://pypi.org/project/ifccsv/) |
|
||||
| [ifcdiff](https://docs.ifcopenshell.org/ifcdiff.html) | Compare changes between IFC models | LGPL-3.0-or-later | [](https://pypi.org/project/ifcdiff/) |
|
||||
| [ifcedit](https://docs.ifcopenshell.org/ifcedit.html) | CLI wrapper for ifcopenshell.api IFC model mutation functions | LGPL-3.0-or-later | [](https://pypi.org/project/ifcedit/) |
|
||||
| [ifcfm](https://docs.ifcopenshell.org/ifcfm.html) | Extract IFC data for FM handover requirements | LGPL-3.0-or-later | [](https://pypi.org/project/ifcfm/) |
|
||||
| [ifcmax](https://docs.ifcopenshell.org/ifcmax.html) | Historic extension for IFC support in 3DS Max | LGPL-3.0-or-later\* | [](https://docs.ifcopenshell.org/ifcmax.html)
|
||||
| [ifcmcp](https://docs.ifcopenshell.org/ifcmcp.html) | MCP server for querying and editing IFC building models | LGPL-3.0-or-later | [](https://pypi.org/project/ifcmcp/) |
|
||||
| [ifcopenshell-python](https://docs.ifcopenshell.org/ifcopenshell-python.html) | Python library for IFC manipulation | LGPL-3.0-or-later\* | [](https://docs.ifcopenshell.org/ifcopenshell-python/installation.html) [](https://github.com/IfcOpenShell/IfcOpenShell/releases?q=ifcopenshell-python&expanded=true) [](https://pypi.org/project/ifcopenshell/) [](https://anaconda.org/conda-forge/ifcopenshell) [](https://anaconda.org/ifcopenshell/ifcopenshell) [](https://hub.docker.com/r/aecgeeks/ifcopenshell) [](https://aur.archlinux.org/packages/ifcopenshell) [](https://aur.archlinux.org/packages/ifcopenshell-git) [Pyodide WASM Wheels](https://github.com/IfcOpenShell/wasm-wheels#pyodide-test-wheels) |
|
||||
| [ifcpatch](https://docs.ifcopenshell.org/ifcpatch.html) | Utility to run pre-packaged scripts to manipulate IFCs | LGPL-3.0-or-later | [](https://pypi.org/project/ifcpatch/) |
|
||||
| [ifcquery](https://docs.ifcopenshell.org/ifcquery.html) | CLI tool for querying and inspecting IFC building models | LGPL-3.0-or-later | [](https://pypi.org/project/ifcquery/) |
|
||||
| [ifcsverchok](https://docs.ifcopenshell.org/ifcsverchok.html) | Blender Add-on for visual node programming with IFC | GPL-3.0-or-later | [](https://github.com/IfcOpenShell/IfcOpenShell/releases?q=ifcsverchok&expanded=true)
|
||||
| [ifctester](https://docs.ifcopenshell.org/ifctester.html) | Library, CLI and webapp for IDS model auditing | LGPL-3.0-or-later | [](https://pypi.org/project/ifctester/) |
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ Requires `ifcopenshell`, `ifcquery`, and `ifcedit`. The `mcp` package is an opti
|
||||
## Running the server
|
||||
|
||||
```bash
|
||||
python3 -m ifcmcp
|
||||
ifcmcp
|
||||
```
|
||||
|
||||
This starts the server on stdio transport, suitable for use with Claude Code
|
||||
@@ -27,7 +27,7 @@ or any MCP client.
|
||||
Use the `claude mcp add` command:
|
||||
|
||||
```bash
|
||||
claude mcp add --transport stdio ifc -- python3 -m ifcmcp
|
||||
claude mcp add --transport stdio ifc -- ifcmcp
|
||||
```
|
||||
|
||||
Or create a `.mcp.json` file in your project root:
|
||||
@@ -37,8 +37,7 @@ Or create a `.mcp.json` file in your project root:
|
||||
"mcpServers": {
|
||||
"ifc": {
|
||||
"type": "stdio",
|
||||
"command": "python3",
|
||||
"args": ["-m", "ifcmcp"]
|
||||
"command": "ifcmcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
IfcEdit
|
||||
=======
|
||||
|
||||
IfcEdit is a CLI wrapper for the full ``ifcopenshell.api`` mutation API. It
|
||||
exposes all editor functions — over 350 across 30+ modules — without requiring
|
||||
you to write a Python script. It supports four subcommands:
|
||||
|
||||
- **list** — list all API modules, or all functions within a module
|
||||
- **docs** — show full documentation for a function (parameters, types, descriptions)
|
||||
- **run** — execute a mutation against an IFC file
|
||||
- **quantify** — run quantity take-off using ifc5d rules; requires the IfcOpenShell C++ geometry bindings
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
::
|
||||
|
||||
pip install ifcedit
|
||||
|
||||
Or install from source:
|
||||
|
||||
1. :doc:`Install IfcOpenShell <ifcopenshell-python/installation>`
|
||||
2. `Clone the IfcOpenShell repository <https://github.com/IfcOpenShell/IfcOpenShell>`_.
|
||||
3. ``cd /path/to/IfcOpenShell/src/ifcedit``
|
||||
4. ``pip install .``
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Discover available API functions::
|
||||
|
||||
$ ifcedit list
|
||||
$ ifcedit list root
|
||||
$ ifcedit list geometry
|
||||
|
||||
Read documentation for a function::
|
||||
|
||||
$ ifcedit docs root.remove_product
|
||||
$ ifcedit docs type.assign_type
|
||||
|
||||
Execute a mutation (overwrites the input file by default)::
|
||||
|
||||
$ ifcedit run model.ifc root.remove_product --product 42
|
||||
$ ifcedit run model.ifc type.assign_type --related_objects 10 --relating_type 20
|
||||
|
||||
Write to a separate output file::
|
||||
|
||||
$ ifcedit run model.ifc root.create_entity -o output.ifc --ifc_class IfcWall
|
||||
|
||||
Dry-run to validate without modifying the file::
|
||||
|
||||
$ ifcedit run model.ifc root.remove_product --dry-run --product 42
|
||||
|
||||
Quantity take-off (writes ``IfcElementQuantity`` psets back to the file; requires C++ geometry bindings)::
|
||||
|
||||
$ ifcedit quantify list
|
||||
$ ifcedit quantify run model.ifc IFC4QtoBaseQuantities
|
||||
$ ifcedit quantify run model.ifc IFC4QtoBaseQuantities --selector IfcWall
|
||||
$ ifcedit quantify run model.ifc IFC4QtoBaseQuantities -o model_qto.ifc
|
||||
|
||||
Parameter types
|
||||
---------------
|
||||
|
||||
IfcEdit automatically coerces CLI string arguments to the correct Python types
|
||||
using the type hints on each API function:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Type
|
||||
- CLI input
|
||||
- Python value
|
||||
* - ``str``
|
||||
- ``"hello"``
|
||||
- ``"hello"``
|
||||
* - ``int``
|
||||
- ``"42"`` or ``"#42"``
|
||||
- ``42``
|
||||
* - ``float``
|
||||
- ``"3.14"``
|
||||
- ``3.14``
|
||||
* - ``bool``
|
||||
- ``"true"``, ``"1"``, ``"yes"``
|
||||
- ``True``
|
||||
* - ``Optional[X]``
|
||||
- ``"none"``
|
||||
- ``None``
|
||||
* - ``entity_instance``
|
||||
- ``"42"`` or ``"#42"``
|
||||
- resolved from model by step ID
|
||||
* - ``list[entity_instance]``
|
||||
- ``"5,6,7"``
|
||||
- list of resolved entities
|
||||
* - ``dict``
|
||||
- ``'{"key": "val"}'``
|
||||
- parsed JSON object
|
||||
* - ``Literal["A", "B"]``
|
||||
- ``"A"``
|
||||
- validated against allowed values
|
||||
|
||||
.. seealso::
|
||||
|
||||
Use :doc:`IfcQuery <ifcquery>` for read-only inspection of IFC files, and
|
||||
:doc:`IfcMCP <ifcmcp>` for interactive AI-assisted editing with an in-memory
|
||||
session.
|
||||
@@ -0,0 +1,110 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
IfcMCP
|
||||
======
|
||||
|
||||
IfcMCP is an MCP (Model Context Protocol) server that exposes IfcOpenShell
|
||||
query and edit tools to AI coding assistants such as Claude. It wraps
|
||||
:doc:`IfcQuery <ifcquery>` and :doc:`IfcEdit <ifcedit>`, holding the IFC model
|
||||
in memory across tool calls so no file I/O is required between operations.
|
||||
|
||||
The ``ifcmcp`` package can also be used directly as a Python library without
|
||||
the MCP server layer.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
To use IfcMCP as an MCP server, install it together with the ``mcp`` package::
|
||||
|
||||
pip install 'ifcmcp[mcp]'
|
||||
|
||||
If you only want to use the library directly (without an MCP client)::
|
||||
|
||||
pip install ifcmcp
|
||||
|
||||
Or install from source:
|
||||
|
||||
1. :doc:`Install IfcOpenShell <ifcopenshell-python/installation>`
|
||||
2. `Clone the IfcOpenShell repository <https://github.com/IfcOpenShell/IfcOpenShell>`_.
|
||||
3. ``cd /path/to/IfcOpenShell/src/ifcmcp``
|
||||
4. ``pip install '.[mcp]'``
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
Add the server to your MCP client. For Claude Code::
|
||||
|
||||
claude mcp add --transport stdio ifc -- ifcmcp
|
||||
|
||||
Or add to ``.mcp.json``:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"mcpServers": {
|
||||
"ifc": {
|
||||
"type": "stdio",
|
||||
"command": "ifcmcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Available tools
|
||||
---------------
|
||||
|
||||
**Session tools**
|
||||
|
||||
- ``ifc_new(schema="IFC4")`` — create a new empty model in memory
|
||||
- ``ifc_load(path)`` — open an IFC file into memory
|
||||
- ``ifc_reset()`` — unload the current model, freeing all session state
|
||||
- ``ifc_save(path="")`` — write model to disk; empty path overwrites the original
|
||||
|
||||
**Query tools**
|
||||
|
||||
- ``ifc_summary()`` — schema version, entity counts, project metadata
|
||||
- ``ifc_tree()`` — full spatial hierarchy
|
||||
- ``ifc_info(element_id)`` — deep inspection by step ID
|
||||
- ``ifc_select(query)`` — filter elements by IFC class
|
||||
- ``ifc_relations(element_id, traverse="")`` — relationships for an element
|
||||
- ``ifc_clash(element_id, ...)`` — geometric intersection and clearance checks
|
||||
- ``ifc_validate(express_rules=False)`` — schema and constraint validation
|
||||
- ``ifc_schedule(max_depth=None)`` — work schedules with nested task trees
|
||||
- ``ifc_cost(max_depth=None)`` — cost schedules with nested cost item trees
|
||||
- ``ifc_schema(entity_type)`` — IFC class documentation
|
||||
- ``ifc_contexts()`` — geometric representation contexts
|
||||
- ``ifc_materials()`` — material definitions
|
||||
|
||||
**Drawing and rendering tools**
|
||||
|
||||
- ``ifc_plot(...)`` — generate a 2D drawing via ``ifcopenshell.draw`` and return it as an inline image the AI assistant can inspect; SVG always available, PNG requires ``cairosvg``
|
||||
- ``ifc_render(...)`` — off-screen 3D render returned as an inline PNG image the AI assistant can inspect; requires ``pyvista`` and the IfcOpenShell C++ geometry bindings
|
||||
|
||||
**ShapeBuilder tools**
|
||||
|
||||
- ``ifc_shape_list()`` — list all available ``ShapeBuilder`` methods
|
||||
- ``ifc_shape_docs(method)`` — documentation for a specific ``ShapeBuilder`` method
|
||||
- ``ifc_shape(method, params="{}")`` — execute a ``ShapeBuilder`` method; entity references resolved by step ID
|
||||
|
||||
**Edit tools**
|
||||
|
||||
- ``ifc_list(module="")`` — list API modules or functions
|
||||
- ``ifc_docs(function_path)`` — documentation for an API function
|
||||
- ``ifc_edit(function_path, params="{}")`` — execute an ``ifcopenshell.api`` mutation
|
||||
- ``ifc_quantify(rule, selector="")`` — run quantity take-off; writes ``IfcElementQuantity`` psets in-place
|
||||
|
||||
Typical workflow
|
||||
----------------
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
ifc_load("/path/to/model.ifc")
|
||||
ifc_summary()
|
||||
ifc_tree()
|
||||
ifc_info(42)
|
||||
ifc_edit("root.remove_product", '{"product": "42"}')
|
||||
ifc_save()
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`IfcQuery <ifcquery>` and :doc:`IfcEdit <ifcedit>` provide the same
|
||||
functionality as standalone CLI tools for scripting and automation.
|
||||
@@ -0,0 +1,75 @@
|
||||
.. This file was generated with the assistance of an AI coding tool.
|
||||
|
||||
IfcQuery
|
||||
========
|
||||
|
||||
IfcQuery is a CLI tool for querying and inspecting IFC building models. It
|
||||
provides read-only subcommands for common inspection tasks, all outputting JSON
|
||||
so results can be piped into other tools.
|
||||
|
||||
Subcommands:
|
||||
|
||||
- **summary** — schema version, entity counts, project metadata
|
||||
- **tree** — full spatial hierarchy (IfcProject → Site → Building → Storeys → Spaces → Elements)
|
||||
- **info** — deep inspection of any entity by step ID (attributes, property sets, placement matrix, type, material)
|
||||
- **select** — filter elements by IFC class using the IfcOpenShell selector syntax
|
||||
- **relations** — relationships for an element; use ``--traverse up`` to walk the hierarchy to IfcProject
|
||||
- **clash** — geometric intersection and clearance checks; requires the IfcOpenShell C++ geometry bindings
|
||||
- **validate** — schema and constraint validation; add ``--rules`` for a full EXPRESS check
|
||||
- **schedule** — work schedules with nested task trees
|
||||
- **cost** — cost schedules with nested cost item trees
|
||||
- **schema** — IFC class documentation using the loaded model's schema version
|
||||
- **contexts** — geometric representation contexts
|
||||
- **materials** — material definitions (IfcMaterial, layer sets, constituent sets, profile sets)
|
||||
- **plot** — generate a drawing (SVG or PNG) using ``ifcopenshell.draw``; PNG output requires ``cairosvg``
|
||||
- **render** — off-screen 3D render to a PNG image; requires ``pyvista`` and the IfcOpenShell C++ geometry bindings
|
||||
|
||||
All subcommands accept ``--format json|text`` to control output (default: ``json``).
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
::
|
||||
|
||||
pip install ifcquery
|
||||
|
||||
For PNG output from ``plot``, also install ``cairosvg``::
|
||||
|
||||
pip install cairosvg
|
||||
|
||||
For 3D rendering with ``render``, also install ``pyvista``::
|
||||
|
||||
pip install pyvista
|
||||
|
||||
Or install from source:
|
||||
|
||||
1. :doc:`Install IfcOpenShell <ifcopenshell-python/installation>`
|
||||
2. `Clone the IfcOpenShell repository <https://github.com/IfcOpenShell/IfcOpenShell>`_.
|
||||
3. ``cd /path/to/IfcOpenShell/src/ifcquery``
|
||||
4. ``pip install .``
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
::
|
||||
|
||||
$ ifcquery model.ifc summary
|
||||
$ ifcquery model.ifc tree
|
||||
$ ifcquery model.ifc info 42
|
||||
$ ifcquery model.ifc select 'IfcWall'
|
||||
$ ifcquery model.ifc relations 42
|
||||
$ ifcquery model.ifc relations 42 --traverse up
|
||||
$ ifcquery model.ifc validate
|
||||
$ ifcquery model.ifc validate --rules
|
||||
$ ifcquery model.ifc schedule
|
||||
$ ifcquery model.ifc cost
|
||||
$ ifcquery model.ifc schema IfcWall
|
||||
$ ifcquery model.ifc materials
|
||||
$ ifcquery model.ifc plot -o floorplan.svg --out-format svg --view floorplan
|
||||
$ ifcquery model.ifc plot -o floorplan.png --view floorplan
|
||||
$ ifcquery model.ifc render -o model.png
|
||||
|
||||
.. seealso::
|
||||
|
||||
Use :doc:`IfcEdit <ifcedit>` to make mutations to IFC files from the command
|
||||
line, and :doc:`IfcMCP <ifcmcp>` for interactive AI-assisted editing.
|
||||
@@ -30,9 +30,12 @@ Let's learn IfcOpenShell!
|
||||
ifcclash
|
||||
ifccsv
|
||||
ifcdiff
|
||||
ifcedit
|
||||
ifcfm
|
||||
ifcmax
|
||||
ifcmcp
|
||||
ifcpatch
|
||||
ifcquery
|
||||
ifcsverchok
|
||||
ifctester
|
||||
other
|
||||
|
||||
@@ -69,9 +69,12 @@ IfcOpenShell is a modular ecosystem of tools that work together, where each tool
|
||||
"`IfcClash <https://docs.ifcopenshell.org/ifcclash.html>`_", "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."
|
||||
"`IfcCSV <https://docs.ifcopenshell.org/ifccsv.html>`_", "View and edit IFC data using spreadsheets or tabular datasets, such as CSV, ODS, XLSX, Pandas DataFrames, and regular Python lists."
|
||||
"`IfcDiff <https://docs.ifcopenshell.org/ifcdiff.html>`_", "A CLI utility and library that lets you compare the changes between two IFC models."
|
||||
"`IfcEdit <https://docs.ifcopenshell.org/ifcedit.html>`_", "A CLI wrapper for all ifcopenshell.api mutation functions. Browse available API modules, read per-function documentation, and run any API function against an IFC file from the command line."
|
||||
"`IfcFM <https://docs.ifcopenshell.org/ifcfm.html>`_", "A highly standards-compliant tool (e.g. COBie 2.4, COBie 3.0, AOH-BSEM) to convert FM data in IFC databases to spreadsheets and other machine readable formats, such as ODS, XLSX, CSV, Pandas, XML, and JSON."
|
||||
"`IfcMax <https://docs.ifcopenshell.org/ifcmax.html>`_", "A 3ds Max importer plugin able to import the IFC file format."
|
||||
"`IfcMCP <https://docs.ifcopenshell.org/ifcmcp.html>`_", "An MCP (Model Context Protocol) server that exposes IfcOpenShell query and edit tools to AI coding assistants. Loads a model into memory and keeps it there across tool calls, so no file I/O is needed between operations."
|
||||
"`IfcPatch <https://docs.ifcopenshell.org/ifcpatch.html>`_", "A CLI utility and library that lets you run and distribute predetermined modifications on an IFC file, known as a patch recipe. Useful in deploying a data pipeline or batch-fixing external models."
|
||||
"`IfcQuery <https://docs.ifcopenshell.org/ifcquery.html>`_", "A CLI tool for querying and inspecting IFC building models. Subcommands cover spatial hierarchy, element inspection, relationship traversal, clash detection, schema documentation, work schedules, and cost schedules."
|
||||
"`IfcSverchok <https://docs.ifcopenshell.org/ifcsverchok.html>`_", "A node based visual programming add-on for Blender to interact with IFC and Sverchok."
|
||||
"`IfcTester <https://docs.ifcopenshell.org/ifctester.html>`_", "Author and read Information Delivery Specification (IDS) files. You can validate IFC models against IDS and generate reports in multiple formats. It works from the command line, as a web app, or as a library."
|
||||
"`VoxelisationToolkit <https://github.com/opensourceBIM/voxelization_toolkit>`_", "Converts .ifc geometry into voxels, and lets you perform voxel based geometric analysis."
|
||||
|
||||
@@ -382,12 +382,14 @@ ifcquery model.ifc materials
|
||||
Generate a 2D technical drawing (floor plan, elevation, or section) of the model and write it to a file.
|
||||
|
||||
```bash
|
||||
ifcquery model.ifc plot output.svg
|
||||
ifcquery model.ifc plot output.png --view floorplan --scale 0.01
|
||||
ifcquery model.ifc plot -o output.svg --out-format svg
|
||||
ifcquery model.ifc plot -o output.png --view floorplan --scale 0.01
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `-o, --output <file>` -- output file path (default: `<ifc_file>.svg` or `<ifc_file>.png`)
|
||||
- `--out-format {svg,png,base64}` -- output format (default: `png`)
|
||||
- `--view {floorplan,elevation,section,auto}` -- drawing view (default: `floorplan`)
|
||||
- `--scale <ratio>` -- model-to-paper scale ratio (default: 0.01 = 1:100)
|
||||
- `--width-mm <mm>` -- paper width in mm (default: 297)
|
||||
@@ -395,16 +397,15 @@ Options:
|
||||
- `--png-width <px>` -- raster output width in pixels (default: 1024)
|
||||
- `--png-height <px>` -- raster output height in pixels (default: 1024)
|
||||
|
||||
Writes SVG when the output path ends in `.svg`, otherwise PNG.
|
||||
Requires the IfcOpenShell drawing module (`ifcopenshell.draw`).
|
||||
Requires the IfcOpenShell drawing module (`ifcopenshell.draw`). PNG output additionally requires `cairosvg`.
|
||||
|
||||
### render
|
||||
|
||||
Render a 3D view of the model geometry to a PNG file.
|
||||
|
||||
```bash
|
||||
ifcquery model.ifc render output.png
|
||||
ifcquery model.ifc render output.png --view iso --selector IfcWall
|
||||
ifcquery model.ifc render -o output.png
|
||||
ifcquery model.ifc render -o output.png --view iso --selector IfcWall
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
Reference in New Issue
Block a user