<!--
{
  "documentType" : "article",
  "framework" : "AVFoundation",
  "identifier" : "/documentation/AVFoundation/creating-auxiliary-depth-data-manually",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Creating auxiliary depth data manually"
}
-->

# Creating auxiliary depth data manually

Generate a depth image and attach it to your own image.

## Discussion

iOS Portrait Mode generates a depth map and attaches it to the image as auxiliary metadata, but for custom effects, you can generate your own auxiliary depth image, one not taken with iOS Portrait Mode or another depth-enabled capture device. This article shows you how to generate this map and attach it to your image.

### Convert pixel values into a compatible floating-point format

The depth image is a single-component image that must be converted per-pixel from grayscale pixel values (`0` = black to `1` = white, zNear to zFar) to either depth (in meters) or disparity (in 1/meters). Then adjust these values to fit your desired floating-point format.

The supported pixel formats for disparity or depth images are:

- `kCVPixelFormatType_DisparityFloat16 = 'hdis'`: An IEEE754-2008 binary16 (half float), describing the normalized shift when comparing two images. Units are 1/meters: (pixelShift / (pixelFocalLength * baselineInMeters))
- `kCVPixelFormatType_DisparityFloat32 = 'fdis'`: An IEEE754-2008 binary32 float, describing the normalized shift when comparing two images. Units are 1/meters: (pixelShift / (pixelFocalLength * baselineInMeters))
- `kCVPixelFormatType_DepthFloat16 = 'hdep'`: An IEEE754-2008 binary16 (half float), describing the depth (distance to an object) in meters
- `kCVPixelFormatType_DepthFloat32 = 'fdep'`: An IEEE754-2008 binary32 float, describing the depth (distance to an object) in meters

Load the grayscale image into a <doc://com.apple.documentation/documentation/CoreVideo/cvpixelbuffer-q2e>. Load its base address, attained via <doc://com.apple.documentation/documentation/CoreVideo/CVPixelBufferLockBaseAddress(_:_:)>, as data (<doc://com.apple.documentation/documentation/CoreFoundation/CFData>) and pass it as the <doc://com.apple.documentation/documentation/ImageIO/kCGImageAuxiliaryDataInfoData> value into a dictionary (<doc://com.apple.documentation/documentation/CoreFoundation/CFDictionary>).

### Parse metadata dictionaries

The format of the dictionary is documented in `CGImageSource.h`. Access this dictionary with <doc://com.apple.documentation/documentation/ImageIO/CGImageSourceCopyAuxiliaryDataInfoAtIndex(_:_:_:)>. The dictionary supports JPEG, HEIF, and DNG images. The <doc://com.apple.documentation/documentation/CoreFoundation/CFDictionary> contains auxiliary data in the following format:

- <doc://com.apple.documentation/documentation/ImageIO/kCGImageAuxiliaryDataInfoData> → Depth data (<doc://com.apple.documentation/documentation/CoreFoundation/CFData>)
- <doc://com.apple.documentation/documentation/ImageIO/kCGImageAuxiliaryDataInfoDataDescription> → Depth data description (<doc://com.apple.documentation/documentation/CoreFoundation/CFDictionary>: See below for more details.)
- <doc://com.apple.documentation/documentation/ImageIO/kCGImageAuxiliaryDataInfoMetadata> → Optional metadata (<doc://com.apple.documentation/documentation/ImageIO/CGImageMetadata>)

<doc://com.apple.documentation/documentation/ImageIO/CGImageSourceCopyAuxiliaryDataInfoAtIndex(_:_:_:)> returns `nil` if the image doesn’t contain `auxiliaryImageDataType` data.

The value for key <doc://com.apple.documentation/documentation/ImageIO/kCGImageAuxiliaryDataInfoDataDescription> is a <doc://com.apple.documentation/documentation/CoreFoundation/CFDictionary> that you populate to tell the image system how to interpret the depth map. It can contain the following depth data parameters:

- <doc://com.apple.documentation/documentation/ImageIO/kCGImagePropertyPixelFormat> → One of the Core Video `CVPixelBuffer.h` depth or disparity formats
- <doc://com.apple.documentation/documentation/ImageIO/kCGImagePropertyWidth> and <doc://com.apple.documentation/documentation/ImageIO/kCGImagePropertyHeight> → Pixel dimensions
- <doc://com.apple.documentation/documentation/ImageIO/kCGImagePropertyBytesPerRow> → The number of bytes per row in the depth map

### Attach your custom depth map to an image

Attach the depth or disparity dictionary to an image as follows:

1. Create [`AVDepthData`](/documentation/AVFoundation/AVDepthData) with [`init(fromDictionaryRepresentation:)`](/documentation/AVFoundation/AVDepthData/init(fromDictionaryRepresentation:)), passing in the depth or disparity dictionary.
2. Create the image destination.
3. Create the image, using helper methods from <doc://com.apple.documentation/documentation/ImageIO>.

```swift
// Add an image to the destination.
CGImageDestinationAddImage(cgImageDestination, renderedCGImage, attachments)  

// Use AVDepthData to get the auxiliary data dictionary.         
var auxDataType :NSString? 
let auxData = depthData.dictionaryRepresentation(forAuxiliaryDataType: &auxDataType)  

// Add auxiliary data to the image destination. 
CGImageDestinationAddAuxiliaryDataInfo(cgImageDestination, auxDataType!, auxData! as CFDictionary)  

if CGImageDestinationFinalize(cgImageDestination) {  
	return data as Data
}  
```

---

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)