Home
You made it to the wiki page of the BCF-Plugin for FreeCAD. In the following paragraphs and sections I will write about the current status of the plugin, and give an introduction to the plugin. This will hopefully help anyone trying to understand the underlying code and aid him or her in extending the functionality.
Before the structure of the plugin is discussed it might be useful to know what BCF actually is. The aim behind this file format is to aid the collaborative development of models of buildings. Before the introduction of BCF the collaboration often consisted of the transmission of some PDF files, and separate snapshots and so on just to communicate a concern or issue with a model. Exactly that part, the communication of issues, this format tries to tackle.
A BCF file is actually a zip file, which becomes apparent if you work with an older version of BCF. In the versions before 2.1, the extension for a BCF file was ".bcfzip", this was changed to ".bcf" sometime on the way to version 2.1 (reference). Such a file is then internally structured into single topics. Each topic describes one issue of a building model. With it meta data are associated. For example it is possible, and a rather integral part of it, to add comments to any given topic. This shall make the communication on these issues more traceable. Another great feature BCF includes are viewpoints. A viewpoint is a collection of settings that shall be applied to the object viewer in your CAD application. With these settings it is supposed to be easier for the other party to spot the issue one wants to communicate.
For a more detailed description of BCF I suggest you read through the XML documentation, all the other references I found just wanted to pitch you BCF and didn't go into detail about what is possible.
The plugin is aimed at the free CAD software FreeCAD and wants to integrate support for the BCF standard into it. Therefore, the plugin is developed as standalone application that can be started from inside FreeCAD in one of two modes: GUI and non-GUI mode. In former, a new task panel will be created in which the Qt5 application of the plugin will be shown. The non-GUI mode however, can be used either from the FreeCAD python console as well as from FreeCAD in the console.
In the next sections I want to give an overview of the plugin and a starting point for anyone wanting to extend its functionality. For that matter I am introducing the high-level structure of the plugin. This structure will be covered in more detail in three separate wiki pages. For people just wanting to try the plugin, a separate "Tutorial" section is available.
The plugin is structured into three layers:
- Front-end (separated into GUI front-end mode and Non-GUI front-end mode)
- Interfacing between first and third layer
- Data model layer.
Following graphic shall illustrate this structure:
In the following three sections I want to give a short description of each layer. More detailed descriptions can be found in the associated pages.
Holds a complete representation of the BCF file in memory and presents it for modification. Apart from just the classes holding only data, the Data Model also includes "interfaces" that add functionality to the data model during runtime. An example would be the Hierarchy interface, which provides the user of an inheriting class with the ability to generate a hierarchy of the given element, corresponding to the hierarchy the associated XML element has in the source XML file (but more on that on the page BCF-Package). The source files are contained in the ./bcfplugin/rdwr. For reading and writing the modules reader.py and writer.py are offered. reader.py reads a BCF file into the in-memory representation whereas writer.py writes updates to the BCF file. But for more detail please see the dedicated page on the bcf package.
The Interface Layer provides access to the in-memory representation of the BCF file (i.e.: the data model). Apart from just modifying the underlying objects it also has to insure that the constraints of the BCF standard are not violated. One such constraint for example might be that a Comment must not reference a Viewpoint that is not listed inside the Markup node. Therefore, when a Viewpoint is being deleted from a topic then the Interface Layer ensures that no comment will reference it any-longer and thus lead to bad user experience.
This layer is logically separated into two parts: the GUI part and the non-GUI part. Former is manifested in code whereas latter one is listed here just for completeness sake. The non-GUI part of this layer is in effect the direct access to the lower interface layer. It offers the user the ability to use the plugin as either a standalone python application or inside the python console of FreeCAD.
GUI Front-end Layer: provides the Qt5 user interface to the user and lets him or her modify the contents of the BCF file through the Interface Layer.
All layers are finished, and the first major version is released. Features implemented in the GUI layer:
- Opening & creating projects
- Opening & creating topics
- Showing details of an opened topic
- Opening files with a double click if they are present on disk
- Adding/modifying and deleting comments
- Viewing associated snapshots and opening them in original resolution
- Viewing of associated viewpoints, as well as applying them to the object view
The non-GUI layer (i.e.: the interface) sports a more complete implementation of the BCF standard. Here a list of what still missing:
- Integration of BIMSnippets
- Optimization rules when adding viewpoints
- Adding only a selection of components during the creation of a viewpoint
- Integration of ViewSetupHints
- Integration of Bitmaps
The bottom most layer (Data Layer) is finished, although one can never be sure of the complete absence of bugs. The middle layer offers basic update capabilities (add/modify/delete) of the data model to the user, and is able to apply viewpoint settings to the currently open view of FreeCAD using the coin3D-library. However, I am not so sure about the application of the camera settings, specifically I doubt that the mathematics behind it is correct.
The top most layer (Front-end) offers the user the following options:
- Open a project (a BCF file)
- Select a random topic
- View all comments, add comments to a topic, modify existing comments and delete existing comments
- Lists at most three snapshots of a given topic and open them in original resolution on double click
- Lists a list of all viewpoints, with a associated snapshot as icon
- Save the current state of the BCF file to a given location again
Currently the lowest layer (Data Model Layer) is finished and initial work has begun on the Interface Layer. The development process, I am currently following, is to write some code and then test it by writing unit tests. But recently I run into strange bugs that occur when I run all test cases at once. As a result, some of these fail, but are the affected test cases executed one by one they succeed. The currently affected test suit is interface_tests.py.