3D Asset Mapping

List 3D asset mappings

Required capabilities: threedAcl:READ

Lists 3D assets mappings that match the ID for the specified filter query parameter type. Only one type of filter can be specified for each request, either assetId, nodeId or intersectsBoundingBox.

In Hybrid CDF projects: The nodeId and assetId mappings are returned by default. To instead see any assetInstanceId mappings (for CoreDM based contextualization), set the getDmsInstances query parameter to true.

In DataModelingOnly CDF projects: This endpoint is not available. Use DMS queries to list CogniteCADNodes.

Note: When filtering for a specific nodeId, only nodeIds that actually exists will be returned. When filtering for a specific assetId, all mappings will be returned, even if the assetId does not exist.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
cursor
string

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

nodeId
integer <int64>
assetId
integer <int64>
intersectsBoundingBox
string

Example: {"min":[0.0, 0.0, 0.0], "max":[1.0, 1.0, 1.0]}

If given, only return asset mappings for assets whose bounding box intersects the given bounding box.

Must be a JSON object with min, max arrays of coordinates.

getDmsInstances
boolean
Default: false

If true, the response will include any assetInstanceId instances for the mappings.

Responses
200

A list of mappings between assets and 3D nodes

400

The response for a failed request.

get/3d/models/{modelId}/revisions/{revisionId}/mappings
Request samples 
const mappings3D = await client.assetMappings3D.list(3244265346345, 32423454353545);
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create 3D asset mappings

Required capabilities: threedAcl:UPDATE

Create asset mappings

Asset mappings allows connections to be made between assets and 3D nodes. This can be used to contextualize 3D models.

In Hybrid CDF projects: Asset IDs obtained from a mapping may be invalid, and not point to real asset IDs. The assetId existence is not checked by any means by the 3D API. The mappings will be stored until an assetId and nodeId pair is removed through the mappings delete endpoint.

In DataModelingOnly CDF projects: When creating asset mappings, the data model based assetInstanceId (with space and externalId), and the 3d model revision nodeId, must be accessible, existing and valid.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
required

The asset mappings to create.

One of:
required
Array of objects (CreateAssetMapping3D) [ 1 .. 1000 ] items
Responses
201

A list of created asset mappings.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/mappings
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Delete 3D asset mappings

Required capabilities: threedAcl:DELETE

Delete a list of asset mappings.

In Hybrid CDF projects: The delete request items requires a nodeId, and either an assetId or an assetInstanceId.

In DataModelingOnly CDF projects: The delete request items requires a nodeId and an assetInstanceId (with space and externalId).

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
required

The IDs of the asset mappings to delete.

One of:
required
Array of objects (DeleteAssetMapping3D) [ 1 .. 1000 ] items
Responses
200

Empty response.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/mappings/delete
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{ }

Filter 3D asset mappings

Required capabilities: threedAcl:READ

Lists 3D assets mappings that match the specified filter parameter. Only one type of filter can be specified for each request, either assetIds, nodeIds or treeIndexes.

In Hybrid CDF projects: The nodeId and assetId mappings are returned by default. To instead see only any assetInstanceId mappings (for CoreDM based contextualization), set the getDmsInstances property to true, in the request body.

In DataModelingOnly CDF projects: This endpoint is not available. Use DMS queries to list CogniteCADNodes.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The filter for asset mappings to get.

getDmsInstances
boolean
Default: false

If true, the response will include only the mappings with assetInstanceId values, for DMS based assets.

AssetMapping3DAssetFilter (object) or AssetMapping3DAssetInstanceIdFilter (object) or AssetMapping3DNodeFilter (object) or AssetMapping3DTreeIndexFilter (object)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
Responses
200

A list of matching asset mappings.

400

The response for a failed request.

post/3d/models/{modelId}/revisions/{revisionId}/mappings/list
Request samples
application/json
{
  • "getDmsInstances": false,
  • "filter": {
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

List mappings for one assetID across all 3D models

Required capabilities: threedAcl:READ

Retrieves a list of node IDs from the hierarchy of all available 3D models which are mapped to the supplied asset ID. If a nodeId is mapped to an assetId but is invalid or does not exist anymore, it will be omitted from the results. An asset referenced in an asset mapping is not guaranteed to exist.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
assetId
required
integer <int64>

Asset ID.

query Parameters
cursor
string

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses
200

A list of mappings between assets and 3D valid nodes and revisions in which exist

400

The response for a failed request.

get/3d/mappings/{assetId}/modelnodes
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Filter which nodes are within a boundingbox for a revision.

This endpoint is only supported in dm-only projects. The nodeIds can be found as part of a CogniteCadNode in the field cadNodeReference. Similar functionality is supported in classic through:

  • list 3D asset mappings endpoint + intersectsBoundingBox
Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json

The Model, Revision, a list of nodes and an area definition

required
object (InstanceReference)
required
object (InstanceReference)
required
object (FilterNodesByBoundingBox)
Responses
200

A list containing the nodes that are within the area definition for the given Model Revision

400

The response for a failed request.

post/3d/nodes/list
Request samples
application/json
{
  • "model": {
    },
  • "revision": {
    },
  • "filterNodesByBoundingBox": {
    }
}
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}
➔ Next to 3D Jobs