1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license     https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore\Ext\Tools\Images;

interface IImage {

    /**
     * MvcCore - version:
     * Comparison by PHP function `version_compare();`.
     * @see http://php.net/manual/en/function.version-compare.php
     */
    const VERSION = '5.0.0';

    /**
     * Base temporary image name in temporary directory.
     */
    const TMP_IMAGE_BASE_NAME = 'MvcCore_Ext_Tools_Images_TMP';

    /**
     * Returns every time new (no singleton) `\MvcCore\Ext\Tools\Image` instance implementation.
     * If there is `Imagick` extension loaded and no `$preferredAdapter` presented,
     * `Imagick` instance is always created more preferably than `GD` instance.
     * If there is no `Imagick` and no `GD` extension loaded, new `\RuntimeException` exception is thrown.
     * @param  int|\MvcCore\Ext\Tools\Images\IAdapter $preferredAdapter optional
     * @throws \RuntimeException
     * @return \MvcCore\Ext\Tools\Image
     */
    public static function CreateInstance ($preferredAdapter = \MvcCore\Ext\Tools\Images\IAdapter::NONE);

    /**
     * Get full directory path for temporary images computation.
     * If no temporary path configured, there is used default
     * system temporary directory from `\MvcCore\Tool::GetSystemTmpDir();`.
     * @return string
     */
    public static function GetTmpDirPath ();

    /**
     * Set custom full directory path for computation temporary images.
     * @param string $fullPath
     */
    public static function SetTmpDirPath ($fullPath);

    /**
     * @param string $hexColor Color in hexadecimal format with or without leading hash.
     * @return array [$r, $g, $b, 'type' => 'RGB'];
     */
    public static function HexColor2RgbArrayColor ($hexColor);

    /**
     * Get image pixel width.
     * @return int
     */
    public function GetWidth ();

    /**
     * Get image pixel height.
     * @return int
     */
    public function GetHeight ();

    /**
     * Scale source image by width with maintaining the aspect ratio.
     * @param int $width Pixel width.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function ResizeByWidth ($width);

    /**
     * Scale source image by height with maintaining the aspect ratio.
     * @param int $height Pixel height.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function ResizeByHeight ($height);

    /**
     * Scale source image by total final count of pixels in the resized image.
     * Useful for list of logotypes, where is necessary to scale all logotypes into
     * the same visual space - with approximately the same importance by filled space,
     * so not resized by height or not by width, logotypes have always different proportions.
     * @param int $resizedImgTotalPixelsCount Pixels count, computed by target width × height,
     *                                        so if you want all images with approximately the same
     *                                        size around 100 × 100 pixels, value will be 100 × 100 = 10000.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function ResizeByPixelsCount ($resizedImgTotalPixelsCount);

    /**
     * Image will be resized into sizes not larger than `$width`
     * or `$height` params with maintaining the aspect ratio.
     * @param int $width Pixel width.
     * @param int $height Pixel height.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Contain ($width, $height);

    /**
     * Image will be resized into given `$width` and `$height` to cover whole place,
     * with optional orientation of source image to cover final place.
     * Possible orientation values are integers with this meaning:
     * - `1` - top left
     * - `2` - top center
     * - `3` - top right
     * - `4` - middle left
     * - `5` - middle center
     * - `6` - middle right
     * - `7` - bottom left
     * - `8` - bottom center
     * - `9` - bottom right
     * @param int $width Pixel width.
     * @param int $height Pixel height.
     * @param int|\MvcCore\Ext\Tools\Images\IOrientation $orientation Possible orientation values are integers by `\MvcCore\Ext\Tools\Images\IOrientation` interface constants.
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Cover ($width, $height, $orientation = \MvcCore\Ext\Tools\Images\IOrientation::MIDDLE_CENTER);

    /**
     * Crop image by percentage value from left, top, right and bottom.
     * @param int $xPercentage Percentage value to crop from left.
     * @param int $yPercentage Percentage value to crop from top.
     * @param int $widthPercentage Percentage value to crop from right.
     * @param int $heightPercentage Percentage value to crop from bottom.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function CropPercent ($xPercentage, $yPercentage, $widthPercentage, $heightPercentage);

    /**
     * Load image into resource by given file full path.
     * @abstract
     * @param string $imgFullPath
     * @throws \RuntimeException
     * @return bool|\MvcCore\Ext\Tools\Image
     */
    public function Load ($imgFullPath);

    /**
     * Save image in desired full path by format and optional quality settings.
     * @abstract
     * @param string $fullPath
     * @param string|\MvcCore\Ext\Tools\Images\IFormat $format `png` by default.
     * @param int $quality `NULL` by default - no quality settings will be used.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Save ($fullPath, $format = \MvcCore\Ext\Tools\Images\IFormat::PNG, $quality = NULL);

    /**
     * Resize image to desired with and height without maintaining the aspect ratio.
     * @abstract
     * @param int $width Pixel width.
     * @param int $height Pixel height.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Resize ($width, $height);

    /**
     * Crop image from left, top right or bottom side.
     * @abstract
     * @param int $x Pixel size to crop from left.
     * @param int $y Pixel size to crop from top.
     * @param int $width Pixel size to crop from right.
     * @param int $height Pixel size to crop from bottom.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Crop ($x, $y, $width, $height);

    /**
     * Image will be resized into sizes not larger than `$width`
     * or `$height` params with maintaining the aspect ratio and
     * places without image content will be filled with transparent
     * background color.
     * @abstract
     * @param int $width Pixel width.
     * @param int $height Pixel height.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Frame ($width, $height);

    /**
     * Set background color for prepared image.
     * @abstract
     * @param string $hexColor Color in hexadecimal format with or without leading hash.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function SetBackgroundColor ($hexColor);

    /**
     * Apply to whole image Photoshop like Unsharp Mask filter to sharp image.
     * This method is very time consuming for `GD` image implementation!
     * @abstract
     * @param int   $amount    Typically: 50 - 200, min. 0, max. 500.
     * @param float $radius    Typically: 0.5 - 1, min. 0, max. 50.
     * @param int   $threshold Typically: 0 - 5, min. 0, max. 255.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function UnsharpMask ($amount, $radius, $threshold);

    /**
     * Apply to whole image Photoshop like Channel Mask.
     * Image given as first argument will be used as grayscale
     * channel mask applied to this image instance.
     * This method is very time consuming for `GD` image implementation!
     * @abstract
     * @param string $maskImgFullPath
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Tools\Image
     */
    public function ApplyMask ($maskImgFullPath);

    /**
     * Convert whole image to grayscale.
     * @abstract
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Grayscale ();

    /**
     * Applies a special effect to the image, similar to the effect achieved
     * in a photo darkroom by sepia toning. Threshold ranges from 0 to QuantumRange
     * and is a measure of the extent of the sepia toning. A threshold of 80 is
     * a good starting point for a reasonable tone.
     * @abstract
     * @param float $threshold
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Sepia ($threshold = 80);

    /**
     * Round image corners with the same x-round and y-round sizes.
     * This method is very time consuming for `GD` image implementation!
     * @abstract
     * @param float $x X-rounding.
     * @param float $y Y-rounding.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function RoundCorners ($x, $y);

    /**
     * Rotate image with optional background color, transparent by default.
     * @abstract
     * @param float $angle
     * @param string $hexBgColor Color in hexadecimal format with or without leading hash. Transparent by default.
     * @return \MvcCore\Ext\Tools\Image
     */
    public function Rotate ($angle, $hexBgColor = 'transparent');

    /**
     * Set background image. If background image has different sizes,
     * it's resized without maintaining the aspect ratio to the same
     * sizes as current image instance.
     * @abstract
     * @param string $bgImgFullPath
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Tools\Image
     */
    public function SetBackgroundImage ($image);

    /**
     * Return `TRUE` if image is vector graphic. `FALSE` otherwise.
     * Return always `FALSE` for `GD` images, `GD` library cannot work with vector graphics.
     * @abstract
     * @return bool
     */
    public function IsVectorGraphic ();

    /**
     * Composite one image onto another at the specified offset.
     * @see http://php.net/manual/en/imagick.compositeimage.php
     * @see http://php.net/manual/en/imagick.constants.php#imagick.constants.composite-default
     * @abstract
     * @param string $overlayImgFullPath
     * @param int $x
     * @param int $y
     * @param int $alpha
     * @param int|\MvcCore\Ext\Tools\Images\IComposite $composite
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Tools\Image
     */
    public function AddOverlay (
        $overlayImgFullPath, $x = 0, $y = 0, $alpha = NULL,
        $composite = \MvcCore\Ext\Tools\Images\IComposite::NORMAL
    );

    /**
     * Create new empty image instance.
     * @param int $width Pixel width.
     * @param int $height Pixel height.
     * @param string $hexBgColor Color in hexadecimal format with or without leading hash.
     * @return resource
     */
    public function CreateEmptyImageResource ($width, $height, $hexBgColor = 'transparent');
}