PhotoKit — cos’è, concetti chiave e PHAsset

Cos’è PhotoKit?

PhotoKit è un framework Apple (introdotto in iOS 8, macOS 10.11) che fornisce un’API orientata agli oggetti per lavorare con la libreria multimediale di sistema. A differenza di AssetsLibrary, PhotoKit tratta la libreria multimediale come un database: le query restituiscono oggetti PHAsset, PHCollection e PHCollectionList che rappresentano il contenuto e la struttura di archiviazione.

PhotoKit supporta tutti i tipi di media: foto (JPEG, HEIF, RAW), video (MOV, MP4), Live Photos e scatti in raffica. Il framework gestisce automaticamente la sincronizzazione iCloud: se un’immagine è archiviata in iCloud, PhotoKit la richiede tramite rete e segnala l’avanzamento tramite PHImageRequestOptions.progressHandler.

Una caratteristica fondamentale di PhotoKit è il modello dati basato su PHObject con un identificatore locale (localIdentifier) che rimane stabile tra le sessioni. Ciò consente di salvare riferimenti a oggetti multimediali e ripristinarli dopo il riavvio dell’app senza nuove query.

Come funziona PhotoKit: modello dati e query

PhotoKit è costruito su tre livelli: modello dati (PHObject), query (PHFetchResult) e modifiche (PHPhotoLibrary.performChanges). Il modello dati è gerarchico: PHAsset (foto/video) risiede all’interno di PHAssetCollection (album) e gli album sono raggruppati in PHCollectionList (cartella).

Esecuzione delle query

Le query vengono eseguite tramite PHAsset.fetchAssets e PHAssetCollection.fetchAssetCollections. Tutti i metodi fetch sono sincroni e restituiscono PHFetchResult, che esegue immediatamente la query nel database della libreria multimediale. PHFetchResult supporta l’accesso rapido per indice (object(at:)) e l’enumerazione tramite enumerateObjects.

• fetchAssets(with:options:) — interrogare tutti i media filtrati per tipo, data, album
• fetchAssetCollections(with:subtype:options:) — interrogare album e cartelle
• fetchAssets(in:options:) — interrogare i media all’interno di un album specifico

PHFetchOptions

PHFetchOptions è un oggetto per configurare le query: ordinamento (sortDescriptors), predicato (predicate), inclusione di media nascosti ed eliminati (includeHiddenAssets, includeAllBurstAssets). Le opzioni fetch consentono di filtrare per tipo di media: PHAssetMediaType.image, .video, .audio.

Classi principali di PhotoKit

PhotoKit include un insieme di classi per accedere, interrogare e modificare la libreria multimediale. Comprendere ciascuna di esse è essenziale per lavorare efficacemente con il framework.

PHAsset

PHAsset è un oggetto immutabile che rappresenta un singolo elemento multimediale. Contiene metadati: mediaType, mediaSubtypes, creationDate, location, pixelWidth, pixelHeight, duration (per video), isFavorite, burstIdentifier. LocalIdentifier è una chiave stringa stabile accessibile anche dopo il riavvio dell’app.

PHAssetCollection

PHAssetCollection è un gruppo di media: album di sistema (Recents, Favorites, Selfies, Screenshots), album utente o Moments (raggruppati automaticamente per tempo e luogo). Attributi: localizedTitle, assetCollectionType, assetCollectionSubtype, startDate, endDate.

PHCollectionList

PHCollectionList è una cartella contenente album (PHAssetCollection) o altre cartelle. Viene usato raramente, principalmente per visualizzare la gerarchia nell’interfaccia utente.

PHImageManager e caching

PhotoKit non restituisce UIImage direttamente da PHAsset — è necessario richiedere un’immagine tramite PHImageManager. Ciò garantisce che l’immagine venga caricata con supporto iCloud, caching e dimensione richiesta.

PHImageManager supporta tre modalità di consegna: opportunistic (prima una versione ridotta, poi la completa), highQualityFormat (solo qualità completa) e fastFormat (versione più veloce disponibile). Per le collezioni, utilizzare sempre PHCachingImageManager con precaricamento delle immagini per le celle visibili.

Esempi di utilizzo di PhotoKit in Swift

PhotoKit viene utilizzato per creare gallerie personalizzate, editor e applicazioni multimediali. Esaminiamo tre scenari chiave.

Recuperare tutte le foto dalla libreria multimediale

PHAsset.fetchAssets con PHFetchOptions ordinato per data di creazione è la query di base per costruire una galleria fotografica personalizzata. PHFetchResult supporta il caricamento lazy e l’accesso in streaming.

let options = PHFetchOptions()
options.sortDescriptors = [NSSortDescriptor(
    key: "creationDate",
    ascending: .false
)]
options.predicate = NSPredicate(
    format: "mediaType == %d",
    PHAssetMediaType.image.rawValue
)

let allPhotos = PHAsset.fetchAssets(with: options)
print("Trovate \(allPhotos.count) foto")

allPhotos.enumerateObjects { asset, index, stop in
    print("Foto \(index): \(asset.localIdentifier)")
}

PHFetchResult è un contenitore thread-safe. L’accesso agli oggetti per indice tramite object(at:) non blocca l’interfaccia utente, ma la richiesta di un’immagine tramite PHImageManager deve essere eseguita in modo asincrono.

Caricare immagini con caching

PHCachingImageManager è una sottoclasse di PHImageManager con i metodi startCachingImages e stopCachingImages per il precaricamento. Viene utilizzato in UICollectionView per uno scorrimento fluido.

let cachingManager = PHCachingImageManager()
let targetSize = CGSize(width: 200, height: 200)

// Precaricamento per celle visibili
cachingManager.startCachingImages(
    for: visibleAssets,
    targetSize: targetSize,
    contentMode: .aspectFill,
    options: nil
)

// Richiedi immagine tramite PHImageRequestOptions con fallback iCloud
let requestOptions = PHImageRequestOptions()
requestOptions.deliveryMode = .opportunistic
requestOptions.isNetworkAccessAllowed = .true
requestOptions.progressHandler = { progress, error, stop, info in
    DispatchQueue.main.async {
        print("Download da iCloud: \(progress * 100)%")
    }
}

let requestID = cachingManager.requestImage(
    for: asset,
    targetSize: targetSize,
    contentMode: .aspectFill,
    options: requestOptions
) { image, info in
    print("Immagine ottenuta: \(image?.size ?? .zero)")
}

Modificare la libreria multimediale: aggiungere preferiti

Le modifiche alla libreria multimediale vengono eseguite tramite PHPhotoLibrary.shared().performChanges all’interno di un blocco changeRequest. Tutte le operazioni vengono raggruppate e applicate in modo transazionale.

PHPhotoLibrary.shared().performChanges {
    let changeRequest = PHAssetChangeRequest(for: asset)
    changeRequest.isFavorite = .true
} completionHandler: { success, error in
    if success {
        print("Aggiunto ai preferiti")
    }
}

Modifiche e osservazione tramite Change Tracking

PhotoKit fornisce un meccanismo per osservare le modifiche alla libreria multimediale attraverso il protocollo PHPhotoLibraryChangeObserver. Quando si verificano modifiche (creazione, eliminazione, modifica), viene chiamato il metodo photoLibraryDidChange con un oggetto PHChange.

PHChange contiene changeDetails per ogni tipo di query: PHFetchResultChangeDetails con removedIndexes, insertedIndexes, changedIndexes. Ciò consente di applicare le modifiche all’interfaccia utente con animazione: performBatchUpdates con move, insert, delete per UICollectionView.

class PhotosViewController: UIViewController {
    var fetchResult: PHFetchResult>PHAsset>?

    override func viewDidLoad() {
        super.viewDidLoad()
        PHPhotoLibrary.shared().register(self)
    }

    deinit {
        PHPhotoLibrary.shared().unregisterChangeObserver(self)
    }
}

extension PhotosViewController: PHPhotoLibraryChangeObserver {
    func photoLibraryDidChange(_ changeInstance: PHChange) {
        guard let fetchResult,
              let details = changeInstance.changeDetails(for: fetchResult)
        else { return }

        DispatchQueue.main.async {
            self.fetchResult = details.fetchResultAfterChanges
            // Applica modifiche a collectionView
        }
    }
}

Modifica RAW ed estensioni

PhotoKit supporta la modifica dei media attraverso il meccanismo PHContentEditingInput e PHContentEditingOutput. L’app richiede editingInput con i dati originali, applica le modifiche e salva il risultato tramite editingOutput. Il framework conserva automaticamente l’originale, consentendo agli utenti di annullare le modifiche ripristinando l’originale.

Le foto RAW (DNG, CR2, NEF) sono supportate tramite PHAssetResourceManager, che fornisce accesso al file RAW originale. Per l’elaborazione RAW, si consiglia di utilizzare CoreImage con il filtro CIRAWFilter, che supporta la regolazione di temperatura, esposizione e nitidezza. PhotoKit supporta anche le estensioni dell’editor tramite Photo Editing Extension (iOS) — un’app può essere richiamata dall’editor di sistema per elaborare una foto o un video selezionato.

Ottimizzazione delle prestazioni di PhotoKit

PhotoKit è un framework potente ma dispendioso in termini di risorse. Un uso improprio può causare rallentamenti nello scorrimento e consumo eccessivo di memoria. Segui queste raccomandazioni per prestazioni ottimali.

• Usa PHCachingImageManager per le collezioni — il precaricamento delle immagini per le celle visibili +/-1 schermo elimina i rallentamenti dello scorrimento
• Imposta targetSize — non richiedere mai PHImageManagerMaximumSize per le miniature. Usa una dimensione uguale alla dimensione fisica della cella moltiplicata per la scala dello schermo
• Annulla le richieste al riutilizzo delle celle — salva PHImageRequestID e chiama cancelImageRequest in prepareForReuse
• Limita le richieste iCloud — durante lo scorrimento veloce, imposta isNetworkAccessAllowed = false e carica le foto iCloud solo quando ti fermi
• Cache PHFetchResult — fetchAssets ripetuti con le stesse opzioni restituiscono un nuovo PHFetchResult. Salva il risultato come proprietà e aggiornalo tramite Change Observer

PHLivePhoto richiede una richiesta separata tramite PHLivePhoto.request(with:targetSize:contentMode:options:resultHandler:). Non richiedere Live Photo per le celle che mostrano solo foto — usa PHLivePhotoBadge come indicatore.