Paparazzo is a component for picking and editing photos.

• Installation
• Usage
  • Presenting entire module
    • Additional parameters of MediaPicker module
    • Memory constraints when cropping
  • Presenting photo library
  • UI Customization
• ImageSource
  • Typical use cases
    • Displaying in UI
    • Getting image data
    • Getting image size

There are two options to install Paparazzo using CocoaPods.

Using Marshroute:

pod "Paparazzo"

or if you don't use Marshroute and prefer not to get it as an additional dependency:

pod "Paparazzo/Core"

You can use either the entire module or photo library exclusively.

Initialize module assembly using Paparazzo.AssemblyFactory (or Paparazzo.MarshrouteAssemblyFactory if you use Marshroute):

let factory = Paparazzo.AssemblyFactory()
let assembly = factory.mediaPickerAssembly()

Create view controller using assembly's module method:

let viewController = assembly.module(
    items: items,
    selectedItem: selectedItem,
    maxItemsCount: maxItemsCount,
    cropEnabled: true,
    cropCanvasSize: cropCanvasSize,
    routerSeed: routerSeed,    // omit this parameter if you're using AssemblyFactory
    configuration: configuration
)

Method parameters:

• items — array of photos that should be initially selected when module is presenter.
• selectedItem — selected photo. If set to nil or if items doesn't contain any photo with matching identifier, then the first photo in array will be selected.
• maxItemsCount — maximum number of photos that user is allowed to pick.
• cropEnabled — boolean flag indicating whether user can perform photo cropping.
• cropCanvasSize — maximum size of canvas when cropping photos. (see Memory constraints when cropping).
• routerSeed — routerSeed provided by Marshroute.
• configuration — closure that allows you to provide module's additional parameters.

Additional parameters is described in protocol MediaPickerModule:

• setContinueButtonTitle(_:) and setContinueButtonEnabled(_:) allow to customize "Continue" button text and availability.
• onItemsAdd is called when user picks items from photo library or takes a new photo using camera.
• onItemUpdate is called after user performed cropping.
• onItemRemove is called when user deletes photo.
• onFinish and onCancel is called when user taps Continue and Close respectively.

When cropping photo on devices with low RAM capacity your application can crash due to memory warning. It happens because in order to perform actual cropping we need to put a bitmap of the original photo in memory. To descrease a chance of crashing on older devices (such as iPhone 4 or 4s) we can scale the source photo beforehand so that it takes up less space in memory. cropCanvasSize is used for that. It specifies the size of the photo we should be targeting when scaling.

Initialize module assembly using Paparazzo.AssemblyFactory (or Paparazzo.MarshrouteAssemblyFactory if you use Marshroute):

let factory = Paparazzo.AssemblyFactory()
let assembly = factory.photoLibraryAssembly()

Create view controller using assembly's module method:

let viewController = assembly.module(
    selectedItems: selectedItems,
    maxSelectedItemsCount: maxSelectedItemsCount,
    routerSeed: routerSeed,    // omit this parameter if you're using AssemblyFactory
    configuration: configuration
)

• selectedItems — preselected photos (or nil).
• maxItemsCount — maximum number of photos that user is allowed to pick.
• routerSeed — routerSeed provided by Marshroute.
• configuration — closure used to provide additional module setup.

You can customize colors, fonts and icons used in photo picker. Just pass an instance of PaparazzoUITheme to the initializer of assembly factory.

var theme = PaparazzoUITheme()
theme.shutterButtonColor = .blue
theme.accessDeniedTitleFont = .boldSystemFont(ofSize: 17)
theme.accessDeniedMessageFont = .systemFont(ofSize: 17)
theme.accessDeniedButtonFont = .systemFont(ofSize: 17)
theme.cameraContinueButtonTitleFont = .systemFont(ofSize: 17)
theme.cancelRotationTitleFont = .boldSystemFont(ofSize: 14)

let assemblyFactory = Paparazzo.AssemblyFactory(theme: theme)

Photos picked by user via Paparazzo is provided to you either as MediaPickerItem (when using MediaPicker module) or as PhotoLibraryItem (when using PhotoLibrary module). Both of these enitities are just wrappers around ImageSource, which is a protocol that allows you to get different image representations regardless of where it comes from.

ImageSource is designed to be plaform-independent. You can use it both on iOS and macOS.

See the sections below to understand how to use ImageSource in different use cases.

To present ImageSource in UIImageView, you should use extension method that comes with ImageSource/UIKit pod:

func setImage(
    fromSource: ImageSource?,
    size: CGSize? = nil,
    placeholder: UIImage? = nil,
    placeholderDeferred: Bool = false,
    adjustOptions: ((_ options: inout ImageRequestOptions) -> ())? = nil,
    resultHandler: ((ImageRequestResult<UIImage>) -> ())? = nil)
    -> ImageRequestId?

In most cases you just want to use its simplest version, passing only the first parameter:

imageView.setImage(fromSource: imageSource)

To get image data use ImageSource.fullResolutionImageData(completion:):

imageSource.fullResolutionImageData { data in
    try? data?.write(to: fileUrl)
}

To get image size use ImageSource.imageSize(completion:):

imageSource.imageSize { size in
    // do something with size
}

Andrey Yutkin ([email protected])

MIT