Detect entities in Engineering Diagrams

async AsyncCogniteClient.diagrams.detect(

entities: Sequence[dict | CogniteResource],

search_field: str = 'name',

partial_match: bool = False,

min_tokens: int = 2,

file_ids: int | Sequence[int] | None = None,

file_external_ids: str | SequenceNotStr[str] | None = None,

file_instance_ids: NodeId | Sequence[NodeId] | None = None,

file_references: list[FileReference] | FileReference | None = None,

pattern_mode: bool | None = None,

configuration: DiagramDetectConfig | None = None,

*,

multiple_jobs: bool = False,

) → DiagramDetectResults | tuple[DetectJobBundle, list[dict[str, Any]]]

Detect annotations in engineering diagrams.

Note

All users on this CDF subscription with assets read-all and files read-all capabilities in the project, are able to access the data sent to this endpoint.

Parameters:

• entities (Sequence[dict | CogniteResource]) – List of entities to detect

• search_field (str) – If entities is a list of dictionaries, this is the key to the values to detect in the PnId

• partial_match (bool) – Allow for a partial match (e.g. missing prefix).

• min_tokens (int) – Minimal number of tokens a match must be based on

• file_ids (int | Sequence[int] | None) – ID of the files, should already be uploaded in the same tenant.

• file_external_ids (str | SequenceNotStr[str] | None) – File external ids, alternative to file_ids and file_references.

• file_instance_ids (NodeId | Sequence[NodeId] | None) – Files to detect in, specified by instance id.

• file_references (list[FileReference] | FileReference | None) – File references (id, external_id or instance_id), and first_page and last_page to specify page ranges per file. Each reference can specify up to 50 pages. Providing a page range will also make the page count of the document a part of the response.

• pattern_mode (bool | None) – If True, entities must be provided with a sample field. This enables detecting tags that are similar to the sample, but not necessarily identical. Defaults to None.

• configuration (DiagramDetectConfig | None) – Additional configuration for the detect algorithm. See DiagramDetectConfig class documentation and beta API docs.

• multiple_jobs (bool) – Enables you to publish multiple jobs. If True the method returns a tuple of DetectJobBundle and list of potentially unposted files. If False it will return a single DiagramDetectResults. Defaults to False.

Returns:

Resulting queued job or a bundle of jobs and a list of unposted files. Note that the .result property of the job or job bundle will block waiting for results.

Return type:

DiagramDetectResults | tuple[DetectJobBundle, list[dict[str, Any]]]

Note

The results are not written to CDF, to create annotations based on detected entities use AnnotationsAPI.

Examples

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.contextualization import FileReference
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> detect_job = client.diagrams.detect(
...     entities=[
...         {"userDefinedField": "21PT1017", "ignoredField": "AA11"},
...         {"userDefinedField": "21PT1018"},
...     ],
...     search_field="userDefinedField",
...     partial_match=True,
...     min_tokens=2,
...     file_ids=[101],
...     file_external_ids=["Test1"],
...     file_references=[
...         FileReference(id=20, first_page=1, last_page=10),
...         FileReference(external_id="ext_20", first_page=11, last_page=20),
...     ],
... )
>>> result = detect_job.get_result()
>>> print(result)
<code>
{
    'items': [
        {'fileId': 101, 'annotations': []},
        {'fileExternalId': 'Test1', 'fileId: 1, 'annotations': []},
        {'fileId': 20, 'fileExternalId': 'ext_20', 'annotations': [], 'pageCount': 17},
        {
            'fileId': 20,
            'fileExternalId': 'ext_20',
            'annotations': [
                {
                    'text': '21PT1017',
                    'entities': [{"userDefinedField": "21PT1017","ignoredField": "AA11"}],
                    'region': {
                        'page': 12,
                        'shape': 'rectangle',
                        'vertices': [
                            {'x': 0.01, 'y': 0.01},
                            {'x': 0.01, 'y': 0.02},
                            {'x': 0.02, 'y': 0.02},
                            {'x': 0.02, 'y': 0.01}
                        ]
                    }
                }
            ],
            'pageCount': 17
        }
    ]
}
</code>

To use beta configuration options you can use a dictionary or DiagramDetectConfig object for convenience:

>>> from cognite.client.data_classes.contextualization import (
...     ConnectionFlags,
...     DiagramDetectConfig,
... )
>>> config = DiagramDetectConfig(
...     remove_leading_zeros=True,
...     connection_flags=ConnectionFlags(
...         no_text_inbetween=True,
...         natural_reading_order=True,
...     ),
... )
>>> job = client.diagrams.detect(entities=[{"name": "A1"}], file_id=123, config=config)

Check the documentation for DiagramDetectConfig for more information on the available options.