COLNEO Pro 1.2
Loading...
Searching...
No Matches
View3dAPI

Description

3D Viewer API interface.

API is provided by Javascript object (WebForms, Macros) cnView3dAPI.

Since
1.0, 11.2024

(c) COLNEO GmbH

Functions

INFO
ApiJsonResponse getInfo ()
TOOLS
ApiJsonResponse getScreenshot (QVariantMap &options={})
ApiJsonResponse raytraceCurrentScene (QVariantMap &options)
ApiJsonResponse rebuildSceneGraph ()
VIEWPOINTS
ApiJsonResponse getCurrentViewData ()
ApiJsonResponse resetView ()
ApiJsonResponse createViewpoint (QString &parentId, QString &name, QVariantMap &options)
ApiJsonResponse updateViewpoint (QString &vpId)
ApiJsonResponse getViewData (QString &vpId)
ApiJsonResponse setViewData (QString &vpId, QVariantMap &data)
ApiJsonResponse getViewpointIds ()
ApiJsonResponse activateViewpoint (QString &vpId)
ApiJsonResponse setHomeViewpointId (QString &vpID)
ApiJsonResponse resetHomeViewpoint ()
ApiJsonResponse getHomeViewpointId ()
ApiJsonResponse getActiveViewpointId ()
CAMERA
ApiJsonResponse getCamera ()
ApiJsonResponse setCamera (QVariantMap &cam)
ApiJsonResponse zoomAll (QVariantMap &opt=QVariantMap())
ApiJsonResponse zoomToObjects (QStringList &objectIds, QVariantMap &options=QVariantMap())
ApiJsonResponse showClash (QString &clashId)
ApiJsonResponse clearClash ()
ApiJsonResponse zoomToPoints (QVariantList &points, QVariantMap &options=QVariantMap())
ApiJsonResponse showHomeViewpoint ()
CLIPPING
ApiJsonResponse setClippingPlanes (QVariantMap &clipping)
ApiJsonResponse getClippingPlanes ()
ApiJsonResponse resetClipping ()
PICKING
ApiJsonResponse getPickedPoints ()
ApiJsonResponse clearPickedPoints ()
ApiJsonResponse getPickedFaces ()
ApiJsonResponse clearPickedFaces ()
ApiJsonResponse startPickedFacesLog ()
ApiJsonResponse stopPickedFacesLog ()
NAVIGATION
ApiJsonResponse setNavigationMode (QVariantMap &cfg)
ApiJsonResponse getNavigationMode ()
CUSTOM OVERLAYS
ApiJsonResponse createOverlay (QString name, QString content, QVariantMap config=QVariantMap())
ApiJsonResponse removeOverlay (QString id)
ApiJsonResponse clearOverlays ()
ApiJsonResponse getOverlayIds ()
ApiJsonResponse getOverlay (QString id)
ApiJsonResponse setOverlayContent (QString id, QString content)
ApiJsonResponse setOverlayName (QString id, QString name)
ApiJsonResponse setOverlayConfig (QString id, QVariantMap config)
ApiJsonResponse getOverlayConfig (QString id)
ApiJsonResponse setOverlayVisible (QString id, bool visible)
ApiJsonResponse showAllOverlays ()
ApiJsonResponse hideAllOverlays ()
LEGEND
ApiJsonResponse setLegendVisible (bool visible)
ApiJsonResponse isLegendVisible ()
QUICKINFO
ApiJsonResponse setQuickInfoVisible (bool visible)
ApiJsonResponse isQuickInfoVisible ()
SCENE
ApiJsonResponse getConfig ()
ApiJsonResponse setConfig (QVariantMap &cfg)
ApiJsonResponse resetConfig ()
ApiJsonResponse getSceneBoundingBox ()
ApiJsonResponse getSceneGlobalTranslation ()

Public Member Functions

 setCurrentSceneRenderer (std::function< QImage(QSize &, int, QColor &, bool, QVariantList &, bool, bool, QVariantList &)> renderer)
Constructors, Destructor
Interface IApiObject

Function Documentation

◆ activateViewpoint

ApiJsonResponse activateViewpoint ( QString & vpId)
slot

Activates a viewpoint linked to a SmartSet.

Parameters
vpIdID of SmartSet associated with the view point.
Returns
True if SmartSet has a view point and could be activated, else false.
data: boolean
Since
1.0, Aug 2025

◆ clearClash

ApiJsonResponse clearClash ( )
slot

Clears the transient clash colors and bounding box from the 3D viewport.

Temporary object styles, visibility, and selection states replaced by showClash() are restored.

Returns
An API response with status 200 after the visualization is cleared.
Since
1.1, 09/2026

◆ clearOverlays

ApiJsonResponse clearOverlays ( )
slot

Remove/Delete all overlays.

Since
1.0, 08.2025, jh

◆ clearPickedFaces

ApiJsonResponse clearPickedFaces ( )
slot
Since
1.0, 2025.02, jh

◆ clearPickedPoints

ApiJsonResponse clearPickedPoints ( )
slot

Clears the points collected during the active measurement session.

Since
1.1, 09/2026

◆ createOverlay

ApiJsonResponse createOverlay ( QString name,
QString content,
QVariantMap config = QVariantMap() )
slot

Create a new overlay in 3D view.

Parameters
name
contentHTML content of overlay/legend
config
{
"position" : [ x:int , y:int ]
}
Returns
Id of newly created overlay
data : string
Since
1.0, 08.2025, jh

◆ createViewpoint

ApiJsonResponse createViewpoint ( QString & parentId,
QString & name,
QVariantMap & options )
slot

Creates a viewpoint.

A viewpoint is created as Smartset with a view (camera, clipping) attached.
To delete a viewpoint, use method cnCoreAPI.deleteObject(id).

Parameters
parentIdParent to which the viewpoint is appended. To append the viewpoint on top level, use the ID returned by cnCoreAPI.getRootId(domain, 'viewpoints').
nameName of the new viewpoint.
options
{
"set_as_home": false, // optional key, not part of internal options //@jh better remove here!
"visible": true, // store visible objects
"selected": false, // store selected objects (not implemented yet)
"styles": {
"colors": "current", // one of ("none", "current", "fixed")
"fixed_color": "#ff00ffff" // RGBA hex color value
"show_legend": true
},
"clipping": false, // store clipping planes
"redlining" : false // store redlining
}
Returns
ID of the newly created SmartSet which is equivalent to viewpoint ID (viewpoint is attached to smartset)
data : string
Since
1.0, Nov 2025, jh

◆ getActiveViewpointId

ApiJsonResponse getActiveViewpointId ( )
slot

Get ID of active viewpoint.

Returns
ID of the currently active viewpoint for the current project, if set, otherwise an error code.
data: string
Since
1.0, Mar 2026

◆ getCamera

ApiJsonResponse getCamera ( )
slot

Returns the current camera configuration of the 3D viewport.

This method retrieves the complete state of the currently active camera and returns it as a JSON-compatible structure (QVariantMap) in the API response data field.

Returns
camera configuration as JSON
{
"projection": "perspective",
"near_plane": 0.1,
"far_plane": 15000,
"aspect_ratio": 1.7778,
"field_of_view": 45,
"position": { "x": -171.14, "y": -171.14, "z": 66.55 },
"view_center": { "x": 0, "y": 0, "z": 23.77 },
"up_vector": { "x": 0, "y": 0, "z": 1 },
"left": -0.5,
"right": 0.5,
"bottom": -0.5,
"top": 0.5
}
Since
1.0, Jan 2026

◆ getClippingPlanes

ApiJsonResponse getClippingPlanes ( )
slot
Since
1.0, 2025.02, jh

◆ getConfig

ApiJsonResponse getConfig ( )
slot

Returns the current configuration of the 3D viewer.

See also
setConfig()
Since
1.0, Feb 2025

◆ getCurrentViewData

ApiJsonResponse getCurrentViewData ( )
slot

Get current view.

Returns
JS object containing view data.
{
"camera": {
"position": { "x": -20.0, "y": -20.0, "z": 5.0 },
"view_center": { "x": 0.0, "y": 0.0, "z": 0.0 },
"up_vector": { "x": 0.0, "y": 0.0, "z": 1.0 }
},
"clipping": [
{
"normal": [1.0, 0.0, 0.0],
"ref_point": [3.0, 1.0, 1.0] // picked point
}
],
"redlining": [
{
"type": "Line",
"pen": {
"color": "#ff0000",
"width": 3,
"style": 1
},
"brush": {
},
"box": [0.0, 0,0, 10.0, 4.0]
}
]
}
Since
1.0, Aug 2025

◆ getHomeViewpointId

ApiJsonResponse getHomeViewpointId ( )
slot

Get ID of home viewpoint.

Returns
ID of the currently set home viewpoint for the current project, if set, otherwise an error code.
data: string
Since
1.0, 11.2025

◆ getInfo

ApiJsonResponse getInfo ( )
slot

Get info about OpenGL version etc.

Since
1.0, 10.2025, jh

◆ getNavigationMode

ApiJsonResponse getNavigationMode ( )
slot

Returns the current navigation mode.

Since
1.0, 2025.02, jh

◆ getOverlay

ApiJsonResponse getOverlay ( QString id)
slot

Get overlay.

Returns
JavaScript object containing the overlay data such as id, name, html content and position.
Since
1.0, Sep 2025, sl

◆ getOverlayConfig

ApiJsonResponse getOverlayConfig ( QString id)
slot

Get config data (position etc) of overlay.

{
"position" : [ x:int, y:int ]
}
Since
1.0, 08.2025, jh

◆ getOverlayIds

ApiJsonResponse getOverlayIds ( )
slot

Get IDs of all overlays.

Since
1.0, 08.2025, jh

◆ getPickedFaces

ApiJsonResponse getPickedFaces ( )
slot
Since
1.0, 2025.02, jh

◆ getPickedPoints

ApiJsonResponse getPickedPoints ( )
slot

Returns the snapped world-space points picked during the active measurement session.

The response data is an array of coordinate arrays. The list is cleared when Escape is pressed, the measurement handler is cleared, or navigation mode changes. Outside measurement mode, an empty array is returned.

[
[x, y, z],
[x, y, z]
]
Since
1.0, 2025.02, jh
1.1, 09/2026, implemented measurement point history

◆ getSceneBoundingBox

ApiJsonResponse getSceneBoundingBox ( )
slot

Get bounding box of scene, i.e. of all objects in coordination model

Since
1.0, 02.206, jh

◆ getSceneGlobalTranslation

ApiJsonResponse getSceneGlobalTranslation ( )
slot

Returns the scene translation from global coordinates to internal render coordinates.

The translation is applied as follows:

internalPosition = globalPosition + translation
Returns
{
data: {
"translation": [x, y, z]
}
}
Note
This method is intended mainly for development and testing.
Since
1.0, 02.2026, jh

◆ getScreenshot

ApiJsonResponse getScreenshot ( QVariantMap & options = {})
slot

Captures the current 3D view as a Base64-encoded PNG image.

The screenshot contains the OpenGL viewport. If includeLegend is true, the legend is composited onto the image when it is currently visible.

Parameters
optionsScreenshot options. All keys are optional.
{
"legend": true // Include a visible legend; defaults to true.
"redlining": true // Include visible redlinings; defaults to true.
}
Returns
API response whose data value is the Base64-encoded PNG image data. The value does not include a data-URL prefix.
data: string (Base64-encoded PNG)
Since
1.0, 2025.02, jh
1.1, 2026.07, legend capture option documented

◆ getViewData

ApiJsonResponse getViewData ( QString & vpId)
slot

Gets view data from specified viewpoint.

Parameters
vpIdID of viewpoint.
See also
getCurrentViewData()
Since
1.0, 11.2025, jh

◆ getViewpointIds

ApiJsonResponse getViewpointIds ( )
slot

Retrieves the IDs of all viewpoints in the design domain. Containers are not included in the list.

Returns
List of all viewpoints except containers
Note
: The method currently only searches the Design domain. Additional domains will also be offered in the future.
Since
1.0, 11.2025, jh

◆ hideAllOverlays

ApiJsonResponse hideAllOverlays ( )
slot

Hide all overlays

Since
1.0, 08.2025, jh

◆ isLegendVisible

ApiJsonResponse isLegendVisible ( )
slot

Checks if the Legend overlay is visible.

Returns
{
data: <boolean>
}
Since
1.1, Jul 2026

◆ isQuickInfoVisible

ApiJsonResponse isQuickInfoVisible ( )
slot

Checks if the QuickInfo is visible.

Returns
{
data: <boolean>
}
Since
1.1, Jul 2026

◆ raytraceCurrentScene

ApiJsonResponse raytraceCurrentScene ( QVariantMap & options)
slot

Ray traces the currently visible 3D scene and returns a Base64-encoded PNG image. The renderer uses the active viewport camera, scene colors, transparency, clipping, and visibility configuration.

Parameters
optionsRendering options. All members are optional.
{
"size": [420, 300],
"quality": 1,
"baseplane": "#fcfcfc",
"shadow": true,
"include_legend": true,
"lights": [{
"type": "point",
"color": [1.0, 1.0, 1.0],
"intensity": 1.0,
"position": ["$eye.x", "$eye.y", "$eye.z"],
"lookat": ["$bbox.min.x", "$bbox.min.y", "$bbox.min.z"],
"range": 20.0,
"innerConeAngle": 20.0,
"outerConeAngle": 30.0,
"castShadows": true,
"shadowBias": 0.001,
"enabled": true
}]
}
size defaults to the viewport size and is limited to 8192 pixels per dimension and 32 million pixels in total. quality is 1 (normal), 2 (good), or 3 (best), and defaults to 1.

baseplane is a Qt-compatible color string such as "#fcfcfc", "#80fcfcfc", or "lightgray". If omitted, no base plane is rendered. Set shadow to true to calculate soft shadows; it defaults to false. Set include_legend to true to composite the currently visible viewport legend as a 2D overlay on the ray-traced image. It defaults to false; no legend is added when it is currently hidden.

Supported light types are directional, point, spot, and ambient. Colors are normalized RGB arrays. Position coordinates may be numbers or scene-relative expressions: $eye.x, $eye.y, $eye.z, and the bounding-box coordinates $bbox.min.x through $bbox.max.z. The bounding box contains only objects that pass the renderer's visibility filters. $bbox.midx, $bbox.midy, and $bbox.midz select its center coordinates. Compact spellings such as $bbox.minx and dotted spellings such as $bbox.mid.x are accepted. A numeric offset may follow, for example $bbox.max.z + 10 or $eye.x - 2.5.

For directional and spot lights, lookat is the world-space point toward which the light at position points. It accepts the same numeric and scene-relative coordinates as position.

If lights is omitted, the original camera-relative key light is used. Passing an empty array disables this default light.

Returns
An API response containing the Base64-encoded PNG and the resolved rendering options on success. Defaults are included, the output dimensions are reported, and scene-relative light coordinates are replaced with their resolved numeric coordinates.
{
"data": {
"image": "iVBORw0KGgo...",
"options": { ... }
}
}

◆ rebuildSceneGraph

ApiJsonResponse rebuildSceneGraph ( )
slot

Rebuild internal scene graph for rendering. Call this method after creating new 3D objects to enforce rendering of new objects.

Since
1.1, 08.2026, jh

◆ removeOverlay

ApiJsonResponse removeOverlay ( QString id)
slot

Remove(delete) overlay.

Parameters
idId of overlay
Returns
Since
1.0, 08.2025, jh

◆ resetClipping

ApiJsonResponse resetClipping ( )
slot
Since
1.0, 2025.02, jh

◆ resetConfig

ApiJsonResponse resetConfig ( )
slot

Resets the current 3D viewer configuration to the default settings.

Since
1.0, Aug 2025

◆ resetHomeViewpoint

ApiJsonResponse resetHomeViewpoint ( )
slot

Reset home viewpoint.

Returns
true if a home viewpoint exists and reset was successful, else false.
data: boolean
Since
1.0, 11.2025

◆ resetView

ApiJsonResponse resetView ( )
slot

Resets the 3D view.

Clears the selection, resets any clipping planes and shows all objects.

Since
1.0, 03.2026, jh

◆ setCamera

ApiJsonResponse setCamera ( QVariantMap & cam)
slot

Patches the camera configuration of the 3D viewport.

This method updates only the provided properties of the currently active camera. Omitted properties retain their current values. A projection-only patch preserves the visible extent when switching between perspective and 'orthographic' 'projection'.

Parameters
camPartial camera configuration, for example: { "projection": "orthographic" } The input aliases near, far, lookat, and up, as well as three-element vector arrays, remain accepted for compatibility.
See also
getCamera()
Since
1.0, Jan 2026

◆ setClippingPlanes

ApiJsonResponse setClippingPlanes ( QVariantMap & clipping)
slot

Sets a clipping plane for the 3D view.

Parameters
clippingClipping-plane definition. Its format is the same as an individual clipping-plane map returned by getClippingPlanes():
{
"normal": [x, y, z],
"ref_point": [x, y, z]
}
normal is the plane's normal vector and ref_point is a point on the plane. Each array contains the three numeric coordinates x, y and z.
Since
1.0, 2025.02, jh

◆ setConfig

ApiJsonResponse setConfig ( QVariantMap & cfg)
slot

Sets the configuration of 3D viewer.

Parameters
cfgConfiguration object (JSON)
const cfg = {
"background_color": "#ffffff",
"selection_color": "#00ff00",
"objects": {
"openings": {
"visible": true,
"use_custom_color": false,
"color": "#ff000040"
},
"spaces": {
"visible": true,
"use_custom_color": false,
"color": "#0091c926"
},
"lines": {
"visible": true
}
},
"edges": {
"visible": true,
"color": "#5c5c5c"
},
"grid": {
"visible": true,
"color": "#e0e0e0"
},
"bounding_boxes": {
"visible": false,
"color": "#00ff00",
"offset": 0.05
},
"rendering": {
"fast_paint": true,
"ambient_occlusion": {
"enabled": true,
"radius": 3.0
}
},
"clipping": {
"fill_faces": true,
"color": "#b8b3c7",
}
}
Note
Color values must be provided in hexadecimal #rrggbb or #rrggbbaa format.
Since
1.0, Feb 2025
1.1, Aug 2025: extended

◆ setCurrentSceneRenderer()

setCurrentSceneRenderer ( std::function< QImage(QSize &, int, QColor &, bool, QVariantList &, bool, bool, QVariantList &)> renderer)

Sets the application-provided renderer for the current 3D scene.

The project library does not depend on the GUI renderer, so GUI applications provide the rendering callback during initialization.

◆ setHomeViewpointId

ApiJsonResponse setHomeViewpointId ( QString & vpID)
slot

Set viewpoint with ID 'vpID' as home viewpoint for the current project.

If an empty ID or non-existent ID is passed, an error code is returned.

Parameters
vpIDID of the viewpoint that is to be set as the home viewpoint
Returns
true if home viewpoint changed, else false. In case of an invalid id check status code.
data: boolean
Since
1.0, 11.2025

◆ setLegendVisible

ApiJsonResponse setLegendVisible ( bool visible)
slot

Sets the visibility of the Legend overlay.

Parameters
visibleTrue to show the overlay, false to hide it.
Since
1.1, Jul 2026

◆ setNavigationMode

ApiJsonResponse setNavigationMode ( QVariantMap & cfg)
slot

Sets the navigation mode of 3D view.

Parameters
cfg
{
"mode" : one of ["orbit", "walk", "clip", "measure", "redline"]
}
Since
1.0, 2025.02

◆ setOverlayConfig

ApiJsonResponse setOverlayConfig ( QString id,
QVariantMap config )
slot

Get config data (position etc) of overlay

Parameters
config
{
"position" : [ x:int , y:int ]
}
Since
1.0, 08.2025, jh

◆ setOverlayContent

ApiJsonResponse setOverlayContent ( QString id,
QString content )
slot

Set HTML content of overlay

Since
1.0, 08.2025, jh

◆ setOverlayName

ApiJsonResponse setOverlayName ( QString id,
QString name )
slot
Since
1.0, 08.2025, jh

◆ setOverlayVisible

ApiJsonResponse setOverlayVisible ( QString id,
bool visible )
slot

Sets the visibility of the overlay.

Parameters
idID of the overlay
visibleTrue to show the overlay, false to hide it.
Since
1.0, 08.2025, jh

◆ setQuickInfoVisible

ApiJsonResponse setQuickInfoVisible ( bool visible)
slot

Sets the visibility of the QuickInfo.

Parameters
visibleTrue to show the QuickInfo, false to hide it.
Since
1.1, Jul 2026

◆ setViewData

ApiJsonResponse setViewData ( QString & vpId,
QVariantMap & data )
slot

Sets view data to specified viewpoint.

Parameters
vpIdID of viewpoint.
dataView data
Returns
Since
1.0, 11.2025, jh

◆ showAllOverlays

ApiJsonResponse showAllOverlays ( )
slot

Show all overlays

Since
1.0, 08.2025, jh

◆ showClash

ApiJsonResponse showClash ( QString & clashId)
slot

Shows one clash finding in the 3D viewport. The two clashing objects are made visible and rendered opaquely with the colors of selections A and B. Other scene objects are hidden. A red corner-frame bounding box marks the clash, while secondary wireframes show the models containing the affected objects. Camera zoom is based on the affected objects' average bounding-box size and remains focused on the clash location.

Parameters
clashIdPersistent ID returned as clash_id in a clash result finding.
Since
1.1, 09/2026

◆ showHomeViewpoint

ApiJsonResponse showHomeViewpoint ( )
slot

Show home viewpoint.

Since
1.0, Jun 2025, jh

◆ startPickedFacesLog

ApiJsonResponse startPickedFacesLog ( )
slot
Since
1.0, 2025.02, jh

◆ stopPickedFacesLog

ApiJsonResponse stopPickedFacesLog ( )
slot
Since
1.0, 2025.02, jh

◆ updateViewpoint

ApiJsonResponse updateViewpoint ( QString & vpId)
slot

Updates a viewpoint.

Unlike updateSmartSets(), which updates the SmartSet structure according to the given rule, this function updates only the viewpoint.

Parameters
vpIdID of viewpoint (SmartSet)
Returns
data : boolean
Since
1.0, Nov 2025

◆ zoomAll

ApiJsonResponse zoomAll ( QVariantMap & opt = QVariantMap())
slot

Adjusts the view to fit the bounding box of all objects (even hidden).

See also
zoomToObjects
Parameters
optOptions (optional)
{
'view' : one of [ 'current' , 'top' , 'left' , 'right' , 'front' , 'back' ]
// 'current' is default, i.e. view direction/vector is not changed
}

Example

// show all objects from top down
const opt = {
'view' : 'top'
}
return cnView3dAPI.zoomAll( opt )
Since
1.0, Aug 2025, sl, 02.2026, jh

◆ zoomToObjects

ApiJsonResponse zoomToObjects ( QStringList & objectIds,
QVariantMap & options = QVariantMap() )
slot

Adjusts the view to fit the bounding box of the given objects.

This method modifies the current view so that all provided objects are visible in the viewport. The method computes the combined bounding box of all valid objects and moves the eye point (camera position) accordingly, so that the entire bounding box fits within the view. The current viewing direction is preserved.

Parameters
objectIdsA list of object IDs. The bounding boxes of the associated objects will be used to compute the zoom target.
optionsOptions (optional)
{
'view' : one of [ 'current' , 'top' , 'left' , 'right' , 'front' , 'back' ]
// 'current' is default, i.e. view direction/vector is not changed
}
Returns
data: null
Note
Objects with invalid or undefined geometry may be ignored.
Since
1.0, Aug 2025, sl

◆ zoomToPoints

ApiJsonResponse zoomToPoints ( QVariantList & points,
QVariantMap & options = QVariantMap() )
slot

Adjusts the view to fit the bounding box of the given points.

This method modifies the current view so that all provided points are visible in the viewport. The method computes the combined bounding box of all valid points and moves the eye point (camera position) accordingly, so that the entire bounding box fits within the view. The current viewing direction is preserved.

Parameters
pointsAn array of points. The x, y and z coordinates must be passed on as a list one after the other. The length of the list must be divisible by three.
optionsOptions (optional)
{
'view' : one of [ 'current' , 'top' , 'left' , 'right' , 'front' , 'back' ]
// 'current' is default, i.e. view direction/vector is not changed
}
Returns
data: null
Since
1.0, 2026.02, jh