A Photo Editing extension lets users edit a photo or video within the Photos app. After users confirm the changes they make in a Photo Editing extension, the adjusted content is available in Photos. Photos always keeps the original version of the content, too, so that users can revert the changes they make in an extension.
BEFORE YOU BEGIN
Make sure that the Photo Editing extension point is appropriate for the functionality you want to provide. A Photo Editing extension should make it easy for users to make quick, targeted adjustments to a photo or video without requiring too much user interaction. If you want to enable a more generic task or help users share photos and videos with others, the Photo Editing extension point is not the right choice.
To learn about other types of app extensions you can create, seeTable 1-1.
Understand How a Photo Editing Extension Works with Photos
To support a consistent editing experience, Photos keeps multiple versions of each media asset’s image or video data, in addition to adjustment data, which describes past edits made to the asset. For each asset, Photos stores the original version, the current version (which includes the most recent adjustments), and the set of adjustments that were applied to the original version to create the current version.
When a user chooses a Photo Editing extension, Photos asks the extension if it can read the adjustment data. If the app extension supports the adjustment data, Photos provides the original version of the asset as input to the editing session. After the extension reads the adjustment data and reconstructs the past edits, it can allow users to alter or revert past edits or add new edits. For example, if the adjustment data describes filters applied to a photo, the extension reapplies those filters to the original asset and can let users change filter parameters, add new filters, or remove filters.
If the extension doesn’t support an asset’s adjustment data, Photos provides the current version of the asset as input to the editing session. Because the current version contains the rendered output of all past edits, the extension can let users apply new edits to the asset but not alter or revert past edits.
IMPORTANT
Photos does not store a current version of video assets. If your extension can’t read a video asset’s adjustment data, it must work with the original version of the video, overwriting past edits.
When a user finishes using a Photo Editing extension, the extension returns the edited asset and the adjustment data.
Use the Xcode Photo Editing Template
The Xcode Photo Editing template provides default header and implementation files for the principal view controller class (calledPhotoEditingViewController), anInfo.plistfile, and an interface file (that is, a storyboard file).
IMPORTANT
Embed no more than one Photo Editing extension for each media type (photo, video, or Live Photo) in a containing app. The Photos app displays to the user, at most, one extension of each type from a given containing app. In general, it’s best when one Photo Editing extension handles multiple media types.
By default, the Photo Editing template supplies the followingInfo.plistkeys and values:
<key>NSExtension</key>
<dict>
<key>NSExtensionAttributes</key>
<dict>
<key>PHSupportedMediaTypes</key>
<array>
<string>Image</string>
</array>
</dict>
<key>NSExtensionMainStoryboard</key>
<string>MainInterface</string>
<key>NSExtensionPointIdentifier</key>
<string>com.apple.photo-editing</string>
</dict>
In particular, make sure that thePHSupportedMediaTypesarray specifies the types of media assets your app extension can edit. The default value isImage, but you can also useVideoandLivePhoto.
Design the UI
IMPORTANT
For best results, use Auto Layout to design the view of a Photo Editing extension.
In iOS, your app extension’s view must support a full-screen presentation on devices of different sizes, as well as Slide Over and Split View presentations on iPad. In macOS, your app extension’s view occupies the entire Photos window, which is resizable and supports full-screen presentation.
The Photos app displays a Photo Editing extension with a navigation bar in iOS or a combined title bar and toolbar in macOS. Don’t create a navigation-based UI, and avoid stacking additional top-oriented toolbars in your app extension.
Photos automatically displays your app extension’s view so that it occupies the full height of the screen (iOS) or window (macOS), including the area behind the navigation bar or title bar. If you want your content view to appear below the bar, and not behind it, use the view’s top layout guide appropriately.
It’s best when a Photo Editing extension lets users preview the results of their edits. Giving users a preview while they’re still using your app extension means that they can get the effect they want without repeatedly exiting and reentering the extension.
Because users are likely to spend time editing a photo or movie in your app extension, you don’t want them to lose their work if they accidentally choose Cancel. To improve the user experience, be sure to implement theshouldShowCancelConfirmationmethod in your view controller, returningYESif there are unsaved changes. When this method returnsYES, Photos displays confirmation UI so that users can confirm if they really want to cancel their changes.
Implement Your Extension
Users get access to Photo Editing extensions in the Photos app. When a user chooses your app extension, display a view that provides a custom editing interface. To present this view, use a view controller that adopts thePHContentEditingControllerprotocol.
When a user chooses your app extension, Photos provides the asset being edited to your extension’s view controller in the form of aPHContentEditingInputobject. For photo and video assets, you use this object to access the asset’s image or video data to perform your editing. When the user chooses to end editing, Photos asks your app extension’s view controller for aPHContentEditingOutputobject, which you use to provide the edited asset data.
NOTE
To provide responsive performance during photo editing, use the content editing input’sdisplaySizeImageproperty to preview edits. When the user chooses to end editing, apply your edits to the full-size image using thefullSizeImageURLproperty.
When your app extension works with Live Photo assets, it doesn’t access the asset’s underlying image and video resources directly. Instead, you create aPHLivePhotoEditingContextobject from the provided content editing input, and use the methods that class provides to perform and preview edits.
For example code illustrating how to edit all asset media types, download theSample Photo Editing Extensionsample code project.
Handling Memory Constraints
Because a Photo Editing extension often needs to work with large high-resolution images and videos, the extension is likely to experience memory pressures when running on a device. It’s recommended that you examine your existing image-processing code and make sure that it performs to a high standard before you use it in your app extension.
Testing a Photo Editing Extension
Avoid making assumptions about the media formats that your app extension may receive. Be sure to test your filtering and other image-processing code with a wide range of media formats; don’t just test with content from the device camera.
Use the following sizes for guidance when preparing custom navigation bar and toolbar icons, but adjust as needed to create balance.
Target sizesMaximum sizes
72px × 72px (24pt × 24pt @3x)
84px × 84px (28pt × 28pt @3x)
48px × 48px (24pt × 24pt @2x)
56px × 56px (28pt × 28pt @2x)
Tab Bar Icon Size
In portrait orientation, tab bar icons appear above tab titles. In landscape orientation, the icons and titles appear side-by-side. Depending on the device and orientation, the system displays either a regular or compact tab bar. Your app should include custom tab bar icons for both sizes.