backslash-f / simage

Multiplatform Core Graphics wrapper 🖼

SImage 🖼

A wrapper around Core Graphics (CG) that provides functionalities such as combining images while adjusting their orientation or creating thumbnails of large images. See some examples below.

Because it relies on CG, it's already multi-platform. It supports iOS (+ iPadOS), macOS, Mac Catalyst, tvOS and watchOS. The results are returned as CGImage, which can be easily displayed (for example) in a NSImage (AppKit), UIImage (UIKit) or Image (SwiftUI).

Usage

Combine Images

Input

Suppose you would like to combine the following images:

(Notice the distinct orientations. Kudos to this repo.)

Code

let imageURLs = [URL] // Suppose this URL array points to the above images.

SImage().combineImages(from: imageURLs) { cgImage, error in
    if let resultImage = cgImage {
        // Do whatever with the result image.
    }
}

Output

(Notice that in this example the orientation is normalized to ".up".)

Create Thumbnails

let imageURL = URL(string: "My huge image URL")

simage.createThumbnail(from: imageURL) { cgImage in
    if let thumbnail = cgImage {
        // Do whatever with the thumbnail.
    }
}

To create thumbnails with a max pixel size:

let imageURL = URL(string: "My huge image URL")
let settings = SImageSettings(thumbsMaxPixelSize: "50")

simage.createThumbnail(from: imageURL, settings: settings) { cgImage in
    if let thumbnail = cgImage {
        // Do whatever with the 50px thumbnail.
    }
}

Optional Settings

To overwrite the default settings, it's possible to pass in a custom SImageSettings instance as argument to functions. For example:

SImage.combineImages(from:👉🏻settings:👈🏻completion:)

SImage.createThumbnail(from:👉🏻settings:👈🏻completion:)

SImage.rotateImages(from:👉🏻settings👈🏻:completion:)

Available APIs

API	Description
SImage.combine(images:settings:completion:)	Combines given images using given SImageSettings. Does not fix orientation. Returns: CGImage.
SImage.combineImages(from:settings:completion:)	Combines the images in the given array of URL using given SImageSettings. Fixes orientation (when possible). Returns: CGImage.
SImage.context(for:settings:)	Creates CGContext using given CGSize and SImageSettings. Returns: CGContext.
SImage.createImage(from:)	Creates a CGImage from given URL. Returns: CGImage.
SImage.createThumbnail(from:settings:completion:)	Creates a thumbnail from the image at the given URL. Returns: CGImage.
SImage.imageOrientation(from:)	Returns the orientation (CGImagePropertyOrientation) of an image from the given URL.
SImage.imageProperties(from:)	Returns all the available metadata of an image from the given URL as CGImageProperty (an [AnyHashable: Any] dictionary).
SImage.imageSize(from:)	Returns the CGSize of an image from the given URL.
SImage.rotateImages(from:settings:completion:)	Rotates images from the given URL array if their orientation do not match with the target orientation in the settings parameter. Returns an array of RotatedImages (a struct which contains the rotated CGImage and its new CGSize). Notice: some images may not have rotation information in its metadata. When SImage.rotateImages(in:settings:completion:) encounters those type of images, it may throw (SImageError.cannotGetImageOrientation(from:)). To ignore missing rotation information and just proceed to the next image, set rotationIgnoreMissingMetadata in the settings parameter to true (default value).
SImage.save(image:settings:completion:)	Saves the given CGImage as "SImage.png" in the temporary directory of the current user (FileManager.default.temporaryDirectory). The default options (filename, file type and destination URL) can be overridden by passing in a custom SImageSettings instance.

Logging

Starting with version 2.0.0, SImage can output its information into Xcode's Console or the macOS Console app.
This behavior can be enabled or disabled as such:

var simage = SImage()
simage.enableLogging()
simage.disableLogging()

In the macOS Console app, you can filter SImage output by SUBSYSTEM: com.backslash-f.SImage:

The logging is done via AppLogger, which supports the following versions:

• iOS 14+
• macOS 11+ (BigSur+)
• Mac Catalyst 14.0+
• tvOS 14+
• watchOS 7+
• Xcode 12.0+

Integration

Xcode

Use Xcode's built-in support for SPM (File / Swift Packages / Add Package Dependency).

Package.swift

In your Package.swift, add SImage as a dependency:

dependencies: [
  .package(url: "https://github.com/backslash-f/simage", from: "2.0.0")
],

Associate the dependency with your target:

targets: [
  .target(name: "App", dependencies: ["SImage"])
]

Run: swift build