graphicsmagick.module

g<?php
/**
 * @file
 * Hooks implementations for the GraphicsMagick module.
 */

use graphicsmagick\Utility\Color;

 /**
 * Implements hook_autoload_info().
 */
function graphicsmagick_autoload_info(): array {
  return array(
    'graphicsmagick\Utility\Color' => 'includes/color.class.inc',
  );
}

/**
 * Implements hook_image_effect_info().
 */
function graphicsmagick_image_effect_info(): array {
  $effects = array();

  $effects['graphicsmagick_effects_blur'] = array(
    'label' => t('Blur'),
    'help' => t('This effect will make the image details less distinct using a Gaussian operator.'),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_blur_form',
    'effect callback' => 'graphicsmagick_effects_blur',
    'summary theme' => 'graphicsmagick_effects_blur_summary',
  );

  $effects['graphicsmagick_effects_despeckle'] = array(
    'label' => t('Despeckle'),
    'help' => t('This effect will reduce the speckle noise in an image while preserving the original image edges.'),
    'dimensions passthrough' => TRUE,
    'effect callback' => 'graphicsmagick_effects_despeckle',
  );

  $effects['graphicsmagick_effects_edge'] = array(
    'label' => t('Edge enhance'),
    'help' => t('This effect will enhance edges within the image with a convolution filter.'),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_edge_form',
    'effect callback' => 'graphicsmagick_effects_edge',
    'summary theme' => 'graphicsmagick_effects_oil_paint_summary',
  );

  $effects['graphicsmagick_effects_emboss'] = array(
    'label' => t('Emboss'),
    'help' => t('This effect will convolve the image using a Gaussian operator, giving the image a three-dimensional effect.'),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_emboss_form',
    'effect callback' => 'graphicsmagick_effects_emboss',
    'summary theme' => 'graphicsmagick_effects_blur_summary',
  );

  $effects['graphicsmagick_effects_enhance'] = array(
    'label' => t('Enhance'),
    'help' => t('This effect will improve the quality of a noisy image.'),
    'dimensions passthrough' => TRUE,
    'effect callback' => 'graphicsmagick_effects_enhance',
  );

  $effects['graphicsmagick_effects_equalize'] = array(
    'label' => t('Equalize'),
    'help' => t('This effect will equalize the image histogram.'),
    'dimensions passthrough' => TRUE,
    'effect callback' => 'graphicsmagick_effects_equalize',
  );

  $effects['graphicsmagick_effects_flip'] = array(
    'label' => t('Vertical mirror'),
    'help' => t('This effect will create a vertical mirror image.'),
    'dimensions passthrough' => TRUE,
    'effect callback' => 'graphicsmagick_effects_flip',
  );

  $effects['graphicsmagick_effects_flop'] = array(
    'help' => t('This effect will create a horizontal mirror image.'),
    'dimensions passthrough' => TRUE,
    'effect callback' => 'graphicsmagick_effects_flop',
  );

  $effects['graphicsmagick_effects_gamma'] = array(
    'label' => t('Gamma'),
    'help' => t("This effect will change the gamma values."),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_gamma_form',
    'effect callback' => 'graphicsmagick_effects_gamma',
    'summary theme' => 'graphicsmagick_effects_gamma_summary',
  );

  $effects['graphicsmagick_effects_noise'] = array(
    'label' => t('Add noise'),
    'help' => t("This effect will add random noise to the image."),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_noise_form',
    'effect callback' => 'graphicsmagick_effects_noise',
    'summary theme' => 'graphicsmagick_effects_noise_summary',
  );

  $effects['graphicsmagick_effects_oil_paint'] = array(
    'label' => t('Oil paint'),
    'help' => t('This effect will simulate an oil painting.'),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_oil_paint_form',
    'effect callback' => 'graphicsmagick_effects_oil_paint',
    'summary theme' => 'graphicsmagick_effects_oil_paint_summary',
  );

  $effects['graphicsmagick_effects_solarize'] = array(
    'label' => t('Solarize'),
    'help' => t('Solarize will apply an effect to the image, similar to the one achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light.'),
    'dimensions passthrough' => TRUE,
    'form callback' => 'graphicsmagick_effects_solarize_form',
    'effect callback' => 'graphicsmagick_effects_solarize',
    'summary theme' => 'graphicsmagick_effects_solarize_summary',
  );

  $effects['graphicsmagick_effects_spread'] = array(
    'label' => t('Spread'),
    'help' => t('This effect will randomly displace each pixel in a block defined by the radius.'),
    'form callback' => 'graphicsmagick_effects_spread_form',
    'effect callback' => 'graphicsmagick_effects_spread',
    'summary theme' => 'graphicsmagick_effects_oil_paint_summary',
  );

  $effects['graphicsmagick_effects_swirl'] = array(
    'label' => t('Swirl'),
    'help' => t('This effect will swirl the pixels about the center of the image.'),
    'form callback' => 'graphicsmagick_effects_swirl_form',
    'effect callback' => 'graphicsmagick_effects_swirl',
    'summary theme' => 'graphicsmagick_effects_swirl_summary',
  );

  return $effects;
}

 /**
 * Implements hook_image_toolkits().
 */
function graphicsmagick_image_toolkits(): array {
  return array(
    'graphicsmagick_toolkit' => array(
      'title' => t('GraphicsMagick toolkit'),
      'available' => graphicsmagick_available(),
    ),
  );
}

/**
 * Implements hook_theme().
 */
function graphicsmagick_theme(): array {
  $summary_base = array(
    'variables' => array( 'data' => NULL),
    'file' => 'includes/graphicsmagick.theme.inc',
  );

  return array(
    'graphicsmagick_effects_blur_summary' => $summary_base,
    'graphicsmagick_effects_edge_summary' => $summary_base,
    'graphicsmagick_effects_emboss_summary' => $summary_base,
    'graphicsmagick_effects_gamma_summary' => $summary_base,
    'graphicsmagick_effects_noise_summary' => $summary_base,
    'graphicsmagick_effects_oil_paint_summary' => $summary_base,
    'graphicsmagick_effects_solarize_summary' => $summary_base,
    'graphicsmagick_effects_spread_summary' => $summary_base,
    'graphicsmagick_effects_swirl_summary' => $summary_base,
  );
}

/**
 * Retrieves settings for the GraphicsMagick toolkit.
 *
 * @return array
 *   The form array.
 */
function image_graphicsmagick_toolkit_settings(): array {
  $form['graphicsmagick_toolkit_jpeg_quality'] = array(
    '#type' => 'number',
    '#title' => t('JPEG quality'),
    '#description' => t('The image quality for JPEG images (from 0 to 100). Higher values mean better image quality but bigger files.'),
    '#default_value' => graphicsmagick_toolkit_get_jpeg_quality(),
    '#min' => 0,
    '#max' => 100,
    '#step' => 1,
  );

  $form['graphicsmagick_toolkit_png_compression'] = array(
    '#type' => 'number',
    '#title' => t('PNG compression'),
    '#description' => t('The PNG compression (from 0 to 99). Higher values do not mean better compression, although 99 usually compresses a PNG image more than other values. Verify the file size once the image has been saved.'),
    '#default_value' => graphicsmagick_toolkit_get_png_compression(),
    '#min' => 0,
    '#max' => 100,
    '#step' => 1,
  );

  return $form;
}

/**
 * Retrieves the supported extensions for the GraphicsMagick toolkit.
 *
 * @return array
 *   The supported extensions.
 */
function image_graphicsmagick_toolkit_supported_extensions(): array {
  // The following list doesn't include all the file types recognized by the
  // GraphicsMagick library; it includes most of the image types, excluding
  // the raw images and those images the Gmagick class is not able to write.
  $extensions = array(
    'BMP' => 'bmp',
    'CIN' => 'cin',
    'DCX' => 'dcx',
    'DPX' => 'dpx',
    'EPI' => 'epi',
    'EPSF' => 'eps',
    'EPSI' => 'eps',
    'EPT' => 'eps',
    'EPT2' => 'eps',
    'EPT3' => 'eps',
    'EPS' => 'eps',
    'FITS' => 'fits',
    'GIF87' => 'gif',
    'GIF' => 'gif',
    'ICB' => 'icb',
    'JPEG' => 'jpeg',
    'JPG' => 'jpg',
    'PAM' => 'pam',
    'PBM' => 'pbm',
    'EPDF' => 'pdf',
    'PDF' => 'pdf',
    'PGM' => 'pgm',
    'PNG00' => 'png',
    'PNG24' => 'png',
    'PNG32' => 'png',
    'PNG48' => 'png',
    'PNG' => 'png',
    'PNM' => 'pnm',
    'PPM' => 'ppm',
    'PS' => 'ps',
    'SGI' => 'sgi',
    'TGA' => 'tga',
    'PTIF' => 'tif',
    'BIGTIFF' => 'tif',
    'TIFF' => 'tiff',
    'VDA' => 'vda',
    'VST' => 'vst',
    'WBMP' => 'wbmp',
    'WEBP' => 'webp',
    'XBM' => 'xbm',
    'PICON' => 'xpm',
  );
  $supported_extensions = array();

  try {
    $handler = new Gmagick();

    foreach ($handler->queryFormats() as $format) {
      if (isset($extensions[$format])) {
        $supported_extensions[] = $extensions[$format];
      }
    }
  }
  catch (GmagickException) {
    // Ignore the thrown exception.
  }

  // The returned extensions exclude raw images.
  return array_unique($supported_extensions);
}

/**
 * Loads an image from a file.
 *
 * @param object $image
 *   An image object. The $image->handler and $image->format values will be
 *   populated by this call.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_load()
 * @see graphicsmagick_image_load()
 */
function image_graphicsmagick_toolkit_load(object $image): bool {
  return graphicsmagick_image_load($image);
}

/**
 * Writes an image to a destination file.
 *
 * @param object $image
 *   An image object. The $image->handler value will be changed by this call.
 * @param string $destination
 *   A URI or file path where the image should be saved.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_save()
 * @see graphicsmagick_image_save()
 */
function image_graphicsmagick_toolkit_save(object $image, string $destination): bool {
  return graphicsmagick_image_save($image, $destination);
}

/**
 * Gets details about an image.
 *
 * @param object $image
 *   An image object.
 *
 * @return false|array
 *   FALSE, if the file could not be found or is not an image. Otherwise, a
 *   keyed array containing information about the image:
 *   - "width": Width, in pixels.
 *   - "height": Height, in pixels.
 *
 * @see image_get_info()
 */
function image_graphicsmagick_toolkit_get_info(object $image): false|array {
  $details = array(
    'width' => 0,
    'height' => 0,
  );

  try {
    $handler = new \Gmagick(backdrop_realpath($image->source));
    $details['width'] = $handler->getImageWidth();
    $details['height'] = $handler->getImageHeight();
  }
  catch (\GmagickException) {
    // An exception has been thrown when trying to access the image information,
    // which could also mean the image file is corrupted. Return FALSE to signal
    // an error.
    return FALSE;
  }

  return $details;
}

/**
 * Scales an image to the specified size using the GraphicsMagick library.
 *
 * @param object $image
 *   An image object. The $image->info['width'] and $image->info['height']
 *   values will be modified by this call.
 * @param int $width
 *   The new width of the resized image, in pixels.
 * @param int $height
 *   The new height of the resized image, in pixels.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_resize()
 */
function image_graphicsmagick_toolkit_resize(object $image, int $width, int $height): bool {
  $effect = (new class {
    public function __invoke($handler, $width, $height) {
      // $background, $filter, and $blur are not passed by image_resize() Use
      // default values for the last three parameters necessary for
      // Gmagick::resizeImage().
      return $handler->resizeImage(
        $width,
        $height,
        'transparent',
        \Gmagick::FILTER_UNDEFINED,
        0.88
      );
    }
  });

  $result = graphicsmagick_image_effect($image, $effect, $width, $height);

  try {
    // The following methods could throw an exception. In the case they do, use
    // the width and height values passed to the method.
    $new_width = $image->handler->getImageWidth();
    $new_height = $image->handler->getImageHeight();
  }
  catch (\GmagickException|\Error) {
    $new_width = $width;
    $new_height = $height;
  }

  $image->info['width'] = $new_width;
  $image->info['height'] = $new_height;

  return $result;
}

/**
 * Rotates an image the given number of degrees.
 *
 * @param object $image
 *   An image object. The $image->info['width'] and $image->info['height']
 *   values will be modified by this call.
 * @param int $degrees
 *   The number of (clockwise) degrees to rotate the image.
 * @param int|string|null $background
 *   A hexadecimal value specifying the background color to use for the
 *   uncovered area of the image after the rotation, for example 0x000000 for
 *   black or 0xff00ff for magenta. The default value is #FFFFFF.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_rotate()
 */
function image_graphicsmagick_toolkit_rotate(object $image, int $degrees, int|string|null $background): bool {
  try {
    $color = Color::toHex($background);
  }
  catch (\InvalidArgumentException $e) {
    watchdog_exception('graphicsmagick', $e);
    return FALSE;
  }

  $effect = (new class {
    public function __invoke($handler, $degrees, $background) {
      return $handler->rotateImage($degrees, $background);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $degrees, $color);
}

/**
 * Crops an image using the GraphicsMagick library.
 *
 * @param object $image
 *   An image object. The $image->info['width'] and $image->info['height']
 *   values will be modified by this call.
 * @param int $x
 *   The starting x offset at which to start the crop, in pixels.
 * @param int $y
 *   The starting y offset at which to start the crop, in pixels.
 * @param int $width
 *   The width of the cropped area, in pixels.
 * @param int $height
 *   The height of the cropped area, in pixels.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_crop()
 */
function image_graphicsmagick_toolkit_crop(object $image, int $x, int $y, int $width, int $height): bool {
  $effect = (new class {
    public function __invoke($handler, $x, $y, $width, $height) {
      $handler = $handler->cropImage($width, $height, $x, $y);

      // This method is not documented on
      // https://www.php.net/manual/en/class.gmagick.php.
      // Verify it is implemented before using it.
      if (method_exists($handler, 'setImagePage')) {
        $handler = $handler->setImagePage($width, $height, $x, $y);
      }

      return $handler;
    }
  });

  $result = graphicsmagick_image_effect($image, $effect, $x, $y, $width, $height);

  try {
    // The following methods could throw an exception. In the case they do, use
    // the width and height values passed to the method.
    $new_width = $image->handler->getImageWidth();
    $new_height = $image->handler->getImageHeight();
  }

  catch (\GmagickException) {
    $new_width = $width;
    $new_height = $height;
  }

  $image->info['width'] = $new_width;
  $image->info['height'] = $new_height;

  return $result;
}

/**
 * Converts an image to grayscale.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *
 * @see image_desaturate()
 */
function image_graphicsmagick_toolkit_desaturate(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->setImageType(Gmagick::IMGTYPE_GRAYSCALE);
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Blurs an image.
 *
 * @param object $image
 *   An image object.
 * @param float $radius
 *   The Gaussian radius.
 * @param float $sigma
 *   The Gaussian sigma.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 */
function image_graphicsmagick_toolkit_blur(object $image, float $radius, float $sigma): bool {
  $effect = (new class {
    public function __invoke($handler, $radius, $sigma) {
      return $handler->blurImage($radius, $sigma);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $radius, $sigma);
}

/**
 * Reduces the speckle noise in an image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 */
function image_graphicsmagick_toolkit_despeckle(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->despeckleImage();
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Enhances the image edges.
 *
 * @param object $image
 *   An image object.
 * @param float $radius
 *   The operation radius.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 */
function image_graphicsmagick_toolkit_edge(object $image, float $radius): bool {
  $effect = (new class {
    public function __invoke($handler, $radius) {
      return $handler->edgeImage($radius);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $radius);
}

/**
 * Embosses an image.
 *
 * @param object $image
 *   An image object.
 * @param float $radius
 *   The Gaussian radius.
 * @param float $sigma
 *   The Gaussian sigma.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_emboss(object $image, float $radius, float $sigma): bool {
  $effect = (new class {
    public function __invoke($handler, $radius, $sigma) {
      return $handler->embossImage($radius, $sigma);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $radius, $sigma);
}

/**
 * Enhances an image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to blur the image.
 */
function image_graphicsmagick_toolkit_enhance(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->enhanceImage();
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Equalizes an image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_equalize(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->equalizeImage();
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Creates a vertical mirror image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_flip(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->flipImage();
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Creates a horizontal mirror image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_flop(object $image): bool {
  $effect = (new class {
    public function __invoke($handler) {
      return $handler->flopImage();
    }
  });

  return graphicsmagick_image_effect($image, $effect);
}

/**
 * Changes the image gamma value.
 *
 * @param object $image
 *   An image object.
 * @param float $gamma
 *   The new gamma value.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_gamma(object $image, float $gamma): bool {
  $effect = (new class {
    public function __invoke($handler, $gamma) {
      return $handler->gammaImage($gamma);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $gamma);
}

/**
 * Adds random noise.
 *
 * @param object $image
 *   An image object.
 * @param int $noise
 *   The noise type.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_noise(object $image, int $noise): bool {
  $effect = (new class {
    public function __invoke($handler, $noise) {
      return $handler->addNoiseImage($noise);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $noise);
}

/**
 * Image effect callback; simulate an oil painting.
 *
 * @param object $image
 *   An image object.
 * @param float $radius
 *   The radius of the circular region used to calculate the most frequently
 *   used color.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_oil_paint(object $image, float $radius): bool {
  $effect = (new class {
    public function __invoke($handler, $radius) {
      return $handler->oilPaintImage($radius);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $radius);
}

/**
 * Simulates a solarize effect.
 *
 * @param object $image
 *   An image object.
 * @param int $level
 *   An integer representing the level of the effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_solarize(object $image, int $level): bool {
  $effect = (new class {
    public function __invoke($handler, $level) {
      return $handler->solarizeImage($level);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $level);
}

/**
 * Randomly displaces each pixel in a circular region.
 *
 * @param object $image
 *   An image object.
 *
 * @param float $radius
 *   The radius of the circular region where the pixels are randomly displaced.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_spread(object $image, float $radius): bool {
  $effect = (new class {
    public function __invoke($handler, $radius) {
      return $handler->spreadImage($radius);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $radius);
}

/**
 * Swirls the pixels about the center of the image.
 *
 * @param object $image
 *   An image object.
 * @param float $degrees
 *   The sweep of the arc through which each pixel is moved.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function image_graphicsmagick_toolkit_swirl(object $image, float $degrees): bool {
  $effect = (new class {
    public function __invoke($handler, $degrees) {
      return $handler->swirlImage($degrees);
    }
  });

  return graphicsmagick_image_effect($image, $effect, $degrees);
}

/**
 * Form structure for the blur effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_blur_form(array $data): array {
  $form['radius'] = array(
    '#type' => 'number',
    '#title' => t('Radius'),
    '#description' => t('This value should typically be either 0, to let the effect choose the best value, or twice the sigma value.'),
    '#default_value' => $data['radius'] ?? 0.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 65355.0,
    '#step' => 0.5,
  );
  $form['sigma'] = array(
    '#type' => 'number',
    '#title' => t('Sigma'),
    '#description' => t('A large sigma value and a smallish radius value will introduce artifacts in the resulting image; small sigma values are typically only used to fuzz lines and smooth edges on images for which no anti-aliasing was used.'),
    '#default_value' => $data['sigma'] ?? 1.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 65355.0,
    '#step' => 0.5,
  );

  return $form;
}

/**
 * Image effect callback; blur an image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when performing the blur effect with the
 *   following items:
 *   - "radius": The Gaussian radius.
 *   - "sigma": The Gaussian sigma.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_blur(object $image, array $data): bool {
  return image_toolkit_invoke('blur', $image, array_values($data));
}

/**
 * Image effect callback; reduce the speckle noise in an image.
 *
 * @param object $image
 *   An image object.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_despeckle(object $image): bool {
  return image_toolkit_invoke('despeckle', $image);
}

/**
 * Form structure for the edge effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   An array of attributes to use when performing the effect with the
 *   following items:
 *   - "radius": the operation radius.
 */
function graphicsmagick_effects_edge_form(array $data): array {
  $form['radius'] = array(
    '#type' => 'number',
    '#title' => t('Radius'),
    '#description' => t('Use a value of zero to let the effect choose the best value.'),
    '#default_value' => $data['radius'] ?? 0.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 65355.0,
    '#step' => 0.5,
  );

  return $form;
}

/**
 * Image effect callback; enhance the image edges.
 *
 * @param object $image
 *   An image object.
 * @param $data
 *   An array of attributes to use when performing the effect with the
 *   following items:
 *   - "radius": the operation radius.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_edge(object $image, array $data): bool {
  return image_toolkit_invoke('edge', $image, array_values($data));
}

/**
 * Form structure for the emboss effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_emboss_form(array $data): array {
  $form['radius'] = array(
    '#type' => 'number',
    '#title' => t('Radius'),
    '#description' => t('For reasonable results, the radius value should be higher than the sigma value. Use a value of zero to let the effect choose the best value.'),
    '#default_value' => $data['radius'] ?? 0.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 65355.0,
    '#step' => 0.5,
  );
  $form['sigma'] = array(
    '#type' => 'number',
    '#title' => t('Sigma'),
    '#description' => t('A large sigma value works well also with color image. It can remove color dominance, but it could also introduce artifacts, especially in JPEG images.'),
    '#default_value' => $data['sigma'] ?? 1.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 65355.0,
    '#step' => 0.5,
  );

  return $form;
}

/**
 * Image effect callback; emboss an image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when performing the emboss effect with the
 *   following items:
 *   - "radius": The Gaussian radius.
 *   - "sigma": The Gaussian sigma.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_emboss(object $image, array $data): bool {
  return image_toolkit_invoke('emboss', $image, array_values($data));
}

/**
 * Image effect callback; enhance an image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when enhancing an image. No attributes are
 *   currently used for this effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to blur the image.
 */
function graphicsmagick_effects_enhance(object $image, array $data): bool {
  return image_toolkit_invoke('enhance', $image, array_values($data));
}

/**
 * Image effect callback; equalize an image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when equalizing an image. No attributes are
 *   currently used for this effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_equalize(object $image, array $data): bool {
  return image_toolkit_invoke('equalize', $image, array_values($data));
}

/**
 * Image effect callback; create a vertical mirror image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when creating a vertical mirror image. No
 *   attributes are currently used for this effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_flip(object $image, array $data): bool {
  return image_toolkit_invoke('flip', $image, array_values($data));
}

/**
 * Image effect callback; create a horizontal mirror image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when creating a horizontal mirror image. No
 *   attributes are currently used for this effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_flop(object $image, array $data): bool {
  return image_toolkit_invoke('flop', $image, array_values($data));
}

/**
 * Form structure for the gamma effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_gamma_form(array $data): array {
  $form['gamma'] = array(
    '#type' => 'number',
    '#title' => t('Gamma'),
    '#description' => t('Values typically range from 0.8 to 2.3. Values lower than one make the image darker; values higher than one make the image lighter.'),
    '#default_value' => $data['gamma'] ?? 0.8,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 10.0,
    '#step' => 0.2,
  );

  return $form;
}

/**
 * Image effect callback; change the image gamma value.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when changing the gamma value with the
 *   following items:
 *   - "gamma": The new gamma value.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_gamma(object $image, array $data): bool {
  return image_toolkit_invoke('gamma', $image, array_values($data));
}

/**
 * Form structure for the noise effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_noise_form(array $data): array {
  $form['noise'] = array(
    '#type' => 'select',
    '#title' => t('Noise type'),
    '#description' => t('The noise type changes for which pixels the color is randomly changed.'),
    '#options' => graphicsmagick_image_noise_options(),
    '#default_value' => $data['noise'] ?? Gmagick::NOISE_UNIFORM,
    '#required' => TRUE,
  );

  return $form;
}

/**
 * Image effect callback; add random noise.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when applying the effect with the following
 *   items:
 *   - "noise": The noise type.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_noise(object $image, array $data): bool {
  return image_toolkit_invoke('noise', $image, array_values($data));
}

/**
 * Form structure for the oil painting effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_oil_paint_form(array $data): array {
  $form['radius'] = array(
    '#type' => 'number',
    '#title' => t('Radius'),
    '#description' => t('Each pixel is replaced by the most frequent color occurring in a circular region defined by the radius value.'),
    '#default_value' => $data['radius'] ?? 0.8,
    '#required' => TRUE,
    '#min' => 0.6,
    '#max' => 50.0,
    '#step' => 0.2,
  );

  return $form;
}

/**
 * Image effect callback; simulate an oil painting.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when applying the effect with the following
 *   items:
 *   - "radius": The radius of the circular region used to calculate the most
 *     frequently used color.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_oil_paint(object $image, array $data): bool {
  return image_toolkit_invoke('oil_paint', $image, array_values($data));
}

/**
 * Form structure for the solarize effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_solarize_form(array $data): array {
  try {
    $gmagick = new Gmagick();
    $quantum_level = $gmagick->getQuantumDepth()['quantumDepthLong'];
  }
  catch (Exception) {
    // As getting the quantum dept value failed, assume its value is 8.
    $quantum_level = 8;
  }

  $level = $data['level'] ?? 1 << (($quantum_level / 2) - 2);

  $form['level'] = array(
    '#type' => 'number',
    '#title' => t('Level'),
    '#description' => t('The effect level.'),
    '#default_value' => $level,
    '#required' => TRUE,
    '#min' => 0,
    '#max' => 1 << $quantum_level,
    '#step' => 1,
  );

  return $form;
}

/**
 * Image effect callback; simulate a solarize effect.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when applying the effect with the
 *   following items:
 *   - "level": An integer representing the level of the effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_solarize(object $image, array $data): bool {
  return image_toolkit_invoke('solarize', $image, array_values($data));
}

/**
 * Form structure for the spread effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_spread_form(array $data): array {
  $form['radius'] = array(
    '#type' => 'number',
    '#title' => t('Radius'),
    '#description' => t('Each pixel in a block defined by the radius parameter is randomly displaced.'),
    '#default_value' => $data['radius'] ?? 2.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 50.0,
    '#step' => 0.4,
  );

  return $form;
}

/**
 * Image effect callback; randomly displace each pixel in a circular region.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when applying the effect with the following
 *   items:
 *   - "radius": The radius of the circular region where the pixels are randomly
 *     displaced.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_spread(object $image, array $data): bool {
  return image_toolkit_invoke('spread', $image, array_values($data));
}

/**
 * Form structure for the swirl effect.
 *
 * Note that this is not a complete form; it only contains the portion of the
 * form for configuring the effect options. Therefore, it does not need to
 * include metadata about the effect, nor a submit button.
 *
 * @param array $data
 *   The current configuration for this effect.
 */
function graphicsmagick_effects_swirl_form(array $data): array {
  $form['degrees'] = array(
    '#type' => 'number',
    '#title' => t('Degrees'),
    '#description' => t('The sweep of the arc through which each pixel is moved.'),
    '#default_value' => $data['degrees'] ?? 10.0,
    '#required' => TRUE,
    '#min' => 0.0,
    '#max' => 360.0,
    '#step' => 2.0,
  );

  return $form;
}

/**
 * Image effect callback; swirl the pixels about the center of the image.
 *
 * @param object $image
 *   An image object.
 * @param array $data
 *   An array of attributes to use when applying the effect with the following
 *   items:
 *   - "degrees": The sweep of the arc through which each pixel is moved.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_effects_swirl(object $image, array $data): bool {
  return image_toolkit_invoke('swirl', $image, array_values($data));
}

/**
 * Returns the image quality to use with JPEG images.
 *
 * @return int
 *   The image quality for JPEG images, a value between 0 and 100, where 95 is
 *   the default value.
 */
function graphicsmagick_toolkit_get_jpeg_quality(): int {
  $value = config_get('graphicsmagick_toolkit_jpeg_quality');

  // If the JPEG quality value hasn't been set, return 80 instead of 0, which
  // would be a bad image quality to use by default.
  return $value ?? 80;
}

/**
 * Returns the compression value to use with PNG images.
 *
 * @return int
 *   The compression value for PNG images, a value between 0 and 99, where 99 is
 *   the default value.
 */
function graphicsmagick_toolkit_get_png_compression(): int {
  $value = config_get('graphicsmagick_toolkit_png_compression');

  // If the PNG compression value hasn't been set, return 99 instead of 0, which
  // is a better compression value to use by default.
  return $value ?? 99;
}

/**
 * Verifies the methods used from the GraphicsMagick toolkit can be used.
 *
 * This function could be used from the modules that need to use the Gmagick
 * extension to alter images, as the methods this function checks are necessary
 * to handle animated images.
 *
 * @return bool
 *   TRUE when the Gmagick PHP extension is loaded, the Gmagick class it
 *   implements is available, and that class implements the methods used by the
 *   toolkit.
 */
function graphicsmagick_available(): bool {
  if (extension_loaded('gmagick') && class_exists('Gmagick')) {
    try {
      $handler = new Gmagick();

      // Verify the undocumented methods used by the toolkit are implemented.
      $missing_methods = FALSE;
      $missing_methods |= !method_exists($handler, 'getNumberImages');
      $missing_methods |= !method_exists($handler, 'coalesceImages');
      $missing_methods |= !method_exists($handler, 'deconstructImages');

      return !$missing_methods;
    }
    catch (\GmagickException) {
      return FALSE;
    }
  }

  return FALSE;
}

/**
 * Loads an image from a file.
 *
 * This function can be used from any module that needs to use the effects
 * implemented by the GraphicsMagick Effects modules independently of the
 * toolkit set for the site. In the case the used toolkit is not
 * GraphicsMagick Toolkit, this function could cause the image to be loaded
 * again, with the consequence that the image data is loaded twice in memory.
 *
 * $image->source is expected to contain the source file path. If it has not
 * been set, or it does not contain the expected value, this function will
 * return FALSE.
 *
 * @param object $image
 *   An image object. The $image->handler, and $image->format, and
 *   $image->mimeType values will be populated by this call.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 */
function graphicsmagick_image_load(object $image): bool {
  if (isset($image->handler) && !is_a($image->handler, 'Gmagick')) {
    // $image->handler has been already set, but it is not a Gmagick instance.
    // To avoid conflicts with other modules, avoid to load the image and return
    // FALSE.
    return FALSE;
  }

  if (isset($image->handler)) {
    // Destroy the existing Gmagick instance.
    try {
      $image->handler->destroy();
    } catch (GmagickException) {
      // Ignore the exception, as there is not anything that can be done when
      // destroying a Gmagick instance fails.
    }

    $image->handler = NULL;
  }

  try {
    if (!isset($image->source) || !is_string($image->source)) {
      // $image->source must be set to a string containing the source file path.
      // Return FALSE for error in case it is not.
      return FALSE;
    }

    $handler = new Gmagick(backdrop_realpath($image->source));
    $format = $handler->getImageFormat();
  } catch (GmagickException) {
    // If either the constructor or getImageFormat() returned an
    // exception, report a failure to the calling function. An exception in
    // those cases could mean the file doesn't contain an image, it does not
    // contain an image recognized from the Gmagick class, or the file is
    // corrupted.
    return FALSE;
  }

  $image->handler = $handler;
  $image->format = $format;
  $image->mimeType = graphicsmagick_image_format_to_mime_type($format);

  return TRUE;
}

/**
 * Retrieves the image format as defined by the Gmagick class.
 *
 * @param object $image
 *   The image object.
 *
 * @return false|string
 *   FALSE in case of error, or a string containing one of the format recognized
 *   by the Gmagick class.
 */
function graphicsmagick_image_format(object $image): false|string {
  if (isset($image->handler) && !is_a($image->handler, 'Gmagick')) {
    // $image->handler has been already set, but it is not a Gmagick instance.
    // To avoid conflicts with other modules, avoid to load the image and return
    // FALSE.
    return FALSE;
  }

  if (!isset($image->handler)) {
    if (!graphicsmagick_image_load($image)) {
      // The file does not contain an image, it does not contain an image
      // recognized from the Gmagick class, the file is corrupted, or creating a
      // Gmagick instance was not possible for other reasons. Return FALSE.
      return FALSE;
    }
  }

  // Return the $image->format value previously set only when $image->handler is
  // a Gmagick instance.
  if (isset($image->format)) {
    return $image->format;
  }

  try {
    $format = $image->handler->getImageFormat();
  } catch (GmagickException) {
    // If Gmagick::getImageFormat() returned an exception, report a failure to
    // the calling function. An exception in this case could mean the file
    // does not contain an image, it does not contain an image recognized from
    // the Gmagick class, or the file is corrupted.
    return FALSE;
  }

  $image->format = $format;

  return $format;
}

/**
 * Returns the option array for noise types implemented by the Gmagick class.
 *
 * @return array
 *   An array whose keys are the Gmagick::NOISE_* constants and the values are
 *   the noise names to shown in forms.
 */
function graphicsmagick_image_noise_options(): array {
  return array(
    Gmagick::NOISE_UNIFORM => t('Uniform'),
    Gmagick::NOISE_GAUSSIAN => t('Gaussian'),
    Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN => t('Multiplicative Gaussian'),
    Gmagick::NOISE_LAPLACIAN => t('Laplacian'),
    Gmagick::NOISE_POISSON => t('Poisson'),
  );
}

/**
 * Converts the format returned by the Gmagick class in the image extension.
 *
 * Modules can get the image format required from this function using
 * graphicsmagick_image_format(), without accessing any method implemented by
 * the Gmagick class.
 *
 * @param string $format
 *   The image format returned from the Gmagick class.
 *
 * @return string
 *   The image extension used by default for that image format.
 *
 * @see graphicsmagick_image_format()
 */
function graphicsmagick_image_format_to_extension(string $format): string {
  // The following list doesn't include all the file types recognized by the
  // GraphicsMagick library; it includes most of the image types, excluding
  // the raw images and those images the Gmagick class is not able to write.
  $extensions = array(
    'BMP' => 'bmp',
    'CIN' => 'cin',
    'DCX' => 'dcx',
    'DPX' => 'dpx',
    'EPI' => 'epi',
    'EPSF' => 'eps',
    'EPSI' => 'eps',
    'EPT' => 'eps',
    'EPT2' => 'eps',
    'EPT3' => 'eps',
    'EPS' => 'eps',
    'FITS' => 'fits',
    'GIF87' => 'gif',
    'GIF' => 'gif',
    'ICB' => 'icb',
    'JPEG' => 'jpeg',
    'JPG' => 'jpg',
    'PAM' => 'pam',
    'PBM' => 'pbm',
    'EPDF' => 'pdf',
    'PDF' => 'pdf',
    'PGM' => 'pgm',
    'PNG00' => 'png',
    'PNG24' => 'png',
    'PNG32' => 'png',
    'PNG48' => 'png',
    'PNG' => 'png',
    'PNM' => 'pnm',
    'PPM' => 'ppm',
    'PS' => 'ps',
    'SGI' => 'sgi',
    'TGA' => 'tga',
    'PTIF' => 'tif',
    'BIGTIFF' => 'tif',
    'TIFF' => 'tiff',
    'VDA' => 'vda',
    'VST' => 'vst',
    'WBMP' => 'wbmp',
    'WEBP' => 'webp',
    'XBM' => 'xbm',
    'PICON' => 'xpm',
  );

  try {
    $handler = new Gmagick();
    $supported_formats = $handler->queryFormats();
  }
  catch (GmagickException) {
    // Return an empty string to signal an error.
    return '';
  }

  if (in_array($format, $supported_formats) && isset($extensions[$format])) {
    return $extensions[$format];
  }
  else {
    // If a format is not in $extensions, return an empty string, since
    // Gmagick::queryFormats() returns also video formats and raw image formats.
    return '';
  }
}

/**
 * Converts the format returned by the Gmagick class in the image MIME type.
 *
 * Modules can get the image format required from this function using
 * graphicsmagick_image_format(), without accessing any method implemented by
 * the Gmagick class.
 *
 * @param string $format
 *   The image format returned from the Gmagick class.
 *
 * @return string
 *   The image MIME type.
 *
 * @see graphicsmagick_image_format()
 */
function graphicsmagick_image_format_to_mime_type(string $format): string {
  // Since the Gmagick class doesn't provide a method to obtain an image MIME
  // type, differently from the Imagick class, this code maps the Gmagick
  // format to the MIME type using a literal array. There is no need to use
  // mime_content_type() nor finfo_open()/finfo_file(), since the Gmagick
  // class already recognized the file type.
  // The following list doesn't include all the file types recognized by the
  // GraphicsMagick library; it includes most of the image types, excluding
  // the raw images and those images the Gmagick class is not able to write.
  $mime_types = array(
    'BIGTIFF' => 'image/tiff',
    'BMP' => 'image/x-ms-bmp',
    'CIN' => 'image/cineon',
    'DCX' => 'image/x-pc-paintbrush',
    'DPX' => 'image/x-dpx',
    'EPDF' => 'application/pdf',
    'EPI' => 'application/postscript',
    'EPS' => 'application/postscript',
    'EPSF' => 'application/postscript',
    'EPSI' => 'application/postscript',
    'EPT' => 'image/eps',
    'EPT2' => 'image/eps',
    'EPT3' => 'image/eps',
    'FITS' => 'image/fits',
    'GIF' => 'image/gif',
    'GIF87' => 'image/gif',
    'ICB' => 'image/x-tga',
    'JPEG' => 'image/jpeg',
    'JPG' => 'image/jpeg',
    'PAM' => 'image/x-portable-pixmap',
    'PBM' => 'image/x-portable-pixmap',
    'PDF' => 'application/pdf',
    'PGM' => 'image/x-portable-greymap',
    'PICON' => 'image/x-xpmi',
    'PNG' => 'image/png',
    'PNG00' => 'image/png',
    'PNG24' => 'image/png',
    'PNG32' => 'image/png',
    'PNG48' => 'image/png',
    'PNM' => 'image/x-portable-pixmap',
    'PPM' => 'image/x-portable-pixmap',
    'PS' => 'application/postscript',
    'PTIF' => 'image/tiff',
    'SGI' => 'imagine/sgi',
    'TGA' => 'image/x-tga',
    'TIFF' => 'image/tiff',
    'VDA' => 'image/x-tga',
    'VST' => 'image/x-tga',
    'WBMP' => 'image/vnd.wap.wbmp',
    'WEBP' => 'image/webp',
    'XBM' => 'image/x‑xbitmap',
  );

  try {
    $handler = new Gmagick();
    $supported_formats = $handler->queryFormats();
  }
  catch (GmagickException) {
    // Return an empty string to signal an error.
    return '';
  }

  if (in_array($format, $supported_formats) && isset($mime_types[$format])) {
    return $mime_types[$format];
  }
  else {
    // If a format is not in $mime_types, return an empty string, since
    // Gmagick::queryFormats() returns also video formats and raw image formats.
    return '';
  }
}

/**
 * Applies an effect to an image.
 *
 * @param object $image
 *   An image object. $image->handler should contain a Gmagick instance used
 *   to load the image.
 *   When the image is loaded with image_load(), and the used image toolkit is
 *   graphicsmagick_toolkit, or when the image is loaded with
 *   graphicsmagick_image_load(), $image->handler is initialized with a Gmagick
 *   instance. If $image->handler hasn't been set, this function will call
 *   graphicsmagick_image_load() to first load the image.
 *
 * @param callable $effect
 *   The callable used to apply the effect.
 * @param array $data
 *   The configuration values for the effect. All the values are passed to the
 *   effect callable, except 'background' that is used from this function to set
 *   the image background color before applying the effect.
 *
 * @return bool
 *   TRUE on success, FALSE on failure to apply the effect.
 */
function graphicsmagick_image_effect(object $image, callable $effect, ...$data): bool {
  if (isset($image->handler) && !is_a($image->handler, 'Gmagick')) {
    // $image->handler has been already set, but it is not a Gmagick instance.
    // To avoid conflicts with other modules, avoid to save the image and return
    // FALSE.
    return FALSE;
  }

  if (!isset($image->handler)) {
    if (!graphicsmagick_image_load($image)) {
      // The file does not contain an image, it does not contain an image
      // recognized from the Gmagick class, the file is corrupted, or creating a
      // Gmagick instance was not possible for other reasons. Return FALSE.
      return FALSE;
    }
  }

  try {
    // Clone the image handler and work with the clone. In case of exceptions,
    // the original image handler and its state is preserved.
    $handler = clone $image->handler;

    if (!method_exists($handler, 'getNumberImages') || !method_exists($handler, 'coalesceImages')) {
      return FALSE;
    }

    if ($handler->getNumberImages() > 1) {
      $handler = $handler->coalesceImages();

      do {
        $handler = $effect($handler, $data);
      } while ($handler->nextImage());

      $handler = $handler->deconstructImages();
    }
    else {
      $handler = $effect($handler, $data);
    }
  }
  catch (\GmagickException $e) {
    watchdog_exception('graphicsmagick', $e);

    try {
      $handler->destroy();
    }
    catch (\GmagickException) {
      // \Gmagick::destroy() can throw an exception, but nothing can be done to
      // fix that.
    }

    return FALSE;
  }

  $image->handler = $handler;

  return TRUE;
}

/**
 * Writes an image to a destination file.
 *
 * @param object $image
 *   An image object. $image->handler must be a Gmagick instance; the image will
 *   be saved and the $image->handler value will be changed by this call.
 * @param string $destination
 *   A URI or file path where the image should be saved.
 *
 * @return bool
 *   TRUE or FALSE, based on success.
 *   The returned value will be FALSE even in the case the $image->handler value
 *   has been set, but it is not a Gmagick instance, or the $image->handler
 *   value has not been set, and it is not possible to load the source image.
 */
function graphicsmagick_image_save(object $image, string $destination): bool {
  if (isset($image->handler) && !is_a($image->handler, 'Gmagick')) {
    // $image->handler has been already set, but it is not a Gmagick instance.
    // To avoid conflicts with other modules, avoid to save the image and return
    // FALSE.
    return FALSE;
  }

  if (!isset($image->handler)) {
    // The image has not been loaded from the file using a Gmagick instance; try
    // to load it.
    // Usually, $image->handler is already set. This code has been added to let
    // a module save an image without first calling image_load() or
    // graphicsmagick_image_load().
    if (!graphicsmagick_image_load($image)) {
      return FALSE;
    }
  }

  try {
    switch ($image->mimeType) {
      case 'image/jpeg':
        $image->handler->setCompressionQuality(graphicsmagick_toolkit_get_jpeg_quality());
        break;

      case 'image/png';
        $image->handler->setCompressionQuality(graphicsmagick_toolkit_get_png_compression());
        break;
    }

    $image->handler->writeImage(backdrop_realpath($destination), $image->handler->getNumberImages() > 1);
    return TRUE;
  } catch (\GmagickException) {
    return FALSE;
  }
}