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.

800 lines
22 KiB

  1. =head1 NAME
  2. Imager::Transformations - Simple transformations of one image into another.
  3. =head1 SYNOPSIS
  4. use Imager;
  5. $newimg = $img->copy();
  6. $newimg = $img->scale(xpixels=>400, qtype => 'mixing');
  7. $newimg = $img->scale(xpixels=>400, ypixels=>400);
  8. $newimg = $img->scale(xpixels=>400, ypixels=>400, type=>'min');
  9. $newimg = $img->scale(scalefactor=>0.25);
  10. $newimg = $img->scaleX(pixels=>400);
  11. $newimg = $img->scaleX(scalefactor=>0.25);
  12. $newimg = $img->scaleY(pixels=>400);
  13. $newimg = $img->scaleY(scalefactor=>0.25);
  14. $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
  15. $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
  16. $dest->paste(left=>40,top=>20,img=>$logo);
  17. $img->rubthrough(src=>$srcimage,tx=>30, ty=>50);
  18. $img->rubthrough(src=>$srcimage,tx=>30, ty=>50,
  19. src_minx=>20, src_miny=>30,
  20. src_maxx=>20, src_maxy=>30);
  21. $img->flip(dir=>"h"); # horizontal flip
  22. $img->flip(dir=>"vh"); # vertical and horizontal flip
  23. $newimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
  24. my $rot20 = $img->rotate(degrees=>20);
  25. my $rotpi4 = $img->rotate(radians=>3.14159265/4);
  26. # Convert image to gray
  27. $new = $img->convert(preset=>'grey');
  28. # Swap red/green channel
  29. $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
  30. [ 1, 0, 0 ],
  31. [ 0, 0, 1 ] ]);
  32. # limit the range of red channel from 0..255 to 0..127
  33. @map = map { int( $_/2 } 0..255;
  34. $img->map( red=>\@map );
  35. # Apply a Gamma of 1.4
  36. my $gamma = 1.4;
  37. my @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  38. $img->map(all=>\@map); # inplace conversion
  39. =head1 DESCRIPTION
  40. The methods described in Imager::Transformations fall into two categories.
  41. Either they take an existing image and modify it in place, or they
  42. return a modified copy.
  43. Functions that modify inplace are C<flip()>, C<paste()> and
  44. C<rubthrough()>. If the original is to be left intact it's possible
  45. to make a copy and alter the copy:
  46. $flipped = $img->copy()->flip(dir=>'h');
  47. =head2 Image copying/resizing/cropping/rotating
  48. A list of the transformations that do not alter the source image follows:
  49. =over
  50. =item copy
  51. To create a copy of an image use the C<copy()> method. This is usefull
  52. if you want to keep an original after doing something that changes the image.
  53. $newimg = $orig->copy();
  54. =item scale
  55. X<scale>To scale an image so porportions are maintained use the
  56. C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
  57. parameter they will determine the width or height respectively. If
  58. both are given the one resulting in a larger image is used, unless you
  59. set the C<type> parameter to C<'min'>. example: C<$img> is 700 pixels
  60. wide and 500 pixels tall.
  61. $newimg = $img->scale(xpixels=>400); # 400x285
  62. $newimg = $img->scale(ypixels=>400); # 560x400
  63. $newimg = $img->scale(xpixels=>400,ypixels=>400); # 560x400
  64. $newimg = $img->scale(xpixels=>400,ypixels=>400,type=>'min'); # 400x285
  65. $newimg = $img->scale(xpixels=>400, ypixels=>400),type=>'nonprop'); # 400x400
  66. $newimg = $img->scale(scalefactor=>0.25); 175x125
  67. $newimg = $img->scale(); # 350x250
  68. If you want to create low quality previews of images you can pass
  69. C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
  70. sampling instead of filtering. It is much faster but also generates
  71. worse looking images - especially if the original has a lot of sharp
  72. variations and the scaled image is by more than 3-5 times smaller than
  73. the original.
  74. =over
  75. =item *
  76. xpixels, ypixels - desired size of the scaled image. The C<type>
  77. parameter controls whether the larger or smaller of the two possible
  78. sizes is chosen, or if the image is scaled non-proportionally.
  79. =item *
  80. constrain - an Image::Math::Constrain object defining the way in which
  81. the image size should be constrained.
  82. =item *
  83. scalefactor - if none of xpixels, ypixels, xscalefactor, yscalefactor
  84. or constrain is supplied then this is used as the ratio to scale by.
  85. Default: 0.5.
  86. =item *
  87. xscalefactor, yscalefactor - if both are supplied then the image is
  88. scaled as per these parameters, whether this is proportionally or not.
  89. New in Imager 0.54.
  90. =item *
  91. type - controls whether the larger or smaller of the two possible
  92. sizes is chosen, possible values are:
  93. =over
  94. =item *
  95. min - the smaller of the 2 sizes are chosen.
  96. =item *
  97. max - the larger of the 2 sizes. This is the default.
  98. =item *
  99. nonprop - non-proportional scaling. New in Imager 0.54.
  100. =back
  101. scale() will fail if C<type> is set to some other value.
  102. For example, if the original image is 400 pixels wide by 200 pixels
  103. high and C<xpixels> is set to 300, and C<ypixels> is set to 160. When
  104. C<type> is C<'min'> the resulting image is 300 x 150, when C<type> is
  105. C<'max'> the resulting image is 320 x 150.
  106. C<type> is only used if both C<xpixels> and C<ypixels> are supplied.
  107. =item *
  108. qtype - defines the quality of scaling performed. Possible values are:
  109. =over
  110. =item *
  111. C<normal> - high quality scaling. This is the default.
  112. =item *
  113. C<preview> - lower quality. When scaling down this will skip input
  114. pixels, eg. scaling by 0.5 will skip every other pixel. When scaling
  115. up this will duplicate pixels.
  116. =item *
  117. C<mixing> - implements the mixing algorithm implemented by pnmscale.
  118. This retains more detail when scaling down than C<normal>. When
  119. scaling down this proportionally accumulates sample data from the
  120. pixels, resulting in a proportional mix of all of the pixels. When
  121. scaling up this will mix pixels when the sampling grid crosses a pixel
  122. boundary but will otherwise copy pixel values.
  123. =back
  124. scale() will fail if C<qtype> is set to some other value.
  125. C<preview> is faster than C<mixing> which is much faster than C<normal>.
  126. =back
  127. To scale an image on a given axis without maintaining proportions, it
  128. is best to call the scaleX() and scaleY() methods with the required
  129. dimensions. eg.
  130. my $scaled = $img->scaleX(pixels=>400)->scaleY(pixels=>200);
  131. From Imager 0.54 you can scale without maintaining proportions either
  132. by supplying both the xscalefactor and yscalefactor arguments:
  133. my $scaled = $img->scale(xscalefactor => 0.5, yscalefactor => 0.67);
  134. or by supplying C<xpixels> and C<ypixels> and setting C<type> to
  135. "nonprop":
  136. my $scaled = $im->scale(xpixels => 200, ypixels => 200, type => 'nonprop');
  137. Returns a new scaled image on success. The source image is not
  138. modified.
  139. Returns false on failure, check the errstr() method for the reason for
  140. failure.
  141. A mandatory warning is produced if scale() is called in void context.
  142. # setup
  143. my $image = Imager->new;
  144. $image->read(file => 'somefile.jpg')
  145. or die $image->errstr;
  146. # all full quality unless indicated otherwise
  147. # half the size:
  148. my $half = $image->scale;
  149. # double the size
  150. my $double = $image->scale(scalefactor => 2.0);
  151. # so a 400 x 400 box fits in the resulting image:
  152. my $fit400x400inside = $image->scale(xpixels => 400, ypixels => 400);
  153. my $fit400x400inside2 = $image->scale(xpixels => 400, ypixels => 400,
  154. type=>'max');
  155. # fit inside a 400 x 400 box
  156. my $inside400x400 = $image->scale(xpixels => 400, ypixels => 400,
  157. type=>'min');
  158. # make it 400 pixels wide or high
  159. my $width400 = $image->scale(xpixels => 400);
  160. my $height400 = $image->scale(ypixels => 400);
  161. # low quality scales:
  162. # to half size
  163. my $low = $image->scale(qtype => 'preview');
  164. # mixing method scale
  165. my $mixed = $image->scale(qtype => 'mixing', scalefactor => 0.1);
  166. # using an Image::Math::Constrain object
  167. use Image::Math::Constrain;
  168. my $constrain = Image::Math::Constrain->new(800, 600);
  169. my $scaled = $image->scale(constrain => $constrain);
  170. # same as Image::Math::Constrain version
  171. my $scaled2 = $image->scale(xpixels => 800, ypixels => 600, type => 'min');
  172. =item scaleX
  173. scaleX() will scale along the X dimension, return a new image with the
  174. new width:
  175. my $newimg = $img->scaleX(pixels=>400); # 400x500
  176. $newimg = $img->scaleX(scalefactor=>0.25) # 175x500
  177. =over
  178. =item *
  179. scalefactor - the amount to scale the X axis. Ignored if C<pixels> is
  180. provided. Default: 0.5.
  181. =item *
  182. pixels - the new width of the image.
  183. =back
  184. Returns a new scaled image on success. The source image is not
  185. modified.
  186. Returns false on failure, check the errstr() method for the reason for
  187. failure.
  188. A mandatory warning is produced if scaleX() is called in void context.
  189. =item scaleY
  190. scaleY() will scale along the Y dimension, return a new image with the
  191. new height:
  192. $newimg = $img->scaleY(pixels=>400); # 700x400
  193. $newimg = $img->scaleY(scalefactor=>0.25) # 700x125
  194. =over
  195. =item *
  196. scalefactor - the amount to scale the Y axis. Ignored if C<pixels> is
  197. provided. Default: 0.5.
  198. =item *
  199. pixels - the new height of the image.
  200. =back
  201. Returns a new scaled image on success. The source image is not
  202. modified.
  203. Returns false on failure, check the errstr() method for the reason for
  204. failure.
  205. A mandatory warning is produced if scaleY() is called in void context.
  206. =item crop
  207. Another way to resize an image is to crop it. The parameters to
  208. crop are the edges of the area that you want in the returned image,
  209. where the right and bottom edges are non-inclusive. If a parameter is
  210. omitted a default is used instead.
  211. crop() returns the cropped image and does not modify the source image.
  212. The possible parameters are:
  213. =over
  214. =item *
  215. C<left> - the left edge of the area to be cropped. Default: 0
  216. =item *
  217. C<top> - the top edge of the area to be cropped. Default: 0
  218. =item *
  219. C<right> - the right edge of the area to be cropped. Default: right
  220. edge of image.
  221. =item *
  222. C<bottom> - the bottom edge of the area to be cropped. Default:
  223. bottom edge of image.
  224. =item *
  225. C<width> - width of the crop area. Ignored if both C<left> and C<right> are
  226. supplied. Centered on the image if neither C<left> nor C<right> are
  227. supplied.
  228. =item *
  229. C<height> - height of the crop area. Ignored if both C<top> and
  230. C<bottom> are supplied. Centered on the image if neither C<top> nor
  231. C<bottom> are supplied.
  232. =back
  233. For example:
  234. # these produce the same image
  235. $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
  236. $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
  237. $newimg = $img->crop(right=>100, bottom=>100, width=>50, height=>90);
  238. # and the following produce the same image
  239. $newimg = $img->crop(left=>50, right=>100);
  240. $newimg = $img->crop(left=>50, right=>100, top=>0,
  241. bottom=>$img->getheight);
  242. # grab the top left corner of the image
  243. $newimg = $img->crop(right=>50, bottom=>50);
  244. You can also specify width and height parameters which will produce a
  245. new image cropped from the center of the input image, with the given
  246. width and height.
  247. $newimg = $img->crop(width=>50, height=>50);
  248. If you supply C<left>, C<width> and C<right> values, the C<right>
  249. value will be ignored. If you supply C<top>, C<height> and C<bottom>
  250. values, the C<bottom> value will be ignored.
  251. The edges of the cropped area default to the edges of the source
  252. image, for example:
  253. # a vertical bar from the middle from top to bottom
  254. $newimg = $img->crop(width=>50);
  255. # the right half
  256. $newimg = $img->crop(left=>$img->getwidth() / 2);
  257. If the resulting image would have zero width or height then crop()
  258. returns false and $img->errstr is an appropriate error message.
  259. A mandatory warning is produced if crop() is called in void context.
  260. =item rotate
  261. Use the rotate() method to rotate an image. This method will return a
  262. new, rotated image.
  263. To rotate by an exact amount in degrees or radians, use the 'degrees'
  264. or 'radians' parameter:
  265. my $rot20 = $img->rotate(degrees=>20);
  266. my $rotpi4 = $img->rotate(radians=>3.14159265/4);
  267. Exact image rotation uses the same underlying transformation engine as
  268. the matrix_transform() method (see Imager::Engines).
  269. You can also supply a C<back> argument which acts as a background
  270. color for the areas of the image with no samples available (outside
  271. the rectangle of the source image.) This can be either an
  272. Imager::Color or Imager::Color::Float object. This is B<not> mixed
  273. transparent pixels in the middle of the source image, it is B<only>
  274. used for pixels where there is no corresponding pixel in the source
  275. image.
  276. To rotate in steps of 90 degrees, use the 'right' parameter:
  277. my $rotated = $img->rotate(right=>270);
  278. Rotations are clockwise for positive values.
  279. Parameters:
  280. =over
  281. =item *
  282. right - rotate by an exact multiple of 90 degrees, specified in
  283. degreess.
  284. =item *
  285. radians - rotate by an angle specified in radians.
  286. =item *
  287. degrees - rotate by an angle specified in degrees.
  288. =item *
  289. back - for C<radians> and C<degrees> this is the color used for the
  290. areas not covered by the original image. For example, the corners of
  291. an image rotated by 45 degrees.
  292. This can be either an Imager::Color object, an Imager::Color::Float
  293. object or any parameter that Imager can convert to a color object, see
  294. L<Imager::Draw/Color Parameters> for details.
  295. This is B<not> mixed transparent pixels in the middle of the source
  296. image, it is B<only> used for pixels where there is no corresponding
  297. pixel in the source image.
  298. Default: transparent black.
  299. =back
  300. # rotate 45 degrees clockwise,
  301. my $rotated = $img->rotate(degrees => 45);
  302. # rotate 10 degrees counter-clockwise
  303. # set pixels not sourced from the original to red
  304. my $rotated = $img->rotate(degrees => -10, back => 'red');
  305. =back
  306. =head2 Image pasting/flipping
  307. A list of the transformations that alter the source image follows:
  308. =over
  309. =item paste
  310. X<paste>To copy an image to onto another image use the C<paste()>
  311. method.
  312. $dest->paste(left=>40, top=>20, src=>$logo);
  313. That copies the entire C<$logo> image onto the C<$dest> image so that the
  314. upper left corner of the C<$logo> image is at (40,20).
  315. Parameters:
  316. =over
  317. =item *
  318. src, img - the source image. I<src> added for compatibility with
  319. rubthrough().
  320. =item *
  321. left, top - position in output of the top left of the pasted image.
  322. Default: (0,0)
  323. =item *
  324. src_minx, src_miny - the top left corner in the source image to start
  325. the paste from. Default: (0, 0)
  326. =item *
  327. src_maxx, src_maxy - the bottom right in the source image of the sub
  328. image to paste. This position is B<non> inclusive. Default: bottom
  329. right corner of the source image.
  330. =item *
  331. width, height - if the corresponding src_maxx or src_maxy is not
  332. defined then width or height is used for the width or height of the
  333. sub image to be pasted.
  334. =back
  335. # copy the 20x20 pixel image from (20,20) in $src_image to (10,10) in $img
  336. $img->paste(src=>$src_image,
  337. left => 10, top => 10,
  338. src_minx => 20, src_miny => 20,
  339. src_maxx => 40, src_maxx => 40);
  340. =item rubthrough
  341. A more complicated way of blending images is where one image is
  342. put 'over' the other with a certain amount of opaqueness. The
  343. method that does this is rubthrough.
  344. $img->rubthrough(src=>$overlay,
  345. tx=>30, ty=>50,
  346. src_minx=>20, src_miny=>30,
  347. src_maxx=>20, src_maxy=>30);
  348. That will take the sub image defined by I<$overlay> and
  349. I<[src_minx,src_maxx)[src_miny,src_maxy)> and overlay it on top of
  350. I<$img> with the upper left corner at (30,50). You can rub 2 or 4
  351. channel images onto a 3 channel image, or a 2 channel image onto a 1
  352. channel image. The last channel is used as an alpha channel. To add
  353. an alpha channel to an image see I<convert()>.
  354. Parameters:
  355. =over
  356. =item *
  357. tx, ty - location in the the target image ($self) to render the top
  358. left corner of the source.
  359. =item *
  360. src_minx, src_miny - the top left corner in the source to transfer to
  361. the target image. Default: (0, 0).
  362. =item *
  363. src_maxx, src_maxy - the bottom right in the source image of the sub
  364. image to overlay. This position is B<non> inclusive. Default: bottom
  365. right corner of the source image.
  366. =back
  367. # overlay all of $source onto $targ
  368. $targ->rubthrough(tx => 20, ty => 25, src => $source);
  369. # overlay the top left corner of $source onto $targ
  370. $targ->rubthrough(tx => 20, ty => 25, src => $source,
  371. src_maxx => 20, src_maxy => 20);
  372. # overlay the bottom right corner of $source onto $targ
  373. $targ->rubthrough(tx => 20, ty => 30, src => $src,
  374. src_minx => $src->getwidth() - 20,
  375. src_miny => $src->getheight() - 20);
  376. rubthrough() returns true on success. On failure check
  377. $target->errstr for the reason for failure.
  378. =item flip
  379. An inplace horizontal or vertical flip is possible by calling the
  380. C<flip()> method. If the original is to be preserved it's possible to
  381. make a copy first. The only parameter it takes is the C<dir>
  382. parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
  383. $img->flip(dir=>"h"); # horizontal flip
  384. $img->flip(dir=>"vh"); # vertical and horizontal flip
  385. $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
  386. flip() returns true on success. On failure check $img->errstr for the
  387. reason for failure.
  388. =back
  389. =head2 Color transformations
  390. =over
  391. =item convert
  392. You can use the convert method to transform the color space of an
  393. image using a matrix. For ease of use some presets are provided.
  394. The convert method can be used to:
  395. =over
  396. =item *
  397. convert an RGB or RGBA image to grayscale.
  398. =item *
  399. convert a grayscale image to RGB.
  400. =item *
  401. extract a single channel from an image.
  402. =item *
  403. set a given channel to a particular value (or from another channel)
  404. =back
  405. The currently defined presets are:
  406. =over
  407. =item gray
  408. =item grey
  409. converts an RGBA image into a grayscale image with alpha channel, or
  410. an RGB image into a grayscale image without an alpha channel.
  411. This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
  412. =item noalpha
  413. removes the alpha channel from a 2 or 4 channel image. An identity
  414. for other images.
  415. =item red
  416. =item channel0
  417. extracts the first channel of the image into a single channel image
  418. =item green
  419. =item channel1
  420. extracts the second channel of the image into a single channel image
  421. =item blue
  422. =item channel2
  423. extracts the third channel of the image into a single channel image
  424. =item alpha
  425. extracts the alpha channel of the image into a single channel image.
  426. If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
  427. the resulting image will be all white.
  428. =item rgb
  429. converts a grayscale image to RGB, preserving the alpha channel if any
  430. =item addalpha
  431. adds an alpha channel to a grayscale or RGB image. Preserves an
  432. existing alpha channel for a 2 or 4 channel image.
  433. =back
  434. For example, to convert an RGB image into a greyscale image:
  435. $new = $img->convert(preset=>'grey'); # or gray
  436. or to convert a grayscale image to an RGB image:
  437. $new = $img->convert(preset=>'rgb');
  438. The presets aren't necessary simple constants in the code, some are
  439. generated based on the number of channels in the input image.
  440. If you want to perform some other colour transformation, you can use
  441. the 'matrix' parameter.
  442. For each output pixel the following matrix multiplication is done:
  443. | channel[0] | | $c00, ..., $c0k | | inchannel[0] |
  444. | ... | = | ... | x | ... |
  445. | channel[k] | | $ck0, ..., $ckk | | inchannel[k] |
  446. 1
  447. Where C<k = $img-E<gt>getchannels()-1>.
  448. So if you want to swap the red and green channels on a 3 channel image:
  449. $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
  450. [ 1, 0, 0 ],
  451. [ 0, 0, 1 ] ]);
  452. or to convert a 3 channel image to greyscale using equal weightings:
  453. $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
  454. Convert a 2 channel image (grayscale with alpha) to an RGBA image with
  455. the grey converted to the specified RGB color:
  456. # set (RGB) scaled on the grey scale portion and copy the alpha
  457. # channel as is
  458. my $colored = $gray->convert(matrix=>[ [ ($red/255), 0 ],
  459. [ ($green/255), 0 ],
  460. [ ($blue/255), 0 ],
  461. [ 0, 1 ],
  462. ]);
  463. To convert a 3 channel image to a 4 channel image with a 50 percent
  464. alpha channel:
  465. my $withalpha = $rgb->convert(matrix =>[ [ 1, 0, 0, 0 ],
  466. [ 0, 1, 0, 0 ],
  467. [ 0, 0, 1, 0 ],
  468. [ 0, 0, 0, 0.5 ],
  469. ]);
  470. =back
  471. =head2 Color Mappings
  472. =over
  473. =item map
  474. You can use the map method to map the values of each channel of an
  475. image independently using a list of lookup tables. It's important to
  476. realize that the modification is made inplace. The function simply
  477. returns the input image again or undef on failure.
  478. Each channel is mapped independently through a lookup table with 256
  479. entries. The elements in the table should not be less than 0 and not
  480. greater than 255. If they are out of the 0..255 range they are
  481. clamped to the range. If a table does not contain 256 entries it is
  482. silently ignored.
  483. Single channels can mapped by specifying their name and the mapping
  484. table. The channel names are C<red>, C<green>, C<blue>, C<alpha>.
  485. @map = map { int( $_/2 } 0..255;
  486. $img->map( red=>\@map );
  487. It is also possible to specify a single map that is applied to all
  488. channels, alpha channel included. For example this applies a gamma
  489. correction with a gamma of 1.4 to the input image.
  490. $gamma = 1.4;
  491. @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
  492. $img->map(all=> \@map);
  493. The C<all> map is used as a default channel, if no other map is
  494. specified for a channel then the C<all> map is used instead. If we
  495. had not wanted to apply gamma to the alpha channel we would have used:
  496. $img->map(all=> \@map, alpha=>[]);
  497. Since C<[]> contains fewer than 256 element the gamma channel is
  498. unaffected.
  499. It is also possible to simply specify an array of maps that are
  500. applied to the images in the rgba order. For example to apply
  501. maps to the C<red> and C<blue> channels one would use:
  502. $img->map(maps=>[\@redmap, [], \@bluemap]);
  503. =back
  504. =head1 SEE ALSO
  505. L<Imager>, L<Imager::Engines>
  506. =head1 AUTHOR
  507. Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson
  508. =head1 REVISION
  509. $Revision: 1261 $
  510. =cut