3D

Models

Retrieve a model by ID

ThreeDModelsAPI.retrieve(id: int) → ThreeDModel | None

Parameters: id (int) – Get the model with this id.
Returns: The requested 3d model.
Return type: ThreeDModel | None

Example

Get 3d model by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.models.retrieve(id=1)

List models

ThreeDModelsAPI.list(published: bool | None = None, limit: int | None = 25) → ThreeDModelList

List 3d models.

Parameters

published (bool | None) – Filter based on whether or not the model has published revisions.
limit (int | None) – Maximum number of models to retrieve. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The list of 3d models.

Return type

ThreeDModelList

Examples

List 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> three_d_model_list = c.three_d.models.list()

Iterate over 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for three_d_model in c.three_d.models:
...     three_d_model # do something with the 3d model

Iterate over chunks of 3d models to reduce memory load:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> for three_d_model in c.three_d.models(chunk_size=50):
...     three_d_model # do something with the 3d model

Create models

ThreeDModelsAPI.create(name: str | Sequence[str], data_set_id: int | None = None, metadata: dict[str, str] | None = None) → ThreeDModel | ThreeDModelList

Create new 3d models.

Parameters

name (str | Sequence[str]) – The name of the 3d model(s) to create.
data_set_id (int | None) – The id of the dataset this 3D model belongs to.
metadata (dict[str, str] | None) – Custom, application-specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.

Returns

The created 3d model(s).

Return type

ThreeDModel | ThreeDModelList

Example

Create new 3d models:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.models.create(name="My Model", data_set_id=1, metadata={"key1": "value1", "key2": "value2"})

Update models

ThreeDModelsAPI.update(item: ThreeDModel | ThreeDModelUpdate | Sequence[ThreeDModel | ThreeDModelUpdate]) → ThreeDModel | ThreeDModelList

Update 3d models.

Parameters: item (ThreeDModel | ThreeDModelUpdate | Sequence[ThreeDModel | ThreeDModelUpdate]) – ThreeDModel(s) to update
Returns: Updated ThreeDModel(s)
Return type: ThreeDModel | ThreeDModelList

Examples

Update 3d model that you have fetched. This will perform a full update of the model:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> three_d_model = c.three_d.models.retrieve(id=1)
>>> three_d_model.name = "New Name"
>>> res = c.three_d.models.update(three_d_model)

Perform a partial update on a 3d model:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelUpdate
>>> c = CogniteClient()
>>> my_update = ThreeDModelUpdate(id=1).name.set("New Name")
>>> res = c.three_d.models.update(my_update)

Delete models

ThreeDModelsAPI.delete(id: int | Sequence[int]) → None

Delete 3d models.

Parameters: id (int | Sequence[int]) – ID or list of IDs to delete.

Example

Delete 3d model by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.models.delete(id=1)

Revisions

Retrieve a revision by ID

ThreeDRevisionsAPI.retrieve(model_id: int, id: int) → ThreeDModelRevision | None

Retrieve a 3d model revision by id

Parameters

model_id (int) – Get the revision under the model with this id.
id (int) – Get the model revision with this id.

Returns

The requested 3d model revision.

Return type

ThreeDModelRevision | None

Example

Retrieve 3d model revision by model id and revision id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.retrieve(model_id=1, id=1)

Create a revision

ThreeDRevisionsAPI.create(model_id: int, revision: ThreeDModelRevision | Sequence[ThreeDModelRevision]) → ThreeDModelRevision | ThreeDModelRevisionList

Create a revisions for a specified 3d model.

Parameters

model_id (int) – Create revisions for this model.
revision (ThreeDModelRevision | Sequence[ThreeDModelRevision]) – The revision(s) to create.

Returns

The created revision(s)

Return type

ThreeDModelRevision | ThreeDModelRevisionList

Example

Create 3d model revision:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelRevision
>>> c = CogniteClient()
>>> my_revision = ThreeDModelRevision(file_id=1)
>>> res = c.three_d.revisions.create(model_id=1, revision=my_revision)

List revisions

ThreeDRevisionsAPI.list(model_id: int, published: bool = False, limit: int | None = 25) → ThreeDModelRevisionList

List 3d model revisions.

Parameters

model_id (int) – List revisions under the model with this id.
published (bool) – Filter based on whether or not the revision is published.
limit (int | None) – Maximum number of models to retrieve. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The list of 3d model revisions.

Return type

ThreeDModelRevisionList

Example

List 3d model revisions:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list(model_id=1, published=True, limit=100)

Update revisions

ThreeDRevisionsAPI.update(model_id: int, item: ThreeDModelRevision | ThreeDModelRevisionUpdate | Sequence[ThreeDModelRevision | ThreeDModelRevisionUpdate]) → ThreeDModelRevision | ThreeDModelRevisionList

Update 3d model revisions.

Parameters

model_id (int) – Update the revision under the model with this id.
item (ThreeDModelRevision | ThreeDModelRevisionUpdate | Sequence[ThreeDModelRevision | ThreeDModelRevisionUpdate]) – ThreeDModelRevision(s) to update

Returns

Updated ThreeDModelRevision(s)

Return type

ThreeDModelRevision | ThreeDModelRevisionList

Examples

Update a revision that you have fetched. This will perform a full update of the revision:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> revision = c.three_d.revisions.retrieve(model_id=1, id=1)
>>> revision.status = "New Status"
>>> res = c.three_d.revisions.update(model_id=1, item=revision)

Perform a partial update on a revision, updating the published property and adding a new field to metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDModelRevisionUpdate
>>> c = CogniteClient()
>>> my_update = ThreeDModelRevisionUpdate(id=1).published.set(False).metadata.add({"key": "value"})
>>> res = c.three_d.revisions.update(model_id=1, item=my_update)

Delete revisions

ThreeDRevisionsAPI.delete(model_id: int, id: int | Sequence[int]) → None

Delete 3d model revisions.

Parameters

model_id (int) – Delete the revision under the model with this id.
id (int | Sequence[int]) – ID or list of IDs to delete.

Example

Delete 3d model revision by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.delete(model_id=1, id=1)

Update a revision thumbnail

ThreeDRevisionsAPI.update_thumbnail(model_id: int, revision_id: int, file_id: int) → None

Update a revision thumbnail.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
file_id (int) – Id of the thumbnail file in the Files API.

Example

Update revision thumbnail:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.update_thumbnail(model_id=1, revision_id=1, file_id=1)

List nodes

ThreeDRevisionsAPI.list_nodes(model_id: int, revision_id: int, node_id: int | None = None, depth: int | None = None, sort_by_node_id: bool = False, partitions: int | None = None, limit: int | None = 25) → ThreeDNodeList

Retrieves a list of nodes from the hierarchy in the 3D Model.

You can also request a specific subtree with the ‘nodeId’ query parameter and limit the depth of the resulting subtree with the ‘depth’ query parameter.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
node_id (int | None) – ID of the root node of the subtree you request (default is the root node).
depth (int | None) – Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.
sort_by_node_id (bool) – Returns the nodes in nodeId order.
partitions (int | None) – The result is retrieved in this many parts in parallel. Requires sort_by_node_id to be set to true.
limit (int | None) – Maximum number of nodes to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The list of 3d nodes.

Return type

ThreeDNodeList

Example

List nodes from the hierarchy in the 3d model:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list_nodes(model_id=1, revision_id=1, limit=10)

Filter nodes

ThreeDRevisionsAPI.filter_nodes(model_id: int, revision_id: int, properties: dict[str, dict[str, Sequence[str]]] | None = None, limit: int | None = 25, partitions: int | None = None) → ThreeDNodeList

List nodes in a revision, filtered by node property values.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
properties (dict[str, dict[str, Sequence[str]]] | None) – Properties for filtering. The object contains one or more category. Each category references one or more properties. Each property is associated with a list of values. For a node to satisfy the filter, it must, for each category/property in the filter, contain the category+property combination with a value that is contained within the corresponding list in the filter.
limit (int | None) – Maximum number of nodes to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
partitions (int | None) – The result is retrieved in this many parts in parallel. Requires sort_by_node_id to be set to true.

Returns

The list of 3d nodes.

Return type

ThreeDNodeList

Example

Filter nodes from the hierarchy in the 3d model that have one of the values “AB76”, “AB77” or “AB78” for property PDMS/Area AND that also have one of the values “PIPE”, “BEND” or “PIPESUP” for the property PDMS/Type.

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.filter_nodes(model_id=1, revision_id=1, properties={ "PDMS": { "Area": ["AB76", "AB77", "AB78"], "Type": ["PIPE", "BEND", "PIPESUP"] } }, limit=10)

List ancestor nodes

ThreeDRevisionsAPI.list_ancestor_nodes(model_id: int, revision_id: int, node_id: int | None = None, limit: int | None = 25) → ThreeDNodeList

Retrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
node_id (int | None) – ID of the node to get the ancestors of.
limit (int | None) – Maximum number of nodes to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The list of 3d nodes.

Return type

ThreeDNodeList

Example

Get a list of ancestor nodes of a given node:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.revisions.list_ancestor_nodes(model_id=1, revision_id=1, node_id=5, limit=10)

Files

Retrieve a 3D file

ThreeDFilesAPI.retrieve(id: int) → bytes

Retrieve the contents of a 3d file by id.

Parameters: id (int) – The id of the file to retrieve.
Returns: The contents of the file.
Return type: bytes

Example

Retrieve the contents of a 3d file by id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.files.retrieve(1)

Asset mappings

Create an asset mapping

ThreeDAssetMappingAPI.create(model_id: int, revision_id: int, asset_mapping: ThreeDAssetMapping | Sequence[ThreeDAssetMapping]) → ThreeDAssetMapping | ThreeDAssetMappingList

Create 3d node asset mappings.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
asset_mapping (ThreeDAssetMapping | Sequence[ThreeDAssetMapping]) – The asset mapping(s) to create.

Returns

The created asset mapping(s).

Return type

ThreeDAssetMapping | ThreeDAssetMappingList

Example

Create new 3d node asset mapping:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import ThreeDAssetMapping
>>> my_mapping = ThreeDAssetMapping(node_id=1, asset_id=1)
>>> c = CogniteClient()
>>> res = c.three_d.asset_mappings.create(model_id=1, revision_id=1, asset_mapping=my_mapping)

List asset mappings

ThreeDAssetMappingAPI.list(model_id: int, revision_id: int, node_id: int | None = None, asset_id: int | None = None, limit: int | None = 25) → ThreeDAssetMappingList

List 3D node asset mappings.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
node_id (int | None) – List only asset mappings associated with this node.
asset_id (int | None) – List only asset mappings associated with this asset.
limit (int | None) – Maximum number of asset mappings to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.

Returns

The list of asset mappings.

Return type

ThreeDAssetMappingList

Example

List 3d node asset mappings:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.three_d.asset_mappings.list(model_id=1, revision_id=1)

Delete asset mappings

ThreeDAssetMappingAPI.delete(model_id: int, revision_id: int, asset_mapping: ThreeDAssetMapping | Sequence[ThreeDAssetMapping]) → None

Delete 3d node asset mappings.

Parameters

model_id (int) – Id of the model.
revision_id (int) – Id of the revision.
asset_mapping (ThreeDAssetMapping | Sequence[ThreeDAssetMapping]) – The asset mapping(s) to delete.

Example

Delete 3d node asset mapping:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> mapping_to_delete = c.three_d.asset_mappings.list(model_id=1, revision_id=1)[0]
>>> res = c.three_d.asset_mappings.delete(model_id=1, revision_id=1, asset_mapping=mapping_to_delete)

Data classes

class cognite.client.data_classes.three_d.BoundingBox3D(max: list[float] | None = None, min: list[float] | None = None, **kwargs: Any)

Bases: dict

The bounding box of the subtree with this sector as the root sector. Is null if there are no geometries in the subtree.

Parameters

max (list[float] | None) – No description.
min (list[float] | None) – No description.
**kwargs (Any) – No description.

class cognite.client.data_classes.three_d.RevisionCameraProperties(target: list[float] | None = None, position: list[float] | None = None, **kwargs: Any)

Bases: dict

Initial camera position and target.

Parameters

target (list[float] | None) – Initial camera target.
position (list[float] | None) – Initial camera position.
**kwargs (Any) – No description.

Bases: CogniteResource

No description.

Parameters

node_id (int | None) – The ID of the node.
asset_id (int | None) – The ID of the associated asset (Cognite’s Assets API).
tree_index (int | None) – A number describing the position of this node in the 3D hierarchy, starting from 0. The tree is traversed in a depth-first order.
subtree_size (int | None) – The number of nodes in the subtree of this node (this number included the node itself).
cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.three_d.ThreeDAssetMappingList(resources: Collection[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[ThreeDAssetMapping]

Bases: CogniteResource

No description.

Parameters

name (str | None) – The name of the model.
id (int | None) – The ID of the model.
created_time (int | None) – The creation time of the resource, in milliseconds since January 1, 1970 at 00:00 UTC.
data_set_id (int | None) – The id of the dataset this 3D model belongs to.
metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.three_d.ThreeDModelList(resources: Collection[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[ThreeDModel]

Bases: CogniteResource

No description.

Parameters

id (int | None) – The ID of the revision.
file_id (int | None) – The file id.
published (bool | None) – True if the revision is marked as published.
rotation (list[float] | None) – No description.
scale (list[float] | None) – Scale of 3D model in directions X,Y and Z. Should be uniform.
translation (list[float] | None) – 3D offset of the model.
camera (dict[str, Any] | RevisionCameraProperties | None) – Initial camera position and target.
status (str | None) – The status of the revision.
metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 32 bytes, value 512 bytes, up to 16 key-value pairs.
thumbnail_threed_file_id (int | None) – The threed file ID of a thumbnail for the revision. Use /3d/files/{id} to retrieve the file.
thumbnail_url (str | None) – The URL of a thumbnail for the revision.
asset_mapping_count (int | None) – The number of asset mappings for this revision.
created_time (int | None) – The creation time of the resource, in milliseconds since January 1, 1970 at 00:00 UTC.
cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.three_d.ThreeDModelRevisionList(resources: Collection[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[ThreeDModelRevision]

class cognite.client.data_classes.three_d.ThreeDModelRevisionUpdate(id: int | None = None, external_id: str | None = None)

Bases: CogniteUpdate

No description.

Parameters: id (int) – A server-generated ID for the object.

class cognite.client.data_classes.three_d.ThreeDModelUpdate(id: int | None = None, external_id: str | None = None)

Bases: CogniteUpdate

No description.

Parameters: id (int) – A server-generated ID for the object.

Bases: CogniteResource

No description.

Parameters

id (int | None) – The ID of the node.
tree_index (int | None) – The index of the node in the 3D model hierarchy, starting from 0. The tree is traversed in a depth-first order.
parent_id (int | None) – The parent of the node, null if it is the root node.
depth (int | None) – The depth of the node in the tree, starting from 0 at the root node.
name (str | None) – The name of the node.
subtree_size (int | None) – The number of descendants of the node, plus one (counting itself).
properties (dict[str, dict[str, str]] | None) – Properties extracted from 3D model, with property categories containing key/value string pairs.
bounding_box (dict[str, Any] | BoundingBox3D | None) – The bounding box of the subtree with this sector as the root sector. Is null if there are no geometries in the subtree.
cognite_client (CogniteClient | None) – The client to associate with this object.

class cognite.client.data_classes.three_d.ThreeDNodeList(resources: Collection[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[ThreeDNode]