Difference between revisions of "MicroMVDs for exchange requirements"

From Wiki.OSArch
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Template:MVD_Documentation}}
 
To guarantee correct BIM data, data exchange requirements need to be specified and audited. '''A MicroMVD is a collection of sentences that describe auditing requirements, written in plain language understood by both technical and non-technical stakeholders. These sentences are organised into categories, and can be processed by a computer to automatically check whether or not the requirements are satisfied.'''
 
To guarantee correct BIM data, data exchange requirements need to be specified and audited. '''A MicroMVD is a collection of sentences that describe auditing requirements, written in plain language understood by both technical and non-technical stakeholders. These sentences are organised into categories, and can be processed by a computer to automatically check whether or not the requirements are satisfied.'''
  
Here is an example of a simple MicroMVD, which checks that an IFC4 file is provided with a particular filename.
+
This approach builds on the concept in software development called [https://en.wikipedia.org/wiki/Unit_testing unit testing], specifically [https://en.wikipedia.org/wiki/Behavior-driven_development behavior driven development]. Describing the requirement in simple to understand (but still machine readable) [https://en.wikipedia.org/wiki/Cucumber_(software) gherkin format] makes the intentions clear to designers and makes writing unit tests simple.
 +
 
 +
[[BIMTester]] has implemented use of MicroMVDs for auditing model quality from IFC files. [[BIMTester]] is integrated into the [[BlenderBIM Add-on]]
 +
 
 +
Here is an example of a simple MicroMVD, which checks that an IFC4 file is provided.
  
 
<pre>
 
<pre>
Line 11: Line 16:
  
 
Scenario: Receiving a file
 
Scenario: Receiving a file
* The IFC file "project.ifc" must be provided
+
  * IFC data must use the "IFC4" schema
  * IFC data must use the IFC4 schema
 
 
</pre>
 
</pre>
  
 
This MicroMVD is stored in a simple text file with the <code>.feature</code> file extension. The file name is arbitrary, but may be used to describe what it is auditing. These simple text files can be edited in any text editor, such as [https://www.vim.org/ Vim], Apple TextEdit, or Microsoft Notepad. No proprietary software is required: anybody can read and write MicroMVDs.
 
This MicroMVD is stored in a simple text file with the <code>.feature</code> file extension. The file name is arbitrary, but may be used to describe what it is auditing. These simple text files can be edited in any text editor, such as [https://www.vim.org/ Vim], Apple TextEdit, or Microsoft Notepad. No proprietary software is required: anybody can read and write MicroMVDs.
  
These <code>*.feature</code> files, each containing sentences like the above can be processed by a computer. In the example above, a MicroMVD auditing program will look for a file named "<code>project.ifc</code>" and will check that it is <code>IFC4</code>. The MicroMVD auditing program can then generate a report, which can be used by stakeholers to track whether or not a project is satisfying its requirements.
+
These <code>*.feature</code> files, each containing sentences like the above can be processed by a computer. In the example above, a MicroMVD auditing program will check that a particular IFC file uses the <code>IFC4</code> schema. The MicroMVD auditing program can then generate a report, which can be used by stakeholers to track whether or not a project is satisfying its requirements.
  
 
Unlike other auditing solutions like Solibri or SimpleBIM, MicroMVDs are non-proprietary, do not expire, are free, much lighter, are easy to change and develop, and are cross-platform.
 
Unlike other auditing solutions like Solibri or SimpleBIM, MicroMVDs are non-proprietary, do not expire, are free, much lighter, are easy to change and develop, and are cross-platform.
Line 29: Line 33:
 
* [[Model federation MicroMVD]]
 
* [[Model federation MicroMVD]]
 
* [[Element classes MicroMVD]]
 
* [[Element classes MicroMVD]]
 +
* [[Geocoding MicroMVD]]
 +
* [[Classification MicroMVD]]
 +
* [[Geometric detail MicroMVD]]
 
* [[Naming MicroMVD]]
 
* [[Naming MicroMVD]]
 +
* [[Construction types MicroMVD]]
 +
* [[Concrete quantity take-off MicroMVD]]
 +
* [[Quantity take-off MicroMVD]]
 +
* [[Spaces MicroMVD]]
 +
* [[Excavation MicroMVD]]
 
* [[Material MicroMVD]]
 
* [[Material MicroMVD]]
 
* [[COBie MicroMVD]]
 
* [[COBie MicroMVD]]
  
== Auditing BIM data with MicroMVDs ==
+
All MicroMVD can be found in [[:Category:MicroMVD|MicroMVD]]
 
 
You will need a MicroMVD auditing program. One free and open source option is [https://blenderbim.org/download.html BIMTester].
 
 
 
TODO: describe how to use BIMTester.
 
 
 
== Authoring a custom MicroMVD ==
 
 
 
If you wish to write your own custom MicroMVD, some basic technical knowledge is required. The first is how to structure a MicroMVD. Each MicroMVD must follow the generic format shown below:
 
 
 
<pre>Feature: Name of the exchange requirement
 
 
 
In order to achieve a business goal
 
As a particular user or stakeholder
 
We need to satisfy specific technical requirements
 
 
 
Scenario: Check a particular technical requirement
 
* Some data must be in a certain way
 
* Some other data must be in another way
 
 
 
Scenario: Check another particular technical requirement
 
* Some data must be in a certain way
 
* Some other data must be in another way
 
</pre>
 
 
 
A feature file always starts by defining the name of the <code>Feature</code>. Below the feature name is an three sentence paragraph which describes the value this MicroMVD delivers to the project. This paragraph is optional, but encouraged to help align both technical and non-technical project participants.
 
 
 
The individual audits are then categorised into one or more <code>Scenario</code> blocks. Each scenario has a name that focuses on a particular technical requirement of the exchange requirement, and contains one or more test sentences. Each sentence checks data related to the scenario. The feature name and scenario names can be anything, but must be prefixed by <code>Feature: </code> and <code>Scenario: </code> respectively. The test sentences within each <code>Scenario</code> block must match a pattern defined in the MicroMVD for the project.
 
 
 
These MicroMVDs are templates to be used as a starting point for projects to describe exchange requirements. It is encouraged to modify it to project requirements, delete irrelevant tests, and add new tests as required.
 
 
 
== Packaging test suites for recipients ==
 
  
The author of the test suite will provide a folder named <code>features/</code>. The contents of this folder will contain:
+
== Auditing BIM data with BlenderBIM Add-on and MicroMVDs ==
  
<pre>features/test-suite-A.feature # This is a test suite
+
[[File:Bimtester.png|300px|thumb|right|The BIMTester Quality Auditing panel in the BlenderBIM Add-on]]
features/test-suite-B.feature # This is another test suite, you can have multiple
 
features/environment.py # This defines the test environment
 
features/template.html # This is the HTML report template
 
features/steps/steps.py # The defines the test sentences
 
</pre>
 
  
These files constitute the full test system, and must be shared in full to all recipients and all authors. This ensures full transparency of exchange requirements.
+
[[File:Bimtester-report.png|300px|thumb|right|An example audit report from BIMTester]]
  
The <code>steps.py</code> file requires basic programming knowledge to understand and modify, and is generally only modified by the test author.  Recipients are free to inspect it to gain a better understanding of what constitutes test compliance.
+
To begin auditing BIM data, you will need an IFC file. Let's imagine you have a file called <code>file.ifc</code>.
  
The <code>environment.py</code> file contains the environment settings to run the tests, using the [https://github.com/behave/behave Behave] system. An intermediate knowledge of <em>Behave</em> and <em>Python</em> is required to modify this file. For most recipients, this file must be left alone.
+
You will then need to specify your exchange requirements. Follow the steps below:
  
The <code>template.html</code> file contains a HTML report template. It is plain HTML code with [https://mustache.github.io/ Mustache] for the templating language. A basic knowledge of HTML and Mustache is required to modify this file, which is self-explanatory.
+
# Create a new text file called <code>audit.feature</code>
 +
# Copy a MicroMVD template (e.g. [[Project setup MicroMVD]]) into your <code>audit.feature</code> file.
 +
# Modify the template based on your project. For example, you may change the sentence <code> * IFC data must use the "{schema}" schema</code> to read <code> * IFC data must use the "IFC4" schema</code>.
  
== Receiving and running test suites ==
+
Now that you have specified your exchange requirements, you can audit it using a program. One free and open source option is [https://blenderbim.org/download.html BIMTester], which comes with the [[BlenderBIM Add-on]], or can be [https://github.com/IfcOpenShell/IfcOpenShell/tree/v0.6.0/src/ifcbimtester run standalone]. Here's an example of how to audit it:
  
A recipient will receive a <code>features/</code> directory. They are not required to modify the files in any way.
+
# Launch Blender with the [[BlenderBIM Add-on]] installed.
 +
# Open up the ''BIMTester'' panel in the ''Scene Properties''.
 +
# Navigate to your <code>file.ifc</code> file in the ''IFC File'' property. This is the IFC that will be audited.
 +
# Navigate to your <code>audit.feature</code> file in the ''Feature / IDS'' property. This is your audit requirements file.
 +
# Press the <code>Execute BIMTester</code> button.
 +
# Your audit report results will pop up in your browser.
  
The cross-platform, free software [https://blenderbim.org/download.html BIMTester] tool is capable of running the test suite and generating reports. The BIMTester tool expects the <code>features/</code> directory to be in the current working directory.
+
The ''Custom Steps'' is for advanced users who have built their own custom requirements. This requires coding knowledge.
  
Recipients are encouraged to run the tests and generate reports at their convenience. The test author may optionally provide an automated platform which runs tests and generate downloadable reports, as well as track progress on test results.
+
== Modifying a MicroMVD ==
  
== Maintaining test suites ==
+
MicroMVDs are designed to be modified to be specific to your project. You are free to delete lines that don't apply to your project, or add additional lines if you need to audit more things in your project. You can have a single <code>.feature</code> or multiple files for each IFC, depending on how you want to organise your project. Once you have tailored it to your project, it is encouraged to include it in your project contract, so that all stakeholders are crystal clear on exactly what the data exchange requirements are, and how it will be audited.
  
The test suite will be working document that will grow throughout the project lifecycle to ensure that data quality regressions are not made, and that the level of information which has been audited is clearly documented.
+
If you know how to code, you can also define your own sentences. Read more in [[Developing custom MicroMVDs]].
  
The test author will advise all recipients whenever new tests are being introduced or new test sentences are being defined.
+
[[Category:Model View Definitions (MVD)]] [[Category:BIMTester]] [[Category:BlenderBIM Add-on]] [[Category:MicroMVD]]

Revision as of 00:16, 21 March 2021


BuildingSMART-Logo 64x64.png This page is about MVD - Model View Definitions. Full documentation is available at the buildingSMART site. All articles in the OSArch wiki related to Model View Definitions (MVD) can be seen in the Model View Definitions (MVD) Category

To guarantee correct BIM data, data exchange requirements need to be specified and audited. A MicroMVD is a collection of sentences that describe auditing requirements, written in plain language understood by both technical and non-technical stakeholders. These sentences are organised into categories, and can be processed by a computer to automatically check whether or not the requirements are satisfied.

This approach builds on the concept in software development called unit testing, specifically behavior driven development. Describing the requirement in simple to understand (but still machine readable) gherkin format makes the intentions clear to designers and makes writing unit tests simple.

BIMTester has implemented use of MicroMVDs for auditing model quality from IFC files. BIMTester is integrated into the BlenderBIM Add-on

Here is an example of a simple MicroMVD, which checks that an IFC4 file is provided.

Feature: Project setup

In order to view the BIM data
As any interested stakeholder
We need an IFC file

Scenario: Receiving a file
 * IFC data must use the "IFC4" schema

This MicroMVD is stored in a simple text file with the .feature file extension. The file name is arbitrary, but may be used to describe what it is auditing. These simple text files can be edited in any text editor, such as Vim, Apple TextEdit, or Microsoft Notepad. No proprietary software is required: anybody can read and write MicroMVDs.

These *.feature files, each containing sentences like the above can be processed by a computer. In the example above, a MicroMVD auditing program will check that a particular IFC file uses the IFC4 schema. The MicroMVD auditing program can then generate a report, which can be used by stakeholers to track whether or not a project is satisfying its requirements.

Unlike other auditing solutions like Solibri or SimpleBIM, MicroMVDs are non-proprietary, do not expire, are free, much lighter, are easy to change and develop, and are cross-platform.

List of MicroMVDs

Although you are free to write your own MicroMVD specific to your project, a series of MicroMVDs have been published online that address common problems. You can copy and paste these templates into your own *.feature files, and modify it to suite your project.

All MicroMVD can be found in MicroMVD

Auditing BIM data with BlenderBIM Add-on and MicroMVDs

The BIMTester Quality Auditing panel in the BlenderBIM Add-on
An example audit report from BIMTester

To begin auditing BIM data, you will need an IFC file. Let's imagine you have a file called file.ifc.

You will then need to specify your exchange requirements. Follow the steps below:

  1. Create a new text file called audit.feature
  2. Copy a MicroMVD template (e.g. Project setup MicroMVD) into your audit.feature file.
  3. Modify the template based on your project. For example, you may change the sentence * IFC data must use the "{schema}" schema to read * IFC data must use the "IFC4" schema.

Now that you have specified your exchange requirements, you can audit it using a program. One free and open source option is BIMTester, which comes with the BlenderBIM Add-on, or can be run standalone. Here's an example of how to audit it:

  1. Launch Blender with the BlenderBIM Add-on installed.
  2. Open up the BIMTester panel in the Scene Properties.
  3. Navigate to your file.ifc file in the IFC File property. This is the IFC that will be audited.
  4. Navigate to your audit.feature file in the Feature / IDS property. This is your audit requirements file.
  5. Press the Execute BIMTester button.
  6. Your audit report results will pop up in your browser.

The Custom Steps is for advanced users who have built their own custom requirements. This requires coding knowledge.

Modifying a MicroMVD

MicroMVDs are designed to be modified to be specific to your project. You are free to delete lines that don't apply to your project, or add additional lines if you need to audit more things in your project. You can have a single .feature or multiple files for each IFC, depending on how you want to organise your project. Once you have tailored it to your project, it is encouraged to include it in your project contract, so that all stakeholders are crystal clear on exactly what the data exchange requirements are, and how it will be audited.

If you know how to code, you can also define your own sentences. Read more in Developing custom MicroMVDs.