<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Crop an image automatically using one of the available modes</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.imagecrop.html">imagecrop</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.imagedashedline.html">imagedashedline</a></div>
<div class="up"><a href="ref.image.html">GD and Image Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.imagecropauto" class="refentry">
<div class="refnamediv">
<h1 class="refname">imagecropauto</h1>
<p class="verinfo">(PHP 5 >= 5.5.0, PHP 7)</p><p class="refpurpose"><span class="refname">imagecropauto</span> — <span class="dc-title">Crop an image automatically using one of the available modes</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.imagecropauto-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">resource</span> <span class="methodname"><strong>imagecropauto</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$image</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$mode</code><span class="initializer"> = -1</span></span>
[, <span class="methodparam"><span class="type">float</span> <code class="parameter">$threshold</code><span class="initializer"> = .5</span></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$color</code><span class="initializer"> = -1</span></span>
]]] )</div>
<p class="para rdfs-comment">
Automatically crops an image according to the given
<code class="parameter">mode</code>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.imagecropauto-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<code class="parameter">
image</code></dt>
<dd>
<p class="para">An image resource, returned by one of the image creation functions,
such as <span class="function"><a href="function.imagecreatetruecolor.html" class="function">imagecreatetruecolor()</a></span>.</p></dd>
<dt>
<code class="parameter">mode</code></dt>
<dd>
<p class="para">
One of the following constants:
</p>
<dl>
<dt>
<strong><code>IMG_CROP_DEFAULT</code></strong></dt>
<dd>
<span class="simpara">
Attempts to use <strong><code>IMG_CROP_TRANSPARENT</code></strong> and if it
fails it falls back to <strong><code>IMG_CROP_SIDES</code></strong>.
</span>
</dd>
<dt>
<strong><code>IMG_CROP_TRANSPARENT</code></strong></dt>
<dd>
<span class="simpara">
Crops out a transparent background.
</span>
</dd>
<dt>
<strong><code>IMG_CROP_BLACK</code></strong></dt>
<dd>
<span class="simpara">
Crops out a black background.
</span>
</dd>
<dt>
<strong><code>IMG_CROP_WHITE</code></strong></dt>
<dd>
<span class="simpara">
Crops out a white background.
</span>
</dd>
<dt>
<strong><code>IMG_CROP_SIDES</code></strong></dt>
<dd>
<span class="simpara">
Uses the 4 corners of the image to attempt to detect the background to
crop.
</span>
</dd>
<dt>
<strong><code>IMG_CROP_THRESHOLD</code></strong></dt>
<dd>
<span class="simpara">
Crops an image using the given <code class="parameter">threshold</code> and
<code class="parameter">color</code>.
</span>
</dd>
</dl>
</dd>
<dt>
<code class="parameter">threshold</code></dt>
<dd>
<p class="para">
Specifies the tolerance in percent to be used while comparing the image
color and the color to crop. The method used to calculate the color
difference is based on the color distance in the RGB(a) cube.
</p>
<p class="para">
Used only in <strong><code>IMG_CROP_THRESHOLD</code></strong> mode.
</p>
</dd>
<dt>
<code class="parameter">color</code></dt>
<dd>
<p class="para">
Either an RGB color value or a palette index.
</p>
<p class="para">
Used only in <strong><code>IMG_CROP_THRESHOLD</code></strong> mode.
</p>
</dd>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.imagecropauto-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns a cropped image resource on success or <strong><code>FALSE</code></strong> on failure.
If no cropping would occur, or the complete image would be cropped, that is
treated as failure, i.e. <span class="function"><a href="function.imagecrop.html" class="function">imagecrop()</a></span> returns <strong><code>FALSE</code></strong>.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.imagecropauto-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-3786">
<p><strong>Example #1 Proper handling of auto-cropping</strong></p>
<div class="example-contents"><p>
As noted in the return value section, <span class="function"><strong>imagecropauto()</strong></span>
returns <strong><code>FALSE</code></strong> when there is either nothing to crop or the whole image
would be cropped. In this example we have an image resource
<em>$im</em> which should be automatically cropped only if there
is something to crop; otherwise we want to proceed with the original image.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$cropped </span><span style="color: #007700">= </span><span style="color: #0000BB">imagecropauto</span><span style="color: #007700">(</span><span style="color: #0000BB">$im</span><span style="color: #007700">, </span><span style="color: #0000BB">IMG_CROP_DEFAULT</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$cropped </span><span style="color: #007700">!== </span><span style="color: #0000BB">false</span><span style="color: #007700">) { </span><span style="color: #FF8000">// in case a new image resource was returned<br /> </span><span style="color: #0000BB">imagedestroy</span><span style="color: #007700">(</span><span style="color: #0000BB">$im</span><span style="color: #007700">); </span><span style="color: #FF8000">// we destroy the original image<br /> </span><span style="color: #0000BB">$im </span><span style="color: #007700">= </span><span style="color: #0000BB">$cropped</span><span style="color: #007700">; </span><span style="color: #FF8000">// and assign the cropped image to $im<br /></span><span style="color: #007700">}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.imagecropauto-seealso">
<h3 class="title">See Also</h3>
<ul class="simplelist">
<li class="member"><span class="function"><a href="function.imagecrop.html" class="function" rel="rdfs-seeAlso">imagecrop()</a> - Crop an image to the given rectangle</span></li>
</ul>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.imagecrop.html">imagecrop</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.imagedashedline.html">imagedashedline</a></div>
<div class="up"><a href="ref.image.html">GD and Image Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
