> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating 360 images

> Step-by-step guide to migrate 360 images and annotations from an asset-centric to a data modeling-based Cognite Data Fusion (CDF) project.

<Warning>
  The migration plugin is an experimental feature. Updates to the Cognite Toolkit are likely to introduce changes to the described commands and processes.
</Warning>

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](#events-based-360-image-data) is not migrated by these commands.

## Prerequisites

<a id="3d-migration-feature-flag" />

<Warning>
  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.
</Warning>

Before migrating 360° images, complete the following:

1. Request enablement of the 3D migration feature flag from Cognite Support
2. [Migrating assets](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/assets) — required because 360° image annotations link images to assets
3. [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries) — required because each 360° image is made up of six cubemap face files that must already exist as `CogniteFile` instances

<Note>
  If you have not completed some prerequisites, see [Manually populate the CogniteMigration data model](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/prepare#manual-population-of-the-cognitemigration-data-model).
</Note>

## Required capabilities

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

### 360 images

| Capability type      | Action                        | Scope                                                      | Description                                                                                                                                 |
| -------------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Events               | `events:read`                 | All                                                        | Required for the [pre-flight check](#events-based-360-image-data) that warns about Events-based 360° image data this command cannot migrate |
| 3D models            | `threed:read`, `threed:write` | All                                                        | To register the Image360 3D model backing each migrated collection                                                                          |
| Data model instances | `datamodelinstances:read`     | The instance space(s) containing the legacy 360 image data | To read the legacy `Image360Collection`, `Image360`, and `Station360` nodes                                                                 |
| Data model instances | `datamodelinstances:write`    | The instance space(s) containing the legacy 360 image data | To create the `Cognite360ImageCollection`, `Cognite360Image`, and `Cognite360ImageStation` nodes                                            |

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

### 360 image annotations

| Capability type      | Action                     | Scope                                                                | Description                                                                 |
| -------------------- | -------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Files                | `files:read`               | The data sets containing the cubemap face files                      | To resolve the face files linked to each 360 image                          |
| Annotations          | `annotations:read`         | All                                                                  | To read `images.AssetLink` annotations linked to the cubemap face files     |
| Data model instances | `datamodelinstances:read`  | The instance space(s) of the migrated 360 images and migrated assets | To look up the migrated `Cognite360Image` and `CogniteAsset` nodes          |
| Data model instances | `datamodelinstances:write` | The selected `--object-3d-space` and `--contextualization-space`     | To create the `Cognite3DObject` nodes and `Cognite360ImageAnnotation` edges |

## Migrating 360 images

<a id="events-based-360-image-data" />

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](/cdf/3d/guides/360images_upload#before-you-start) 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`.

<Warning>
  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.
</Warning>

<Steps>
  <Step title="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`.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf migrate 360-images
    ```

    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](#3d-migration-feature-flag) in the prerequisites above.
  </Step>

  <Step title="Run `cdf migrate 360-image-annotations`">
    After the images are migrated, migrate `images.AssetLink` annotations. See [Migrating 360 image annotations](#migrating-360-image-annotations).
  </Step>

  <Step title="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](#verifying-migrated-360-images-and-annotations-in-the-ui).
  </Step>
</Steps>

## Migrating 360 image annotations

After migrating the 360° images, migrate the annotations that link images to assets:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate 360-image-annotations
```

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.

<Note>
  Only annotations of type `images.AssetLink` can be migrated. The `images.InstanceLink` annotation type is not yet supported.
</Note>

## 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](/cdf/3d/guides/3dmodels_intro#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:

<Steps>
  <Step title="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:

    ```
    https://<organization>.fusion.cognite.com/<project>/profile/data-modeling-override?cluster=<cluster>.cognitedata.com&workspace=data-fusion
    ```
  </Step>

  <Step title="Enable the override">
    Turn on the **DATA\_MODELING\_ONLY override**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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](/cdf/dm/dm_reference/dm_core_data_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:

<Steps>
  <Step title="Check for unsupported legacy data">
    The Cognite Toolkit checks if the project has any [Events-based 360° image data](#events-based-360-image-data). If it does, a warning is printed, since this data is not migrated by this command.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Write the migrated nodes to CDF">
    The Cognite Toolkit writes the created nodes to CDF using the `/models/instances` endpoint.
  </Step>
</Steps>

## What `cdf migrate 360-image-annotations` does

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Look up cubemap face files">
    For each selected collection, the Cognite Toolkit looks up which cubemap face files back the already-migrated `Cognite360Image` nodes.
  </Step>

  <Step title="Download annotations">
    The Cognite Toolkit downloads `images.AssetLink` annotations linked to those face files from the Annotations API.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Further reading

* [Migrating 3D models](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/3d)
* [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries)
* [Migrating assets](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/assets)
* [Kelmarsh example](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/example)
* [Migration overview](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/steps)