A viewpoint shows where an issue is in the model. A comment adds a message to an issue. This article explains how BIMcollab shows viewpoints and how to add viewpoints and comments so that users can always see them.
What is a viewpoint?
A viewpoint is a saved view of the model. It can contain:
Camera position: the location and direction from which you look at the model.
Components: the objects in the model that are selected, visible, hidden, or colored. Components are identified by their IFC GUID.
Clipping planes: planes that cut away part of the model, for example, to look inside a building.
A snapshot: an image of the view.
When a user opens an issue in a BIM application, such as BIMcollab Zoom, the application uses the viewpoint to show the same view of the model.
How BIMcollab shows viewpoints
The BCF-API allows several viewpoints per issue. However, a viewpoint has no information about when it was added, by whom, or why. Without this information, users can't understand an extra viewpoint. These viewpoints are called floating viewpoints.
BIMcollab handles viewpoints as follows:
The first viewpoint you add to an issue is visible, and it is the default viewpoint.
Other viewpoints are only visible when a comment refers to them.
A viewpoint without a comment is saved, but users don't see it.
⚠️ Attention: Add a comment for every viewpoint you upload. This way, users can always see the viewpoint and understand why it was added.
Add a viewpoint with a comment
Follow these steps to add a viewpoint that users can see. Choose the option that suits you:
Option A: Postman: the collection you created during authorization adds the access token to every request.
Option B: cURL: replace
<access-token>with your access token.
In both options, replace <project-id> and <topic-guid> with the IDs of the project and issue.
Step 1: Add the viewpoint
The request body below describes the viewpoint:
{
"perspective_camera": {
"camera_view_point": { "x": 12.0, "y": 8.5, "z": 4.2 },
"camera_direction": { "x": -0.6, "y": -0.7, "z": -0.3 },
"camera_up_vector": { "x": 0.0, "y": 0.0, "z": 1.0 },
"field_of_view": 60.0
},
"components": {
"selection": [
{ "ifc_guid": "2MF28NhmDBiRVyFakgdbCT" }
],
"visibility": { "default_visibility": true }
},
"snapshot": {
"snapshot_type": "png",
"snapshot_data": "<base64-image>"
}
}'About this request:
Camera coordinates are in meters.
snapshot_datais the image file encoded as Base64 text.ifc_guidis the IFCGUID of a component in the model.
📝 Note: Base64 turns a file into text, so it can be sent in JSON. Most programming languages have a built-in function for this.
Option A: Postman
Create a new POST request in your collection.
Paste the endpoint below in the URL field. Replace the placeholders with your IDs:
https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>/viewpoints
Go to the Body tab and select raw and JSON.
Paste the request body.
Click Send.
Option B: cURL
curl -X POST "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>/viewpoints" \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"perspective_camera": {
"camera_view_point": { "x": 12.0, "y": 8.5, "z": 4.2 },
"camera_direction": { "x": -0.6, "y": -0.7, "z": -0.3 },
"camera_up_vector": { "x": 0.0, "y": 0.0, "z": 1.0 },
"field_of_view": 60.0
},
"components": {
"selection": [
{ "ifc_guid": "2MF28NhmDBiRVyFakgdbCT" }
],
"visibility": { "default_visibility": true }
},
"snapshot": {
"snapshot_type": "png",
"snapshot_data": "<base64-image>"
}
}'
The response contains the new viewpoint, including its <globalId>. Copy it for the next step.
Step 2: Add a comment that refers to the viewpoint
The request body below contains the comment and the <globalId> of the viewpoint from Step 1.
{
"comment": "The beam is still inside the wall after the last update.",
"viewpoint_guid": "<globalId>"
}
Option A: Postman
Create a new POST request in your collection.
Paste the endpoint below in the URL field. Replace the placeholders with your IDs:
https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>/comments
Go to the Body tab and select raw and JSON.
Paste the request body.
Click Send.
Option B: cURL
curl -X POST "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<topic-guid>/comments" \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
-d '{
"comment": "The beam is still inside the wall after the last update.",
"viewpoint_guid": "<globalId>"
}'
The viewpoint is now visible in BIMcollab, together with the comment.
Read viewpoints and comments
Task | Method and endpoint |
Get all viewpoints of an issue |
|
Get one viewpoint |
|
Get the snapshot of a viewpoint |
|
Get all comments of an issue |
|
To find the viewpoint that belongs to a comment, check the viewpoint_guid of the comment.
💡 Tip: Snapshot requests don't count toward the rate limits. See Rate limits and handling HTTP 429.
Troubleshooting
Problem | Possible cause | Solution |
A viewpoint you added isn't visible in BIMcollab. | No comment refers to the viewpoint. | Add a comment with the |
The view opens at the wrong position. | The camera coordinates use the wrong unit or axis. | Use meters, and check the direction and up vectors. |
The snapshot doesn't show. | The image isn't valid Base64, or | Check the encoding, and use |