brunopostle/ifcmerge

A three-way-merge tool for IFC files

IFC Merge

Collaborative BIM

ifcmerge is a three-way-merge tool for IFC files, intended to support a modern fork, branch, pull-request and merge workflow using revision control systems such as git or mercurial. This enables multiple people to work on separate copies of the same IFC data, periodically merging their work.

This tool requires that a Native IFC application, such as BlenderBIM, is used for all authoring and editing.

A Native IFC application behaves in the following ways when editing a pre-existing IFC (STEP/SPF) file:

1. IFC entities must be written in the same format as received, with the same numeric IDs as before.

2. Attribute changes to entities must be written in-place.

3. Numeric IDs of deleted entities must not be reused for new entities.

If you use a traditional BIM application that saves in a proprietary format, and that exports IFC files, you probably do not have a Native IFC application :(

This whitepaper shows why you might want to use Native IFC for your work: https://github.com/brunopostle/ifcmerge/blob/main/docs/whitepaper.rst

This video presentation shows interactive use of ifcmerge in the BlenderBIM application: https://peertube.linuxrocks.online/w/jotEqADodmuYz8J1Sku7B2

Quickstart

Given a base IFC file and two different forked versions of it, combine the changes from the two forks into a merged result like so:

ifcmerge base.ifc local_fork.ifc remote_fork.ifc result_merged.ifc

Using ifcmerge with git

Configure git to add ifcmerge to the list of available merge tools (set the path to suit your installation location):

git config --global mergetool.ifcmerge.cmd '/path/to/ifcmerge $BASE $LOCAL $REMOTE $MERGED'
git config --global mergetool.ifcmerge.trustExitCode true

Assuming you already have a git repository containing test_model.ifc. Create a new branch, edit and commit some changes to the IFC file in this branch:

git branch my_branch
git switch my_branch
  [some editing of the IFC file]
git commit test_model.ifc

(The procedure is similar with a remote pull request: create a temporary local branch and use git pull to update it with the remote changes rather than making those changes yourself)

Switch back to the original main branch where the IFC file remains unmodified, edit and commit some different changes:

git switch main
  [some editing of the IFC file]
git commit test_model.ifc

At this point the two branches have diverged, instruct git to merge them:

git merge my_branch

This will not complete, resulting in an unresolved conflict, because the default git merge will always find conflicts between two versions of the same IFC file. Complete the merge by resolving the conflict using ifcmerge:

git mergetool --tool=ifcmerge

Commit the merge if it is successful (i.e. with no error messages):

git commit -i test_model.ifc

Otherwise, if ifcmerge refuses because it can't safely merge the branches, such as when an entity has been modified in one branch and deleted in the other, you can always abandon the merge:

git merge --abort

If your repository only contains IFC files, you can set git mergetool to default to using ifcmerge:

git config merge.tool ifcmerge

About

Copyright 2022, Bruno Postle [email protected] License: GPLv3

ifcmerge's Issues

Aren't we now using the BCF instead of mail?

Thanks for the white paper! It was a pleasant read.

Just a little remake to this example! I am not sure how far the AEC industry got in two years since the publication of this white paper, however do they not use BCF instead of mail?

ifcmerge/docs/whitepaper.rst

Line 34 in 14807c4

A structural engineer can't provisionally move a door in the architect's model; they have to create a sketch showing how they think the door should move, send it in an email to the architect, hoping then that the architect might update their model at some point - eventually this moved door will cascade into the federated model that everyone sees.

You may be interested to know about "IFC Normalization"

Hi Bruno,

Thank you very much for the idea of "Native IFC whitepaper", which is among the references in the paper "A Parallel IFC Normalization Algorithm for Incremental Storage and Version Control".

The paper can be found at
https://arxiv.org/abs/2312.14931

The related project can be found at
https://github.com/THUCBIMS/CBIMS.IFCNormalization

I believe that you may be interested to know about the project because it provides a different point of view for version comparison and incremental storage of IFC data.

The motivation for IFC Normalization is slightly different, which is to make IFC comparison also applicable to the IFC files exported from some non-IFC BIM editing tools. I hope the algorithm may help bring some new ideas to the community or to start some new discussions.

I am still working on research about IFC data structure and algorithms. Glad to establish contact with you.

Han Liu

Question about authors in CITATION file

When I look for the term Native IFC in DuckDuckGo, the first website is from the OSArch blog post:

In it, I found three authors:

However, in the CITATION file in this repo, I found only two authors. I would like to cite this white paper in my work, so I am asking.

Errors during merge: Use of uninitialized value

I am not sure if the tool was designed for such a use, but I tried to merge three locally existing IFC files. Probably, it is not an intended use case. In any case, I got these errors.

Use of uninitialized value $local_class in string ne at ./ifcmerge line 102.
Use of uninitialized value $text in pattern match (m//) at ./ifcmerge line 340.
Use of uninitialized value $text in pattern match (m//) at ./ifcmerge line 340.
Use of uninitialized value $base_class in string ne at ./ifcmerge line 102.
Use of uninitialized value $local_class in string ne at ./ifcmerge line 102.
Use of uninitialized value $text in pattern match (m//) at ./ifcmerge line 340.
Use of uninitialized value $text in pattern match (m//) at ./ifcmerge line 340.

Any plans to port to Python ?

Perl is awesome. The issue is the need to support the perl interpreter as a 3rd party dependency.

Thanks for the amazing work on this!

Entities added after trailing entities deleted

ifcmerge relies on the Native IFC principle that no application will reuse the IDs of deleted elements. However there is a theoretical possibility of failure in this situation:

1. Application deletes some entities, one or more of them are the 'last' entity with the highest step-ID in the file.
2. File is saved to disk and opened again by the same or another application.
3. The new application adds new entities with ID values that have previously been used.

ifcmerge will typically refuse to merge such a file as the class of the ID will likely have changed. This is a robust failure mode, and avoids corruption.

It should be possible for ifcmerge to detect this situation and simply renumber the offending IFC file such that there is no clash before merging.

Zotero Connector does not recognise CITATION.cff

I then validated the CITATION.cff and found that type has an invalid value:

ifcmerge/CITATION.cff

Line 8 in 74226d6

type: article

type in this top position can only be software or dataset, see https://github.com/citation-file-format/citation-file-format/blob/1.2.0/schema-guide.md#type

However, for example in credit-redirection block, you can use type with the value article.

Nonetheless, I am uncertain whether this approach would resolve my Zotero Connector issue. Therefore, I would like to inquire whether it is feasible to incorporate a bib file that I can import into Zotero?

Ordered lists of step IDs

ifcmerge will happily merge lists of step IDs, eg. (#5,#2,#1,#2222) but it doesn't preserve list ordering. This is not a problem with most IFC data, such as aggregates, but will break when ordering is important, ie. nested relationships.

ifcmerge needs to be fixed to support merging of changes in ordered lists, this will require some heuristics similar to that in diff/patch.