Opticrop: Usage and Implementation
Opticrop is a PHP script I wrote to crop a thumbnail of a specific width and height from a full-sized image.
Unlike most cropping routines out there, Opticrop uses edge-detection to find the most “interesting” part of the image to crop, so you won’t get a useless thumbnail just because the top-left corner of your image happened to be a big patch of featureless sky. This post is an overview of usage and implementation. For a more general discussion, see my post on the methods behind the script. Also check out the live demo of Opticrop, with a slick jQuery interface. You can also get the Opticrop code on Github.
Usage
To use the Opticrop image-cropping script, download opticrop.php and save it into its own folder on your webserver. You’ll need ImageMagick and the Imagick PHP extension installed. If all goes well, calling the script by its URL with the following arguments should give you an image in response.
- src – The path to the image to be cropped. This must be on the same machine as the script, but you can provide its path in URL form, as a relative path to the directory the script is in, or as an absolute path on the webserver’s document root (i.e. preceded by a /)
- w – The width of the thumbnail you want, in pixels.
- h – The height of the thumbnail you want, in pixels.
- gamma (optional) – A number between 0 and 1, for tuning the “tightness” of the crop. Default is 0.2. See discussion.
- format (optional) – Either
img(default) orjson. If set tojson, script will return a JSON-encoded object containing the height, width, and x and y coordinates of the top-left corner of the optimal crop region in the full-sized image. - cache (optional) – Either
yes(default),no, orrefresh. Set tonoto disable caching temporarily for current request, andrefreshto update the cached image for the given set of parameters. - debug (optional) – Either 0 (default) or 1. If set to 1, returns a page with debugging info rather than an image.
For example, to run my copy of the script on a test image on my server, go to:
http://jueseph.com/scripts/opticrop/opticrop.php?src=test3.jpg&w=100&h=100&debug=1&cache=no
This will display some debug output, and the result image (a 100×100 thumbnail) at the very end. Remove the debug=1 from the URL to get just the result image.
Implementation
Explanation of script to come. Until then, you can see the source here.
Hi Jue,
Thanks a lot for sharing this script, it looks like it’s exactly what I’ve been looking for!
I’m trying to get it to work on my server, but I haven’t been successful yet, and I suspect it may be a problem with the version of Imagick I have installed.
Would you mind specifying which version of Imagick is needed for your script to run?
Many thanks!
Just thought I’d add the error message I’m getting, in case you have an idea what may be causing it:
I’m running the script with the url:
http://mysite.com/scripts/opticrop.php?src=testimage.jpg&w=100&h=100&debug=1&cache=no
And I’m getting this:
Fatal error: Trying to clone an uncloneable object of class Imagick in /var/www/mysite/scripts/opticrop.php on line 300
Any insight would be much appreciated!
The demo I’m hosting here is running on PHP 5.3.2 with Imagick module 3.0.0RC1 and ImageMagick 6.6.2-6 2010-06-16 Q16
I also have a test environment running on XAMPP with PHP 5.3.1, Imagick 2.3.0, and ImageMagick 6.6.2-4 2010-06-07 Q16
Both work just fine.
I imagine you can get away with slightly older versions for all 3, but haven’t bothered trying to track down what the minimum requirements are. Let me know if I can help further, and good to know the script helped you!
Thanks for the quick response, Wang!
I’ll look into installing a more recent version of Imagick and see if that fixes the problem.
Cheers!
How does one call the script from within HTML/PHP to embed an image within a page?
I’m fetching a source image from Movable Type’s asset system and trying to output an Opticrop thumbnail, but I can’t figure out how to call the Opticrop script in the right way given the file name of the asset provided by the CMS.
@Tim: Sorry, I didn’t get to finish writing up the documentation above. To use this in a webpage, set the src attribute of an img tag to the url of the script, and pass it a parameter containing the url of your image to be cropped. For example,
<img src=”http://jueseph.com/scripts/opticrop/opticrop.php?src=test3.jpg&w=100&h=100″ />
would display the 100×100 thumbnail of the image test3.jpg (i.e. jueseph.com/scripts/opticrop/test3.jpg, since the path is relative)
You could also give the script an absolute path, like
<img src=”http://jueseph.com/scripts/opticrop/opticrop.php?src=/scripts/opticrop/test3.jpg&w=100&h=100″ />
The only thing you can’t give it is a remote http path, which means you’ll have to copy the script onto your own server (and make sure ImageMagick, Imagick, PHP, etc are all installed and working properly) and use your own path for the script rather than the one to my script that I use in these examples.
This limitation was deliberate–otherwise I would have other people’s crop requests flooding my website. Let me know by email if you need more help setting things up–this page isn’t too detailed I realize.
Hey, I love the script. Can you make it resize remote images?
Hi Nathan, wasn’t planning on it–but I can help you set it up if you’re thinking about using it.
[...] site and ftp the file to your server. If you add a test image and visit the url as outlined in Jue’s demo you should see the successful “smart” cropping of the [...]
Wang,
Thanks for the great script. Perfect for what I have been looking for sometime now.
Is there a way you can release the code for the jquery demo page you have including the options of fix size etc.?
Yes, I’ve been thinking of releasing an updated version of the code + accessory code for a while now. I’ll let you know when I get a chance to do this.
Wang,
Cool. Thanks and thumbs up on the quick response.
P90X Meal Plan Download…
[...]just below, are some totally unrelated sites to ours, however, they are definitely worth checking out[...]…
Awesome script! Why not host it on Github so people can more easily work with it/fork it?
Ok, I should definitely search before posting comments about
https://github.com/jueseph/Opticrop
Haha, yeah it’s on Github, although I think I intended it mostly for personal use so it’s not very organized. Just added a link to it in this blog post, thanks for pointing that out.