##########
BCF Format
##########

Overview
========

The BIM Collaboration Format (BCF) is an open file format used for storing data (comments, screenshots, etc.) about IFC models. The official documentation for BCF can be found `here <https://github.com/BuildingSMART/BCF-XML/tree/master/Documentation>`_. This document describes how to load a BCF file and interact with the data in the HOOPS Web Viewer.

Find information about which BCF versions are currently supported on the :doc:`Supported Formats </overview/supported-formats>` page.


BCF API
=======

BCFManager
----------

The :doc:`BCFManager </api_ref/viewing/classes/Communicator.BCFManager>` class facilitates loading, accessing, and editing data from a BCF file.


BCFData
-------

The :doc:`BCFData </api_ref/viewing/classes/Communicator.BCFData>` class represents a single BCF file. It contains a set of ``BCFTopics``, as well as information about the BCF filename and version.


BCFTopic
--------

Each BCF file can contain multiple topics. Each topic contains a ``BCFMarkup``, set of BCFSnapshots, and set of BCFViewpoints. Each ``BCFViewpoint`` can have exactly one corresponding snapshot.

Each topic has a unique id and contains images, camera viewpoints, markup, and comments. The :doc:`/api_ref/viewing/classes/Communicator.BCFTopic` class provides access to this data via the ``BCFMarkup``, ``BCFViewpoint``, and ``BCFSnapshot`` classes.


BCFMarkup
---------

The :doc:`BCFMarkup </api_ref/viewing/classes/communicator.BCFMarkup>` class contains textual information about the topic. This includes the title, author, description, comments, etc. For a list of all markup data to query, see the webviewer API Reference.


BCFSnapshot
-----------

The :doc:`BCFSnapshot </api_ref/viewing/classes/Communicator.BCFSnapshot>` class contains image data related to the topic.


BCFViewpoint
------------

The :doc:`BCFViewpoint </api_ref/viewing/classes/communicator.BCFViewpoint>` class contains information about components related to the topic, camera settings, and possible markup and clipping information. This class can be used to activate a view, which will change the camera, visibility, cutting planes, colors, and markup.


BCF import
==========

To load a file via HTTP request:

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [Load_BCF]
	   :end-before: //! [Load_BCF]	

After a BCF is loaded, the ``bcfLoaded`` callback is triggered. This callback contains an ID that corresponds to the ``BCFData`` object representing the BCF file and can be used to retrieve it.


Interacting with BCF data
=========================

It is also possible to create BCF data using the BCFManager :doc:`createBCFData </api_ref/viewing/classes/Communicator.BCFManager:createbcfdata>` function.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [Create_BCF]
	   :end-before: //! [Create_BCF]

Using the ID that is returned in the ``bcfLoaded`` callback, you can get the ``BCFData`` object.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [BCF_Data]
	   :end-before: //! [BCF_Data]

The :doc:`getTopics </api_ref/viewing/classes/Communicator.BCFData:gettopics>` function will return a map containing the ``BCFTopic`` IDs and ``BCFTopic`` objects.

Each topic can have only one markup and can contain multiple snapshots and viewpoints.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [BCF_Topics]
	   :end-before: //! [BCF_Topics]

To add a topic to our ``BCFData``, first we create the topic, and then add it using the ``addTopic`` function.  

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [create_topic]
	   :end-before: //! [create_topic]

To delete a topic, remove it from the ``BCFData`` topics map.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [delete_topic]
	   :end-before: //! [delete_topic]
	   
Topic comments are part of the markup class. Below we create and add a comment, update it, then delete it.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [markup_comments]
	   :end-before: //! [markup_comments]

To correlate a snapshot and viewpoint, we first create them and then add them to the topic snapshot and viewpoint maps, as well as add it to the markup class. The viewpoint and snapshot name prefixes do not have to match but are associated by the markup class.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [snapshot_viewpoint]
	   :end-before: //! [snapshot_viewpoint]


BCF export
==========

To export a BCF and download a zip file, use the :ref:`exportBCF  <api_ref/viewing/classes/Communicator.BCFData:exportbcf>` function.

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [export_bcf]
	   :end-before: //! [export_bcf]

Callbacks
=========

There are two callbacks related to BCF, :ref:`bcfLoaded <api_ref/viewing/interfaces/Communicator.CallbackMap:bcfloaded>` and :ref:`bcfRemoved  <api_ref/viewing/interfaces/Communicator.CallbackMap:bcfremoved>`. 

.. literalinclude:: /../../applications/client/docs/PG_BCF.ts
	   :start-after: //! [BCF_Callback]
	   :end-before: //! [BCF_Callback]
