<!--
{
  "availability" : [
    "iOS: -",
    "iPadOS: -",
    "visionOS: 26.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation26ImagePresentationComponentV14Spatial3DImageC"
  },
  "title" : "ImagePresentationComponent.Spatial3DImage"
}
-->

# ImagePresentationComponent.Spatial3DImage

A 3D spatial scene created from a 2D image.

```
class Spatial3DImage
```

## Overview

Create and generate a `Spatial3DImage`  to present a *spatial scene* in RealityKit.
Spatial scenes are a 3D representation of a 2D image or photo
which RealityKit renders with depth and motion parallax.

### Spatial scene generation

To present a `Spatial3DImage` as a spatial scene, you must first *generate* it.
Call the [`generate()`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/generate()) method to generate an in-memory representation of a spatial scene from the original image.
Generation can take a few seconds to complete.

> Note: You can’t generate a `Spatial3DImage` with the visionOS Simulator.
> You can create and work with `Spatial3DImage` instances in the Simulator,
> but calling the ``doc://com.apple.RealityKit/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/generate()`` method throws an error.

You can choose to pre-generate a spatial scene in advance of presentation,
or post-generate it in response to an interaction such as someone pressing a button.

In either case, start by creating a new `Spatial3DImage` from a local file URL for an existing image,
or from an existing `CGImageSource`.

To pre-generate and present the image as a spatial scene,
call the [`generate()`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/generate()) method on the `Spatial3DImage`
to generate its in-memory spatial scene representation.
Next, use the [`init(spatial3DImage:)`](/documentation/RealityKit/ImagePresentationComponent/init(spatial3DImage:)) initializer
to create an [`ImagePresentationComponent`](/documentation/RealityKit/ImagePresentationComponent) from the generated `Spatial3DImage`.
Set the component’s [`desiredViewingMode`](/documentation/RealityKit/ImagePresentationComponent/desiredViewingMode)
to [`spatial3D`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatial3D)
or [`spatial3DImmersive`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatial3DImmersive),
then add the component to an entity to present the spatial scene immediately.

To post-generate a spatial scene,
create a new [`ImagePresentationComponent`](/documentation/RealityKit/ImagePresentationComponent) from the `Spatial3DImage` *before* generating it,
and add the component to an entity.
By default, the component displays the image with a monoscopic
([`mono`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/mono)) viewing mode.
If you created the image from a spatial photo,
you can choose to present the `Spatial3DImage` as a spatial photo instead
by setting the component’s [`desiredViewingMode`](/documentation/RealityKit/ImagePresentationComponent/desiredViewingMode)
to [`spatialStereo`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatialStereo)
or [`spatialStereoImmersive`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatialStereoImmersive).

In your app’s UI, add a button or other trigger to convert the image to 3D.
When someone presses the button,
set the component’s [`desiredViewingMode`](/documentation/RealityKit/ImagePresentationComponent/desiredViewingMode)
to [`spatial3D`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatial3D)
or [`spatial3DImmersive`](/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/spatial3DImmersive),
to indicate that you want the component to present the spatial scene
as soon as the app finishes generating it.
Then, call the [`generate()`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/generate()) method to begin the generation process.
The component displays a generation animation, similar to the Photos app on visionOS,
and transitions to presenting the spatial scene as soon as generation completes.

> Note: Spatial scenes are created by an AI algorithm
> that leverages computational depth to create multiple perspectives of a 2D photo.
> In some cases, spatial scenes may contain visual artifacts.
> When you include a spatial scene in your app’s UI,
> consider providing a button to switch to the original 2D photo instead,
> by setting the component’s ``doc://com.apple.RealityKit/documentation/RealityKit/ImagePresentationComponent/desiredViewingMode``
> to ``doc://com.apple.RealityKit/documentation/RealityKit/ImagePresentationComponent/ViewingMode-swift.struct/mono``.

## Topics

### Creating a spatial scene from a 2D image or spatial photo

[`init(contentsOf:)`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/init(contentsOf:))

Initializes a spatial 3D image from the contents of an image file.

[`init(imageSource:)`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/init(imageSource:))

Initializes a spatial 3D image from the contents of an image source.

### Generating a spatial scene

[`generate()`](/documentation/RealityKit/ImagePresentationComponent/Spatial3DImage/generate())

Creates a 3D representation of the image if one does not already exist.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)