[4.x] How to customise image transform creation?

[d--j]

We have pictures of people in various aspect ratios and want to automatically create square avatars of them by "zooming" onto the faces. That's done (face detection by OpenCV with their pre-trained DNN) and works like a charm. But now we need to create the actual image transform that generates the zoomed version of the image. What I thought was the easy part doesn't look that easy after I scoured the CraftCMS source code for the right extension point.

Option 1: Create a new craft\base\imagetransforms\ImageTransformerInterface

Looks like ImageTransforms service has an extension point to register new ImageTransformers

cms/src/services/ImageTransforms.php

Lines 563 to 582 in 232546e

	/**
	* Return all available image transformers.
	*
	* @return string[]
	* @phpstan-return class-string<ImageTransformerInterface>[]
	*/
	public function getAllImageTransformers(): array
	{
	$transformers = [
	ImageTransformer::class,
	];
	$event = new RegisterComponentTypesEvent([
	'types' => $transformers,
	]);
	$this->trigger(self::EVENT_REGISTER_IMAGE_TRANSFORMERS, $event);
	return $event->types;
	}

But how do I get a craft\models\ImageTransform or craft\models\ImageTransformIndex to actually use anything but the default ImageTransformer? I have not found a way to do that. Is there some documentation that I missed or can you provide me with some pointers?

Option 2: craft\imagetransforms\ImageTransformer::EVENT_TRANSFORM_IMAGE

Use the EVENT_TRANSFORM_IMAGE to hook into the image transformation process to overwrite the CraftCMS version of the transform with a new version. This is not that optimal because the image transform would be generated twice (CraftCMS does its thing and we create a new version).

Here is the relevant CraftCMS code:

cms/src/imagetransforms/ImageTransformer.php

Lines 382 to 410 in 232546e

	$tempFilename = uniqid(pathinfo($index->filename, PATHINFO_FILENAME), true) . '.' . $index->detectedFormat;
	$tempPath = Craft::$app->getPath()->getTempPath() . DIRECTORY_SEPARATOR . $tempFilename;
	$image->saveAs($tempPath);
	clearstatcache(true, $tempPath);
	try {
	$event = new ImageTransformerOperationEvent([
	'asset' => $asset,
	'imageTransformIndex' => $index,
	'path' => $transformPath,
	'image' => $image,
	]);
	$this->trigger(static::EVENT_TRANSFORM_IMAGE, $event);
	$stream = fopen($tempPath, 'rb');
	$transformFs->writeFileFromStream($transformPath, $stream, []);
	if (file_exists($event->path)) {
	FileHelper::unlink($event->path);
	}
	} catch (FsException $e) {
	Craft::$app->getErrorHandler()->logException($e);
	}
	// Maybe a plugin changed the path to something else. Check if we need to remove this, too.
	if (file_exists($tempPath)) {
	FileHelper::unlink($tempPath);
	}

The transform gets saved into $tempPath, the event is fired without providing $tempPath, $tempPath is streamed into the Fs.

How do one should overwrite $tempPath when the event does not provide it? What is $event->path used for?

Isn't this wrong the way it is?

cms/src/imagetransforms/ImageTransformer.php

Lines 400 to 402 in 232546e

	if (file_exists($event->path)) {
	FileHelper::unlink($event->path);
	}

$event->path currently is not a file system path. It's the path in the Fs where image transform should be saved. So directly remove the image transform after we created it does not make much sense (and it only works, because $event->path is never found because it is not an absolute file path).

Have I maybe found a bug and the code should look like the following or is this event for something different than overwriting the image transform?

  $tempFilename = uniqid(pathinfo($index->filename, PATHINFO_FILENAME), true) . '.' . $index->detectedFormat; 
  $tempPath = Craft::$app->getPath()->getTempPath() . DIRECTORY_SEPARATOR . $tempFilename; 
  $image->saveAs($tempPath); 
   
  clearstatcache(true, $tempPath); 
   
  try { 
      $event = new ImageTransformerOperationEvent([ 
          'asset' => $asset, 
          'imageTransformIndex' => $index, 
-         'path' => $transformPath, 
+         'path' => $tempPath, 
          'image' => $image, 
      ]); 
      $this->trigger(static::EVENT_TRANSFORM_IMAGE, $event); 
   
-     $stream = fopen($tempPath, 'rb'); 
+     $stream = fopen($event->path, 'rb'); 
      $transformFs->writeFileFromStream($transformPath, $stream, []); 
   
      if (file_exists($event->path)) { 
          FileHelper::unlink($event->path); 
      } 
  } catch (FsException $e) { 
      Craft::$app->getErrorHandler()->logException($e); 
  } 
   
  // Maybe a plugin changed the path to something else. Check if we need to remove this, too. 
  if (file_exists($tempPath)) { 
      FileHelper::unlink($tempPath); 
  } 

[brandonkelly]

The custom image transformer functionality is half-baked at the moment. We’re planning to revisit and make the API simpler in a 4.x release (or 5.0 if it ends up involving breaking changes).

In the meantime, craft\elements\Asset::EVENT_BEFORE_GENERATE_TRANSFORM is probably the best place to override the built-in image transformer. If $event->url is set when the event is finished, that will be returned by Asset::getUrl() rather than getting Craft’s transformer involved.

Another thing to consider, though, is whether you need to override transform generation in the first place? If the only reason you’re doing it is because you want control over where the transform centers its crops, that’s what focal points are for. You could start setting those programmatically on the assets ahead of time, and Craft will respect them for all its native transforms (including control panel thumbnails).

$myAsset->setFocalPoint(['x' => 0.35, 'y' => 0.25]);
$myAsset->setScenario(\craft\base\Element::SCENARIO_ESSENTIALS);
Craft::$app->elements->saveElement($myAsset);

[d--j]

OK I will go with the craft\elements\Asset::EVENT_BEFORE_GENERATE_TRANSFORM route for now. The event handler needs to do the file existence check on its own but that's not that big of a deal.

---

Could you enlighten me on what these lines should do?

cms/src/imagetransforms/ImageTransformer.php

Lines 400 to 402 in 232546e

	if (file_exists($event->path)) {
	FileHelper::unlink($event->path);
	}

I believe that the path property of this event does not make much sense as it is. Why do you delete it after the event?!

In ac8d214#diff-39674e29c35cd11b071ebed336144724878816847e9bc4df62fffdd62457fe92 the events path property was used as tempPath.

The 3.x code would allow extensions to overwrite the transformation:

cms/src/services/AssetTransforms.php

Lines 1609 to 1623 in 7c58e97

	$event = new GenerateTransformEvent([
	'transformIndex' => $index,
	'asset' => $asset,
	'image' => $image,
	]);
	$this->trigger(self::EVENT_GENERATE_TRANSFORM, $event);
	if ($event->tempPath !== null) {
	$tempPath = $event->tempPath;
	} else {
	$tempFilename = uniqid(pathinfo($index->filename, PATHINFO_FILENAME), true) . '.' . $index->detectedFormat;
	$tempPath = Craft::$app->getPath()->getTempPath() . DIRECTORY_SEPARATOR . $tempFilename;
	$image->saveAs($tempPath);
	}

Maybe also add a tempPath property to the event (or use the path property but that might be a breaking change) so that this event can get used to overwrite image transformations like it was possible in CraftCMS 3.

---

Another thing to consider, though, is whether you need to override transform generation in the first place? If the only reason you’re doing it is because you want control over where the transform centers its crops, that’s what focal points are for. You could start setting those programmatically on the assets ahead of time, and Craft will respect them for all its native transforms (including control panel thumbnails).

We already set the focal point (for the normal transforms) but for avatars we also "zoom" onto the face. Consider this random picture I grabbed from Wikipedia:

Capt. Yau-Liong Tsai, Public domain, via Wikimedia Commons

we detected the face at 0.4622;0.0980;0.0567;0.0888 (x;y;w;h in percent of width/height) and thus the transform needs to crop this area to only the face:

Normal CraftCMS Image transforms cannot do that.

[brandonkelly]

Normal CraftCMS Image transforms cannot do that.

They will in v4, as everything is run through image transforms now.

[d--j]

As @brandonkelly suggested, I took the route to hook into Asset::EVENT_BEFORE_GENERATE_TRANSFORM until using a custom ImageTransformer is feasible.

For anyone stumbling onto this wanting to do the same: here is how this approximately looks like:

Event::on(
    Asset::class,
    Asset::EVENT_BEFORE_GENERATE_TRANSFORM,
    function (GenerateTransformEvent $event) {
        if ($event->transform && preg_match('~^authorSquare(\d+)$~', $event->transform->handle ?? '')) {
            $event->url = $this->getAuthorSquareAssetUrl($event->asset, $event->transform);
        }
    }
);


public function getAuthorSquareAssetUrl(Asset $asset, ImageTransform $transform): ?string
{
    $match = [];
    if (! preg_match('~^authorSquare(\d+)$~', $transform->handle ?? '', $match)) {
        throw new \InvalidArgumentException('$transform needs to be a authorSquare transform');
    }
    $size = min(1024, max(24, intval($match[1])));
    $fs   = $asset->getVolume()->getTransformFs();
    if (! $fs instanceof LocalFsInterface) {
        throw new \InvalidArgumentException('$asset transformFs needs to be a local file system');
    }
    if (! in_array($asset->getMimeType(), ['image/png', 'image/jpeg'])) {
        Craft::warning(
            'tried to create an author crop for source image with mime type '.$asset->getMimeType().' ID: '.$asset->id,
            __METHOD__
        );

        return null;
    }
    if (empty($transform->format)) {
        $transform->format = 'jpg';
    }
    $subPath           = $asset->getVolume()->transformSubpath;
    $subPath           = StringHelper::removeRight($subPath, '/');
    $transformBasePath = ($subPath ? $subPath.DIRECTORY_SEPARATOR : '').$asset->folderPath;
    $transformString   = '_'.$transform->handle;
    $transformFilename = $asset->getFilename(false).'.'.$transform->format;
    $uri               = str_replace('\\', '/', $transformBasePath).$transformString.DIRECTORY_SEPARATOR.$transformFilename;
    $destPath          = $fs->getRootPath().DIRECTORY_SEPARATOR.$uri;
    $assetTimeStamp    = $asset->dateUpdated->getTimestamp();
    clearstatcache(true, $destPath);

    if (! file_exists($destPath) || ($destTimeStamp = filemtime($destPath)) < $assetTimeStamp || filesize($destPath) < 1) {
        $sourcePath     = $asset->getImageTransformSourcePath();
        $imageDimension = getimagesize($sourcePath);
        $tmpPath        = $this->cropAvatar($sourcePath, $asset, $size); // this does the actual transform creation
        FileHelper::createDirectory(pathinfo($destPath, PATHINFO_DIRNAME));
        rename($tmpPath, $destPath);
        $destTimeStamp = filemtime($destPath);

        // synthesise an ImageTransformIndex for our transform if it is missing
        // needed for Craft::$app->getImageTransforms()->deleteCreatedTransformsForAsset($asset); to work
        $existing = (new Query())->select([
            'id',
            'fileExists',
            'inProgress',
            'error',
            'filename',
            'format',
        ])->from(Table::IMAGETRANSFORMINDEX)->where([
            'assetId'         => $asset->id,
            'format'          => $transform->format,
            'transformString' => $transformString,
        ])->one();
        if (is_array($existing) && (! $existing['fileExists'] || $existing['inProgress'] || $existing['error'])) {
            Db::delete(Table::IMAGETRANSFORMINDEX, ['id' => $existing['id']]);
            $existing = null;
        }
        if (! $existing) {
            Db::insert(Table::IMAGETRANSFORMINDEX, [
                'assetId'         => $asset->id,
                'transformer'     => ImageTransform::DEFAULT_TRANSFORMER,
                'filename'        => $transformFilename,
                'format'          => $transform->format,
                'transformString' => $transformString,
                'fileExists'      => 1,
                'inProgress'      => 0,
                'error'           => 0,
            ]);
        }
    }

    return UrlHelper::urlWithParams(
        $fs->getRootUrl().$uri,
        AssetsHelper::revParams($asset, new \DateTime('@'.$destTimeStamp)),
    );
}

[timkelty]

Create a new craft\base\imagetransforms\ImageTransformerInterface

@d--j I'm actively working on making this the go-to solution for this, but it requires some API changes that will be coming in a near 4.x release. I'll make sure to update you here when those changes land.