reference/image/functions/imagecropauto.xml
e6849e1e63c206f34d25378ea2f1d0bde4e9a396
e6849e1e63c206f34d25378ea2f1d0bde4e9a396
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
4
3
<refentry xml:id="function.imagecropauto" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>imagecropauto</refname>
...
...
@@ -10,18 +9,16 @@
10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
11
<methodsynopsis>
13
-
<type>resource</type><methodname>imagecropauto</methodname>
14
-
<methodparam><type>resource</type><parameter>image</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer>-1</initializer></methodparam>
16
-
<methodparam choice="opt"><type>float</type><parameter>threshold</parameter><initializer>.5</initializer></methodparam>
12
+
<type class="union"><type>GdImage</type><type>false</type></type><methodname>imagecropauto</methodname>
13
+
<methodparam><type>GdImage</type><parameter>image</parameter></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>IMG_CROP_DEFAULT</constant></initializer></methodparam>
15
+
<methodparam choice="opt"><type>float</type><parameter>threshold</parameter><initializer>0.5</initializer></methodparam>
17
16
<methodparam choice="opt"><type>int</type><parameter>color</parameter><initializer>-1</initializer></methodparam>
18
17
</methodsynopsis>
19
18
<para>
20
-
19
+
Automatically crops an image according to the given
20
+
<parameter>mode</parameter>.
21
21
</para>
22
-
23
-
&warn.undocumented.func;
24
-
25
22
</refsect1>
26
23
27
24
<refsect1 role="parameters">
...
...
@@ -32,23 +29,92 @@
32
29
<term><parameter>mode</parameter></term>
33
30
<listitem>
34
31
<para>
35
-
One of <constant>IMG_CROP_*</constant> constants.
32
+
One of the following constants:
36
33
</para>
34
+
<variablelist>
35
+
<varlistentry>
36
+
<term><constant>IMG_CROP_DEFAULT</constant></term>
37
+
<listitem>
38
+
<simpara>
39
+
Same as <constant>IMG_CROP_TRANSPARENT</constant>.
40
+
Before PHP 7.4.0, the bundled libgd fell back to <constant>IMG_CROP_SIDES</constant>,
41
+
if the image had no transparent color.
42
+
</simpara>
43
+
</listitem>
44
+
</varlistentry>
45
+
<varlistentry>
46
+
<term><constant>IMG_CROP_TRANSPARENT</constant></term>
47
+
<listitem>
48
+
<simpara>
49
+
Crops out a transparent background.
50
+
</simpara>
51
+
</listitem>
52
+
</varlistentry>
53
+
<varlistentry>
54
+
<term><constant>IMG_CROP_BLACK</constant></term>
55
+
<listitem>
56
+
<simpara>
57
+
Crops out a black background.
58
+
</simpara>
59
+
</listitem>
60
+
</varlistentry>
61
+
<varlistentry>
62
+
<term><constant>IMG_CROP_WHITE</constant></term>
63
+
<listitem>
64
+
<simpara>
65
+
Crops out a white background.
66
+
</simpara>
67
+
</listitem>
68
+
</varlistentry>
69
+
<varlistentry>
70
+
<term><constant>IMG_CROP_SIDES</constant></term>
71
+
<listitem>
72
+
<simpara>
73
+
Uses the 4 corners of the image to attempt to detect the background to
74
+
crop.
75
+
</simpara>
76
+
</listitem>
77
+
</varlistentry>
78
+
<varlistentry>
79
+
<term><constant>IMG_CROP_THRESHOLD</constant></term>
80
+
<listitem>
81
+
<simpara>
82
+
Crops an image using the given <parameter>threshold</parameter> and
83
+
<parameter>color</parameter>.
84
+
</simpara>
85
+
</listitem>
86
+
</varlistentry>
87
+
</variablelist>
37
88
</listitem>
38
89
</varlistentry>
39
90
<varlistentry>
40
91
<term><parameter>threshold</parameter></term>
41
92
<listitem>
42
93
<para>
43
-
Used in <constant>IMG_CROP_THRESHOLD</constant> mode.
94
+
Specifies the tolerance in percent to be used while comparing the image
95
+
color and the color to crop. The method used to calculate the color
96
+
difference is based on the color distance in the RGB(a) cube.
44
97
</para>
98
+
<para>
99
+
Used only in <constant>IMG_CROP_THRESHOLD</constant> mode.
100
+
</para>
101
+
<note>
102
+
<simpara>
103
+
Before PHP 7.4.0, the bundled libgd used a somewhat different algorithm,
104
+
so the same <parameter>threshold</parameter> yielded different results
105
+
for system and bundled libgd.
106
+
</simpara>
107
+
</note>
45
108
</listitem>
46
109
</varlistentry>
47
110
<varlistentry>
48
111
<term><parameter>color</parameter></term>
49
112
<listitem>
50
113
<para>
51
-
Used in <constant>IMG_CROP_THRESHOLD</constant> mode.
114
+
Either an RGB color value or a palette index.
115
+
</para>
116
+
<para>
117
+
Used only in <constant>IMG_CROP_THRESHOLD</constant> mode.
52
118
</para>
53
119
</listitem>
54
120
</varlistentry>
...
...
@@ -58,12 +124,88 @@
58
124
<refsect1 role="returnvalues">
59
125
&reftitle.returnvalues;
60
126
<para>
61
-
Return cropped image resource on success&return.falseforfailure;.
127
+
Returns a cropped image object on success&return.falseforfailure;.
128
+
&false; is also returned if the whole image was cropped.
62
129
</para>
63
130
</refsect1>
64
131
65
-
</refentry>
132
+
<refsect1 role="changelog">
133
+
&reftitle.changelog;
134
+
<informaltable>
135
+
<tgroup cols="2">
136
+
<thead>
137
+
<row>
138
+
<entry>&Version;</entry>
139
+
<entry>&Description;</entry>
140
+
</row>
141
+
</thead>
142
+
<tbody>
143
+
&gd.changelog.image-param;
144
+
<row>
145
+
<entry>8.0.0</entry>
146
+
<entry>
147
+
On success, this function returns a <classname>GDImage</classname> instance now;
148
+
previously, a <type>resource</type> was returned.
149
+
</entry>
150
+
</row>
151
+
<row>
152
+
<entry>7.4.0</entry>
153
+
<entry>
154
+
The behavior of imagecropauto() in the bundled libgd has been synced with
155
+
that of system libgd: <constant>IMG_CROP_DEFAULT</constant> no longer falls
156
+
back to <constant>IMG_CROP_SIDES</constant> and threshold-cropping now uses
157
+
the same algorithm as system libgd.
158
+
</entry>
159
+
</row>
160
+
<row>
161
+
<entry>7.4.0</entry>
162
+
<entry>
163
+
The default value of <parameter>mode</parameter> has been changed to
164
+
<constant>IMG_CROP_AUTO</constant>. Formerly, the default value has been
165
+
<literal>-1</literal> which corresponds to <constant>IMG_CROP_DEFAULT</constant>,
166
+
but passing <literal>-1</literal> is now deprecated.
167
+
</entry>
168
+
</row>
169
+
</tbody>
170
+
</tgroup>
171
+
</informaltable>
172
+
</refsect1>
173
+
174
+
<refsect1 role="examples">
175
+
&reftitle.examples;
176
+
<para>
177
+
<example>
178
+
<title>Proper handling of auto-cropping</title>
179
+
<para>
180
+
As noted in the return value section, <function>imagecropauto</function>
181
+
returns &false; if the whole image
182
+
was cropped. In this example we have an image object
183
+
<literal>$im</literal> which should be automatically cropped only if there
184
+
is something to crop; otherwise we want to proceed with the original image.
185
+
</para>
186
+
<programlisting role="php">
187
+
<![CDATA[
188
+
<?php
189
+
$cropped = imagecropauto($im, IMG_CROP_DEFAULT);
190
+
if ($cropped !== false) { // in case a new image object was returned
191
+
imagedestroy($im); // we destroy the original image
192
+
$im = $cropped; // and assign the cropped image to $im
193
+
}
194
+
?>
195
+
]]>
196
+
</programlisting>
197
+
</example>
198
+
</para>
199
+
</refsect1>
200
+
201
+
<refsect1 role="seealso">
202
+
&reftitle.seealso;
203
+
<simplelist>
204
+
<member><function>imagecrop</function></member>
205
+
</simplelist>
206
+
</refsect1>
66
207
208
+
</refentry>
67
209
<!-- Keep this comment at the end of the file
68
210
Local variables:
69
211
mode: sgml
70
212