Skip to main content
The migration plugin is an experimental feature. Updates to the Cognite Toolkit are likely to introduce changes to the described commands and processes.
This guide walks data engineers through migrating 360° image collections and their asset annotations from an asset-centric Cognite Data Fusion (CDF) project to data modeling instances. Only 360° images stored in the cdf_360_image_schema data model are supported; Events-based 360° image data is not migrated by these commands.

​
Prerequisites

Migrating 360° images requires a CDF project-level feature flag that is not enabled by default. Contact your Cognite representative or Cognite Support to enable the 3D migration feature flag before you start.
Before migrating 360° images, complete the following:
  1. Request enablement of the 3D migration feature flag from Cognite Support
  2. Migrating assets — required because 360° image annotations link images to assets
  3. Migrating files and time series — required because each 360° image is made up of six cubemap face files that must already exist as CogniteFile instances
If you have not completed some prerequisites, see Manually populate the CogniteMigration data model.

​
Required capabilities

The following capabilities are required to run cdf migrate 360-images:

​
360 images

The following capabilities are required to run cdf migrate 360-image-annotations:

​
360 image annotations

​
Migrating 360 images

Only 360° images already stored in the cdf_360_image_schema data model are supported. Events-based 360° image data is an older, deprecated storage format that is no longer supported in CDF and is not migrated by these commands. See Upload 360° images for background. Before downloading any 360° image collections, cdf migrate 360-images checks for Events-based 360° image data in your project. If any are found, the Cognite Toolkit prints a warning but continues the migration of collections stored in cdf_360_image_schema.
If your project has Events-based 360° image data, you must first migrate it to the cdf_360_image_schema data model using a standalone custom script before you can migrate it to CDM with this command. The Cognite Toolkit does not support this step. Contact Cognite Support if you need assistance.
1

Run `cdf migrate 360-images`

Run the command in interactive mode to select which 360° image collections to migrate, or pass the options as arguments. See cdf migrate 360-images --help.
All six cubemap face files for each image must already exist as CogniteFile instances. 360 images with any face files that are not yet migrated will be fully skipped and logged. Run cdf migrate files first, then re-run this command to pick up any remaining images.If you see the error You need to have the 3D migration feature flag enabled..., enable the 3D migration feature flag in the prerequisites above.
2

Run `cdf migrate 360-image-annotations`

After the images are migrated, migrate images.AssetLink annotations. See Migrating 360 image annotations.
3

Verify the migration

Hybrid projects do not show migrated 360° images in the UI by default. Follow Verifying migrated 360 images and annotations in the UI.

​
Migrating 360 image annotations

After migrating the 360° images, migrate the annotations that link images to assets:
The command prompts you to select which 360° image collections to migrate annotations for, and the instance spaces to use for the Cognite3DObject nodes and Cognite360ImageAnnotation edges. You can also pass all options as command-line arguments. See cdf migrate 360-image-annotations --help for details.
Only annotations of type images.AssetLink can be migrated. The images.InstanceLink annotation type is not yet supported.

​
Verifying migrated 360 images and annotations in the UI

CDF projects that contain asset-centric resources are, by default, in what is called hybrid mode. See 3D models and project types for more information. In hybrid mode, the UI only renders the legacy, asset-centric 360° image collections — not the migrated Cognite360ImageCollection resources. The legacy collections stay visible and untouched by the migration. To inspect the migrated data, temporarily switch the UI to render the migrated data instead:
1

Open the data modeling override page

Navigate to the hidden profile/data-modeling-override page in your project, replacing <organization>, <project>, and <cluster> with your values:
2

Enable the override

Turn on the DATA_MODELING_ONLY override.
3

Inspect the migrated 360 images

Open the 3D UI as usual and navigate to 360 images. With the override enabled, the UI renders the migrated Cognite360ImageCollection and Cognite360Image nodes instead of the legacy collection. A successful migration renders identically to the legacy collection.
While the DATA_MODELING_ONLY override is enabled, treat the UI as read-only for 3D resources. Do not create, edit, or delete 3D models, revisions, or 360° image collections while the override is active, as this can cause unexpected behavior. If your user group has 3D write access, consider disabling it for the duration. Turn the override off again once you are done verifying.

​
How the migration works

When migrating 360° images, the Cognite Toolkit reads the legacy Image360Collection, Image360, and Station360 nodes from the cdf_360_image_schema data model. For each node, the Cognite Toolkit creates a corresponding Cognite360ImageCollection, Cognite360Image, or Cognite360ImageStation node in the CogniteCore model, in the same instance space as the legacy node. Behind the scenes, the Cognite Toolkit also registers an Image360 3D model for each collection to back the Cognite360ImageCollection node. When migrating 360° image annotations, the Cognite Toolkit converts each images.AssetLink annotation on a cubemap face file into a Cognite360ImageAnnotation edge that connects the migrated Cognite360Image node to a Cognite3DObject node, which in turn is linked to the migrated CogniteAsset node. The polygon that marks the annotated region is converted from cubemap face coordinates to the spherical coordinates used by Cognite360ImageAnnotation.

​
What cdf migrate 360-images does

When you run cdf migrate 360-images, the Cognite Toolkit performs the following steps:
1

Check for unsupported legacy data

The Cognite Toolkit checks if the project has any Events-based 360° image data. If it does, a warning is printed, since this data is not migrated by this command.
2

Select 360 image collections

The Cognite Toolkit downloads the selected 360° image collections, along with the images and stations that belong to them, from the cdf_360_image_schema data model.
3

Register the Image360 3D model

For each collection, the Cognite Toolkit registers a new Image360 3D model (or reuses an existing one if the collection has already been migrated) and uses it to create the Cognite360ImageCollection node.
4

Convert stations and images

The Cognite Toolkit converts each Station360 node to a Cognite360ImageStation node, and each Image360 node to a Cognite360Image node. 360 images with any face files not yet migrated as CogniteFile instances are fully skipped and logged.
5

Write the migrated nodes to CDF

The Cognite Toolkit writes the created nodes to CDF using the /models/instances endpoint.

​
What cdf migrate 360-image-annotations does

When you run cdf migrate 360-image-annotations, the Cognite Toolkit performs the following steps:
1

Select 360 image collections and target spaces

The Cognite Toolkit prompts you to select the 360° image collections to migrate annotations for, and the instance spaces to use for the new Cognite3DObject nodes and Cognite360ImageAnnotation edges.
2

Look up cubemap face files

For each selected collection, the Cognite Toolkit looks up which cubemap face files back the already-migrated Cognite360Image nodes.
3

Download annotations

The Cognite Toolkit downloads images.AssetLink annotations linked to those face files from the Annotations API.
4

Convert annotations

For each annotation, the Cognite Toolkit converts the annotated polygon from cubemap face coordinates to spherical coordinates, and looks up the CogniteAsset node for the linked asset using the lineage stored in the CogniteMigration data model.
5

Call the 360-image contextualization endpoint

The Cognite Toolkit groups the converted annotations by collection and calls the /3d/contextualization/image360 endpoint for each group. This endpoint creates the Cognite3DObject nodes and Cognite360ImageAnnotation edges that link the images to the assets.

​
Further reading

Last modified on August 21, 2026