How to set up local development environment to fix bug's and create PR to contribute in xbim repositories.

[CCT-Mukund-Thakare]

Hello Team,

I am looking for reference documentation or guidance to set up local development environment xbimGeometry repositories.
I have cloned most of the repositories like XbimGeometry, XbimEssentials, XbimWindowsUI on my local machine and have started debugging it.

But I am finding it hard to related and understand all this repositories with each other.
I can see multiple solutions\projects in
XbimGeometry
--Xbim.Geometry.Engine.Interop.Tests
--Xbim.Geometry.Engine.Interop
--Xbim.Geometry.Engine
--Xbim.Geometry.Portable
--Xbim.Geometry.Regression
--Xbim.ModelGeometry.Scene

XbimEssentials
--Xbim.Common
--Xbim.IO.Esent
--Xbim.IO.MemoryModel
--Xbim.Ifc
--Xbim.Ifc2*3
--Xbim.Ifc4
--Xbim.Tessellator

I am finding it hard to understand the purpose of each project.
Suppose I fix a bug in Xbim.Geometry.Engine solution how would I test it ? How can I visualize it that it is being fixed ?

The document or readme would really help in this case to do local environment setup and understand these projects.

any kind of help\comments\suggestions are appreciated.

Thank you !!

[andyward]

HI @CCT-Mukund-Thakare, yes you're right a doc would help. I'll make a few notes quickly here and hopefully we can revisit with a md doc:

Understanding the Projects / purposes

So high level, xbimEssentials is the core of xbim Toolkit. It's reads and writes IFC schema files in a variety of formats. It also provides some fundamental data structures for representing the Geometry and visual aspects of models (and a Tesselator to turn geometry into a mesh), but doesn't implement any geometry itself.

xbimGeometry is a separate repo that depends on Essentials, which translates the many IFC logical representations and their conventions into pure geometry, and incorporates a boolean library (OpenCascade) for fundamental shape operations. @Ibrahim5aad did a nice overview post of the fundamentals on LinkedIn

For an overview of the wider Toolkit dependencies see this (slightly out of date) section of the Readme

In a bit more detail, what the assemblies do
XbimEssentials

• Xbim.Common : defines foundational xbim types such as IPersistEntity, IModel, geometry primitives etc.
• Xbim.IO.Esent : an implementation of IModel with persistence backed by the (Windows only) Esent data store
• Xbim.IO.MemoryModel : an in-memory implementation of IModel - no persistence beyond native IFC formats
• Xbim.Ifc : Higher order implementations around IModel, e.g. IfcStore, and extensions to do things like persist wexbim Geometry
• Xbim.Ifc2x3 : code-generated entities for the Ifc2x3 schema
• Xbim.Ifc4: code-generated entities for the Ifc4 ADD2 TC1 schema. Includes the cross schema interfaces
• Xbim.Ifc4x3: code-generated entities for the Ifc4.3 schema
• Xbim.Tessellator: Supports generation of optimised tessellated meshes from xbim Geometry

XbimGeometry

• Xbim.Geometry.Engine: a CLI/C++ 'Mixed mode' library that implements the low level geometric operations on IfcRepresentations to Geometry shapes. Incorporates the OpenCascade C++ library etc.
• Xbim.Geometry.Engine.Interop : A C# wrapper assembly that handles correct deployment of the native Geometry Engine. It delegates all calls down to the core engine.
• Xbim.Geometry.Engine.Interop.Tests : Unit tests for Xbim.Geometry.Engine[.Interop] and Xbim.ModelGeometry.Scene
• Xbim.Geometry.Portable : Redundant. Ignore
• Xbim.Geometry.Regression: A test project used to test a set of models against a baseline
• Xbim.ModelGeometry.Scene: Implements a 3D scene, including placement, materials etc using Xbim.Geometry.Engine.Interop and Xbim.Tessellator. Introduces Xbim3DModelContext

Working with XbimGeometry - Debugging etc

Typically we target the develop branch (v5.1) but in the short term I recommend using feature/netcore (v6) as the base branch - as this will shortly become develop and any fix won't need back-porting to v6. It's also a lot easier / quicker to debug with.

Assumption: you can already build and test the XbimGeometry solution. See the Readme for pre-requisites.

To some extent your approach depends on how deep you are going but this is my typical workflow when I have to go into Geometry:

1. Establish a minimal reproduction of the issue by stripping down an IFC to the minimal required elements.
   Start by identifying the Ifcproduct(s) that cause the issue. Usually the logs will help you here. To create a mininal IFC test file,
   I recommend using the 'Ifc Stripping' feature in XbimXplorer for this. Note you don't need to be able to visualise the model to strip out a product. Here's I'm stripping a single product (FlowTerminal #120371) out of an 18MB MEP model to create a 100k test sample.

2. Ensure all tests pass to start with
3. Create a unit test exercising the code with that minimal file For example
4. Debug from the unit test, and determine a fix, ensuring no regressions in the unit tests

(If there's a major change we'd also run the Xbim Regression test suite)

How to visualise

A couple of different approaches:

1. Use model.SaveAsWexBim(wexBimBinaryWriter) to output a tessellated wexbim file, and load into the xbimWebUI viewer. This is probably the quickest way to view a scene, and means you don't need to create Nuget packages
2. Manually package the Xbim.ModelGeometry.Scene and Xbim.Geometry.Engine.Interop projects into a nupkg nuget file (dotnet pack etc or just use the IDE), host these in a local / private nuget repo, and integrate into XbimWindowsUI - or your own service.
3. Lastly for more advanced cases you can save individual objects to a Brep text format using WriteBrep() on a GeometryEngine instance and tools such as OpenCascade's CAD Assistant will render that file for you. e.g.

Hope that's a good starting point.