Upload 360° images programmatically

You can upload 360° images in the Cognite Data Fusion (CDF) user interface by uploading E57 files and configuring filtering and indexing. This guide covers two programmatic options:

Triggering 360° extraction from E57 files with a Python script.
Uploading and registering other 360° formats (cube maps) using the Files API and the DMS API.

Trigger 360° image extraction from E57 files using Python

Use the Cognite Python SDK to trigger 360° image extraction from E57 files. Set extractPhotosphereImages to true to turn on this setting. Adjust file_id, model_id, and dmsInstancesSpaceId for your environment.

This option works for asset-centric projects only.

The example shows the Python script that triggers the extraction of 360° images.

from cognite.client import CogniteClient
client = CogniteClient()

# Specify previously created model ID
model_id = 12346789

# Specify the E57 fileId to be processed for the revision
file_id = 987654321

# Specify the spaceId where the Image360 DMS instances will be stored
space_id = "threed_data"

session = client.iam.sessions.create()

payload = {
  "items": [
    {
      "fileId": file_id,
      "nonce": session.nonce,
      "pipelineConfiguration":
      {
        "indexingOptions" :
        {
          "extractPhotosphereImages": "true",
          "dmsInstancesSpaceId": space_id
        }
      }
    }
  ]
}

response = client.post(f"/api/v1/projects/{client.config.project}/3d/models/{model_id}/revisions", payload)

Custom script for other formatted 360° images

Follow these steps to upload the cube map images to CDF for 360° formats other than E57 and specify the location and orientation of the 360° images in the data modeling service (DMS) instances.

This workflow works only for asset-centric (legacy) projects.

Upload cube map images

Upload the cube map images to the Files API, for example using a Python script. Each image file needs an externalId and metadata.A unique externalId should be set for each file, and it should be the same as referenced from the corresponding Image360 instances image-360-cubemap-front and similar property fields.

Name	Value	Example
`site_id`	A common identifier across all 360° images in the set. You will use this identifier when including the images in a scene.	”site-S01-area-a03”
`site_name`	A human-readable site name.	”Norway Site S01 Area 03”
`station_id`	A unique identifier for the scanning position.	”s01-a03-0012”
`station_name`	A human-readable station name.	”Area 03 - 0012”
`image_type`	Always “cubemap”.	“cubemap”
`image_resolution`	The resolution of the cubemap image. The recommended resolution is 2048 x 2048 pixels.	2048
`face`	The direction of the image (one of left, front, right, back, top, and bottom).	“left”

Create DMS instances

For each 360° image collection, use the Instances API to create instances that specify the location and orientation of the images. See Ingesting instances into a graph or Create or update nodes/edges for more information.Three data model views are used for 360° images:

Image360Collection
Station360
Image360

If your project admin has allowed it, they are available in the cdf_360_image_schema system data model in all CDF projects.You can store the instances in the same space, when ingesting instances for a collection through these three data model views. The DMS instances should have the following metadata:Image360Collection

{
  "items": [
    {
      "instanceType": "node",
      "space": "collection-space-id",
      "externalId": "collection-external-id",
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "cdf_360_image_schema",
            "externalId": "Image360Collection",
            "version": "v1"
          },
          "properties": {
            "label": "collection-label"
          }
        }
      ]
    }
  ],
  "autoCreateDirectRelations": true,
  "autoCreateStartNodes": false,
  "autoCreateEndNodes": false,
  "skipOnVersionConflict": false,
  "replace": false
}

Value	Description
`collection_label`	The name of the collection, for example, “site-factory1-area-a01”.
`collection-space-id`	The space ID to store the `Image360Collection` instance.
`collection-external-id`	The external ID of the `Image360Collection` instance.

Station360

{
  "items": [
    {
      "instanceType": "node",
      "space": "station-space-id",
      "externalId": "station-external-id",
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "cdf_360_image_schema",
            "externalId": "Station360",
            "version": "v1"
          },
          "properties": {
            "label": "station-label"
          }
        }
      ]
    }
  ],
  "autoCreateDirectRelations": true,
  "autoCreateStartNodes": false,
  "autoCreateEndNodes": false,
  "skipOnVersionConflict": false,
  "replace": false
}

Value	Description
`station-space-id`	The space ID to store the `Station360` instance.
`station-external-id`	The external ID of the `Station360` instance.
`station-label`	The name of the station, for example, “station-0012”.

Image360

{
  "items": [
    {
      "instanceType": "node",
      "space": "image-360-space-id",
      "externalId": "image-360-external-id",
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "cdf_360_image_schema",
            "externalId": "Image360",
            "version": "v1"
          },
          "properties": {
            "image": {
              "label": "image-360-label",
              "translationX": 0,
              "translationY": 0,
              "translationZ": 0,
              "eulerRotationX": 0,
              "eulerRotationY": 0,
              "eulerRotationZ": 0,
              "scaleX": 1.0,
              "scaleY": 1.0,
              "scaleZ": 1.0,
              "cubeMapFront": "image-360-cubemap-front",
              "cubeMapBack": "image-360-cubemap-back",
              "cubeMapLeft": "image-360-cubemap-left",
              "cubeMapRight": "image-360-cubemap-right",
              "cubeMapTop": "image-360-cubemap-top",
              "cubeMapBottom": "image-360-cubemap-bottom",
              "collection": "image-360-collection",
              "station": "image-360-station",
              "timeTaken": "image-360-time-taken"
            }
          }
        }
      ]
    }
  ],
  "autoCreateDirectRelations": true,
  "autoCreateStartNodes": false,
  "autoCreateEndNodes": false,
  "skipOnVersionConflict": false,
  "replace": false
}

Value	Description
`image-360-space-id`	The space ID to store the `Image360` instance. Normally the same as for `Image360Collection` and `Station360`.
`image-360-external-id`	The external ID of the `Image360` instance. There is one `Image360` instance per set of 6 images.
`image-360-label`	The name of the image set, for example, “station-0012-images”.
`image-360-translation-x`, `image-360-translation-y`, `image-360-translation-z`	The translation coordinates of the image set.
`image-360-euler-rotation-x`, `image-360-euler-rotation-y`, `image-360-euler-rotation-z`	The rotation angles for the front image (radians).
`image-360-scale-x`, `image-360-scale-y`, `image-360-scale-z`	The scale factors of the image set. Normally 1.0.
`image-360-cubemap-front`, `image-360-cubemap-back`, and similar	The external IDs of the cube map images stored in the Files API.
`image-360-collection`	The external ID of the `Image360Collection` instance.
`image-360-station`	The name of the `Station360` instance.
`image-360-time-taken`	The time when the images were taken.

Next steps

After uploading 360° images, add 360° images to a scene to view them in CDF and the Reveal 3D viewer.

Develop

SDKs and toolkits

Upload 360° images programmatically

Trigger 360° image extraction from E57 files using Python

Custom script for other formatted 360° images

Next steps

​Trigger 360° image extraction from E57 files using Python

​Custom script for other formatted 360° images

​Next steps

Trigger 360° image extraction from E57 files using Python

Custom script for other formatted 360° images

Next steps