4 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS %formats $DEBUG %filters %DSOs $ERRSTR $fontstate %OPCODES $I2P $FORMATGUESS);
81 i_writetiff_wiol_faxable
148 $VERSION = '0.39pre1';
149 @ISA = qw(Exporter DynaLoader);
150 bootstrap Imager $VERSION;
154 i_init_fonts(); # Initialize font engines
155 Imager::Font::__init();
156 for(i_list_formats()) { $formats{$_}++; }
158 if ($formats{'t1'}) {
162 if (!$formats{'t1'} and !$formats{'tt'}
163 && !$formats{'ft2'} && !$formats{'w32'}) {
164 $fontstate='no font support';
167 %OPCODES=(Add=>[0],Sub=>[1],Mult=>[2],Div=>[3],Parm=>[4],'sin'=>[5],'cos'=>[6],'x'=>[4,0],'y'=>[4,1]);
171 # the members of the subhashes under %filters are:
172 # callseq - a list of the parameters to the underlying filter in the
173 # order they are passed
174 # callsub - a code ref that takes a named parameter list and calls the
176 # defaults - a hash of default values
177 # names - defines names for value of given parameters so if the names
178 # field is foo=> { bar=>1 }, and the user supplies "bar" as the
179 # foo parameter, the filter will receive 1 for the foo
182 callseq => ['image','intensity'],
183 callsub => sub { my %hsh=@_; i_contrast($hsh{image},$hsh{intensity}); }
187 callseq => ['image', 'amount', 'subtype'],
188 defaults => { amount=>3,subtype=>0 },
189 callsub => sub { my %hsh=@_; i_noise($hsh{image},$hsh{amount},$hsh{subtype}); }
192 $filters{hardinvert} ={
193 callseq => ['image'],
195 callsub => sub { my %hsh=@_; i_hardinvert($hsh{image}); }
198 $filters{autolevels} ={
199 callseq => ['image','lsat','usat','skew'],
200 defaults => { lsat=>0.1,usat=>0.1,skew=>0.0 },
201 callsub => sub { my %hsh=@_; i_autolevels($hsh{image},$hsh{lsat},$hsh{usat},$hsh{skew}); }
204 $filters{turbnoise} ={
205 callseq => ['image'],
206 defaults => { xo=>0.0,yo=>0.0,scale=>10.0 },
207 callsub => sub { my %hsh=@_; i_turbnoise($hsh{image},$hsh{xo},$hsh{yo},$hsh{scale}); }
210 $filters{radnoise} ={
211 callseq => ['image'],
212 defaults => { xo=>100,yo=>100,ascale=>17.0,rscale=>0.02 },
213 callsub => sub { my %hsh=@_; i_radnoise($hsh{image},$hsh{xo},$hsh{yo},$hsh{rscale},$hsh{ascale}); }
217 callseq => ['image', 'coef'],
219 callsub => sub { my %hsh=@_; i_conv($hsh{image},$hsh{coef}); }
223 callseq => ['image', 'xo', 'yo', 'colors', 'dist'],
225 callsub => sub { my %hsh=@_; i_gradgen($hsh{image}, $hsh{xo}, $hsh{yo}, $hsh{colors}, $hsh{dist}); }
228 $filters{nearest_color} ={
229 callseq => ['image', 'xo', 'yo', 'colors', 'dist'],
231 callsub => sub { my %hsh=@_; i_nearest_color($hsh{image}, $hsh{xo}, $hsh{yo}, $hsh{colors}, $hsh{dist}); }
233 $filters{gaussian} = {
234 callseq => [ 'image', 'stddev' ],
236 callsub => sub { my %hsh = @_; i_gaussian($hsh{image}, $hsh{stddev}); },
240 callseq => [ qw(image size) ],
241 defaults => { size => 20 },
242 callsub => sub { my %hsh = @_; i_mosaic($hsh{image}, $hsh{size}) },
246 callseq => [ qw(image bump elevation lightx lighty st) ],
247 defaults => { elevation=>0, st=> 2 },
250 i_bumpmap($hsh{image}, $hsh{bump}{IMG}, $hsh{elevation},
251 $hsh{lightx}, $hsh{lighty}, $hsh{st});
254 $filters{postlevels} =
256 callseq => [ qw(image levels) ],
257 defaults => { levels => 10 },
258 callsub => sub { my %hsh = @_; i_postlevels($hsh{image}, $hsh{levels}); },
260 $filters{watermark} =
262 callseq => [ qw(image wmark tx ty pixdiff) ],
263 defaults => { pixdiff=>10, tx=>0, ty=>0 },
267 i_watermark($hsh{image}, $hsh{wmark}{IMG}, $hsh{tx}, $hsh{ty},
273 callseq => [ qw(image xa ya xb yb ftype repeat combine super_sample ssample_param segments) ],
275 ftype => { linear => 0,
281 repeat => { none => 0,
296 multiply => 2, mult => 2,
299 subtract => 5, sub => 5,
309 defaults => { ftype => 0, repeat => 0, combine => 0,
310 super_sample => 0, ssample_param => 4,
313 Imager::Color->new(0,0,0),
314 Imager::Color->new(255, 255, 255),
322 i_fountain($hsh{image}, $hsh{xa}, $hsh{ya}, $hsh{xb}, $hsh{yb},
323 $hsh{ftype}, $hsh{repeat}, $hsh{combine}, $hsh{super_sample},
324 $hsh{ssample_param}, $hsh{segments});
328 $FORMATGUESS=\&def_guess_type;
336 # NOTE: this might be moved to an import override later on
340 # (look through @_ for special tags, process, and remove them);
342 # print Dumper($pack);
347 my %parms=(loglevel=>1,@_);
349 init_log($parms{'log'},$parms{'loglevel'});
352 # if ($parms{T1LIB_CONFIG}) { $ENV{T1LIB_CONFIG}=$parms{T1LIB_CONFIG}; }
353 # if ( $ENV{T1LIB_CONFIG} and ( $fontstate eq 'missing conf' )) {
361 print "shutdown code\n";
362 # for(keys %instances) { $instances{$_}->DESTROY(); }
363 malloc_state(); # how do decide if this should be used? -- store something from the import
364 print "Imager exiting\n";
368 # Load a filter plugin
373 my ($DSO_handle,$str)=DSO_open($filename);
374 if (!defined($DSO_handle)) { $Imager::ERRSTR="Couldn't load plugin '$filename'\n"; return undef; }
375 my %funcs=DSO_funclist($DSO_handle);
376 if ($DEBUG) { print "loading module $filename\n"; $i=0; for(keys %funcs) { printf(" %2d: %s\n",$i++,$_); } }
378 for(keys %funcs) { if ($filters{$_}) { $ERRSTR="filter '$_' already exists\n"; DSO_close($DSO_handle); return undef; } }
380 $DSOs{$filename}=[$DSO_handle,\%funcs];
383 my $evstr="\$filters{'".$_."'}={".$funcs{$_}.'};';
384 $DEBUG && print "eval string:\n",$evstr,"\n";
396 if (!$DSOs{$filename}) { $ERRSTR="plugin '$filename' not loaded."; return undef; }
397 my ($DSO_handle,$funcref)=@{$DSOs{$filename}};
398 for(keys %{$funcref}) {
400 $DEBUG && print "unloading: $_\n";
402 my $rc=DSO_close($DSO_handle);
403 if (!defined($rc)) { $ERRSTR="unable to unload plugin '$filename'."; return undef; }
407 # take the results of i_error() and make a message out of it
409 return join(": ", map $_->[0], i_errors());
413 # Methods to be called on objects.
416 # Create a new Imager object takes very few parameters.
417 # usually you call this method and then call open from
418 # the resulting object
425 $self->{IMG}=undef; # Just to indicate what exists
426 $self->{ERRSTR}=undef; #
427 $self->{DEBUG}=$DEBUG;
428 $self->{DEBUG} && print "Initialized Imager\n";
429 if ($hsh{xsize} && $hsh{ysize}) { $self->img_set(%hsh); }
433 # Copy an entire image with no changes
434 # - if an image has magic the copy of it will not be magical
438 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
440 my $newcopy=Imager->new();
441 $newcopy->{IMG}=i_img_new();
442 i_copy($newcopy->{IMG},$self->{IMG});
450 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
451 my %input=(left=>0, top=>0, @_);
452 unless($input{img}) {
453 $self->{ERRSTR}="no source image";
456 $input{left}=0 if $input{left} <= 0;
457 $input{top}=0 if $input{top} <= 0;
459 my($r,$b)=i_img_info($src->{IMG});
461 i_copyto($self->{IMG}, $src->{IMG},
462 0,0, $r, $b, $input{left}, $input{top});
463 return $self; # What should go here??
466 # Crop an image - i.e. return a new image that is smaller
470 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
471 my %hsh=(left=>0,right=>0,top=>0,bottom=>0,@_);
473 my ($w,$h,$l,$r,$b,$t)=($self->getwidth(),$self->getheight(),
474 @hsh{qw(left right bottom top)});
475 $l=0 if not defined $l;
476 $t=0 if not defined $t;
478 $r||=$l+delete $hsh{'width'} if defined $l and exists $hsh{'width'};
479 $b||=$t+delete $hsh{'height'} if defined $t and exists $hsh{'height'};
480 $l||=$r-delete $hsh{'width'} if defined $r and exists $hsh{'width'};
481 $t||=$b-delete $hsh{'height'} if defined $b and exists $hsh{'height'};
483 $r=$self->getwidth if not defined $r;
484 $b=$self->getheight if not defined $b;
486 ($l,$r)=($r,$l) if $l>$r;
487 ($t,$b)=($b,$t) if $t>$b;
490 $l=int(0.5+($w-$hsh{'width'})/2);
495 if ($hsh{'height'}) {
496 $b=int(0.5+($h-$hsh{'height'})/2);
497 $t=$h+$hsh{'height'};
499 $hsh{'height'}=$b-$t;
502 # print "l=$l, r=$r, h=$hsh{'width'}\n";
503 # print "t=$t, b=$b, w=$hsh{'height'}\n";
505 my $dst=Imager->new(xsize=>$hsh{'width'}, ysize=>$hsh{'height'}, channels=>$self->getchannels());
507 i_copyto($dst->{IMG},$self->{IMG},$l,$t,$r,$b,0,0);
511 # Sets an image to a certain size and channel number
512 # if there was previously data in the image it is discarded
517 my %hsh=(xsize=>100, ysize=>100, channels=>3, bits=>8, type=>'direct', @_);
519 if (defined($self->{IMG})) {
520 # let IIM_DESTROY destroy it, it's possible this image is
521 # referenced from a virtual image (like masked)
522 #i_img_destroy($self->{IMG});
526 if ($hsh{type} eq 'paletted' || $hsh{type} eq 'pseudo') {
527 $self->{IMG} = i_img_pal_new($hsh{xsize}, $hsh{ysize}, $hsh{channels},
528 $hsh{maxcolors} || 256);
530 elsif ($hsh{bits} == 16) {
531 $self->{IMG} = i_img_16_new($hsh{xsize}, $hsh{ysize}, $hsh{channels});
534 $self->{IMG}=Imager::ImgRaw::new($hsh{'xsize'}, $hsh{'ysize'},
539 # created a masked version of the current image
543 $self or return undef;
544 my %opts = (left => 0,
546 right => $self->getwidth,
547 bottom => $self->getheight,
549 my $mask = $opts{mask} ? $opts{mask}{IMG} : undef;
551 my $result = Imager->new;
552 $result->{IMG} = i_img_masked_new($self->{IMG}, $mask, $opts{left},
553 $opts{top}, $opts{right} - $opts{left},
554 $opts{bottom} - $opts{top});
555 # keep references to the mask and base images so they don't
557 $result->{DEPENDS} = [ $self->{IMG}, $mask ];
562 # convert an RGB image into a paletted image
566 if (@_ != 1 && !ref $_[0]) {
573 my $result = Imager->new;
574 $result->{IMG} = i_img_to_pal($self->{IMG}, $opts);
576 #print "Type ", i_img_type($result->{IMG}), "\n";
578 $result->{IMG} or undef $result;
583 # convert a paletted (or any image) to an 8-bit/channel RGB images
589 $result = Imager->new;
590 $result->{IMG} = i_img_to_rgb($self->{IMG})
599 my %opts = (colors=>[], @_);
601 @{$opts{colors}} or return undef;
603 $self->{IMG} and i_addcolors($self->{IMG}, @{$opts{colors}});
608 my %opts = (start=>0, colors=>[], @_);
609 @{$opts{colors}} or return undef;
611 $self->{IMG} and i_setcolors($self->{IMG}, $opts{start}, @{$opts{colors}});
617 if (!exists $opts{start} && !exists $opts{count}) {
620 $opts{count} = $self->colorcount;
622 elsif (!exists $opts{count}) {
625 elsif (!exists $opts{start}) {
630 return i_getcolors($self->{IMG}, $opts{start}, $opts{count});
634 i_colorcount($_[0]{IMG});
638 i_maxcolors($_[0]{IMG});
644 $opts{color} or return undef;
646 $self->{IMG} and i_findcolor($self->{IMG}, $opts{color});
651 $self->{IMG} and i_img_bits($self->{IMG});
657 return i_img_type($self->{IMG}) ? "paletted" : "direct";
663 $self->{IMG} and i_img_virtual($self->{IMG});
667 my ($self, %opts) = @_;
669 $self->{IMG} or return;
671 if (defined $opts{name}) {
675 while (defined($found = i_tags_find($self->{IMG}, $opts{name}, $start))) {
676 push @result, (i_tags_get($self->{IMG}, $found))[1];
679 return wantarray ? @result : $result[0];
681 elsif (defined $opts{code}) {
685 while (defined($found = i_tags_findn($self->{IMG}, $opts{code}, $start))) {
686 push @result, (i_tags_get($self->{IMG}, $found))[1];
693 return map { [ i_tags_get($self->{IMG}, $_) ] } 0.. i_tags_count($self->{IMG})-1;
696 return i_tags_count($self->{IMG});
705 return -1 unless $self->{IMG};
707 if (defined $opts{value}) {
708 if ($opts{value} =~ /^\d+$/) {
710 return i_tags_addn($self->{IMG}, $opts{name}, 0, $opts{value});
713 return i_tags_add($self->{IMG}, $opts{name}, 0, $opts{value}, 0);
716 elsif (defined $opts{data}) {
717 # force addition as a string
718 return i_tags_add($self->{IMG}, $opts{name}, 0, $opts{data}, 0);
721 $self->{ERRSTR} = "No value supplied";
725 elsif ($opts{code}) {
726 if (defined $opts{value}) {
727 if ($opts{value} =~ /^\d+$/) {
729 return i_tags_addn($self->{IMG}, $opts{code}, 0, $opts{value});
732 return i_tags_add($self->{IMG}, $opts{code}, 0, $opts{value}, 0);
735 elsif (defined $opts{data}) {
736 # force addition as a string
737 return i_tags_add($self->{IMG}, $opts{code}, 0, $opts{data}, 0);
740 $self->{ERRSTR} = "No value supplied";
753 return 0 unless $self->{IMG};
755 if (defined $opts{index}) {
756 return i_tags_delete($self->{IMG}, $opts{index});
758 elsif (defined $opts{name}) {
759 return i_tags_delbyname($self->{IMG}, $opts{name});
761 elsif (defined $opts{code}) {
762 return i_tags_delbycode($self->{IMG}, $opts{code});
765 $self->{ERRSTR} = "Need to supply index, name, or code parameter";
770 # Read an image from file
777 if (defined($self->{IMG})) {
778 # let IIM_DESTROY do the destruction, since the image may be
779 # referenced from elsewhere
780 #i_img_destroy($self->{IMG});
784 if (!$input{fd} and !$input{file} and !$input{data}) {
785 $self->{ERRSTR}='no file, fd or data parameter'; return undef;
788 $fh = new IO::File($input{file},"r");
790 $self->{ERRSTR}='Could not open file'; return undef;
799 # FIXME: Find the format here if not specified
800 # yes the code isn't here yet - next week maybe?
801 # Next week? Are you high or something? That comment
802 # has been there for half a year dude.
803 # Look, i just work here, ok?
805 if (!$input{type} and $input{file}) {
806 $input{type}=$FORMATGUESS->($input{file});
808 if (!$formats{$input{type}}) {
809 $self->{ERRSTR}='format not supported'; return undef;
812 my %iolready=(jpeg=>1, png=>1, tiff=>1, pnm=>1, raw=>1, bmp=>1);
814 if ($iolready{$input{type}}) {
816 $IO = io_new_fd($fd); # sort of simple for now eh?
818 if ( $input{type} eq 'jpeg' ) {
819 ($self->{IMG},$self->{IPTCRAW})=i_readjpeg_wiol( $IO );
820 if ( !defined($self->{IMG}) ) {
821 $self->{ERRSTR}='unable to read jpeg image'; return undef;
823 $self->{DEBUG} && print "loading a jpeg file\n";
827 if ( $input{type} eq 'tiff' ) {
828 $self->{IMG}=i_readtiff_wiol( $IO, -1 ); # Fixme, check if that length parameter is ever needed
829 if ( !defined($self->{IMG}) ) {
830 $self->{ERRSTR}='unable to read tiff image'; return undef;
832 $self->{DEBUG} && print "loading a tiff file\n";
836 if ( $input{type} eq 'pnm' ) {
837 $self->{IMG}=i_readpnm_wiol( $IO, -1 ); # Fixme, check if that length parameter is ever needed
838 if ( !defined($self->{IMG}) ) {
839 $self->{ERRSTR}='unable to read pnm image: '._error_as_msg(); return undef;
841 $self->{DEBUG} && print "loading a pnm file\n";
845 if ( $input{type} eq 'png' ) {
846 $self->{IMG}=i_readpng_wiol( $IO, -1 ); # Fixme, check if that length parameter is ever needed
847 if ( !defined($self->{IMG}) ) {
848 $self->{ERRSTR}='unable to read png image';
851 $self->{DEBUG} && print "loading a png file\n";
854 if ( $input{type} eq 'bmp' ) {
855 $self->{IMG}=i_readbmp_wiol( $IO );
856 if ( !defined($self->{IMG}) ) {
857 $self->{ERRSTR}='unable to read bmp image';
860 $self->{DEBUG} && print "loading a bmp file\n";
863 if ( $input{type} eq 'raw' ) {
864 my %params=(datachannels=>3,storechannels=>3,interleave=>1,%input);
866 if ( !($params{xsize} && $params{ysize}) ) {
867 $self->{ERRSTR}='missing xsize or ysize parameter for raw';
871 $self->{IMG} = i_readraw_wiol( $IO,
874 $params{datachannels},
875 $params{storechannels},
876 $params{interleave});
877 if ( !defined($self->{IMG}) ) {
878 $self->{ERRSTR}='unable to read raw image';
881 $self->{DEBUG} && print "loading a raw file\n";
886 # Old code for reference while changing the new stuff
888 if (!$input{type} and $input{file}) {
889 $input{type}=$FORMATGUESS->($input{file});
893 $self->{ERRSTR}='type parameter missing and not possible to guess from extension'; return undef;
896 if (!$formats{$input{type}}) {
897 $self->{ERRSTR}='format not supported';
902 $fh = new IO::File($input{file},"r");
904 $self->{ERRSTR}='Could not open file';
915 if ( $input{type} eq 'gif' ) {
917 if ($input{colors} && !ref($input{colors})) {
918 # must be a reference to a scalar that accepts the colour map
919 $self->{ERRSTR} = "option 'colors' must be a scalar reference";
922 if (exists $input{data}) {
923 if ($input{colors}) {
924 ($self->{IMG}, $colors) = i_readgif_scalar($input{data});
926 $self->{IMG}=i_readgif_scalar($input{data});
929 if ($input{colors}) {
930 ($self->{IMG}, $colors) = i_readgif( $fd );
932 $self->{IMG} = i_readgif( $fd )
936 # we may or may not change i_readgif to return blessed objects...
937 ${ $input{colors} } = [ map { NC(@$_) } @$colors ];
939 if ( !defined($self->{IMG}) ) {
940 $self->{ERRSTR}= 'reading GIF:'._error_as_msg();
943 $self->{DEBUG} && print "loading a gif file\n";
949 # Write an image to file
952 my %input=(jpegquality=>75, gifquant=>'mc', lmdither=>6.0, lmfixed=>[],
954 my ($fh, $rc, $fd, $IO);
956 my %iolready=( tiff=>1, raw=>1, png=>1, pnm=>1, bmp=>1, jpeg=>1 ); # this will be SO MUCH BETTER once they are all in there
958 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
960 if (!$input{file} and !$input{'fd'} and !$input{'data'}) { $self->{ERRSTR}='file/fd/data parameter missing'; return undef; }
961 if (!$input{type} and $input{file}) { $input{type}=$FORMATGUESS->($input{file}); }
962 if (!$input{type}) { $self->{ERRSTR}='type parameter missing and not possible to guess from extension'; return undef; }
964 if (!$formats{$input{type}}) { $self->{ERRSTR}='format not supported'; return undef; }
966 if (exists $input{'fd'}) {
968 } elsif (exists $input{'data'}) {
969 $IO = Imager::io_new_bufchain();
971 $fh = new IO::File($input{file},"w+");
972 if (!defined $fh) { $self->{ERRSTR}='Could not open file'; return undef; }
977 if ($iolready{$input{type}}) {
979 $IO = io_new_fd($fd);
982 if ($input{type} eq 'tiff') {
983 if (defined $input{class} && $input{class} eq 'fax') {
984 if (!i_writetiff_wiol_faxable($self->{IMG}, $IO, $input{fax_fine})) {
985 $self->{ERRSTR}='Could not write to buffer';
989 if (!i_writetiff_wiol($self->{IMG}, $IO)) {
990 $self->{ERRSTR}='Could not write to buffer';
994 } elsif ( $input{type} eq 'pnm' ) {
995 if ( ! i_writeppm_wiol($self->{IMG},$IO) ) {
996 $self->{ERRSTR}='unable to write pnm image';
999 $self->{DEBUG} && print "writing a pnm file\n";
1000 } elsif ( $input{type} eq 'raw' ) {
1001 if ( !i_writeraw_wiol($self->{IMG},$IO) ) {
1002 $self->{ERRSTR}='unable to write raw image';
1005 $self->{DEBUG} && print "writing a raw file\n";
1006 } elsif ( $input{type} eq 'png' ) {
1007 if ( !i_writepng_wiol($self->{IMG}, $IO) ) {
1008 $self->{ERRSTR}='unable to write png image';
1011 $self->{DEBUG} && print "writing a png file\n";
1012 } elsif ( $input{type} eq 'jpeg' ) {
1013 if ( !i_writejpeg_wiol($self->{IMG}, $IO, $input{jpegquality})) {
1014 $self->{ERRSTR}='unable to write jpeg image';
1017 $self->{DEBUG} && print "writing a jpeg file\n";
1018 } elsif ( $input{type} eq 'bmp' ) {
1019 if ( !i_writebmp_wiol($self->{IMG}, $IO) ) {
1020 $self->{ERRSTR}='unable to write bmp image';
1023 $self->{DEBUG} && print "writing a bmp file\n";
1026 if (exists $input{'data'}) {
1027 my $data = io_slurp($IO);
1029 $self->{ERRSTR}='Could not slurp from buffer';
1032 ${$input{data}} = $data;
1036 if ( $input{type} eq 'gif' ) {
1037 if (not $input{gifplanes}) {
1039 my $count=i_count_colors($self->{IMG}, 256);
1040 $gp=8 if $count == -1;
1041 $gp=1 if not $gp and $count <= 2;
1042 $gp=2 if not $gp and $count <= 4;
1043 $gp=3 if not $gp and $count <= 8;
1044 $gp=4 if not $gp and $count <= 16;
1045 $gp=5 if not $gp and $count <= 32;
1046 $gp=6 if not $gp and $count <= 64;
1047 $gp=7 if not $gp and $count <= 128;
1048 $input{gifplanes} = $gp || 8;
1051 if ($input{gifplanes}>8) {
1052 $input{gifplanes}=8;
1054 if ($input{gifquant} eq 'gen' || $input{callback}) {
1057 if ($input{gifquant} eq 'lm') {
1059 $input{make_colors} = 'addi';
1060 $input{translate} = 'perturb';
1061 $input{perturb} = $input{lmdither};
1062 } elsif ($input{gifquant} eq 'gen') {
1063 # just pass options through
1065 $input{make_colors} = 'webmap'; # ignored
1066 $input{translate} = 'giflib';
1069 if ($input{callback}) {
1070 defined $input{maxbuffer} or $input{maxbuffer} = -1;
1071 $rc = i_writegif_callback($input{callback}, $input{maxbuffer},
1072 \%input, $self->{IMG});
1074 $rc = i_writegif_gen($fd, \%input, $self->{IMG});
1077 } elsif ($input{gifquant} eq 'lm') {
1078 $rc=i_writegif($self->{IMG},$fd,$input{gifplanes},$input{lmdither},$input{lmfixed});
1080 $rc=i_writegifmc($self->{IMG},$fd,$input{gifplanes});
1082 if ( !defined($rc) ) {
1083 $self->{ERRSTR} = "Writing GIF file: "._error_as_msg(); return undef;
1085 $self->{DEBUG} && print "writing a gif file\n";
1093 my ($class, $opts, @images) = @_;
1095 if ($opts->{type} eq 'gif') {
1096 my $gif_delays = $opts->{gif_delays};
1097 local $opts->{gif_delays} = $gif_delays;
1098 unless (ref $opts->{gif_delays}) {
1099 # assume the caller wants the same delay for each frame
1100 $opts->{gif_delays} = [ ($gif_delays) x @images ];
1102 # translate to ImgRaw
1103 if (grep !UNIVERSAL::isa($_, 'Imager') || !$_->{IMG}, @images) {
1104 $ERRSTR = "Usage: Imager->write_multi({ options }, @images)";
1107 my @work = map $_->{IMG}, @images;
1108 if ($opts->{callback}) {
1109 # Note: you may need to fix giflib for this one to work
1110 my $maxbuffer = $opts->{maxbuffer};
1111 defined $maxbuffer or $maxbuffer = -1; # max by default
1112 return i_writegif_callback($opts->{callback}, $maxbuffer,
1116 return i_writegif_gen($opts->{fd}, $opts, @work);
1119 my $fh = IO::File->new($opts->{file}, "w+");
1121 $ERRSTR = "Error creating $opts->{file}: $!";
1125 return i_writegif_gen(fileno($fh), $opts, @work);
1129 $ERRSTR = "Sorry, write_multi doesn't support $opts->{type} yet";
1134 # read multiple images from a file
1136 my ($class, %opts) = @_;
1138 if ($opts{file} && !exists $opts{type}) {
1140 my $type = $FORMATGUESS->($opts{file});
1141 $opts{type} = $type;
1143 unless ($opts{type}) {
1144 $ERRSTR = "No type parameter supplied and it couldn't be guessed";
1150 $file = IO::File->new($opts{file}, "r");
1152 $ERRSTR = "Could not open file $opts{file}: $!";
1156 $fd = fileno($file);
1159 $fd = fileno($opts{fh});
1161 $ERRSTR = "File handle specified with fh option not open";
1168 elsif ($opts{callback} || $opts{data}) {
1172 $ERRSTR = "You need to specify one of file, fd, fh, callback or data";
1176 if ($opts{type} eq 'gif') {
1179 @imgs = i_readgif_multi($fd);
1182 if (Imager::i_giflib_version() < 4.0) {
1183 $ERRSTR = "giflib3.x does not support callbacks";
1186 if ($opts{callback}) {
1187 @imgs = i_readgif_multi_callback($opts{callback})
1190 @imgs = i_readgif_multi_scalar($opts{data});
1195 bless { IMG=>$_, DEBUG=>$DEBUG, ERRSTR=>undef }, 'Imager'
1199 $ERRSTR = _error_as_msg();
1204 $ERRSTR = "Cannot read multiple images from $opts{type} files";
1208 # Destroy an Imager object
1212 # delete $instances{$self};
1213 if (defined($self->{IMG})) {
1214 # the following is now handled by the XS DESTROY method for
1215 # Imager::ImgRaw object
1216 # Re-enabling this will break virtual images
1217 # tested for in t/t020masked.t
1218 # i_img_destroy($self->{IMG});
1219 undef($self->{IMG});
1221 # print "Destroy Called on an empty image!\n"; # why did I put this here??
1225 # Perform an inplace filter of an image
1226 # that is the image will be overwritten with the data
1232 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1234 if (!$input{type}) { $self->{ERRSTR}='type parameter missing'; return undef; }
1236 if ( (grep { $_ eq $input{type} } keys %filters) != 1) {
1237 $self->{ERRSTR}='type parameter not matching any filter'; return undef;
1240 if ($filters{$input{type}}{names}) {
1241 my $names = $filters{$input{type}}{names};
1242 for my $name (keys %$names) {
1243 if (defined $input{$name} && exists $names->{$name}{$input{$name}}) {
1244 $input{$name} = $names->{$name}{$input{$name}};
1248 if (defined($filters{$input{type}}{defaults})) {
1249 %hsh=('image',$self->{IMG},%{$filters{$input{type}}{defaults}},%input);
1251 %hsh=('image',$self->{IMG},%input);
1254 my @cs=@{$filters{$input{type}}{callseq}};
1257 if (!defined($hsh{$_})) {
1258 $self->{ERRSTR}="missing parameter '$_' for filter ".$input{type}; return undef;
1262 &{$filters{$input{type}}{callsub}}(%hsh);
1266 $self->{DEBUG} && print "callseq is: @cs\n";
1267 $self->{DEBUG} && print "matching callseq is: @b\n";
1272 # Scale an image to requested size and return the scaled version
1276 my %opts=(scalefactor=>0.5,type=>'max',qtype=>'normal',@_);
1277 my $img = Imager->new();
1278 my $tmp = Imager->new();
1280 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1282 if ($opts{xpixels} and $opts{ypixels} and $opts{type}) {
1283 my ($xpix,$ypix)=( $opts{xpixels}/$self->getwidth() , $opts{ypixels}/$self->getheight() );
1284 if ($opts{type} eq 'min') { $opts{scalefactor}=min($xpix,$ypix); }
1285 if ($opts{type} eq 'max') { $opts{scalefactor}=max($xpix,$ypix); }
1286 } elsif ($opts{xpixels}) { $opts{scalefactor}=$opts{xpixels}/$self->getwidth(); }
1287 elsif ($opts{ypixels}) { $opts{scalefactor}=$opts{ypixels}/$self->getheight(); }
1289 if ($opts{qtype} eq 'normal') {
1290 $tmp->{IMG}=i_scaleaxis($self->{IMG},$opts{scalefactor},0);
1291 if ( !defined($tmp->{IMG}) ) { $self->{ERRSTR}='unable to scale image'; return undef; }
1292 $img->{IMG}=i_scaleaxis($tmp->{IMG},$opts{scalefactor},1);
1293 if ( !defined($img->{IMG}) ) { $self->{ERRSTR}='unable to scale image'; return undef; }
1296 if ($opts{'qtype'} eq 'preview') {
1297 $img->{IMG}=i_scale_nn($self->{IMG},$opts{'scalefactor'},$opts{'scalefactor'});
1298 if ( !defined($img->{IMG}) ) { $self->{ERRSTR}='unable to scale image'; return undef; }
1301 $self->{ERRSTR}='scale: invalid value for qtype'; return undef;
1304 # Scales only along the X axis
1308 my %opts=(scalefactor=>0.5,@_);
1310 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1312 my $img = Imager->new();
1314 if ($opts{pixels}) { $opts{scalefactor}=$opts{pixels}/$self->getwidth(); }
1316 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1317 $img->{IMG}=i_scaleaxis($self->{IMG},$opts{scalefactor},0);
1319 if ( !defined($img->{IMG}) ) { $self->{ERRSTR}='unable to scale image'; return undef; }
1323 # Scales only along the Y axis
1327 my %opts=(scalefactor=>0.5,@_);
1329 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1331 my $img = Imager->new();
1333 if ($opts{pixels}) { $opts{scalefactor}=$opts{pixels}/$self->getheight(); }
1335 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1336 $img->{IMG}=i_scaleaxis($self->{IMG},$opts{scalefactor},1);
1338 if ( !defined($img->{IMG}) ) { $self->{ERRSTR}='unable to scale image'; return undef; }
1343 # Transform returns a spatial transformation of the input image
1344 # this moves pixels to a new location in the returned image.
1345 # NOTE - should make a utility function to check transforms for
1350 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1352 my (@op,@ropx,@ropy,$iop,$or,@parm,$expr,@xt,@yt,@pt,$numre);
1354 # print Dumper(\%opts);
1357 if ( $opts{'xexpr'} and $opts{'yexpr'} ) {
1359 eval ("use Affix::Infix2Postfix;");
1362 $self->{ERRSTR}='transform: expr given and Affix::Infix2Postfix is not avaliable.';
1365 $I2P=Affix::Infix2Postfix->new('ops'=>[{op=>'+',trans=>'Add'},
1366 {op=>'-',trans=>'Sub'},
1367 {op=>'*',trans=>'Mult'},
1368 {op=>'/',trans=>'Div'},
1369 {op=>'-',type=>'unary',trans=>'u-'},
1371 {op=>'func',type=>'unary'}],
1372 'grouping'=>[qw( \( \) )],
1373 'func'=>[qw( sin cos )],
1378 @xt=$I2P->translate($opts{'xexpr'});
1379 @yt=$I2P->translate($opts{'yexpr'});
1381 $numre=$I2P->{'numre'};
1384 for(@xt) { if (/$numre/) { push(@pt,$_); push(@{$opts{'xopcodes'}},'Parm',$#pt); } else { push(@{$opts{'xopcodes'}},$_); } }
1385 for(@yt) { if (/$numre/) { push(@pt,$_); push(@{$opts{'yopcodes'}},'Parm',$#pt); } else { push(@{$opts{'yopcodes'}},$_); } }
1386 @{$opts{'parm'}}=@pt;
1389 # print Dumper(\%opts);
1391 if ( !exists $opts{'xopcodes'} or @{$opts{'xopcodes'}}==0) {
1392 $self->{ERRSTR}='transform: no xopcodes given.';
1396 @op=@{$opts{'xopcodes'}};
1398 if (!defined ($OPCODES{$iop}) and ($iop !~ /^\d+$/) ) {
1399 $self->{ERRSTR}="transform: illegal opcode '$_'.";
1402 push(@ropx,(exists $OPCODES{$iop}) ? @{$OPCODES{$iop}} : $iop );
1408 if ( !exists $opts{'yopcodes'} or @{$opts{'yopcodes'}}==0) {
1409 $self->{ERRSTR}='transform: no yopcodes given.';
1413 @op=@{$opts{'yopcodes'}};
1415 if (!defined ($OPCODES{$iop}) and ($iop !~ /^\d+$/) ) {
1416 $self->{ERRSTR}="transform: illegal opcode '$_'.";
1419 push(@ropy,(exists $OPCODES{$iop}) ? @{$OPCODES{$iop}} : $iop );
1424 if ( !exists $opts{'parm'}) {
1425 $self->{ERRSTR}='transform: no parameter arg given.';
1429 # print Dumper(\@ropx);
1430 # print Dumper(\@ropy);
1431 # print Dumper(\@ropy);
1433 my $img = Imager->new();
1434 $img->{IMG}=i_transform($self->{IMG},\@ropx,\@ropy,$opts{'parm'});
1435 if ( !defined($img->{IMG}) ) { $self->{ERRSTR}='transform: failed'; return undef; }
1443 my ($opts, @imgs) = @_;
1446 # this is fairly big, delay loading it
1447 eval "use Imager::Expr";
1452 $opts->{variables} = [ qw(x y) ];
1453 my ($width, $height) = @{$opts}{qw(width height)};
1455 $width ||= $imgs[0]->getwidth();
1456 $height ||= $imgs[0]->getheight();
1458 for my $img (@imgs) {
1459 $opts->{constants}{"w$img_num"} = $img->getwidth();
1460 $opts->{constants}{"h$img_num"} = $img->getheight();
1461 $opts->{constants}{"cx$img_num"} = $img->getwidth()/2;
1462 $opts->{constants}{"cy$img_num"} = $img->getheight()/2;
1467 $opts->{constants}{w} = $width;
1468 $opts->{constants}{cx} = $width/2;
1471 $Imager::ERRSTR = "No width supplied";
1475 $opts->{constants}{h} = $height;
1476 $opts->{constants}{cy} = $height/2;
1479 $Imager::ERRSTR = "No height supplied";
1482 my $code = Imager::Expr->new($opts);
1484 $Imager::ERRSTR = Imager::Expr::error();
1488 my $img = Imager->new();
1489 $img->{IMG} = i_transform2($opts->{width}, $opts->{height}, $code->code(),
1490 $code->nregs(), $code->cregs(),
1491 [ map { $_->{IMG} } @imgs ]);
1492 if (!defined $img->{IMG}) {
1493 $Imager::ERRSTR = "transform2 failed";
1503 my %opts=(tx=>0,ty=>0,@_);
1505 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1506 unless ($opts{src} && $opts{src}->{IMG}) { $self->{ERRSTR}='empty input image for source'; return undef; }
1508 unless (i_rubthru($self->{IMG}, $opts{src}->{IMG}, $opts{tx},$opts{ty})) {
1509 $self->{ERRSTR} = $self->_error_as_msg();
1519 my %xlate = (h=>0, v=>1, hv=>2, vh=>2);
1521 return () unless defined $opts{'dir'} and defined $xlate{$opts{'dir'}};
1522 $dir = $xlate{$opts{'dir'}};
1523 return $self if i_flipxy($self->{IMG}, $dir);
1530 if (defined $opts{right}) {
1531 my $degrees = $opts{right};
1533 $degrees += 360 * int(((-$degrees)+360)/360);
1535 $degrees = $degrees % 360;
1536 if ($degrees == 0) {
1537 return $self->copy();
1539 elsif ($degrees == 90 || $degrees == 180 || $degrees == 270) {
1540 my $result = Imager->new();
1541 if ($result->{IMG} = i_rotate90($self->{IMG}, $degrees)) {
1545 $self->{ERRSTR} = $self->_error_as_msg();
1550 $self->{ERRSTR} = "Parameter 'right' must be a multiple of 90 degrees";
1554 elsif (defined $opts{radians} || defined $opts{degrees}) {
1555 my $amount = $opts{radians} || $opts{degrees} * 3.1415926535 / 180;
1557 my $result = Imager->new;
1558 if ($result->{IMG} = i_rotate_exact($self->{IMG}, $amount)) {
1562 $self->{ERRSTR} = $self->_error_as_msg();
1567 $self->{ERRSTR} = "Only the 'right' parameter is available";
1572 sub matrix_transform {
1576 if ($opts{matrix}) {
1577 my $xsize = $opts{xsize} || $self->getwidth;
1578 my $ysize = $opts{ysize} || $self->getheight;
1580 my $result = Imager->new;
1581 $result->{IMG} = i_matrix_transform($self->{IMG}, $xsize, $ysize,
1588 $self->{ERRSTR} = "matrix parameter required";
1594 *yatf = \&matrix_transform;
1596 # These two are supported for legacy code only
1599 return Imager::Color->new(@_);
1603 return Imager::Color::set(@_);
1606 # Draws a box between the specified corner points.
1609 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1610 my $dflcl=i_color_new(255,255,255,255);
1611 my %opts=(color=>$dflcl,xmin=>0,ymin=>0,xmax=>$self->getwidth()-1,ymax=>$self->getheight()-1,@_);
1613 if (exists $opts{'box'}) {
1614 $opts{'xmin'} = min($opts{'box'}->[0],$opts{'box'}->[2]);
1615 $opts{'xmax'} = max($opts{'box'}->[0],$opts{'box'}->[2]);
1616 $opts{'ymin'} = min($opts{'box'}->[1],$opts{'box'}->[3]);
1617 $opts{'ymax'} = max($opts{'box'}->[1],$opts{'box'}->[3]);
1620 if ($opts{filled}) {
1621 i_box_filled($self->{IMG},$opts{xmin},$opts{ymin},$opts{xmax},
1622 $opts{ymax},$opts{color});
1624 elsif ($opts{fill}) {
1625 unless (UNIVERSAL::isa($opts{fill}, 'Imager::Fill')) {
1626 # assume it's a hash ref
1627 require 'Imager/Fill.pm';
1628 $opts{fill} = Imager::Fill->new(%{$opts{fill}});
1630 i_box_cfill($self->{IMG},$opts{xmin},$opts{ymin},$opts{xmax},
1631 $opts{ymax},$opts{fill}{fill});
1634 i_box($self->{IMG},$opts{xmin},$opts{ymin},$opts{xmax},$opts{ymax},$opts{color});
1639 # Draws an arc - this routine SUCKS and is buggy - it sometimes doesn't work when the arc is a convex polygon
1643 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1644 my $dflcl=i_color_new(255,255,255,255);
1645 my %opts=(color=>$dflcl,
1646 'r'=>min($self->getwidth(),$self->getheight())/3,
1647 'x'=>$self->getwidth()/2,
1648 'y'=>$self->getheight()/2,
1649 'd1'=>0, 'd2'=>361, @_);
1651 unless (UNIVERSAL::isa($opts{fill}, 'Imager::Fill')) {
1652 # assume it's a hash ref
1653 require 'Imager/Fill.pm';
1654 $opts{fill} = Imager::Fill->new(%{$opts{fill}});
1656 i_arc_cfill($self->{IMG},$opts{'x'},$opts{'y'},$opts{'r'},$opts{'d1'},
1657 $opts{'d2'}, $opts{fill}{fill});
1660 i_arc($self->{IMG},$opts{'x'},$opts{'y'},$opts{'r'},$opts{'d1'},
1661 $opts{'d2'},$opts{'color'});
1667 # Draws a line from one point to (but not including) the destination point
1671 my $dflcl=i_color_new(0,0,0,0);
1672 my %opts=(color=>$dflcl,@_);
1673 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1675 unless (exists $opts{x1} and exists $opts{y1}) { $self->{ERRSTR}='missing begining coord'; return undef; }
1676 unless (exists $opts{x2} and exists $opts{y2}) { $self->{ERRSTR}='missing ending coord'; return undef; }
1678 if ($opts{antialias}) {
1679 i_line_aa($self->{IMG},$opts{x1}, $opts{y1}, $opts{x2}, $opts{y2}, $opts{color});
1681 i_draw($self->{IMG},$opts{x1}, $opts{y1}, $opts{x2}, $opts{y2}, $opts{color});
1686 # Draws a line between an ordered set of points - It more or less just transforms this
1687 # into a list of lines.
1691 my ($pt,$ls,@points);
1692 my $dflcl=i_color_new(0,0,0,0);
1693 my %opts=(color=>$dflcl,@_);
1695 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1697 if (exists($opts{points})) { @points=@{$opts{points}}; }
1698 if (!exists($opts{points}) and exists($opts{'x'}) and exists($opts{'y'}) ) {
1699 @points=map { [ $opts{'x'}->[$_],$opts{'y'}->[$_] ] } (0..(scalar @{$opts{'x'}}-1));
1702 # print Dumper(\@points);
1704 if ($opts{antialias}) {
1706 if (defined($ls)) { i_line_aa($self->{IMG},$ls->[0],$ls->[1],$pt->[0],$pt->[1],$opts{color}); }
1711 if (defined($ls)) { i_draw($self->{IMG},$ls->[0],$ls->[1],$pt->[0],$pt->[1],$opts{color}); }
1718 # this the multipoint bezier curve
1719 # this is here more for testing that actual usage since
1720 # this is not a good algorithm. Usually the curve would be
1721 # broken into smaller segments and each done individually.
1725 my ($pt,$ls,@points);
1726 my $dflcl=i_color_new(0,0,0,0);
1727 my %opts=(color=>$dflcl,@_);
1729 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1731 if (exists $opts{points}) {
1732 $opts{'x'}=map { $_->[0]; } @{$opts{'points'}};
1733 $opts{'y'}=map { $_->[1]; } @{$opts{'points'}};
1736 unless ( @{$opts{'x'}} and @{$opts{'x'}} == @{$opts{'y'}} ) {
1737 $self->{ERRSTR}='Missing or invalid points.';
1741 i_bezier_multi($self->{IMG},$opts{'x'},$opts{'y'},$opts{'color'});
1747 my %opts = ( color=>Imager::Color->new(255, 255, 255), @_ );
1749 unless (exists $opts{x} && exists $opts{'y'}) {
1750 $self->{ERRSTR} = "missing seed x and y parameters";
1755 unless (UNIVERSAL::isa($opts{fill}, 'Imager::Fill')) {
1756 # assume it's a hash ref
1757 require 'Imager/Fill.pm';
1758 $opts{fill} = Imager::Fill->new(%{$opts{fill}});
1760 i_flood_cfill($self->{IMG}, $opts{x}, $opts{'y'}, $opts{fill}{fill});
1763 i_flood_fill($self->{IMG}, $opts{x}, $opts{'y'}, $opts{color});
1769 # make an identity matrix of the given size
1773 my $matrix = [ map { [ (0) x $size ] } 1..$size ];
1774 for my $c (0 .. ($size-1)) {
1775 $matrix->[$c][$c] = 1;
1780 # general function to convert an image
1782 my ($self, %opts) = @_;
1785 # the user can either specify a matrix or preset
1786 # the matrix overrides the preset
1787 if (!exists($opts{matrix})) {
1788 unless (exists($opts{preset})) {
1789 $self->{ERRSTR} = "convert() needs a matrix or preset";
1793 if ($opts{preset} eq 'gray' || $opts{preset} eq 'grey') {
1794 # convert to greyscale, keeping the alpha channel if any
1795 if ($self->getchannels == 3) {
1796 $matrix = [ [ 0.222, 0.707, 0.071 ] ];
1798 elsif ($self->getchannels == 4) {
1799 # preserve the alpha channel
1800 $matrix = [ [ 0.222, 0.707, 0.071, 0 ],
1805 $matrix = _identity($self->getchannels);
1808 elsif ($opts{preset} eq 'noalpha') {
1809 # strip the alpha channel
1810 if ($self->getchannels == 2 or $self->getchannels == 4) {
1811 $matrix = _identity($self->getchannels);
1812 pop(@$matrix); # lose the alpha entry
1815 $matrix = _identity($self->getchannels);
1818 elsif ($opts{preset} eq 'red' || $opts{preset} eq 'channel0') {
1820 $matrix = [ [ 1 ] ];
1822 elsif ($opts{preset} eq 'green' || $opts{preset} eq 'channel1') {
1823 $matrix = [ [ 0, 1 ] ];
1825 elsif ($opts{preset} eq 'blue' || $opts{preset} eq 'channel2') {
1826 $matrix = [ [ 0, 0, 1 ] ];
1828 elsif ($opts{preset} eq 'alpha') {
1829 if ($self->getchannels == 2 or $self->getchannels == 4) {
1830 $matrix = [ [ (0) x ($self->getchannels-1), 1 ] ];
1833 # the alpha is just 1 <shrug>
1834 $matrix = [ [ (0) x $self->getchannels, 1 ] ];
1837 elsif ($opts{preset} eq 'rgb') {
1838 if ($self->getchannels == 1) {
1839 $matrix = [ [ 1 ], [ 1 ], [ 1 ] ];
1841 elsif ($self->getchannels == 2) {
1842 # preserve the alpha channel
1843 $matrix = [ [ 1, 0 ], [ 1, 0 ], [ 1, 0 ], [ 0, 1 ] ];
1846 $matrix = _identity($self->getchannels);
1849 elsif ($opts{preset} eq 'addalpha') {
1850 if ($self->getchannels == 1) {
1851 $matrix = _identity(2);
1853 elsif ($self->getchannels == 3) {
1854 $matrix = _identity(4);
1857 $matrix = _identity($self->getchannels);
1861 $self->{ERRSTR} = "Unknown convert preset $opts{preset}";
1867 $matrix = $opts{matrix};
1870 my $new = Imager->new();
1871 $new->{IMG} = i_img_new();
1872 unless (i_convert($new->{IMG}, $self->{IMG}, $matrix)) {
1873 # most likely a bad matrix
1874 $self->{ERRSTR} = _error_as_msg();
1881 # general function to map an image through lookup tables
1884 my ($self, %opts) = @_;
1885 my @chlist = qw( red green blue alpha );
1887 if (!exists($opts{'maps'})) {
1888 # make maps from channel maps
1890 for $chnum (0..$#chlist) {
1891 if (exists $opts{$chlist[$chnum]}) {
1892 $opts{'maps'}[$chnum] = $opts{$chlist[$chnum]};
1893 } elsif (exists $opts{'all'}) {
1894 $opts{'maps'}[$chnum] = $opts{'all'};
1898 if ($opts{'maps'} and $self->{IMG}) {
1899 i_map($self->{IMG}, $opts{'maps'} );
1904 # destructive border - image is shrunk by one pixel all around
1907 my ($self,%opts)=@_;
1908 my($tx,$ty)=($self->getwidth()-1,$self->getheight()-1);
1909 $self->polyline('x'=>[0,$tx,$tx,0,0],'y'=>[0,0,$ty,$ty,0],%opts);
1913 # Get the width of an image
1917 if (!defined($self->{IMG})) { $self->{ERRSTR} = 'image is empty'; return undef; }
1918 return (i_img_info($self->{IMG}))[0];
1921 # Get the height of an image
1925 if (!defined($self->{IMG})) { $self->{ERRSTR} = 'image is empty'; return undef; }
1926 return (i_img_info($self->{IMG}))[1];
1929 # Get number of channels in an image
1933 if (!defined($self->{IMG})) { $self->{ERRSTR} = 'image is empty'; return undef; }
1934 return i_img_getchannels($self->{IMG});
1941 if (!defined($self->{IMG})) { $self->{ERRSTR} = 'image is empty'; return undef; }
1942 return i_img_getmask($self->{IMG});
1950 if (!defined($self->{IMG})) { $self->{ERRSTR} = 'image is empty'; return undef; }
1951 i_img_setmask( $self->{IMG} , $opts{mask} );
1954 # Get number of colors in an image
1958 my %opts=(maxcolors=>2**30,@_);
1959 if (!defined($self->{IMG})) { $self->{ERRSTR}='image is empty'; return undef; }
1960 my $rc=i_count_colors($self->{IMG},$opts{'maxcolors'});
1961 return ($rc==-1? undef : $rc);
1964 # draw string to an image
1968 unless ($self->{IMG}) { $self->{ERRSTR}='empty input image'; return undef; }
1970 my %input=('x'=>0, 'y'=>0, @_);
1971 $input{string}||=$input{text};
1973 unless(exists $input{string}) {
1974 $self->{ERRSTR}="missing required parameter 'string'";
1978 unless($input{font}) {
1979 $self->{ERRSTR}="missing required parameter 'font'";
1983 unless ($input{font}->draw(image=>$self, %input)) {
1984 $self->{ERRSTR} = $self->_error_as_msg();
1991 # Shortcuts that can be exported
1993 sub newcolor { Imager::Color->new(@_); }
1994 sub newfont { Imager::Font->new(@_); }
1996 *NC=*newcolour=*newcolor;
2003 #### Utility routines
2006 ref $_[0] ? $_[0]->{ERRSTR} : $ERRSTR
2009 # Default guess for the type of an image from extension
2011 sub def_guess_type {
2014 $ext=($name =~ m/\.([^\.]+)$/)[0];
2015 return 'tiff' if ($ext =~ m/^tiff?$/);
2016 return 'jpeg' if ($ext =~ m/^jpe?g$/);
2017 return 'pnm' if ($ext =~ m/^p[pgb]m$/);
2018 return 'png' if ($ext eq "png");
2019 return 'bmp' if ($ext eq "bmp" || $ext eq "dib");
2020 return 'gif' if ($ext eq "gif");
2024 # get the minimum of a list
2028 for(@_) { if ($_<$mx) { $mx=$_; }}
2032 # get the maximum of a list
2036 for(@_) { if ($_>$mx) { $mx=$_; }}
2040 # string stuff for iptc headers
2044 $str = substr($str,3);
2045 $str =~ s/[\n\r]//g;
2052 # A little hack to parse iptc headers.
2057 my($caption,$photogr,$headln,$credit);
2059 my $str=$self->{IPTCRAW};
2063 @ar=split(/8BIM/,$str);
2068 @sar=split(/\034\002/);
2069 foreach $item (@sar) {
2070 if ($item =~ m/^x/) {
2071 $caption=&clean($item);
2074 if ($item =~ m/^P/) {
2075 $photogr=&clean($item);
2078 if ($item =~ m/^i/) {
2079 $headln=&clean($item);
2082 if ($item =~ m/^n/) {
2083 $credit=&clean($item);
2089 return (caption=>$caption,photogr=>$photogr,headln=>$headln,credit=>$credit);
2092 # Autoload methods go after =cut, and are processed by the autosplit program.
2096 # Below is the stub of documentation for your module. You better edit it!
2100 Imager - Perl extension for Generating 24 bit Images
2104 use Imager qw(init);
2107 $img = Imager->new();
2108 $img->open(file=>'image.ppm',type=>'pnm')
2109 || print "failed: ",$img->{ERRSTR},"\n";
2110 $scaled=$img->scale(xpixels=>400,ypixels=>400);
2111 $scaled->write(file=>'sc_image.ppm',type=>'pnm')
2112 || print "failed: ",$scaled->{ERRSTR},"\n";
2116 Imager is a module for creating and altering images - It is not meant
2117 as a replacement or a competitor to ImageMagick or GD. Both are
2118 excellent packages and well supported.
2122 Almost all functions take the parameters in the hash fashion.
2125 $img->open(file=>'lena.png',type=>'png');
2129 $img->open(file=>'lena.png');
2131 =head2 Basic concept
2133 An Image object is created with C<$img = Imager-E<gt>new()> Should
2134 this fail for some reason an explanation can be found in
2135 C<$Imager::ERRSTR> usually error messages are stored in
2136 C<$img-E<gt>{ERRSTR}>, but since no object is created this is the only
2137 way to give back errors. C<$Imager::ERRSTR> is also used to report
2138 all errors not directly associated with an image object. Examples:
2140 $img=Imager->new(); # This is an empty image (size is 0 by 0)
2141 $img->open(file=>'lena.png',type=>'png'); # initializes from file
2143 or if you want to create an empty image:
2145 $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
2147 This example creates a completely black image of width 400 and
2148 height 300 and 4 channels.
2150 If you have an existing image, use img_set() to change it's dimensions
2151 - this will destroy any existing image data:
2153 $img->img_set(xsize=>500, ysize=>500, channels=>4);
2155 To create paletted images, set the 'type' parameter to 'paletted':
2157 $img = Imager->new(xsize=>200, ysize=>200, channels=>3, type=>'paletted');
2159 which creates an image with a maxiumum of 256 colors, which you can
2160 change by supplying the C<maxcolors> parameter.
2162 You can create a new paletted image from an existing image using the
2163 to_paletted() method:
2165 $palimg = $img->to_paletted(\%opts)
2167 where %opts contains the options specified under L<Quantization options>.
2169 You can convert a paletted image (or any image) to an 8-bit/channel
2172 $rgbimg = $img->to_rgb8;
2174 Warning: if you draw on a paletted image with colors that aren't in
2175 the palette, the image will be internally converted to a normal image.
2177 For improved color precision you can use the bits parameter to specify
2178 16 bites per channel:
2180 $img = Imager->new(xsize=>200, ysize=>200, channels=>3, bits=>16);
2182 Note that as of this writing all functions should work on 16-bit
2183 images, but at only 8-bit/channel precision.
2185 Currently only 8 and 16/bit per channel image types are available,
2186 this may change later.
2188 Color objects are created by calling the Imager::Color->new()
2191 $color = Imager::Color->new($red, $green, $blue);
2192 $color = Imager::Color->new($red, $green, $blue, $alpha);
2193 $color = Imager::Color->new("#C0C0FF"); # html color specification
2195 This object can then be passed to functions that require a color parameter.
2197 Coordinates in Imager have the origin in the upper left corner. The
2198 horizontal coordinate increases to the right and the vertical
2201 =head2 Reading and writing images
2203 C<$img-E<gt>read()> generally takes two parameters, 'file' and 'type'.
2204 If the type of the file can be determined from the suffix of the file
2205 it can be omitted. Format dependant parameters are: For images of
2206 type 'raw' two extra parameters are needed 'xsize' and 'ysize', if the
2207 'channel' parameter is omitted for type 'raw' it is assumed to be 3.
2208 gif and png images might have a palette are converted to truecolor bit
2209 when read. Alpha channel is preserved for png images irregardless of
2210 them being in RGB or gray colorspace. Similarly grayscale jpegs are
2211 one channel images after reading them. For jpeg images the iptc
2212 header information (stored in the APP13 header) is avaliable to some
2213 degree. You can get the raw header with C<$img-E<gt>{IPTCRAW}>, but
2214 you can also retrieve the most basic information with
2215 C<%hsh=$img-E<gt>parseiptc()> as always patches are welcome. pnm has no
2216 extra options. Examples:
2218 $img = Imager->new();
2219 $img->read(file=>"cover.jpg") or die $img->errstr; # gets type from name
2221 $img = Imager->new();
2222 { local(*FH,$/); open(FH,"file.gif") or die $!; $a=<FH>; }
2223 $img->read(data=>$a,type=>'gif') or die $img->errstr;
2225 The second example shows how to read an image from a scalar, this is
2226 usefull if your data originates from somewhere else than a filesystem
2227 such as a database over a DBI connection.
2229 When writing to a tiff image file you can also specify the 'class'
2230 parameter, which can currently take a single value, "fax". If class
2231 is set to fax then a tiff image which should be suitable for faxing
2232 will be written. For the best results start with a grayscale image.
2233 By default the image is written at fine resolution you can override
2234 this by setting the "fax_fine" parameter to 0.
2236 If you are reading from a gif image file, you can supply a 'colors'
2237 parameter which must be a reference to a scalar. The referenced
2238 scalar will receive an array reference which contains the colors, each
2239 represented as an Imager::Color object.
2241 If you already have an open file handle, for example a socket or a
2242 pipe, you can specify the 'fd' parameter instead of supplying a
2243 filename. Please be aware that you need to use fileno() to retrieve
2244 the file descriptor for the file:
2246 $img->read(fd=>fileno(FILE), type=>'gif') or die $img->errstr;
2248 For writing using the 'fd' option you will probably want to set $| for
2249 that descriptor, since the writes to the file descriptor bypass Perl's
2250 (or the C libraries) buffering. Setting $| should avoid out of order
2253 *Note that load() is now an alias for read but will be removed later*
2255 C<$img-E<gt>write> has the same interface as C<read()>. The earlier
2256 comments on C<read()> for autodetecting filetypes apply. For jpegs
2257 quality can be adjusted via the 'jpegquality' parameter (0-100). The
2258 number of colorplanes in gifs are set with 'gifplanes' and should be
2259 between 1 (2 color) and 8 (256 colors). It is also possible to choose
2260 between two quantizing methods with the parameter 'gifquant'. If set
2261 to mc it uses the mediancut algorithm from either giflibrary. If set
2262 to lm it uses a local means algorithm. It is then possible to give
2263 some extra settings. lmdither is the dither deviation amount in pixels
2264 (manhattan distance). lmfixed can be an array ref who holds an array
2265 of Imager::Color objects. Note that the local means algorithm needs
2266 much more cpu time but also gives considerable better results than the
2267 median cut algorithm.
2269 Currently just for gif files, you can specify various options for the
2270 conversion from Imager's internal RGB format to the target's indexed
2271 file format. If you set the gifquant option to 'gen', you can use the
2272 options specified under L<Quantization options>.
2274 To see what Imager is compiled to support the following code snippet
2278 print "@{[keys %Imager::formats]}";
2280 When reading raw images you need to supply the width and height of the
2281 image in the xsize and ysize options:
2283 $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
2284 or die "Cannot read raw image\n";
2286 If your input file has more channels than you want, or (as is common),
2287 junk in the fourth channel, you can use the datachannels and
2288 storechannels options to control the number of channels in your input
2289 file and the resulting channels in your image. For example, if your
2290 input image uses 32-bits per pixel with red, green, blue and junk
2291 values for each pixel you could do:
2293 $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
2295 or die "Cannot read raw image\n";
2297 Normally the raw image is expected to have the value for channel 1
2298 immediately following channel 0 and channel 2 immediately following
2299 channel 1 for each pixel. If your input image has all the channel 0
2300 values for the first line of the image, followed by all the channel 1
2301 values for the first line and so on, you can use the interleave option:
2303 $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
2304 or die "Cannot read raw image\n";
2306 =head2 Multi-image files
2308 Currently just for gif files, you can create files that contain more
2313 Imager->write_multi(\%opts, @images)
2315 Where %opts describes 4 possible types of outputs:
2321 This is C<gif> for gif animations.
2325 A code reference which is called with a single parameter, the data to
2326 be written. You can also specify $opts{maxbuffer} which is the
2327 maximum amount of data buffered. Note that there can be larger writes
2328 than this if the file library writes larger blocks. A smaller value
2329 maybe useful for writing to a socket for incremental display.
2333 The file descriptor to save the images to.
2337 The name of the file to write to.
2339 %opts may also include the keys from L<Gif options> and L<Quantization
2344 You must also specify the file format using the 'type' option.
2346 The current aim is to support other multiple image formats in the
2347 future, such as TIFF, and to support reading multiple images from a
2353 # ... code to put images in @images
2354 Imager->write_multi({type=>'gif',
2356 gif_delays=>[ (10) x @images ] },
2360 You can read multi-image files (currently only GIF files) using the
2361 read_multi() method:
2363 my @imgs = Imager->read_multi(file=>'foo.gif')
2364 or die "Cannot read images: ",Imager->errstr;
2366 The possible parameters for read_multi() are:
2372 The name of the file to read in.
2376 A filehandle to read in. This can be the name of a filehandle, but it
2377 will need the package name, no attempt is currently made to adjust
2378 this to the caller's package.
2382 The numeric file descriptor of an open file (or socket).
2386 A function to be called to read in data, eg. reading a blob from a
2387 database incrementally.
2391 The data of the input file in memory.
2395 The type of file. If the file is parameter is given and provides
2396 enough information to guess the type, then this parameter is optional.
2400 Note: you cannot use the callback or data parameter with giflib
2401 versions before 4.0.
2403 When reading from a GIF file with read_multi() the images are returned
2408 These options can be specified when calling write_multi() for gif
2409 files, when writing a single image with the gifquant option set to
2410 'gen', or for direct calls to i_writegif_gen and i_writegif_callback.
2412 Note that some viewers will ignore some of these options
2413 (gif_user_input in particular).
2417 =item gif_each_palette
2419 Each image in the gif file has it's own palette if this is non-zero.
2420 All but the first image has a local colour table (the first uses the
2421 global colour table.
2425 The images are written interlaced if this is non-zero.
2429 A reference to an array containing the delays between images, in 1/100
2432 If you want the same delay for every frame you can simply set this to
2433 the delay in 1/100 seconds.
2435 =item gif_user_input
2437 A reference to an array contains user input flags. If the given flag
2438 is non-zero the image viewer should wait for input before displaying
2443 A reference to an array of image disposal methods. These define what
2444 should be done to the image before displaying the next one. These are
2445 integers, where 0 means unspecified, 1 means the image should be left
2446 in place, 2 means restore to background colour and 3 means restore to
2449 =item gif_tran_color
2451 A reference to an Imager::Color object, which is the colour to use for
2452 the palette entry used to represent transparency in the palette. You
2453 need to set the transp option (see L<Quantization options>) for this
2458 A reference to an array of references to arrays which represent screen
2459 positions for each image.
2461 =item gif_loop_count
2463 If this is non-zero the Netscape loop extension block is generated,
2464 which makes the animation of the images repeat.
2466 This is currently unimplemented due to some limitations in giflib.
2470 =head2 Quantization options
2472 These options can be specified when calling write_multi() for gif
2473 files, when writing a single image with the gifquant option set to
2474 'gen', or for direct calls to i_writegif_gen and i_writegif_callback.
2480 A arrayref of colors that are fixed. Note that some color generators
2485 The type of transparency processing to perform for images with an
2486 alpha channel where the output format does not have a proper alpha
2487 channel (eg. gif). This can be any of:
2493 No transparency processing is done. (default)
2497 Pixels more transparent that tr_threshold are rendered as transparent.
2501 An error diffusion dither is done on the alpha channel. Note that
2502 this is independent of the translation performed on the colour
2503 channels, so some combinations may cause undesired artifacts.
2507 The ordered dither specified by tr_orddith is performed on the alpha
2512 This will only be used if the image has an alpha channel, and if there
2513 is space in the palette for a transparency colour.
2517 The highest alpha value at which a pixel will be made transparent when
2518 transp is 'threshold'. (0-255, default 127)
2522 The type of error diffusion to perform on the alpha channel when
2523 transp is 'errdiff'. This can be any defined error diffusion type
2524 except for custom (see errdiff below).
2528 The type of ordered dither to perform on the alpha channel when transp
2529 is 'ordered'. Possible values are:
2535 A semi-random map is used. The map is the same each time.
2547 horizontal line dither.
2551 vertical line dither.
2557 diagonal line dither
2563 diagonal line dither
2567 dot matrix dither (currently the default). This is probably the best
2568 for displays (like web pages).
2572 A custom dither matrix is used - see tr_map
2578 When tr_orddith is custom this defines an 8 x 8 matrix of integers
2579 representing the transparency threshold for pixels corresponding to
2580 each position. This should be a 64 element array where the first 8
2581 entries correspond to the first row of the matrix. Values should be
2586 Defines how the quantization engine will build the palette(s).
2587 Currently this is ignored if 'translate' is 'giflib', but that may
2588 change. Possible values are:
2594 Only colors supplied in 'colors' are used.
2598 The web color map is used (need url here.)
2602 The original code for generating the color map (Addi's code) is used.
2606 Other methods may be added in the future.
2610 A arrayref containing Imager::Color objects, which represents the
2611 starting set of colors to use in translating the images. webmap will
2612 ignore this. The final colors used are copied back into this array
2613 (which is expanded if necessary.)
2617 The maximum number of colors to use in the image.
2621 The method used to translate the RGB values in the source image into
2622 the colors selected by make_colors. Note that make_colors is ignored
2623 whene translate is 'giflib'.
2625 Possible values are:
2631 The giflib native quantization function is used.
2635 The closest color available is used.
2639 The pixel color is modified by perturb, and the closest color is chosen.
2643 An error diffusion dither is performed.
2647 It's possible other transate values will be added.
2651 The type of error diffusion dither to perform. These values (except
2652 for custom) can also be used in tr_errdif.
2658 Floyd-Steinberg dither
2662 Jarvis, Judice and Ninke dither
2670 Custom. If you use this you must also set errdiff_width,
2671 errdiff_height and errdiff_map.
2677 =item errdiff_height
2683 When translate is 'errdiff' and errdiff is 'custom' these define a
2684 custom error diffusion map. errdiff_width and errdiff_height define
2685 the size of the map in the arrayref in errdiff_map. errdiff_orig is
2686 an integer which indicates the current pixel position in the top row
2691 When translate is 'perturb' this is the magnitude of the random bias
2692 applied to each channel of the pixel before it is looked up in the
2697 =head2 Obtaining/setting attributes of images
2699 To get the size of an image in pixels the C<$img-E<gt>getwidth()> and
2700 C<$img-E<gt>getheight()> are used.
2702 To get the number of channels in
2703 an image C<$img-E<gt>getchannels()> is used. $img-E<gt>getmask() and
2704 $img-E<gt>setmask() are used to get/set the channel mask of the image.
2706 $mask=$img->getmask();
2707 $img->setmask(mask=>1+2); # modify red and green only
2708 $img->setmask(mask=>8); # modify alpha only
2709 $img->setmask(mask=>$mask); # restore previous mask
2711 The mask of an image describes which channels are updated when some
2712 operation is performed on an image. Naturally it is not possible to
2713 apply masks to operations like scaling that alter the dimensions of
2716 It is possible to have Imager find the number of colors in an image
2717 by using C<$img-E<gt>getcolorcount()>. It requires memory proportionally
2718 to the number of colors in the image so it is possible to have it
2719 stop sooner if you only need to know if there are more than a certain number
2720 of colors in the image. If there are more colors than asked for
2721 the function return undef. Examples:
2723 if (!defined($img->getcolorcount(maxcolors=>512)) {
2724 print "Less than 512 colors in image\n";
2727 The bits() method retrieves the number of bits used to represent each
2728 channel in a pixel, typically 8. The type() method returns either
2729 'direct' for truecolor images or 'paletted' for paletted images. The
2730 virtual() method returns non-zero if the image contains no actual
2731 pixels, for example masked images.
2733 =head2 Paletted Images
2735 In general you can work with paletted images in the same way as RGB
2736 images, except that if you attempt to draw to a paletted image with a
2737 color that is not in the image's palette, the image will be converted
2738 to an RGB image. This means that drawing on a paletted image with
2739 anti-aliasing enabled will almost certainly convert the image to RGB.
2741 You can add colors to a paletted image with the addcolors() method:
2743 my @colors = ( Imager::Color->new(255, 0, 0),
2744 Imager::Color->new(0, 255, 0) );
2745 my $index = $img->addcolors(colors=>\@colors);
2747 The return value is the index of the first color added, or undef if
2748 adding the colors would overflow the palette.
2750 Once you have colors in the palette you can overwrite them with the
2753 $img->setcolors(start=>$start, colors=>\@colors);
2755 Returns true on success.
2757 To retrieve existing colors from the palette use the getcolors() method:
2759 # get the whole palette
2760 my @colors = $img->getcolors();
2761 # get a single color
2762 my $color = $img->getcolors(start=>$index);
2763 # get a range of colors
2764 my @colors = $img->getcolors(start=>$index, count=>$count);
2766 To quickly find a color in the palette use findcolor():
2768 my $index = $img->findcolor(color=>$color);
2770 which returns undef on failure, or the index of the color.
2772 You can get the current palette size with $img->colorcount, and the
2773 maximum size of the palette with $img->maxcolors.
2775 =head2 Drawing Methods
2777 IMPLEMENTATION MORE OR LESS DONE CHECK THE TESTS
2778 DOCUMENTATION OF THIS SECTION OUT OF SYNC
2780 It is possible to draw with graphics primitives onto images. Such
2781 primitives include boxes, arcs, circles and lines. A reference
2782 oriented list follows.
2785 $img->box(color=>$blue,xmin=>10,ymin=>30,xmax=>200,ymax=>300,filled=>1);
2787 The above example calls the C<box> method for the image and the box
2788 covers the pixels with in the rectangle specified. If C<filled> is
2789 ommited it is drawn as an outline. If any of the edges of the box are
2790 ommited it will snap to the outer edge of the image in that direction.
2791 Also if a color is omitted a color with (255,255,255,255) is used
2795 $img->arc(color=>$red, r=20, x=>200, y=>100, d1=>10, d2=>20 );
2797 This creates a filled red arc with a 'center' at (200, 100) and spans
2798 10 degrees and the slice has a radius of 20. SEE section on BUGS.
2800 Both the arc() and box() methods can take a C<fill> parameter which
2801 can either be an Imager::Fill object, or a reference to a hash
2802 containing the parameters used to create the fill:
2804 $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
2805 fill => { hatch=>'cross2' });
2807 my $fill = Imager::Fill->new(hatch=>'stipple');
2808 $img->box(fill=>$fill);
2810 See L<Imager::Fill> for the type of fills you can use.
2813 $img->circle(color=>$green, r=50, x=>200, y=>100);
2815 This creates a green circle with its center at (200, 100) and has a
2819 $img->line(color=>$green, x1=10, x2=>100,
2820 y1=>20, y2=>50, antialias=>1 );
2822 That draws an antialiased line from (10,100) to (20,50).
2825 $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
2826 $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], antialias=>1);
2828 Polyline is used to draw multilple lines between a series of points.
2829 The point set can either be specified as an arrayref to an array of
2830 array references (where each such array represents a point). The
2831 other way is to specify two array references.
2833 You can fill a region that all has the same color using the
2834 flood_fill() method, for example:
2836 $img->flood_fill(x=>50, y=>50, color=>$color);
2838 will fill all regions the same color connected to the point (50, 50).
2840 You can also use a general fill, so you could fill the same region
2841 with a check pattern using:
2843 $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'check2x2' });
2845 See L<Imager::Fill> for more information on general fills.
2847 =head2 Text rendering
2849 Text rendering is described in the Imager::Font manpage.
2851 =head2 Image resizing
2853 To scale an image so porportions are maintained use the
2854 C<$img-E<gt>scale()> method. if you give either a xpixels or ypixels
2855 parameter they will determine the width or height respectively. If
2856 both are given the one resulting in a larger image is used. example:
2857 C<$img> is 700 pixels wide and 500 pixels tall.
2859 $img->scale(xpixels=>400); # 400x285
2860 $img->scale(ypixels=>400); # 560x400
2862 $img->scale(xpixels=>400,ypixels=>400); # 560x400
2863 $img->scale(xpixels=>400,ypixels=>400,type=>min); # 400x285
2865 $img->scale(scalefactor=>0.25); 175x125 $img->scale(); # 350x250
2867 if you want to create low quality previews of images you can pass
2868 C<qtype=E<gt>'preview'> to scale and it will use nearest neighbor
2869 sampling instead of filtering. It is much faster but also generates
2870 worse looking images - especially if the original has a lot of sharp
2871 variations and the scaled image is by more than 3-5 times smaller than
2874 If you need to scale images per axis it is best to do it simply by
2875 calling scaleX and scaleY. You can pass either 'scalefactor' or
2876 'pixels' to both functions.
2878 Another way to resize an image size is to crop it. The parameters
2879 to crop are the edges of the area that you want in the returned image.
2880 If a parameter is omited a default is used instead.
2882 $newimg = $img->crop(left=>50, right=>100, top=>10, bottom=>100);
2883 $newimg = $img->crop(left=>50, top=>10, width=>50, height=>90);
2884 $newimg = $img->crop(left=>50, right=>100); # top
2886 You can also specify width and height parameters which will produce a
2887 new image cropped from the center of the input image, with the given
2890 $newimg = $img->crop(width=>50, height=>50);
2892 The width and height parameters take precedence over the left/right
2893 and top/bottom parameters respectively.
2895 =head2 Copying images
2897 To create a copy of an image use the C<copy()> method. This is usefull
2898 if you want to keep an original after doing something that changes the image
2899 inplace like writing text.
2903 To copy an image to onto another image use the C<paste()> method.
2905 $dest->paste(left=>40,top=>20,img=>$logo);
2907 That copies the entire C<$logo> image onto the C<$dest> image so that the
2908 upper left corner of the C<$logo> image is at (40,20).
2911 =head2 Flipping images
2913 An inplace horizontal or vertical flip is possible by calling the
2914 C<flip()> method. If the original is to be preserved it's possible to
2915 make a copy first. The only parameter it takes is the C<dir>
2916 parameter which can take the values C<h>, C<v>, C<vh> and C<hv>.
2918 $img->flip(dir=>"h"); # horizontal flip
2919 $img->flip(dir=>"vh"); # vertical and horizontal flip
2920 $nimg = $img->copy->flip(dir=>"v"); # make a copy and flip it vertically
2922 =head2 Rotating images
2924 Use the rotate() method to rotate an image.
2926 To rotate by an exact amount in degrees or radians, use the 'degrees'
2927 or 'radians' parameter:
2929 my $rot20 = $img->rotate(degrees=>20);
2930 my $rotpi4 = $img->rotate(radians=>3.14159265/4);
2932 To rotate in steps of 90 degrees, use the 'right' parameter:
2934 my $rotated = $img->rotate(right=>270);
2936 Rotations are clockwise for positive values.
2938 =head2 Blending Images
2940 To put an image or a part of an image directly
2941 into another it is best to call the C<paste()> method on the image you
2944 $img->paste(img=>$srcimage,left=>30,top=>50);
2946 That will take paste C<$srcimage> into C<$img> with the upper
2947 left corner at (30,50). If no values are given for C<left>
2948 or C<top> they will default to 0.
2950 A more complicated way of blending images is where one image is
2951 put 'over' the other with a certain amount of opaqueness. The
2952 method that does this is rubthrough.
2954 $img->rubthrough(src=>$srcimage,tx=>30,ty=>50);
2956 That will take the image C<$srcimage> and overlay it with the upper
2957 left corner at (30,50). You can rub 2 or 4 channel images onto a 3
2958 channel image, or a 2 channel image onto a 1 channel image. The last
2959 channel is used as an alpha channel.
2964 A special image method is the filter method. An example is:
2966 $img->filter(type=>'autolevels');
2968 This will call the autolevels filter. Here is a list of the filters
2969 that are always avaliable in Imager. This list can be obtained by
2970 running the C<filterlist.perl> script that comes with the module
2974 autolevels lsat(0.1) usat(0.1) skew(0)
2975 bumpmap bump elevation(0) lightx lighty st(2)
2978 fountain xa ya xb yb ftype(linear) repeat(none) combine(none)
2979 super_sample(none) ssample_param(4) segments(see below)
2981 gradgen xo yo colors dist
2984 noise amount(3) subtype(0)
2985 postlevels levels(10)
2986 radnoise xo(100) yo(100) ascale(17.0) rscale(0.02)
2987 turbnoise xo(0.0) yo(0.0) scale(10.0)
2988 watermark wmark pixdiff(10) tx(0) ty(0)
2990 The default values are in parenthesis. All parameters must have some
2991 value but if a parameter has a default value it may be omitted when
2992 calling the filter function.
3000 scales the value of each channel so that the values in the image will
3001 cover the whole possible range for the channel. I<lsat> and I<usat>
3002 truncate the range by the specified fraction at the top and bottom of
3003 the range respectivly..
3007 uses the channel I<elevation> image I<bump> as a bumpmap on your
3008 image, with the light at (I<lightx>, I<lightty>), with a shadow length
3013 scales each channel by I<intensity>. Values of I<intensity> < 1.0
3014 will reduce the contrast.
3018 performs 2 1-dimensional convolutions on the image using the values
3019 from I<coef>. I<coef> should be have an odd length.
3023 renders a fountain fill, similar to the gradient tool in most paint
3024 software. The default fill is a linear fill from opaque black to
3025 opaque white. The points A(xa, ya) and B(xb, yb) control the way the
3026 fill is performed, depending on the ftype parameter:
3032 the fill ramps from A through to B.
3036 the fill ramps in both directions from A, where AB defines the length
3041 A is the center of a circle, and B is a point on it's circumference.
3042 The fill ramps from the center out to the circumference.
3046 A is the center of a square and B is the center of one of it's sides.
3047 This can be used to rotate the square. The fill ramps out to the
3048 edges of the square.
3052 A is the centre of a circle and B is a point on it's circumference. B
3053 marks the 0 and 360 point on the circle, with the fill ramping
3058 A is the center of a circle and B is a point on it's circumference. B
3059 marks the 0 and point on the circle, with the fill ramping in both
3060 directions to meet opposite.
3064 The I<repeat> option controls how the fill is repeated for some
3065 I<ftype>s after it leaves the AB range:
3071 no repeats, points outside of each range are treated as if they were
3072 on the extreme end of that range.
3076 the fill simply repeats in the positive direction
3080 the fill repeats in reverse and then forward and so on, in the
3085 the fill repeats in both the positive and negative directions (only
3086 meaningful for a linear fill).
3090 as for triangle, but in the negative direction too (only meaningful
3095 By default the fill simply overwrites the whole image (unless you have
3096 parts of the range 0 through 1 that aren't covered by a segment), if
3097 any segments of your fill have any transparency, you can set the
3098 I<combine> option to 'normal' to have the fill combined with the
3099 existing pixels. See the description of I<combine> in L<Imager/Fill>.
3101 If your fill has sharp edges, for example between steps if you use
3102 repeat set to 'triangle', you may see some aliased or ragged edges.
3103 You can enable super-sampling which will take extra samples within the
3104 pixel in an attempt anti-alias the fill.
3106 The possible values for the super_sample option are:
3112 no super-sampling is done
3116 a square grid of points are sampled. The number of points sampled is
3117 the square of ceil(0.5 + sqrt(ssample_param)).
3121 a random set of points within the pixel are sampled. This looks
3122 pretty bad for low ssample_param values.
3126 the points on the radius of a circle within the pixel are sampled.
3127 This seems to produce the best results, but is fairly slow (for now).
3131 You can control the level of sampling by setting the ssample_param
3132 option. This is roughly the number of points sampled, but depends on
3133 the type of sampling.
3135 The segments option is an arrayref of segments. You really should use
3136 the Imager::Fountain class to build your fountain fill. Each segment
3137 is an array ref containing:
3143 a floating point number between 0 and 1, the start of the range of fill parameters covered by this segment.
3147 a floating point number between start and end which can be used to
3148 push the color range towards one end of the segment.
3152 a floating point number between 0 and 1, the end of the range of fill
3153 parameters covered by this segment. This should be greater than
3160 The colors at each end of the segment. These can be either
3161 Imager::Color or Imager::Color::Float objects.
3165 The type of segment, this controls the way the fill parameter varies
3166 over the segment. 0 for linear, 1 for curved (unimplemented), 2 for
3167 sine, 3 for sphere increasing, 4 for sphere decreasing.
3171 The way the color varies within the segment, 0 for simple RGB, 1 for
3172 hue increasing and 2 for hue decreasing.
3176 Don't forgot to use Imager::Fountain instead of building your own.
3177 Really. It even loads GIMP gradient files.
3181 performs a gaussian blur of the image, using I<stddev> as the standard
3182 deviation of the curve used to combine pixels, larger values give
3183 bigger blurs. For a definition of Gaussian Blur, see:
3185 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
3189 renders a gradient, with the given I<colors> at the corresponding
3190 points (x,y) in I<xo> and I<yo>. You can specify the way distance is
3191 measured for color blendeing by setting I<dist> to 0 for Euclidean, 1
3192 for Euclidean squared, and 2 for Manhattan distance.
3196 inverts the image, black to white, white to black. All channels are
3197 inverted, including the alpha channel if any.
3201 produces averaged tiles of the given I<size>.
3205 adds noise of the given I<amount> to the image. If I<subtype> is
3206 zero, the noise is even to each channel, otherwise noise is added to
3207 each channel independently.
3211 renders radiant Perlin turbulent noise. The centre of the noise is at
3212 (I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
3213 and I<rscale> the radial scale, higher numbers give more detail.
3217 alters the image to have only I<levels> distinct level in each
3222 renders Perlin turbulent noise. (I<xo>, I<yo>) controls the origin of
3223 the noise, and I<scale> the scale of the noise, with lower numbers
3228 applies I<wmark> as a watermark on the image with strength I<pixdiff>,
3229 with an origin at (I<tx>, I<ty>)
3233 A demonstration of most of the filters can be found at:
3235 http://www.develop-help.com/imager/filters.html
3237 (This is a slow link.)
3239 =head2 Color transformations
3241 You can use the convert method to transform the color space of an
3242 image using a matrix. For ease of use some presets are provided.
3244 The convert method can be used to:
3250 convert an RGB or RGBA image to grayscale.
3254 convert a grayscale image to RGB.
3258 extract a single channel from an image.
3262 set a given channel to a particular value (or from another channel)
3266 The currently defined presets are:
3274 converts an RGBA image into a grayscale image with alpha channel, or
3275 an RGB image into a grayscale image without an alpha channel.
3277 This weights the RGB channels at 22.2%, 70.7% and 7.1% respectively.
3281 removes the alpha channel from a 2 or 4 channel image. An identity
3288 extracts the first channel of the image into a single channel image
3294 extracts the second channel of the image into a single channel image
3300 extracts the third channel of the image into a single channel image
3304 extracts the alpha channel of the image into a single channel image.
3306 If the image has 1 or 3 channels (assumed to be grayscale of RGB) then
3307 the resulting image will be all white.
3311 converts a grayscale image to RGB, preserving the alpha channel if any
3315 adds an alpha channel to a grayscale or RGB image. Preserves an
3316 existing alpha channel for a 2 or 4 channel image.
3320 For example, to convert an RGB image into a greyscale image:
3322 $new = $img->convert(preset=>'grey'); # or gray
3324 or to convert a grayscale image to an RGB image:
3326 $new = $img->convert(preset=>'rgb');
3328 The presets aren't necessary simple constants in the code, some are
3329 generated based on the number of channels in the input image.
3331 If you want to perform some other colour transformation, you can use
3332 the 'matrix' parameter.
3334 For each output pixel the following matrix multiplication is done:
3336 channel[0] [ [ $c00, $c01, ... ] inchannel[0]
3337 [ ... ] = ... x [ ... ]
3338 channel[n-1] [ $cn0, ..., $cnn ] ] inchannel[max]
3341 So if you want to swap the red and green channels on a 3 channel image:
3343 $new = $img->convert(matrix=>[ [ 0, 1, 0 ],
3347 or to convert a 3 channel image to greyscale using equal weightings:
3349 $new = $img->convert(matrix=>[ [ 0.333, 0.333, 0.334 ] ])
3351 =head2 Color Mappings
3353 You can use the map method to map the values of each channel of an
3354 image independently using a list of lookup tables. It's important to
3355 realize that the modification is made inplace. The function simply
3356 returns the input image again or undef on failure.
3358 Each channel is mapped independently through a lookup table with 256
3359 entries. The elements in the table should not be less than 0 and not
3360 greater than 255. If they are out of the 0..255 range they are
3361 clamped to the range. If a table does not contain 256 entries it is
3364 Single channels can mapped by specifying their name and the mapping
3365 table. The channel names are C<red>, C<green>, C<blue>, C<alpha>.
3367 @map = map { int( $_/2 } 0..255;
3368 $img->map( red=>\@map );
3370 It is also possible to specify a single map that is applied to all
3371 channels, alpha channel included. For example this applies a gamma
3372 correction with a gamma of 1.4 to the input image.
3375 @map = map { int( 0.5 + 255*($_/255)**$gamma ) } 0..255;
3376 $img->map(all=> \@map);
3378 The C<all> map is used as a default channel, if no other map is
3379 specified for a channel then the C<all> map is used instead. If we
3380 had not wanted to apply gamma to the alpha channel we would have used:
3382 $img->map(all=> \@map, alpha=>[]);
3384 Since C<[]> contains fewer than 256 element the gamma channel is
3387 It is also possible to simply specify an array of maps that are
3388 applied to the images in the rgba order. For example to apply
3389 maps to the C<red> and C<blue> channels one would use:
3391 $img->map(maps=>[\@redmap, [], \@bluemap]);
3395 =head2 Transformations
3397 Another special image method is transform. It can be used to generate
3398 warps and rotations and such features. It can be given the operations
3399 in postfix notation or the module Affix::Infix2Postfix can be used.
3400 Look in the test case t/t55trans.t for an example.
3402 transform() needs expressions (or opcodes) that determine the source
3403 pixel for each target pixel. Source expressions are infix expressions
3404 using any of the +, -, *, / or ** binary operators, the - unary
3405 operator, ( and ) for grouping and the sin() and cos() functions. The
3406 target pixel is input as the variables x and y.
3408 You specify the x and y expressions as xexpr and yexpr respectively.
3409 You can also specify opcodes directly, but that's magic deep enough
3410 that you can look at the source code.
3412 You can still use the transform() function, but the transform2()
3413 function is just as fast and is more likely to be enhanced and
3416 Later versions of Imager also support a transform2() class method
3417 which allows you perform a more general set of operations, rather than
3418 just specifying a spatial transformation as with the transform()
3419 method, you can also perform colour transformations, image synthesis
3420 and image combinations.
3422 transform2() takes an reference to an options hash, and a list of
3423 images to operate one (this list may be empty):
3428 my $img = Imager::transform2(\%opts, @imgs)
3429 or die "transform2 failed: $Imager::ERRSTR";
3431 The options hash may define a transformation function, and optionally:
3437 width - the width of the image in pixels. If this isn't supplied the
3438 width of the first input image is used. If there are no input images
3443 height - the height of the image in pixels. If this isn't supplied
3444 the height of the first input image is used. If there are no input
3445 images an error occurs.
3449 constants - a reference to hash of constants to define for the
3450 expression engine. Some extra constants are defined by Imager
3454 The tranformation function is specified using either the expr or
3455 rpnexpr member of the options.
3459 =item Infix expressions
3461 You can supply infix expressions to transform 2 with the expr keyword.
3463 $opts{expr} = 'return getp1(w-x, h-y)'
3465 The 'expression' supplied follows this general grammar:
3467 ( identifier '=' expr ';' )* 'return' expr
3469 This allows you to simplify your expressions using variables.
3471 A more complex example might be:
3473 $opts{expr} = 'pix = getp1(x,y); return if(value(pix)>0.8,pix*0.8,pix)'
3475 Currently to use infix expressions you must have the Parse::RecDescent
3476 module installed (available from CPAN). There is also what might be a
3477 significant delay the first time you run the infix expression parser
3478 due to the compilation of the expression grammar.
3480 =item Postfix expressions
3482 You can supply postfix or reverse-polish notation expressions to
3483 transform2() through the rpnexpr keyword.
3485 The parser for rpnexpr emulates a stack machine, so operators will
3486 expect to see their parameters on top of the stack. A stack machine
3487 isn't actually used during the image transformation itself.
3489 You can store the value at the top of the stack in a variable called
3490 foo using !foo and retrieve that value again using @foo. The !foo
3491 notation will pop the value from the stack.
3493 An example equivalent to the infix expression above:
3495 $opts{rpnexpr} = 'x y getp1 !pix @pix value 0.8 gt @pix 0.8 * @pix ifp'
3499 transform2() has a fairly rich range of operators.
3503 =item +, *, -, /, %, **
3505 multiplication, addition, subtraction, division, remainder and
3506 exponentiation. Multiplication, addition and subtraction can be used
3507 on colour values too - though you need to be careful - adding 2 white
3508 values together and multiplying by 0.5 will give you grey, not white.
3510 Division by zero (or a small number) just results in a large number.
3511 Modulo zero (or a small number) results in zero.
3513 =item sin(N), cos(N), atan2(y,x)
3515 Some basic trig functions. They work in radians, so you can't just
3518 =item distance(x1, y1, x2, y2)
3520 Find the distance between two points. This is handy (along with
3521 atan2()) for producing circular effects.
3525 Find the square root. I haven't had much use for this since adding
3526 the distance() function.
3530 Find the absolute value.
3532 =item getp1(x,y), getp2(x,y), getp3(x, y)
3534 Get the pixel at position (x,y) from the first, second or third image
3535 respectively. I may add a getpn() function at some point, but this
3536 prevents static checking of the instructions against the number of
3537 images actually passed in.
3539 =item value(c), hue(c), sat(c), hsv(h,s,v)
3541 Separates a colour value into it's value (brightness), hue (colour)
3542 and saturation elements. Use hsv() to put them back together (after
3543 suitable manipulation).
3545 =item red(c), green(c), blue(c), rgb(r,g,b)
3547 Separates a colour value into it's red, green and blue colours. Use
3548 rgb(r,g,b) to put it back together.
3552 Convert a value to an integer. Uses a C int cast, so it may break on
3555 =item if(cond,ntrue,nfalse), if(cond,ctrue,cfalse)
3557 A simple (and inefficient) if function.
3559 =item <=,<,==,>=,>,!=
3561 Relational operators (typically used with if()). Since we're working
3562 with floating point values the equalities are 'near equalities' - an
3563 epsilon value is used.
3565 =item &&, ||, not(n)
3567 Basic logical operators.
3575 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat x y getp1 !pix @pix sat 0.7 gt @pat @pix ifp'
3577 tiles a smaller version of the input image over itself where the
3578 colour has a saturation over 0.7.
3580 =item rpnexpr=>'x 25 % 15 * y 35 % 10 * getp1 !pat y 360 / !rat x y getp1 1 @rat - pmult @pat @rat pmult padd'
3582 tiles the input image over itself so that at the top of the image the
3583 full-size image is at full strength and at the bottom the tiling is
3586 =item rpnexpr=>'x y getp1 !pix @pix value 0.96 gt @pix sat 0.1 lt and 128 128 255 rgb @pix ifp'
3588 replace pixels that are white or almost white with a palish blue
3590 =item rpnexpr=>'x 35 % 10 * y 45 % 8 * getp1 !pat x y getp1 !pix @pix sat 0.2 lt @pix value 0.9 gt and @pix @pat @pix value 2 / 0.5 + pmult ifp'
3592 Tiles the input image overitself where the image isn't white or almost
3595 =item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a2 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
3599 =item rpnexpr=>'x y 160 180 distance !d y 180 - x 160 - atan2 !a @d 10 / @a + 3.1416 2 * % !a2 @a 180 * 3.1416 / 1 @a2 sin 1 + 2 / hsv'
3601 A spiral built on top of a colour wheel.
3605 For details on expression parsing see L<Imager::Expr>. For details on
3606 the virtual machine used to transform the images, see
3607 L<Imager::regmach.pod>.
3609 =head2 Matrix Transformations
3611 Rather than having to write code in a little language, you can use a
3612 matrix to perform transformations, using the matrix_transform()
3615 my $im2 = $im->matrix_transform(matrix=>[ -1, 0, $im->getwidth-1,
3619 By default the output image will be the same size as the input image,
3620 but you can supply the xsize and ysize parameters to change the size.
3622 Rather than building matrices by hand you can use the Imager::Matrix2d
3623 module to build the matrices. This class has methods to allow you to
3624 scale, shear, rotate, translate and reflect, and you can combine these
3625 with an overloaded multiplication operator.
3627 WARNING: the matrix you provide in the matrix operator transforms the
3628 co-ordinates within the B<destination> image to the co-ordinates
3629 within the I<source> image. This can be confusing.
3631 Since Imager has 3 different fairly general ways of transforming an
3632 image spatially, this method also has a yatf() alias. Yet Another
3633 Transformation Function.
3635 =head2 Masked Images
3637 Masked images let you control which pixels are modified in an
3638 underlying image. Where the first channel is completely black in the
3639 mask image, writes to the underlying image are ignored.
3641 For example, given a base image called $img:
3643 my $mask = Imager->new(xsize=>$img->getwidth, ysize=>getheight,
3645 # ... draw something on the mask
3646 my $maskedimg = $img->masked(mask=>$mask);
3648 You can specifiy the region of the underlying image that is masked
3649 using the left, top, right and bottom options.
3651 If you just want a subset of the image, without masking, just specify
3652 the region without specifying a mask.
3656 It is possible to add filters to the module without recompiling the
3657 module itself. This is done by using DSOs (Dynamic shared object)
3658 avaliable on most systems. This way you can maintain our own filters
3659 and not have to get me to add it, or worse patch every new version of
3660 the Module. Modules can be loaded AND UNLOADED at runtime. This
3661 means that you can have a server/daemon thingy that can do something
3664 load_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
3665 %hsh=(a=>35,b=>200,type=>lin_stretch);
3667 unload_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
3668 $img->write(type=>'pnm',file=>'testout/t60.jpg')
3669 || die "error in write()\n";
3671 Someone decides that the filter is not working as it should -
3672 dyntest.c modified and recompiled.
3674 load_plugin("dynfilt/dyntest.so") || die "unable to load plugin\n";
3677 An example plugin comes with the module - Please send feedback to
3678 addi@umich.edu if you test this.
3680 Note: This seems to test ok on the following systems:
3681 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
3682 If you test this on other systems please let me know.
3686 Image tags contain meta-data about the image, ie. information not
3687 stored as pixels of the image.
3689 At the perl level each tag has a name or code and a value, which is an
3690 integer or an arbitrary string. An image can contain more than one
3691 tag with the same name or code.
3693 You can retrieve tags from an image using the tags() method, you can
3694 get all of the tags in an image, as a list of array references, with
3695 the code or name of the tag followed by the value of the tag:
3697 my @alltags = $img->tags;
3699 or you can get all tags that have a given name:
3701 my @namedtags = $img->tags(name=>$name);
3705 my @tags = $img->tags(code=>$code);
3707 You can add tags using the addtag() method, either by name:
3709 my $index = $img->addtag(name=>$name, value=>$value);
3713 my $index = $img->addtag(code=>$code, value=>$value);
3715 You can remove tags with the deltag() method, either by index:
3717 $img->deltag(index=>$index);
3721 $img->deltag(name=>$name);
3725 $img->deltag(code=>$code);
3727 In each case deltag() returns the number of tags deleted.
3729 When you read a GIF image using read_multi(), each image can include
3736 the offset of the image from the left of the "screen" ("Image Left
3741 the offset of the image from the top of the "screen" ("Image Top Position")
3745 non-zero if the image was interlaced ("Interlace Flag")
3747 =item gif_screen_width
3749 =item gif_screen_height
3751 the size of the logical screen ("Logical Screen Width",
3752 "Logical Screen Height")
3756 Non-zero if this image had a local color map.
3758 =item gif_background
3760 The index in the global colormap of the logical screen's background
3761 color. This is only set if the current image uses the global
3764 =item gif_trans_index
3766 The index of the color in the colormap used for transparency. If the
3767 image has a transparency then it is returned as a 4 channel image with
3768 the alpha set to zero in this palette entry. ("Transparent Color Index")
3772 The delay until the next frame is displayed, in 1/100 of a second.
3775 =item gif_user_input
3777 whether or not a user input is expected before continuing (view dependent)
3778 ("User Input Flag").
3782 how the next frame is displayed ("Disposal Method")
3786 the number of loops from the Netscape Loop extension. This may be zero.
3790 the first block of the first gif comment before each image.
3794 Where applicable, the ("name") is the name of that field from the GIF89
3797 The following tags are set in a TIFF image when read, and can be set
3802 =item tiff_resolutionunit
3804 The value of the ResolutionUnit tag. This is ignored on writing if
3805 the i_aspect_only tag is non-zero.
3809 The following tags are set when reading a Windows BMP file is read:
3813 =item bmp_compression
3815 The type of compression, if any.
3817 =item bmp_important_colors
3819 The number of important colors as defined by the writer of the image.
3823 Some standard tags will be implemented as time goes by:
3831 The spatial resolution of the image in pixels per inch. If the image
3832 format uses a different scale, eg. pixels per meter, then this value
3833 is converted. A floating point number stored as a string.
3837 If this is non-zero then the values in i_xres and i_yres are treated
3838 as a ratio only. If the image format does not support aspect ratios
3839 then this is scaled so the smaller value is 72dpi.
3845 box, arc, circle do not support antialiasing yet. arc, is only filled
3846 as of yet. Some routines do not return $self where they should. This
3847 affects code like this, C<$img-E<gt>box()-E<gt>arc()> where an object
3850 When saving Gif images the program does NOT try to shave of extra
3851 colors if it is possible. If you specify 128 colors and there are
3852 only 2 colors used - it will have a 128 colortable anyway.
3856 Arnar M. Hrafnkelsson, addi@umich.edu, and recently lots of assistance
3857 from Tony Cook. See the README for a complete list.
3861 perl(1), Imager::Color(3), Imager::Font(3), Imager::Matrix2d(3),
3862 Affix::Infix2Postfix(3), Parse::RecDescent(3)
3863 http://www.eecs.umich.edu/~addi/perl/Imager/