Image.php

<?php

/**
 * Vips is a php binding for the vips image processing library
 *
 * PHP version 7
 *
 * LICENSE:
 *
 * Copyright (c) 2016 John Cupitt
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * @category  Images
 * @package   Jcupitt\Vips
 * @author    John Cupitt <jcupitt@gmail.com>
 * @copyright 2016 John Cupitt
 * @license   https://opensource.org/licenses/MIT MIT
 * @link      https://github.com/jcupitt/php-vips
 */

namespace Jcupitt\Vips;

/**
 * This class represents a Vips image object.
 *
 * This module provides a binding for the [vips image processing
 * library](https://jcupitt.github.io/libvips/).
 *
 * It needs libvips 8.0 or later to be installed, and it needs the binary
 * [`vips` extension](https://github.com/jcupitt/php-vips-ext) to be added to
 * your PHP.
 *
 * # Example
 *
 * ```php
 * <?php
 * use Jcupitt\Vips;
 * $im = Vips\Image::newFromFile($argv[1], ['access' => 'sequential']);
 * $im = $im->crop(100, 100, $im->width - 200, $im->height - 200);
 * $im = $im->reduce(1.0 / 0.9, 1.0 / 0.9, ['kernel' => 'linear']);
 * $mask = Vips\Image::newFromArray(
 *      [[-1,  -1, -1],
 *       [-1,  16, -1],
 *       [-1,  -1, -1]], 8);
 * $im = $im->conv($mask);
 * $im->writeToFile($argv[2]);
 * ?>
 * ```
 *
 * You'll need this in your `composer.json`:
 *
 * ```
 *     "require": {
 *         "jcupitt/vips" : "@dev"
 *     }
 * ```
 *
 * And run with:
 *
 * ```
 * $ composer install
 * $ ./try1.php ~/pics/k2.jpg x.tif
 * ```
 *
 * This example loads a file, crops 100 pixels from every edge, reduces by 10%
 * using a bilinear interpolator (the default is lanczos3),
 * sharpens the image, and saves it back to disc again.
 *
 * Reading this example line by line, we have:
 *
 * ```php
 * $im = Vips\Image::newFromFile($argv[1], ['access' => 'sequential']);
 * ```
 *
 * `Image::newFromFile` can load any image file supported by vips. Almost all
 * operations can be given an array of options as a final argument.
 *
 * In this
 * example, we will be accessing pixels top-to-bottom as we sweep through the
 * image reading and writing, so `sequential` access mode is best for us. The
 * default mode is `random`, this allows for full random access to image pixels,
 * but is slower and needs more memory.
 *
 * You can also load formatted images from
 * strings or create images from PHP arrays.
 *
 * The next line:
 *
 * ```php
 * $im = $im->crop(100, 100, $im->width - 200, $im->height - 200);
 * ```
 *
 * Crops 100 pixels from every edge. You can access any vips image property
 * directly as a PHP property. If the vips property name does not
 * conform to PHP naming conventions, you can use something like
 * `$image->get('ipct-data')`.
 *
 * Next we have:
 *
 * ```php
 * $mask = Vips\Image::newFromArray(
 *      [[-1,  -1, -1],
 *       [-1,  16, -1],
 *       [-1,  -1, -1]], 8);
 * $im = $im->conv($mask);
 * ```
 *
 * `Image::newFromArray` creates an image from an array constant. The 8 at
 * the end sets the scale: the amount to divide the image by after
 * integer convolution. See the libvips API docs for `vips_conv()` (the operation
 * invoked by `Image::conv`) for details on the convolution operator. See
 * **Getting more help** below.
 *
 * Finally:
 *
 * ```php
 * $im->writeToFile($argv[2]);
 * ```
 *
 * `Image::writeToFile` writes an image back to the filesystem. It can
 * write any format supported by vips: the file type is set from the filename
 * suffix. You can also write formatted images to strings.
 *
 * # Getting more help
 *
 * This binding lets you call the complete C API almost directly. You should
 * [consult the C docs](https://jcupitt.github.io/libvips/API/current)
 * for full details on the operations that are available and
 * the arguments they take. There's a handy [function
 * list](https://jcupitt.github.io/libvips/API/current/func-list.html)
 * which summarises the operations in the library. You can use the `vips`
 * command-line interface to get help as well, for example:
 *
 * ```
 * $ vips embed
 * embed an image in a larger image
 * usage:
 *    embed in out x y width height
 * where:
 *    in           - Input image, input VipsImage
 *    out          - Output image, output VipsImage
 *    x            - Left edge of input in output, input gint
 *                     default: 0
 *                     min: -1000000000, max: 1000000000
 *    y            - Top edge of input in output, input gint
 *                     default: 0
 *                     min: -1000000000, max: 1000000000
 *    width        - Image width in pixels, input gint
 *                     default: 1
 *                     min: 1, max: 1000000000
 *    height       - Image height in pixels, input gint
 *                     default: 1
 *                     min: 1, max: 1000000000
 * optional arguments:
 *    extend       - How to generate the extra pixels, input VipsExtend
 *                     default: black
 *                     allowed: black, copy, repeat, mirror, white, background
 *    background   - Colour for background pixels, input VipsArrayDouble
 * operation flags: sequential-unbuffered
 * ```
 *
 * You can call this from PHP as:
 *
 * ```php
 * $out = $in->embed($x, $y, $width, $height,
 *     ['extend' => 'copy', 'background' => [1, 2, 3]]);
 * ```
 *
 * `'background'` can also be a simple constant, such as `12`, see below.
 *
 * The `vipsheader` command-line program is an easy way to see all the
 * properties of an image. For example:
 *
 * ```
 * $ vipsheader -a ~/pics/k2.jpg
 * /home/john/pics/k2.jpg: 1450x2048 uchar, 3 bands, srgb, jpegload
 * width: 1450
 * height: 2048
 * bands: 3
 * format: 0 - uchar
 * coding: 0 - none
 * interpretation: 22 - srgb
 * xoffset: 0
 * yoffset: 0
 * xres: 2.834646
 * yres: 2.834646
 * filename: "/home/john/pics/k2.jpg"
 * vips-loader: jpegload
 * jpeg-multiscan: 0
 * ipct-data: VIPS_TYPE_BLOB, data = 0x20f0010, length = 332
 * ```
 *
 * You can access any of these fields as PHP properties of the `Image` class.
 * Use `$image->get('ipct-data')` for property names which are not valid under
 * PHP syntax.
 *
 * # How it works
 *
 * The binary
 * [`vips` extension](https://github.com/jcupitt/php-vips-ext) adds a few extra
 * functions to PHP to let you call anything in the libvips library. The API
 * it provides is simple, but horrible.
 *
 * This module is pure PHP and builds on the binary extension to provide a
 * convenient interface for programmers. It uses the PHP magic methods
 * `__call()`, `__callStatic()`, `__get()` and `__set()` to make vips operators
 * appear as methods on the `Image` class, and vips properties as PHP
 * properties.
 *
 * The API you end up with is a object-oriented version of the [VIPS C
 * API](https://jcupitt.github.io/libvips/API/current).
 * Full documentation
 * on the operations and what they do is there, you can use it directly. This
 * document explains the extra features of the PHP API and lists the available
 * operations very briefly.
 *
 * # Automatic wrapping
 *
 * This binding has a `__call()` method and uses
 * it to look up vips operations. For example, the libvips operation `embed`,
 * which appears in C as `vips_embed()`, appears in PHP as `Image::embed`.
 *
 * The operation's list of required arguments is searched and the first input
 * image is set to the value of `self`. Operations which do not take an input
 * image, such as `Image::black`, appear as static methods. The remainder of
 * the arguments you supply in the function call are used to set the other
 * required input arguments. If the final supplied argument is an array, it is
 * used to set any optional input arguments. The result is the required output
 * argument if there is only one result, or an array of values if the operation
 * produces several results.
 *
 * For example, `Image::min`, the vips operation that searches an image for
 * the minimum value, has a large number of optional arguments. You can use it to
 * find the minimum value like this:
 *
 * ```php
 * $min_value = $image->min();
 * ```
 *
 * You can ask it to return the position of the minimum with `x` and `y`.
 *
 * ```php
 * $result = $image->min(['x' => true, 'y' => true]);
 * $min_value = $result['out'];
 * $x_pos = $result['x'];
 * $y_pos = $result['y'];
 * ```
 *
 * Now `x_pos` and `y_pos` will have the coordinates of the minimum value.
 * There's actually a convenience function for this, `Image::minpos`, see
 * below.
 *
 * You can also ask for the top *n* minimum, for example:
 *
 * ```php
 * $result = $image->min(['size' => 10, 'x_array' => true, 'y_array' => true]);
 * $x_pos = $result['x_array'];
 * $y_pos = $result['y_array'];
 * ```
 *
 * Now `x_pos` and `y_pos` will be 10-element arrays.
 *
 * Because operations are member functions and return the result image, you can
 * chain them. For example, you can write:
 *
 * ```php
 * $result_image = $image->real()->cos();
 * ```
 *
 * to calculate the cosine of the real part of a complex image.
 *
 * libvips types are also automatically wrapped and unwrapped. The binding
 * looks at the type
 * of argument required by the operation and converts the value you supply,
 * when it can. For example, `Image::linear` takes a `VipsArrayDouble` as
 * an argument
 * for the set of constants to use for multiplication. You can supply this
 * value as an integer, a float, or some kind of compound object and it
 * will be converted for you. You can write:
 *
 * ```php
 * $result = $image->linear(1, 3);
 * $result = $image->linear(12.4, 13.9);
 * $result = $image->linear([1, 2, 3], [4, 5, 6]);
 * $result = $image->linear(1, [4, 5, 6]);
 * ```
 *
 * And so on. You can also use `Image::add()` and friends, see below.
 *
 * It does a couple of more ambitious conversions. It will automatically convert
 * to and from the various vips types, like `VipsBlob` and `VipsArrayImage`. For
 * example, you can read the ICC profile out of an image like this:
 *
 * ```php
 * $profile = $image->get('icc-profile-data');
 * ```
 *
 * and `$profile` will be a PHP string.
 *
 * If an operation takes several input images, you can use a constant for all but
 * one of them and the wrapper will expand the constant to an image for you. For
 * example, `Image::ifthenelse()` uses a condition image to pick pixels
 * between a then and an else image:
 *
 * ```php
 * $result = $condition->ifthenelse($then_image, $else_image);
 * ```
 *
 * You can use a constant instead of either the then or the else parts and it
 * will be expanded to an image for you. If you use a constant for both then and
 * else, it will be expanded to match the condition image. For example:
 *
 * ```php
 * $result = $condition->ifthenelse([0, 255, 0], [255, 0, 0]);
 * ```
 *
 * Will make an image where true pixels are green and false pixels are red.
 *
 * This is useful for `Image::bandjoin`, the thing to join two or more
 * images up bandwise. You can write:
 *
 * ```php
 * $rgba = $rgb->bandjoin(255);
 * ```
 *
 * to append a constant 255 band to an image, perhaps to add an alpha channel. Of
 * course you can also write:
 *
 * ```php
 * $result = $image->bandjoin($image2);
 * $result = $image->bandjoin([image2, image3]);
 * $result = Image::bandjoin([image1, image2, image3]);
 * $result = $image->bandjoin([image2, 255]);
 * ```
 *
 * and so on.
 *
 * # Array access
 *
 * Images can be treated as arrays of bands. You can write:
 *
 * ```php
 * $result = $image[1];
 * ```
 *
 * to get band 1 from an image (green, in an RGB image).
 *
 * You can assign to bands as well. You can write:
 *
 * ```php
 * $image[1] = $other_image;
 * ```
 *
 * And band 1 will be replaced by all the bands in `$other_image` using
 * `bandjoin`. Use no offset to mean append, use -1 to mean prepend:
 *
 * ```php
 * $image[] = $other_image; // append bands from other
 * $image[-1] = $other_image; // prepend bands from other
 * ```
 *
 * You can use number and array constants as well, for example:
 *
 * ```php
 * $image[] = 255; // append a constant 255
 * $image[1] = [1, 2, 3]; // swap band 1 for three constant bands
 * ```
 *
 * Finally, you can delete bands with `unset`:
 *
 * ```php
 * unset($image[1]); // remove band 1
 * ```
 *
 * # Exceptions
 *
 * The wrapper spots errors from vips operations and throws
 * `Vips\Exception`. You can catch it in the usual way.
 *
 * # Draw operations
 *
 * Paint operations like `Image::draw_circle` and `Image::draw_line`
 * modify their input image. This
 * makes them hard to use with the rest of libvips: you need to be very careful
 * about the order in which operations execute or you can get nasty crashes.
 *
 * The wrapper spots operations of this type and makes a private copy of the
 * image in memory before calling the operation. This stops crashes, but it does
 * make it inefficient. If you draw 100 lines on an image, for example, you'll
 * copy the image 100 times. The wrapper does make sure that memory is recycled
 * where possible, so you won't have 100 copies in memory.
 *
 * If you want to avoid the copies, you'll need to call drawing operations
 * yourself.
 *
 * # Thumbnailing
 *
 * The thumbnailing functionality is implemented by `Vips\Image::thumbnail` and
 * `Vips\Image::thumbnail_buffer` (which thumbnails an image held as a string).
 *
 * You could write:
 *
 * ```php
 * $filename = 'image.jpg';
 * $image = Vips\Image::thumbnail($filename, 200, ['height' => 200]);
 * $image->writeToFile('my-thumbnail.jpg');
 * ```
 *
 * # Resample
 *
 * There are three types of operation in this section.
 *
 * First, `->affine()` applies an affine transform to an image.
 * This is any sort of 2D transform which preserves straight lines;
 * so any combination of stretch, sheer, rotate and translate.
 * You supply an interpolator for it to use to generate pixels
 * (@see Image::newInterpolator()). It will not produce good results for
 * very large shrinks: you'll see aliasing.
 *
 * `->reduce()` is like `->affine()`, but it can only shrink images,
 * it can't enlarge, rotate, or skew.
 * It's very fast and uses an adaptive kernel (@see Kernel for possible values)
 * for interpolation. It will be slow for very large shrink factors.
 *
 * `->shrink()` is a fast block shrinker. It can quickly reduce images by large
 * integer factors. It will give poor results for small size reductions:
 * again, you'll see aliasing.
 *
 * Next, `->resize()` specialises in the common task of image reduce and enlarge.
 * It strings together combinations of `->shrink()`, `->reduce()`, `->affine()`
 * and others to implement a general, high-quality image resizer.
 *
 * Finally, `->mapim()` can apply arbitrary 2D image transforms to an image.
 *
 * # Expansions
 *
 * Some vips operators take an enum to select an action, for example
 * `Image::math` can be used to calculate sine of every pixel like this:
 *
 * ```php
 * $result = $image->math('sin');
 * ```
 *
 * This is annoying, so the wrapper expands all these enums into separate members
 * named after the enum. So you can write:
 *
 * ```php
 * $result = $image->sin();
 * ```
 *
 * # Convenience functions
 *
 * The wrapper defines a few extra useful utility functions:
 * `Image::get`, `Image::set`, `Image::bandsplit`,
 * `Image::maxpos`, `Image::minpos`,
 * `Image::median`. See below.
 *
 * # Logging
 *
 * Use `Config::setLogger` to enable logging in the usual manner. A
 * sample logger, handy for debugging, is defined in `Vips\DebugLogger`. You
 * can enable debug logging with:
 *
 * ```php
 * Vips\Config::setLogger(new Vips\DebugLogger);
 * ```
 *
 * # Configuration
 *
 * You can use the methods in `Vips\Config` to set various global properties of
 * the library. For example, you can control the size of the libvips cache,
 * or the size of the worker threadpools that libvips uses to evaluate images.
 *
 * @category  Images
 * @package   Jcupitt\Vips
 * @author    John Cupitt <jcupitt@gmail.com>
 * @copyright 2016 John Cupitt
 * @license   https://opensource.org/licenses/MIT MIT
 * @link      https://github.com/jcupitt/php-vips
 */
class Image extends ImageAutodoc implements \ArrayAccess
{
    /**
     * Map load nicknames to canonical names. Regenerate this table with
     * something like:
     *
     * $ vips -l foreign | grep -i load | awk '{ print $2, $1; }'
     *
     * Plus a bit of editing.
     *
     * @internal
     */
    private static $nicknameToCanonical = [
        'csvload' => 'VipsForeignLoadCsv',
        'matrixload' => 'VipsForeignLoadMatrix',
        'rawload' => 'VipsForeignLoadRaw',
        'vipsload' => 'VipsForeignLoadVips',
        'analyzeload' => 'VipsForeignLoadAnalyze',
        'ppmload' => 'VipsForeignLoadPpm',
        'radload' => 'VipsForeignLoadRad',
        'pdfload' => 'VipsForeignLoadPdfFile',
        'pdfload_buffer' => 'VipsForeignLoadPdfBuffer',
        'svgload' => 'VipsForeignLoadSvgFile',
        'svgload_buffer' => 'VipsForeignLoadSvgBuffer',
        'gifload' => 'VipsForeignLoadGifFile',
        'gifload_buffer' => 'VipsForeignLoadGifBuffer',
        'pngload' => 'VipsForeignLoadPng',
        'pngload_buffer' => 'VipsForeignLoadPngBuffer',
        'matload' => 'VipsForeignLoadMat',
        'jpegload' => 'VipsForeignLoadJpegFile',
        'jpegload_buffer' => 'VipsForeignLoadJpegBuffer',
        'webpload' => 'VipsForeignLoadWebpFile',
        'webpload_buffer' => 'VipsForeignLoadWebpBuffer',
        'tiffload' => 'VipsForeignLoadTiffFile',
        'tiffload_buffer' => 'VipsForeignLoadTiffBuffer',
        'magickload' => 'VipsForeignLoadMagickFile',
        'magickload_buffer' => 'VipsForeignLoadMagickBuffer',
        'fitsload' => 'VipsForeignLoadFits',
        'openexrload' => 'VipsForeignLoadOpenexr'
    ];

    /**
     * Combine takes an array of blend modes, passed to libvips as an array of
     * int. Because libvips does now know they should be enums, we have to do
     * the string->int conversion ourselves. We ought to introspect to find the
     * mapping, but until we have the machinery for that, we just hardwire the
     * mapping here.
     *
     * @internal
     */
    private static $blendModeToInt = [
        BlendMode::CLEAR => 0,
        BlendMode::SOURCE => 1,
        BlendMode::OVER => 2,
        BlendMode::IN => 3,
        BlendMode::OUT => 4,
        BlendMode::ATOP => 5,
        BlendMode::DEST => 6,
        BlendMode::DEST_OVER => 7,
        BlendMode::DEST_IN => 8,
        BlendMode::DEST_OUT => 9,
        BlendMode::DEST_ATOP => 10,
        BlendMode::XOR => 11,
        BlendMode::ADD => 12,
        BlendMode::SATURATE => 13,
        BlendMode::MULTIPLY => 14,
        BlendMode::SCREEN => 15,
        BlendMode::OVERLAY => 16,
        BlendMode::DARKEN => 17,
        BlendMode::LIGHTEN => 18,
        BlendMode::COLOUR_DODGE => 19,
        BlendMode::COLOUR_BURN => 20,
        BlendMode::HARD_LIGHT => 21,
        BlendMode::SOFT_LIGHT => 22,
        BlendMode::DIFFERENCE => 23,
        BlendMode::EXCLUSION => 24
    ];

    /**
     * The resource for the underlying VipsImage.
     *
     * @internal
     */
    private $image;

    /**
     * Wrap a Image around an underlying vips resource.
     *
     * Don't call this yourself, users should stick to (for example)
     * Image::newFromFile().
     *
     * @param resource $image The underlying vips image resource that this
     *      class should wrap.
     *
     * @internal
     */
    public function __construct($image)
    {
        $this->image = $image;
    }

    /**
     * Apply a func to every numeric member of $value. Useful for self::subtract
     * etc.
     *
     * @param mixed    $value The thing we walk.
     * @param \Closure $func  Apply this.
     *
     * @return mixed The updated $value.
     *
     * @internal
     */
    private static function mapNumeric($value, \Closure $func)
    {
        if (is_numeric($value)) {
            $value = $func($value);
        } else {
            if (is_array($value)) {
                array_walk_recursive($value, function (&$value) use ($func) {
                    $value = self::mapNumeric($value, $func);
                });
            }
        }

        return $value;
    }

    /**
     * Is a $value a rectangular 2D array?
     *
     * @param mixed $value Test this.
     *
     * @return bool true if this is a 2D array.
     *
     * @internal
     */
    private static function is2D($value): bool
    {
        if (!is_array($value)) {
            return false;
        }

        if (!is_array($value[0])) {
            return false;
        }
        $width = count($value[0]);

        foreach ($value as $row) {
            if (!is_array($row) || count($row) !== $width) {
                return false;
            }
        }

        return true;
    }

    /**
     * Is $value something that we should treat as an image?
     *
     * Instance of Image, or 2D arrays are images; 1D arrays or single values
     * are constants.
     *
     * @param mixed $value The value to test.
     *
     * @return bool true if this is like an image.
     *
     * @internal
     */
    private static function isImageish($value): bool
    {
        return self::is2D($value) || $value instanceof Image;
    }

    /**
     * Turn a constant (eg. 1, '12', [1, 2, 3], [[1]]) into an image using
     * match_image as a guide.
     *
     * @param Image $match_image Use this image as a guide.
     * @param mixed $value       Turn this into an image.
     *
     * @throws Exception
     *
     * @return Image The image we created.
     *
     * @internal
     */
    private static function imageize(Image $match_image, $value): Image
    {
        if (self::is2D($value)) {
            $result = self::newFromArray($value);
        } else {
            $result = $match_image->newFromImage($value);
        }

        return $result;
    }

    /**
     * Unwrap an array of stuff ready to pass down to the vips_ layer. We
     * swap instances of the Image for the plain resource.
     *
     * @param array $result Unwrap this.
     *
     * @return array $result unwrapped, ready for vips.
     *
     * @internal
     */
    private static function unwrap(array $result): array
    {
        array_walk_recursive($result, function (&$value) {
            if ($value instanceof Image) {
                $value = $value->image;
            }
        });

        return $result;
    }

    /**
     * Is $value a VipsImage.
     *
     * @param mixed $value The thing to test.
     *
     * @return bool true if this is a vips image resource.
     *
     * @internal
     */
    private static function isImage($value): bool
    {
        return is_resource($value) &&
            get_resource_type($value) === 'GObject';
    }

    /**
     * Wrap up the result of a vips_ call ready to return it to PHP. We do
     * two things:
     *
     * - If the array is a singleton, we strip it off. For example, many
     *   operations return a single result and there's no sense handling
     *   this as an array of values, so we transform ['out' => x] -> x.
     *
     * - Any VipsImage resources are rewrapped as instances of Image.
     *
     * @param mixed $result Wrap this up.
     *
     * @return mixed $result, but wrapped up as a php class.
     *
     * @internal
     */
    private static function wrapResult($result)
    {
        if (!is_array($result)) {
            $result = ['x' => $result];
        }

        array_walk_recursive($result, function (&$item) {
            if (self::isImage($item)) {
                $item = new self($item);
            }
        });

        if (count($result) === 1) {
            $result = array_shift($result);
        }

        return $result;
    }

    /**
     * Throw a vips error as an exception.
     *
     * @throws Exception
     *
     * @return void
     *
     * @internal
     */
    private static function errorVips()
    {
        $message = vips_error_buffer();
        $exception = new Exception($message);
        Utils::errorLog($message, $exception);
        throw $exception;
    }

    /**
     * Check the result of a vips_ call for an error, and throw an exception
     * if we see one.
     *
     * This won't work for things like __get where a non-array return can be
     * a valid return.
     *
     * @param mixed $result Test this.
     *
     * @throws Exception
     *
     * @return void
     *
     * @internal
     */
    private static function errorIsArray($result)
    {
        if (!is_array($result)) {
            self::errorVips();
        }
    }

    /**
     * Create a new Image from a file on disc.
     *
     * @param string $filename The file to open.
     * @param array  $options  Any options to pass on to the load operation.
     *
     * @throws Exception
     *
     * @return Image A new Image.
     */
    public static function newFromFile(
        string $filename,
        array $options = []
    ): Image {
        Utils::debugLog('newFromFile', [
            'instance' => null,
            'arguments' => [$filename, $options]
        ]);

        $options = self::unwrap($options);
        $result = vips_image_new_from_file($filename, $options);
        self::errorIsArray($result);
        $result = self::wrapResult($result);

        Utils::debugLog('newFromFile', ['result' => $result]);

        return $result;
    }

    /**
     * Find the name of the load operation vips will use to load a file, for
     * example "VipsForeignLoadJpegFile". You can use this to work out what
     * options to pass to newFromFile().
     *
     * @param string $filename The file to test.
     *
     * @return string|null The name of the load operation, or null.
     */
    public static function findLoad(string $filename)
    {
        Utils::debugLog('findLoad', [
            'instance' => null,
            'arguments' => [$filename]
        ]);

        // added in 1.0.5 of the binary module
        if (function_exists('vips_foreign_find_load')) {
            $result = vips_foreign_find_load($filename);
        } else {
            $result = null;

            // fallback: use the vips-loader property ... this can be much slower
            try {
                $image = self::newFromFile($filename);
                // Unfortunately, vips-loader is the operation nickname, rather
                // than the canonical name returned by vips_foreign_find_load().
                $loader = $image->get('vips-loader');
                $result = self::$nicknameToCanonical[$loader];
            } catch (Exception $ignored) {
            }
        }

        Utils::debugLog('findLoad', ['result' => [$result]]);

        return $result;
    }

    /**
     * Create a new Image from a compressed image held as a string.
     *
     * @param string $buffer        The formatted image to open.
     * @param string $option_string Any text-style options to pass to the
     *     selected loader.
     * @param array  $options       Any options to pass on to the load operation.
     *
     * @throws Exception
     *
     * @return Image A new Image.
     */
    public static function newFromBuffer(
        string $buffer,
        string $option_string = '',
        array $options = []
    ): Image {
        Utils::debugLog('newFromBuffer', [
            'instance' => null,
            'arguments' => [$buffer, $option_string, $options]
        ]);

        $options = self::unwrap($options);
        $result = vips_image_new_from_buffer($buffer, $option_string, $options);
        self::errorIsArray($result);
        $result = self::wrapResult($result);

        Utils::debugLog('newFromBuffer', ['result' => $result]);

        return $result;
    }

    /**
     * Find the name of the load operation vips will use to load a buffer, for
     * example 'VipsForeignLoadJpegBuffer'. You can use this to work out what
     * options to pass to newFromBuffer().
     *
     * @param string $buffer The formatted image to test.
     *
     * @return string|null The name of the load operation, or null.
     */
    public static function findLoadBuffer(string $buffer)
    {
        Utils::debugLog('findLoadBuffer', [
            'instance' => null,
            'arguments' => [$buffer]
        ]);

        // added in 1.0.5 of the binary module
        if (function_exists('vips_foreign_find_load_buffer')) {
            $result = vips_foreign_find_load_buffer($buffer);
        } else {
            $result = null;

            // fallback: use the vips-loader property ... this can be much slower
            try {
                $image = self::newFromBuffer($buffer);
                // Unfortunately, vips-loader is the operation nickname, rather
                // than the canonical name returned by
                // vips_foreign_find_load_buffer().
                $loader = $image->get('vips-loader');
                $result = self::$nicknameToCanonical[$loader];
            } catch (Exception $ignored) {
            }
        }

        Utils::debugLog('findLoadBuffer', ['result' => [$result]]);

        return $result;
    }

    /**
     * Create a new Image from a php array.
     *
     * 2D arrays become 2D images. 1D arrays become 2D images with height 1.
     *
     * @param array $array  The array to make the image from.
     * @param float $scale  The "scale" metadata item. Useful for integer
     *     convolution masks.
     * @param float $offset The "offset" metadata item. Useful for integer
     *     convolution masks.
     *
     * @throws Exception
     *
     * @return Image A new Image.
     */
    public static function newFromArray(
        array $array,
        float $scale = 1.0,
        float $offset = 0.0
    ): Image {
        Utils::debugLog('newFromArray', [
            'instance' => null,
            'arguments' => [$array, $scale, $offset]
        ]);

        $result = vips_image_new_from_array($array, $scale, $offset);
        if ($result === -1) {
            self::errorVips();
        }
        $result = self::wrapResult($result);

        Utils::debugLog('newFromArray', ['result' => $result]);

        return $result;
    }

    /**
     * Wraps an Image around an area of memory containing a C-style array.
     *
     * @param string $data   C-style array.
     * @param int    $width  Image width in pixels.
     * @param int    $height Image height in pixels.
     * @param int    $bands  Number of bands.
     * @param string $format Band format. (@see BandFormat)
     *
     * @throws Exception
     *
     * @return Image A new Image.
     */
    public static function newFromMemory(
        string $data,
        int $width,
        int $height,
        int $bands,
        string $format
    ): Image {
        Utils::debugLog('newFromMemory', [