session-ios/SignalUtilitiesKit/Media Viewing & Editing/Image Editing/ImageEditorTransform.swift

//
//  Copyright (c) 2019 Open Whisper Systems. All rights reserved.
//

import UIKit

// The image editor uses multiple coordinate systems.
//
// * Image unit coordinates.  Brush stroke and text content should be pegged to
//   image content, so they are specified relative to the bounds of the image.
// * Canvas coordinates.  We render the image, strokes and text into the "canvas",
//   a viewport that has the aspect ratio of the view.  Rendering is transformed, so
//   this is pre-tranform.
// * View coordinates.  The coordinates of the actual view (or rendered output).
//   Bounded by the view's bounds / viewport.
//
// Sometimes we use unit coordinates.  This facilitates a number of operations such
// as clamping to 0-1, etc.  So in practice almost all values will be in one of six
// coordinate systems:
//
// * unit image coordinates
// * image coordinates
// * unit canvas coordinates
// * canvas coordinates
// * unit view coordinates
// * view coordinates
//
// For simplicity, the canvas bounds are always identical to view bounds.
// If we wanted to manipulate output quality, we would use the layer's "scale".
// But canvas values are pre-transform and view values are post-transform so they
// are only identical if the transform has no scaling, rotation or translation.
//
// The "ImageEditorTransform" can be used to generate an CGAffineTransform
// for the layers used to render the content.  In practice, the affine transform
// is applied to a superlayer of the sublayers used to render content.
//
// CALayers apply their transform relative to the layer's anchorPoint, which
// by default is the center of the layer's bounds.  E.g. rotation occurs
// around the center of the layer.  Therefore when projecting absolute
// (but not relative) coordinates between the "view" and "canvas" coordinate
// systems, it's necessary to project them relative to the center of the
// view/canvas.
//
// To simplify our representation & operations, the default size of the image
// content is "exactly large enough to fill the canvas if rotation
// but not scaling or translation were applied".  This might seem unusual,
// but we have a key invariant: we always want the image to fill the canvas.
// It's far easier to ensure this if the transform is always (just barely)
// valid when scaling = 1 and translation = .zero.  The image size that
// fulfills this criteria is calculated using
// ImageEditorCanvasView.imageFrame(forViewSize:...).  Transforming between
// the "image" and "canvas" coordinate systems is done with that image frame.
@objc
public class ImageEditorTransform: NSObject {
    // The outputSizePixels is used to specify the aspect ratio and size of the
    // output.
    public let outputSizePixels: CGSize
    // The unit translation of the content, relative to the
    // canvas viewport.
    public let unitTranslation: CGPoint
    // Rotation about the center of the content.
    public let rotationRadians: CGFloat
    // x >= 1.0.
    public let scaling: CGFloat
    // Flipping is horizontal.
    public let isFlipped: Bool

    public init(outputSizePixels: CGSize,
                unitTranslation: CGPoint,
                rotationRadians: CGFloat,
                scaling: CGFloat,
                isFlipped: Bool) {
        self.outputSizePixels = outputSizePixels
        self.unitTranslation = unitTranslation
        self.rotationRadians = rotationRadians
        self.scaling = scaling
        self.isFlipped = isFlipped
    }

    public class func defaultTransform(srcImageSizePixels: CGSize) -> ImageEditorTransform {
        // It shouldn't be necessary normalize the default transform, but we do so to be safe.
        return ImageEditorTransform(outputSizePixels: srcImageSizePixels,
                                    unitTranslation: .zero,
                                    rotationRadians: 0.0,
                                    scaling: 1.0,
                                    isFlipped: false).normalize(srcImageSizePixels: srcImageSizePixels)
    }

    public var isNonDefault: Bool {
        return !isEqual(ImageEditorTransform.defaultTransform(srcImageSizePixels: outputSizePixels))
    }

    public func affineTransform(viewSize: CGSize) -> CGAffineTransform {
        let translation = unitTranslation.fromUnitCoordinates(viewSize: viewSize)
        // Order matters.  We need want SRT (scale-rotate-translate) ordering so that the translation
        // is not affected affected by the scaling or rotation, which shoud both be about the "origin"
        // (in this case the center of the content).
        //
        // NOTE: CGAffineTransform transforms are composed in reverse order.
        let transform = CGAffineTransform.identity.translate(translation).rotated(by: rotationRadians).scaledBy(x: scaling, y: scaling)
        return transform
    }

    // This method normalizes a "proposed" transform (self) into
    // one that is guaranteed to be valid.
    public func normalize(srcImageSizePixels: CGSize) -> ImageEditorTransform {
        // Normalize scaling.
        // The "src/background" image is rendered at a size that will fill
        // the canvas bounds if scaling = 1.0 and translation = .zero.
        // Therefore, any scaling >= 1.0 is valid.
        let minScaling: CGFloat = 1.0
        let scaling = max(minScaling, self.scaling)

        // We don't need to normalize rotation.

        // Normalize translation.
        //
        // This is decidedly non-trivial because of the way that
        // scaling, rotation and translation combine.  We need to
        // guarantee that the image _always_ fills the canvas
        // bounds.  So want to clamp the translation such that the
        // image can be moved _exactly_ to the edge of the canvas
        // and no further in a way that reflects the current
        // crop, scaling and rotation.
        //
        // We need to clamp the translation to the valid "translation
        // region" which is a rectangle centered on the origin.
        // However, this rectangle is axis-aligned in canvas
        // coordinates, not view coordinates.  e.g. if you have
        // a long image and a square output size, you could "slide"
        // the crop region along the image's contents.  That
        // movement would appear diagonal to the user in the view
        // but would be vertical on the canvas.

        // Normalize translation, Step 1:
        //
        // We project the viewport onto the canvas to determine
        // its bounding box.
        let viewBounds = CGRect(origin: .zero, size: self.outputSizePixels)
        // This "naive" transform represents the proposed transform
        // with no translation.
        let naiveTransform = ImageEditorTransform(outputSizePixels: outputSizePixels,
                                                  unitTranslation: .zero,
                                                  rotationRadians: rotationRadians,
                                                  scaling: scaling,
                                                  isFlipped: self.isFlipped)
        let naiveAffineTransform = naiveTransform.affineTransform(viewSize: viewBounds.size)
        var naiveViewportMinCanvas = CGPoint.zero
        var naiveViewportMaxCanvas = CGPoint.zero
        var isFirstCorner = true
        // Find the "naive" bounding box of the viewport on the canvas
        // by projecting its corners from view coordinates to canvas
        // coordinates.
        //
        // Due to symmetry, it should be sufficient to project 2 corners
        // but we do all four corners for safety.
        for viewCorner in [
            viewBounds.topLeft,
            viewBounds.topRight,
            viewBounds.bottomLeft,
            viewBounds.bottomRight
            ] {
                let naiveViewCornerInCanvas = viewCorner.minus(viewBounds.center).applyingInverse(naiveAffineTransform).plus(viewBounds.center)
                if isFirstCorner {
                    naiveViewportMinCanvas = naiveViewCornerInCanvas
                    naiveViewportMaxCanvas = naiveViewCornerInCanvas
                    isFirstCorner = false
                } else {
                    naiveViewportMinCanvas = naiveViewportMinCanvas.min(naiveViewCornerInCanvas)
                    naiveViewportMaxCanvas = naiveViewportMaxCanvas.max(naiveViewCornerInCanvas)
                }
        }
        let naiveViewportSizeCanvas: CGPoint = naiveViewportMaxCanvas.minus(naiveViewportMinCanvas)

        // Normalize translation, Step 2:
        //
        // Now determine the "naive" image frame on the canvas.
        let naiveImageFrameCanvas = ImageEditorCanvasView.imageFrame(forViewSize: viewBounds.size, imageSize: srcImageSizePixels, transform: naiveTransform)
        let naiveImageSizeCanvas = CGPoint(x: naiveImageFrameCanvas.width, y: naiveImageFrameCanvas.height)

        // Normalize translation, Step 3:
        //
        // The min/max translation can now by computed by diffing
        // the size of the bounding box of the naive viewport and
        // the size of the image on canvas.
        let maxTranslationCanvas = naiveImageSizeCanvas.minus(naiveViewportSizeCanvas).times(0.5).max(.zero)

        // Normalize translation, Step 4:
        //
        // Clamp the proposed translation to the "max translation"
        // from the last step.
        //
        // This is subtle.  We want to clamp in canvas coordinates
        // since the min/max translation is specified by a bounding
        // box in "unit canvas" coordinates.  However, because the
        // translation is applied in SRT order (scale-rotate-transform),
        // it effectively operates in view coordinates since it is
        // applied last.  So we project it from view coordinates
        // to canvas coordinates, clamp it, then project it back
        // into unit view coordinates using the "naive" (no translation)
        // transform.
        let translationInView = self.unitTranslation.fromUnitCoordinates(viewBounds: viewBounds)
        let translationInCanvas = translationInView.applyingInverse(naiveAffineTransform)
        // Clamp the translation to +/- maxTranslationCanvasUnit.
        let clampedTranslationInCanvas = translationInCanvas.min(maxTranslationCanvas).max(maxTranslationCanvas.inverse())
        let clampedTranslationInView = clampedTranslationInCanvas.applying(naiveAffineTransform)
        let unitTranslation = clampedTranslationInView.toUnitCoordinates(viewBounds: viewBounds, shouldClamp: false)

        return ImageEditorTransform(outputSizePixels: outputSizePixels,
                                    unitTranslation: unitTranslation,
                                    rotationRadians: rotationRadians,
                                    scaling: scaling,
                                    isFlipped: self.isFlipped)
    }

    public override func isEqual(_ object: Any?) -> Bool {
        guard let other = object as? ImageEditorTransform  else {
            return false
        }
        return (outputSizePixels == other.outputSizePixels &&
            unitTranslation == other.unitTranslation &&
            rotationRadians == other.rotationRadians &&
            scaling == other.scaling &&
            isFlipped == other.isFlipped)
    }

    public override var hash: Int {
        return (outputSizePixels.width.hashValue ^
            outputSizePixels.height.hashValue ^
            unitTranslation.x.hashValue ^
            unitTranslation.y.hashValue ^
            rotationRadians.hashValue ^
            scaling.hashValue ^
            isFlipped.hashValue)
    }

    open override var description: String {
        return "[outputSizePixels: \(outputSizePixels), unitTranslation: \(unitTranslation), rotationRadians: \(rotationRadians), scaling: \(scaling), isFlipped: \(isFlipped)]"
    }
}