Almost-minimal filesystem based blog.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

695 lines
18 KiB

  1. =head1 NAME
  2. Imager::Filters - Entire Image Filtering Operations
  3. =head1 SYNOPSIS
  4. use Imager;
  5. $img = ...;
  6. $img->filter(type=>'autolevels');
  7. $img->filter(type=>'autolevels', lsat=>0.2);
  8. $img->filter(type=>'turbnoise')
  9. # and lots of others
  10. load_plugin("dynfilt/dyntest.so")
  11. or die "unable to load plugin\n";
  12. $img->filter(type=>'lin_stretch', a=>35, b=>200);
  13. unload_plugin("dynfilt/dyntest.so")
  14. or die "unable to load plugin\n";
  15. $out = $img->difference(other=>$other_img);
  16. =head1 DESCRIPTION
  17. Filters are operations that have similar calling interface.
  18. =over
  19. =item filter
  20. Parameters:
  21. =over
  22. =item *
  23. type - the type of filter, see L</Types of Filters>.
  24. =item *
  25. many other possible parameters, see L</Types of Filters> below.
  26. =back
  27. =back
  28. =head2 Types of Filters
  29. Here is a list of the filters that are always avaliable in Imager.
  30. This list can be obtained by running the C<filterlist.perl> script
  31. that comes with the module source.
  32. Filter Arguments Default value
  33. autolevels lsat 0.1
  34. usat 0.1
  35. skew 0
  36. bumpmap bump lightx lighty
  37. elevation 0
  38. st 2
  39. bumpmap_complex bump
  40. channel 0
  41. tx 0
  42. ty 0
  43. Lx 0.2
  44. Ly 0.4
  45. Lz -1
  46. cd 1.0
  47. cs 40.0
  48. n 1.3
  49. Ia (0 0 0)
  50. Il (255 255 255)
  51. Is (255 255 255)
  52. contrast intensity
  53. conv coef
  54. fountain xa ya xb yb
  55. ftype linear
  56. repeat none
  57. combine none
  58. super_sample none
  59. ssample_param 4
  60. segments(see below)
  61. gaussian stddev
  62. gradgen xo yo colors
  63. dist 0
  64. hardinvert
  65. mosaic size 20
  66. noise amount 3
  67. subtype 0
  68. postlevels levels 10
  69. radnoise xo 100
  70. yo 100
  71. ascale 17.0
  72. rscale 0.02
  73. turbnoise xo 0.0
  74. yo 0.0
  75. scale 10.0
  76. unsharpmask stddev 2.0
  77. scale 1.0
  78. watermark wmark
  79. pixdiff 10
  80. tx 0
  81. ty 0
  82. All parameters must have some value but if a parameter has a default
  83. value it may be omitted when calling the filter function.
  84. Every one of these filters modifies the image in place.
  85. A reference of the filters follows:
  86. =over
  87. =item autolevels
  88. scales the value of each channel so that the values in the image will
  89. cover the whole possible range for the channel. I<lsat> and I<usat>
  90. truncate the range by the specified fraction at the top and bottom of
  91. the range respectivly.
  92. # increase contrast per channel, losing little detail
  93. $img->filter(type=>"autolevels")
  94. or die $img->errstr;
  95. # increase contrast, losing 20% of highlight at top and bottom range
  96. $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
  97. or die $img->errstr;
  98. =item bumpmap
  99. uses the channel I<elevation> image I<bump> as a bumpmap on your
  100. image, with the light at (I<lightx>, I<lightty>), with a shadow length
  101. of I<st>.
  102. $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
  103. lightx=>10, lighty=>10, st=>5)
  104. or die $img->errstr;
  105. =item bumpmap_complex
  106. uses the channel I<channel> image I<bump> as a bumpmap on your image.
  107. If Lz<0 the three L parameters are considered to be the direction of
  108. the light. If Lz>0 the L parameters are considered to be the light
  109. position. I<Ia> is the ambient colour, I<Il> is the light colour,
  110. I<Is> is the color of specular highlights. I<cd> is the diffuse
  111. coefficient and I<cs> is the specular coefficient. I<n> is the
  112. shininess of the surface.
  113. $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
  114. or die $img->errstr;
  115. =item contrast
  116. scales each channel by I<intensity>. Values of I<intensity> < 1.0
  117. will reduce the contrast.
  118. # higher contrast
  119. $img->filter(type=>"contrast", intensity=>1.3)
  120. or die $img->errstr;
  121. # lower contrast
  122. $img->filter(type=>"contrast", intensity=>0.8)
  123. or die $img->errstr;
  124. =item conv
  125. performs 2 1-dimensional convolutions on the image using the values
  126. from I<coef>. I<coef> should be have an odd length and the sum of the
  127. coefficients must be non-zero.
  128. # sharper
  129. $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
  130. or die $img->errstr;
  131. # blur
  132. $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
  133. or die $img->errstr;
  134. =item fountain
  135. renders a fountain fill, similar to the gradient tool in most paint
  136. software. The default fill is a linear fill from opaque black to
  137. opaque white. The points A(xa, ya) and B(xb, yb) control the way the
  138. fill is performed, depending on the ftype parameter:
  139. =over
  140. =item linear
  141. the fill ramps from A through to B.
  142. =item bilinear
  143. the fill ramps in both directions from A, where AB defines the length
  144. of the gradient.
  145. =item radial
  146. A is the center of a circle, and B is a point on it's circumference.
  147. The fill ramps from the center out to the circumference.
  148. =item radial_square
  149. A is the center of a square and B is the center of one of it's sides.
  150. This can be used to rotate the square. The fill ramps out to the
  151. edges of the square.
  152. =item revolution
  153. A is the centre of a circle and B is a point on it's circumference. B
  154. marks the 0 and 360 point on the circle, with the fill ramping
  155. clockwise.
  156. =item conical
  157. A is the center of a circle and B is a point on it's circumference. B
  158. marks the 0 and point on the circle, with the fill ramping in both
  159. directions to meet opposite.
  160. =back
  161. The I<repeat> option controls how the fill is repeated for some
  162. I<ftype>s after it leaves the AB range:
  163. =over
  164. =item none
  165. no repeats, points outside of each range are treated as if they were
  166. on the extreme end of that range.
  167. =item sawtooth
  168. the fill simply repeats in the positive direction
  169. =item triangle
  170. the fill repeats in reverse and then forward and so on, in the
  171. positive direction
  172. =item saw_both
  173. the fill repeats in both the positive and negative directions (only
  174. meaningful for a linear fill).
  175. =item tri_both
  176. as for triangle, but in the negative direction too (only meaningful
  177. for a linear fill).
  178. =back
  179. By default the fill simply overwrites the whole image (unless you have
  180. parts of the range 0 through 1 that aren't covered by a segment), if
  181. any segments of your fill have any transparency, you can set the
  182. I<combine> option to 'normal' to have the fill combined with the
  183. existing pixels. See the description of I<combine> in L<Imager::Fill>.
  184. If your fill has sharp edges, for example between steps if you use
  185. repeat set to 'triangle', you may see some aliased or ragged edges.
  186. You can enable super-sampling which will take extra samples within the
  187. pixel in an attempt anti-alias the fill.
  188. The possible values for the super_sample option are:
  189. =over
  190. =item none
  191. no super-sampling is done
  192. =item grid
  193. a square grid of points are sampled. The number of points sampled is
  194. the square of ceil(0.5 + sqrt(ssample_param)).
  195. =item random
  196. a random set of points within the pixel are sampled. This looks
  197. pretty bad for low ssample_param values.
  198. =item circle
  199. the points on the radius of a circle within the pixel are sampled.
  200. This seems to produce the best results, but is fairly slow (for now).
  201. =back
  202. You can control the level of sampling by setting the ssample_param
  203. option. This is roughly the number of points sampled, but depends on
  204. the type of sampling.
  205. The segments option is an arrayref of segments. You really should use
  206. the L<Imager::Fountain> class to build your fountain fill. Each
  207. segment is an array ref containing:
  208. =over
  209. =item start
  210. a floating point number between 0 and 1, the start of the range of
  211. fill parameters covered by this segment.
  212. =item middle
  213. a floating point number between start and end which can be used to
  214. push the color range towards one end of the segment.
  215. =item end
  216. a floating point number between 0 and 1, the end of the range of fill
  217. parameters covered by this segment. This should be greater than
  218. start.
  219. =item c0
  220. =item c1
  221. The colors at each end of the segment. These can be either
  222. Imager::Color or Imager::Color::Float objects.
  223. =item segment type
  224. The type of segment, this controls the way the fill parameter varies
  225. over the segment. 0 for linear, 1 for curved (unimplemented), 2 for
  226. sine, 3 for sphere increasing, 4 for sphere decreasing.
  227. =item color type
  228. The way the color varies within the segment, 0 for simple RGB, 1 for
  229. hue increasing and 2 for hue decreasing.
  230. =back
  231. Don't forget to use Imager::Fountain instead of building your own.
  232. Really. It even loads GIMP gradient files.
  233. # build the gradient the hard way - linear from black to white,
  234. # then back again
  235. my @simple =
  236. (
  237. [ 0, 0.25, 0.5, 'black', 'white', 0, 0 ],
  238. [ 0.5. 0.75, 1.0, 'white', 'black', 0, 0 ],
  239. );
  240. # across
  241. my $linear = $img->copy;
  242. $linear->filter(type => "fountain",
  243. ftype => 'linear',
  244. repeat => 'sawtooth',
  245. segments => \@simple,
  246. xa => 0,
  247. ya => $linear->getheight / 2,
  248. xb => $linear->getwidth - 1,
  249. yb => $linear->getheight / 2)
  250. or die $linear->errstr;
  251. # around
  252. my $revolution = $img->copy;
  253. $revolution->filter(type => "fountain",
  254. ftype => 'revolution',
  255. segments => \@simple,
  256. xa => $revolution->getwidth / 2,
  257. ya => $revolution->getheight / 2,
  258. xb => $revolution->getwidth / 2,
  259. yb => 0)
  260. or die $revolution->errstr;
  261. # out from the middle
  262. my $radial = $img->copy;
  263. $radial->filter(type => "fountain",
  264. ftype => 'radial',
  265. segments => \@simple,
  266. xa => $im->getwidth / 2,
  267. ya => $im->getheight / 2,
  268. xb => $im->getwidth / 2,
  269. yb => 0)
  270. or die $radial->errstr;
  271. =item gaussian
  272. performs a gaussian blur of the image, using I<stddev> as the standard
  273. deviation of the curve used to combine pixels, larger values give
  274. bigger blurs. For a definition of Gaussian Blur, see:
  275. http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
  276. Values of C<stddev> around 0.5 provide a barely noticable blur, values
  277. around 5 provide a very strong blur.
  278. # only slightly blurred
  279. $img->filter(type=>"gaussian", stddev=>0.5)
  280. or die $img->errstr;
  281. # more strongly blurred
  282. $img->filter(type=>"gaussian", stddev=>5)
  283. or die $img->errstr;
  284. =item gradgen
  285. renders a gradient, with the given I<colors> at the corresponding
  286. points (x,y) in I<xo> and I<yo>. You can specify the way distance is
  287. measured for color blending by setting I<dist> to 0 for Euclidean, 1
  288. for Euclidean squared, and 2 for Manhattan distance.
  289. $img->filter(type="gradgen",
  290. xo=>[ 10, 50, 10 ],
  291. yo=>[ 10, 50, 50 ],
  292. colors=>[ qw(red blue green) ]);
  293. =item hardinvert
  294. inverts the image, black to white, white to black. All channels are
  295. inverted, including the alpha channel if any.
  296. $img->filter(type=>"hardinvert")
  297. or die $img->errstr;
  298. =item mosaic
  299. produces averaged tiles of the given I<size>.
  300. $img->filter(type=>"mosaic", size=>5)
  301. or die $img->errstr;
  302. =item noise
  303. adds noise of the given I<amount> to the image. If I<subtype> is
  304. zero, the noise is even to each channel, otherwise noise is added to
  305. each channel independently.
  306. # monochrome noise
  307. $img->filter(type=>"noise", amount=>20, subtype=>0)
  308. or die $img->errstr;
  309. # color noise
  310. $img->filter(type=>"noise", amount=>20, subtype=>1)
  311. or die $img->errstr;
  312. =item radnoise
  313. renders radiant Perlin turbulent noise. The centre of the noise is at
  314. (I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
  315. and I<rscale> the radial scale, higher numbers give more detail.
  316. $img->filter(type=>"radnoise", xo=>50, yo=>50,
  317. ascale=>1, rscale=>0.02)
  318. or die $img->errstr;
  319. =item postlevels
  320. alters the image to have only I<levels> distinct level in each
  321. channel.
  322. $img->filter(type=>"postlevels", levels=>10)
  323. or die $img->errstr;
  324. =item turbnoise
  325. renders Perlin turbulent noise. (I<xo>, I<yo>) controls the origin of
  326. the noise, and I<scale> the scale of the noise, with lower numbers
  327. giving more detail.
  328. $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
  329. or die $img->errstr;
  330. =item unsharpmask
  331. performs an unsharp mask on the image. This increases the contrast of
  332. edges in the image.
  333. This is the result of subtracting a gaussian blurred version of the
  334. image from the original. I<stddev> controls the stddev parameter of
  335. the gaussian blur. Each output pixel is: in + I<scale> * (in -
  336. blurred).
  337. $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
  338. or die $img->errstr;
  339. unsharpmark has the following parameters:
  340. =over
  341. =item *
  342. stddev - this is equivalent to the C<Radius> value in the GIMP's
  343. unsharpmask filter. This controls the size of the contrast increase
  344. around edges, larger values will remove fine detail. You should
  345. probably experiement on the types of images you plan to work with.
  346. Default: 2.0.
  347. =item *
  348. scale - controls the strength of the edge enhancement, equivalent to
  349. I<Amount> in the GIMP's unsharp mask filter. Default: 1.0.
  350. =back
  351. =item watermark
  352. applies I<wmark> as a watermark on the image with strength I<pixdiff>,
  353. with an origin at (I<tx>, I<ty>)
  354. $img->filter(type=>"watermark", tx=>10, ty=>50,
  355. wmark=>$wmark_image, pixdiff=>50)
  356. or die $img->errstr;
  357. =back
  358. A demonstration of most of the filters can be found at:
  359. http://www.develop-help.com/imager/filters.html
  360. =head2 External Filters
  361. As of Imager 0.48 you can create perl or XS based filters and hook
  362. them into Imager's filter() method:
  363. =over
  364. =item register_filter
  365. Registers a filter so it is visible via Imager's filter() method.
  366. Imager->register_filter(type => 'your_filter',
  367. defaults => { parm1 => 'default1' },
  368. callseq => [ qw/image parm1/ ],
  369. callsub => \&your_filter);
  370. $img->filter(type=>'your_filter', parm1 => 'something');
  371. The following parameters are needed:
  372. =over
  373. =item *
  374. type - the type value that will be supplied to filter() to use your
  375. filter.
  376. =item *
  377. defaults - a hash of defaults for the filter's parameters
  378. =item *
  379. callseq - a reference to an array of required parameter names.
  380. =item *
  381. callsub - a code reference called to execute your filter. The
  382. parameters passed to filter() are supplied as a list of parameter
  383. name, value ... which can be assigned to a hash.
  384. The special parameters C<image> and C<imager> are supplied as the low
  385. level image object from $self and $self itself respectively.
  386. The function you supply must modify the image in place.
  387. =back
  388. See Imager::Filter::Mandelbrot for an example.
  389. =back
  390. =head2 Plugins
  391. The plugin interface is deprecated. Please use the Imager API, see
  392. L</Imager::API> and L<External Filters> for details
  393. It is possible to add filters to the module without recompiling the
  394. module itself. This is done by using DSOs (Dynamic shared object)
  395. avaliable on most systems. This way you can maintain our own filters
  396. and not have to get me to add it, or worse patch every new version of
  397. the Module. Modules can be loaded AND UNLOADED at runtime. This
  398. means that you can have a server/daemon thingy that can do something
  399. like:
  400. load_plugin("dynfilt/dyntest.so")
  401. or die "unable to load plugin\n";
  402. $img->filter(type=>'lin_stretch', a=>35, b=>200);
  403. unload_plugin("dynfilt/dyntest.so")
  404. or die "unable to load plugin\n";
  405. Someone decides that the filter is not working as it should -
  406. dyntest.c modified and recompiled.
  407. load_plugin("dynfilt/dyntest.so")
  408. or die "unable to load plugin\n";
  409. $img->filter(%hsh);
  410. An example plugin comes with the module - Please send feedback to
  411. addi@umich.edu if you test this.
  412. Note: This seems to test ok on the following systems:
  413. Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
  414. If you test this on other systems please let me know.
  415. =over
  416. =item load_plugin
  417. This is a function, not a method, exported by default. You should
  418. import this function explicitly for future compatibility if you need
  419. it.
  420. Accepts a single parameter, the name of a shared library file to load.
  421. Returns true on success. Check Imager->errstr on failure.
  422. =item unload_plugin
  423. This is a function, not a method, which is exported by default. You
  424. should import this function explicitly for future compatibility if you
  425. need it.
  426. Accepts a single parameter, the name of a shared library to unload.
  427. This library must have been previously loaded by load_plugin().
  428. Returns true on success. Check Imager->errstr on failure.
  429. =back
  430. =head2 Image Difference
  431. =over
  432. =item difference
  433. You can create a new image that is the difference between 2 other images.
  434. my $diff = $img->difference(other=>$other_img);
  435. For each pixel in $img that is different to the pixel in $other_img,
  436. the pixel from $other_img is given, otherwise the pixel is transparent
  437. black.
  438. This can be used for debugging image differences ("Where are they
  439. different?"), and for optimizing animated GIFs.
  440. Note that $img and $other_img must have the same number of channels.
  441. The width and height of $diff will be the minimum of each of the width
  442. and height of $img and $other_img.
  443. Parameters:
  444. =over
  445. =item *
  446. other - the other image object to compare against
  447. =item *
  448. mindist - the difference between corresponding samples must be greater
  449. than I<mindist> for the pixel to be considered different. So a value
  450. of zero returns all different pixels, not all pixels. Range: 0 to 255
  451. inclusive. Default: 0.
  452. For large sample images this is scaled down to the range 0 .. 1.
  453. =back
  454. =back
  455. =head1 AUTHOR
  456. Arnar M. Hrafnkelsson, Tony Cook <tony@imager.perl.org>.
  457. =head1 SEE ALSO
  458. Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
  459. =head1 REVISION
  460. $Revision: 1252 $
  461. =cut