Swiftpack.co - Package - backslash-f/simage

swift-version swift-package-manager platform build-status license

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

Github

link
Stars: 1

Dependencies

Used By

Total: 0

Releases

v2.0.1 - 2020-10-10 15:03:56

Reenable tests as https://github.com/apple/swift-package-manager/pull/2817 is merged (Xcode 12.0.1 beta 2). 🎉

v2.0.0 - 2020-08-04 09:34:01

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+

v1.4.0 - 2020-02-27 19:59:45

Adds a new SImageSettings:

  • rotationIgnoreMissingMetadata

What does it do?

Well, some images may not have rotation information in its metadata. When SImage.rotateImages(from:settings:completion:) encounters those type of images, it may throw (SImageError.cannotGetImageOrientation(from:)).

If you want to ignore missing rotation information and just proceed to the next image, set this property to true.

If you want to stop the rotation operation when there is no rotation information available, set it to false.

The default is true (missing rotation information is ignored).

Notice that when it's set to true, the image itself won't be skipped -- it will be included in the result image, but "untouched" (not rotated).

- 2020-02-26 22:46:42

Introduces a new API:

  • SImage.save(image:settings:completion:)

It saves the given CGImage in the temporary directory of the current user (FileManager.default.temporaryDirectory) as SImage.png. These default options can be overridden by passing in a custom SImageSettings instance.

- 2020-02-24 00:37:32

Introduces a new API:

  • SImage.createThumbnail(from:settings:completion:)

- 2020-02-21 14:02:50

It's now possible to combine an array of CGImage via:

SImage.combine(images:settings:completion:)

Notice that the image orientation won't be fixed by this API, as the rotation algorithm relies on the image metadata (which is not present in a CGImage object).

The Combinator - 2020-02-19 21:33:52

In this first release, SImage supports combining images while normalising their orientation to the ".up" position (AKA "0th row at top" / "0th column on left" / "default orientation" or "normal").

terminator