Upload and display 360-degree images

You can upload 360-degree images to Cognite Data Fusion (CDF) and display them in its various programs and applications in the Reveal 3D viewer. 360-degree images are often captured as part of a point cloud scan, such as an E57 format file, but you can also capture and upload them manually or using robots.

When displayed in Reveal 3D viewer, the locations of the 360-degree images are displayed as round markers in the 3D view. Select a marker to enter the specific 360-degree image, and use your mouse to rotate the camera in any direction. You can select other markers to move to nearby 360-degree images.

You need to upload the image files to Cognite Data Fusion (CDF), where each station has six cubemap images with a specific set of metadata. Together, the cubemap images constitute one 360-degree image, representing six directions (left, front, right, back, top, and bottom). The cubemap images can be available separately through file exports from the lidar scanning software or embedded in E57 point cloud files.

tip

You can also use a set of 360 panoramic images (equirectangular images). Before uploading the images to CDF, you need to convert them to cubemap images, for example, with a tool like py360convert.

Upload 360-degree images

You can upload 360-degree images to CDF in two ways:

• For E57 files with 360-degree images, if you have a point cloud file set in the E57 file format that includes both 360-degree images and point cloud data. A zip file of E57 files is also supported.

• For other formatted 360-degree images, if you have 360-degree images and related custom metadata in separate, other (not E57) formatted files.

After uploading in UI or using a custom script, you can view 360-degree images in Search by adding the 360-degree image collection to a scene. To see 360-degree images in custom applications using Reveal, see the Reveal documentation.

caution

Uploading the 360-degree image metadata (pose information) to the Events API is no longer possible. This functionality has been deprecated and will stop working in the future.

E57 files with 360 degree images

Follow these steps to upload the E57 files to CDF, trigger point cloud filtering and indexing, and opt-in to 360-degree image extraction.

Prerequisites:

To use the 360-degree image extraction process, you must have the sessions:create and sessions:list capabilities (in addition to files:write and 3d:read and 3d:create).

Limitations:

360-degree image extraction from E57 files is currently not supported for a 3D model with a dataset associated with it; it will fail with an HTTP 403 error.

Steps:

1. Upload your E57 files to CDF. If these files are large:

   • Upload the files in the ZIP format using the file extractor.

   • Or, upload them as individual E57 files with a custom Python script.

2. Copy the main file ID you uploaded (Individual E57, ZIP, or JSON file).

3. Navigate to Data management > Configure > 3D > Upload 3D models > + Add model.

4. Name your model and select + Create Empty model to create the model without the initial file.

5. In the new model, select More Actions > Filtering and Indexing.

6. For Input data, select Choose your own file and enter the file ID you uploaded earlier.

7. Select Extract 360° images > OK to start processing.

In custom script for other formatted 360 degree images

Follow these steps to upload the cubemap images to CDF and specify the location and orientation of the 360-degree images in the data modeling service (DMS) instances.

1. Upload the cubemap images to the Files API, for example, using a Python script. Each image file needs an externalID and a specific set of 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 of cubemap images is 2048 x 2048 pixels.	2048
   face	The direction of the image (one of left, front, right, back, top, and bottom).	“left”

2. For each 360-degree image collection, use the Data modeling API to create a set of instances to specify the location and orientation of the images. For more information about ingesting and removing instances, see Ingesting instances into a graph or Create or update nodges/edges.

Three data model views are made explicitly for 360 images:

• Image360Collection
• Station360
• Image360

If your project admin has allowed this, the models will be available with 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": image-360-translation-x,
                  "translationY": image-360-translation-y,
                  "translationZ": image-360-translation-z,
                  "eulerRotationX": image-360-euler-rotation-x,
                  "eulerRotationY": image-360-euler-rotation-y,
                  "eulerRotationZ": image-360-euler-rotation-z,
                  "scaleX": image-360-scale-x,
                  "scaleY": image-360-scale-y,
                  "scaleZ": image-360-scale-z,
                  "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 the space ID for the Image360Collection and Station360 instances.
image-360-external-id	The external ID of the Image360 image set instance. Note that there's only one Image360 instance for each 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 in the image set. The rotation angles are in 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, image-360-cubemap-left, image-360-cubemap-right, image-360-cubemap-top, image-360-cubemap-bottom	The external IDs of the cubemap 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.

Add 360-degree images to the scene

To see the 360-degree images in CDF programs and applications using the Reveal 3D viewer, add 360-degree images to the scene.

For the E57 file with both point cloud and 360-degree images, add 3D data when configuring or editing the scene. Select the point cloud, the 360-degree image collection, and, optionally, the related 3D CAD model.

note

The 360-degree images extracted from the E57 file set will be put in a 360-degree image collection named site-<modelId>-<revisionId>. For example, site-111-222, where 111 is the model ID and 222 is the revision ID.