An object that represents one image and its corresponding metadata.
This object holds a single input image for constructing 3D objects from a
series of photographs, along with the image’s metadata, such as EXIF data or
information about a depth buffer, an object mask, or gravity vector.
Use a unique ``RealityKit/PhotogrammetrySample/id-swift.property-8ew3n`` for each ``PhotogrammetrySession`` so RealityKit can distinguish different ``PhotogrammetrySample``
instances in status updates, error messages, and other contexts.
Synchronously loads the image file located at URL into a `PhotogrammetrySample` with as many data fields populated as can be
found in the target file. HEIC images captured with the `ObjectCaptureSession` will contain more advanced data fields
beyond just the image. Which properties are populated depends on how the images were captured.
The `id` of the sample will be automatically created to be unique to the current process.
Throws: If `url` does not point to a file URL or there is a problem loading `url`.
Note: this call will block the calling thread until it completes!
It should not be called from the main thread or main actor, but can be useful if
synchronous code is required. For use in an asynchronous context, please use the
`init(contentsOf:) async throws` version.
This function is primarily used for creating
a custom `Sequence<PhotogrammetrySample>` input for a `PhotogrammetrySession` which is
synchronous but guaranteed by `PhotogrammetrySession` to be iterated off the main thread.
For example, we could compute and add an object mask to
data captured with `ObjectCaptureSession` while preserving all other data.
Here's example code to make a lazy sequence using `init(contentsOf:)` to do this:
```
let inputSequence = myImageUrls.lazy.compactMap { file in
do {
var sample = try PhotogrammetrySample(contentsOf: file)
sample.objectMask = myComputeObjectMask(image: sample.image)
return sample
} catch {
print("Can't load sample: \(file)")
return nil
}
}
let session = PhotogrammetrySession(input: inputSequence)
...
```
Asynchronously loads the image file located at URL into a `PhotogrammetrySample` with as many data fields populated as can be
found in the target file. HEIC images captured with the `ObjectCaptureSession` will contain more advanced data fields
beyond just the image. Which properties are populated depends on how the images were captured.
The `id` of the sample will be automatically created to be unique to the current process.
Throws: If `url` does not point to a file URL or there is a problem loading `url`.
This function is useful for making a capture image inspector or other system that needs
to operate in an asynchronous context, such as operating within the main actor.
For example:
```
func loadDepthData(contentsOf url: URL) async -> CVPixelBuffer? {
return try? await PhotogrammetrySample(contentsOf: url).depthDataMap
}
```
get · iOS 17.0+
objectMask
TypeScript
get objectMask(): (_CoreVideo_CVBuffer) | null
Swift declaration
var objectMask: CVPixelBuffer? { get set }
The image’s object mask.
When a photograph of an object includes surrounding objects, such as
plants, buildings, or people in an outdoor space, you can create an
object mask to exclude the portions of the image that don’t contain the
object. Masking extraneous image data reduces the number of landmarks
RealityKit attempts to match, speeds up the object-creation process, and
produces a more accurate 3D model.
Provide the object mask in
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_onecomponent8>
format and with the same height and width as
``PhotogrammetrySample/image``. RealityKit ignores any pixel in
``PhotogrammetrySample/image`` when the corresponding pixel in
``PhotogrammetrySample/objectMask`` has a value of `0.0` (black) unless
``PhotogrammetrySession/Configuration-swift.struct/isObjectMaskingEnabled``
is set to `False` in the session’s configuration.
set · iOS 17.0+
objectMask
TypeScript
set objectMask(value: (_CoreVideo_CVBuffer) | null)
Swift declaration
var objectMask: CVPixelBuffer? { get set }
The image’s object mask.
When a photograph of an object includes surrounding objects, such as
plants, buildings, or people in an outdoor space, you can create an
object mask to exclude the portions of the image that don’t contain the
object. Masking extraneous image data reduces the number of landmarks
RealityKit attempts to match, speeds up the object-creation process, and
produces a more accurate 3D model.
Provide the object mask in
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_onecomponent8>
format and with the same height and width as
``PhotogrammetrySample/image``. RealityKit ignores any pixel in
``PhotogrammetrySample/image`` when the corresponding pixel in
``PhotogrammetrySample/objectMask`` has a value of `0.0` (black) unless
``PhotogrammetrySession/Configuration-swift.struct/isObjectMaskingEnabled``
is set to `False` in the session’s configuration.
get · iOS 18.0+
scanPassID
TypeScript
get scanPassID(): (number) | null
Swift declaration
var scanPassID: Int? { get }
If captured with `ObjectCaptureSession`, this will contain the ID of the scan pass within the given `sessionID` in which
this sample was captured. Each new scan pass within a specific `sessionID` will have a different `scanPassID` which can be used to
differentiate any associated `boundingBox` data since a new bounding box may have been created after flipping an object
and starting a new pass.
Note that `scanPassID` can only be equated if the `sessionID` is the same -- if the `sessionID` of two samples is
different but the `scanPassID` is the same, these are semantically different coordinate systems and data between them is not
commensurate.
Note that for samples not captured with `ObjectCaptureSession` (where `sessionID` is `nil`), this `scanPassID` is also `nil`.
get · iOS 18.0+
boundingBox
TypeScript
get boundingBox(): (SDKHandle) | null
Swift declaration
var boundingBox: simd_float4x4? { get }
The bounding box of the scene or object being captured, represented as the transform of a
unit cube centered at the origin into an oriented box in the session's world
coordinate system. The transform can be factored as an SRT into the scale (axis length),
orientation (rotation), and center (translation) using `Transform(matrix:)`.
get · iOS 18.0+
captureTime
TypeScript
get captureTime(): (globalThis.Date) | null
Swift declaration
var captureTime: Date? { get }
The capture time of the sample.
get · iOS 18.0+
description
TypeScript
get description(): string
Swift declaration
var description: String { get }
A textual representation of this instance.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(describing:)`
initializer. This initializer works with any type, and uses the custom
`description` property for types that conform to
`CustomStringConvertible`:
struct Point: CustomStringConvertible {
let x: Int, y: Int
var description: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(describing: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `description` property.
get · iOS 26.0+
orientation
TypeScript
get orientation(): _ImageIO_CGImagePropertyOrientation
Swift declaration
var orientation: CGImagePropertyOrientation { get }
The orientation at which the `image` pixel buffer is intended to be displayed in a 2D UI.
get · iOS 17.0+
depthDataMap
TypeScript
get depthDataMap(): (_CoreVideo_CVBuffer) | null
Swift declaration
var depthDataMap: CVPixelBuffer? { get set }
The image’s depth data.
Some cameras, including iPhone cameras, capture depth data in addition
to image data. Providing this data can help ``PhotogrammetrySession``
determine the real-world scale of the photographed object and result in
a correctly sized 3D object for placement in an AR scene. This property
is read-only.
Depth data can be in either
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_disparityfloat32>
or
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_depthfloat32>
format.
set · iOS 17.0+
depthDataMap
TypeScript
set depthDataMap(value: (_CoreVideo_CVBuffer) | null)
Swift declaration
var depthDataMap: CVPixelBuffer? { get set }
The image’s depth data.
Some cameras, including iPhone cameras, capture depth data in addition
to image data. Providing this data can help ``PhotogrammetrySession``
determine the real-world scale of the photographed object and result in
a correctly sized 3D object for placement in an AR scene. This property
is read-only.
Depth data can be in either
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_disparityfloat32>
or
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_depthfloat32>
format.
get · iOS 18.0+
depthConfidenceMap
TypeScript
get depthConfidenceMap(): (_CoreVideo_CVBuffer) | null
Swift declaration
var depthConfidenceMap: CVPixelBuffer? { get }
Depth confidence map associated with the `depthDataMap` if available.
Pixel format is `kCVPixelFormatType_OneComponent8`.
Creates a new sample.
- Parameters:
- id: A unique identifier for the sample. This `id` _must_ be in the domain [0, 2147483647].
- image: The image data in one of the following formats:
* <doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_32bgra>
* <doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_32argb>
get · iOS 17.0+
id
TypeScript
get id(): number
Swift declaration
let id: Int
Unique identifier for the sample. This `id` _must_ be in the domain [0, 2147483647].
get · iOS 17.0+
image
TypeScript
get image(): _CoreVideo_CVBuffer
Swift declaration
let image: CVPixelBuffer
The image data for this sample.
Provide image data in the
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_32bgra>
or
<doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_32argb>
pixel formats.
get · iOS 18.0+
camera
TypeScript
get camera(): (PhotogrammetrySample_Camera) | null
Swift declaration
var camera: PhotogrammetrySample.Camera? { get }
Optional information about the camera that captured the image.
get · iOS 17.0+
gravity
TypeScript
get gravity(): (_CoreMotion_CMAcceleration) | null
Swift declaration
var gravity: CMAcceleration? { get set }
An image’s gravity vector.
Some cameras, including iPhone cameras, capture a gravity vector for
each image. This vector indicates the orientation of the camera at the
moment you took the picture. RealityKit uses this gravity vector to
improve landmark matching with the other images in the session.
set · iOS 17.0+
gravity
TypeScript
set gravity(value: (_CoreMotion_CMAcceleration) | null)
Swift declaration
var gravity: CMAcceleration? { get set }
An image’s gravity vector.
Some cameras, including iPhone cameras, capture a gravity vector for
each image. This vector indicates the orientation of the camera at the
moment you took the picture. RealityKit uses this gravity vector to
improve landmark matching with the other images in the session.
get · iOS 17.0+
metadata
TypeScript
get metadata(): Record<string, unknown>
Swift declaration
var metadata: [String : Any] { get set }
An image’s EXIF metadata.
You can provide EXIF metadata captured by your digital camera to assist
in the object-creation process. During object creation, RealityKit can
use data from the EXIF keys listed below.
- `TIFFMake`
- `TIFFModel`
- `TIFFOrientation`
- `ExifBodySerialNumber`
- `ExifLensMake`
- `ExifLensModel`
- `ExifLensSerialNumber`
- `ExifFocalLength`
- `ExifFocalLengthIn35mmFilm`
- `GPSAltitude`
- `GPSAltitudeRef`
- `GPSLatitude`
- `GPSLatitudeRef`
- `GPSLongitude`
- `GPSLongitudeRef`
set · iOS 17.0+
metadata
TypeScript
set metadata(value: Record<string, unknown>)
Swift declaration
var metadata: [String : Any] { get set }
An image’s EXIF metadata.
You can provide EXIF metadata captured by your digital camera to assist
in the object-creation process. During object creation, RealityKit can
use data from the EXIF keys listed below.
- `TIFFMake`
- `TIFFModel`
- `TIFFOrientation`
- `ExifBodySerialNumber`
- `ExifLensMake`
- `ExifLensModel`
- `ExifLensSerialNumber`
- `ExifFocalLength`
- `ExifFocalLengthIn35mmFilm`
- `GPSAltitude`
- `GPSAltitudeRef`
- `GPSLatitude`
- `GPSLatitudeRef`
- `GPSLongitude`
- `GPSLongitudeRef`
get · iOS 18.0+
sessionID
TypeScript
get sessionID(): (string) | null
Swift declaration
var sessionID: UUID? { get }
If captured with `ObjectCaptureSession`, this will contain a UUID associated with the session.
Note that any `boundingBox` or camera pose information will only be in a consistent coordinate system if the `sessionID`
for those samples is the same. In this sense, the `sessionID` is a tag that defines the coordinate system of all poses and
transforms when comparing samples from multiple captures.
